Ingres CL SI
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - SI
Abstract
This is the specification of the SI facility provided by the compatibility library.
Revision: 1.4, 13-Apr-1999
Document History
- Revision 1.4, 13-Apr-1999
- Added '%X' (uppercase hexadecimal) output formatting for SIfprintf().
- Revision 1.3, 15-Dec-1997
- Formatted in html.
- Revision 1.2, 30-Jul-94
- SI_MAX_TXT_REC is a mess, and 32k looks like the least wrong value. (21-may-93, 11-jun-93)
- The '%p' pointer format added to SI*printf (7-may-93).
- Revision 1.1, last modified 25-Oct-91
- You may now do SIgetc/SIputc on SI_RACC files.
- Revision 1.0, last modified 3-May-91
- Interaction of SI, TE and TR was described.
- Typos fixed.
Specification
Introduction
The SI module provides a Stream Input/Output (SI) facility for reading and writing simple files. SI is based on the stream (ie FILE*) abstraction of UNIX. There are several other flavors of I/O, most importantly the DI (Direct I/O) support used to implement DBMS files.
The SI routines are system dependent, because file systems vary between Ingres environments.
Library
CL
Intended Uses
The SI abstraction is intended to be used for temporary files, single-user read/write files, or multiple user read-only files.
The SI routines were intended for non-multi-threading, non-server code. In particular, for any DBMS server that may run on a platform that does not support native, operating-system threads, they are NOT to be called by the code which runs in the DBMS server (because they would block the entire server). Where native, operating-system threads are supported, SI routines will block only the calling thread.
SI, TE and TR files may be open and used in the same program. SI and/or TR may do i/o to the terminal when it is in the default TE_NORMAL mode, assuming flushes (SIflush, TEflush, TRflush) of pending output are done. When in TE_FORMS or TE_CMDMODE, operations by SI or TR to the terminal are undefined. Output may be mixed as long as flush calls are made before using a new interface and the terminal mode restrictions are obeyed. Mixing input from one file between SI and TR gives undefined results.
SI is used to:
Read user files created with the System text editor and/or user programs. Examples are EQUEL/OSL and the Report Writer which use SI to read a user's source file. Write text files for user use. Examples are EQUEL/OSL/RW which output text files for users to either view (as with RW output) or to use with System utilities (like compilers or editors). Store/retrieve binary data. SI can be used to store and retrieve data in sequential order. Examples are the QBF-OSL query facility which stores binary versions of tuples in SI files or DS which writes a data structure to an SI file for later use.
Assumptions
We assume the concept of a file is understood, and that the notion of sequential vs. random file access is understood.
The System is assumed to have some kind of file system that SI is built on top of or mirrored after. This is known as the System file system and as the BASE implementation.
We also assume a kind of file in the System that a user creates in a system text editor (or its alternative) and is used by such utilities as editors and compilers. The file must store lines of text. In the event that the System supports more than one file of this kind then SI must either support all types or pick one to support. The key point is that there must be a file that a user creates in a text editor which is a sequence of lines of text.
SI assumes all IO is blocking.
SI also assumes that the process has default input and output devices assigned. For interactive processes this must be the terminal. These devices are ready for use once SIeqinit() has been called.
All SI implementations only need type and length to differentiate file types. It is expected that SIgetattr() will simply interpret fields stored in the FILE structure by SIfopen(); in any case the underlying file should not be affected in any way.
Many of these routines may be implemented as macros in the global header <si.h>.
The format strings and arguments to the *printf routines (SIprintf and SIfprintf) are interpreted differently than in the printf family provided in most system libraries. The most important difference is the requirement that the routines be handed a 'decimal point character' after every floating point argument.
The routines SIgetfd and SIinitfp are used by the Front Ends in Testing mode when they are configured as multiple processes. These routines are obsolete.
Definitions/Concepts
SI supports the following file types -- SI_TXT, SI_BIN, SI_VAR and SI_RACC. SI_RACC files, SI_BIN files, and SI_VAR files are "binary" on systems which distinguish between opening a file "binary" vs. "text", i.e. without or with translation of CR/LF pairs.
A SI_TXT file is a file of text. That is, a SI_TXT file is a sequence of lines - each line consists of up to SI_MAX_TXT_REC number of bytes of data followed by an end-of-line delimiter (EOL). SI_TXT files are either generated by INGRES or by the user. If they are created by the user, then they must be equivalent to the System's notion of a text file described above. Also, any file supplied by the user to INGRES is a SI_TXT file.
An appropriate value for SI_MAX_TXT_REC is 32k. This is adequate to support reasonable machine-generated lines, but still small enough to fit in one DOS segment.
Each byte of data stored in a SI_TXT file can be any 8 bit value. The end-of-line delimiter is always returned to Clients as '\n' (this means whatever character the Resident C compiler uses as '\n').
SI_BIN files are semi-structured sequential files that store blocks of bytes. SI_BIN files have an associated record length; data can be read from or written to these files only in record-sized units. SI_VAR files are unstructured sequential files that store blocks of bytes. Data can be read or written to these files in any size chunks. There is no concept of a record with SI_VAR files. The SI_RACC file type is used for manipulation of binary data in a stream file, and allows byte-level seek operations as well as update mode. It is a special file type to allow isolation of these requirements on systems which require special work to implement them (VMS), or which incur performance penalties for file types capable of using them (IBM). The routines which may be used with SI_RACC files are limited to a subset of the SI library, also done in consideration of implementation requirements on some systems.
SI_RACC files are files that allow SIfseek() calls to be made, to reposition the file pointer for read/write operations. These files may be opened in an additional mode, also. This mode is "rw", which indicates an updatable file. For the "rw" mode, a write following a seek may be used to overwrite previous data in the file, or a read following a seek may be used to read previously written bytes. If an existing file is opened "rw", the file pointer is initially positioned at the beginning of the file, ready to overwrite the first bytes. Seeks should be done before switching between read/write operations on update mode files. Seeking works on SI_RACC files opened in all modes.
I/O to SI_RACC files must be done through the SIread() / SIwrite() calls. SIread(), SIwrite(), SIfseek(), SIftell(), SIflush() and SIclose() are the only calls which should be used with this file type. The others may not be implemented for SI_RACC files on some systems.
NOTE: these 4 file types are also known by the OBSOLETE terms TXT_FILE, BIN_FILE, VAR_FILE, and RACC_FILE. The 2 sets of terms are synonymous, but the SI_* terms are considered preferable, due to the embedding of the "SI" module name in the terms. The obsolete terms should be removed from the code as time permits.
SI files are not required to be recoverable in the event of OS crashes or abnormal termination by the client code, including exit without SIclose, and SI makes no guarantee of consistency in the event of a system failure. If the system experiences some type of fault while a Client is reading or writing an SI file, no assumptions can be made as to the state of the file. The results of an open operation on an abnormally terminated file are unpredictable, although the SIfopen call should return - a successful open of a partially written file or an error return may result.
No assumptions can be made as to when data written to an SI file is actually written to permanent System storage. It is intended that the process creating the file will always be able to start over from the beginning to handle crashes and other such failures.
SI files are also not required to support concurrent access involving write operations. That is, two clients, or even two pieces of code within the same client, can't have the same file open for write operations at the same time. SI may not catch attempts to share a file, and if the BASE implementation supports sharing, and SI fails to recognize an attempt at sharing, the results are undefined and cannot be relied upon. If a process has a file open for write, append, or update, any other SI opens on that same file, either within the same process or by other processes, are going to cause unpredictable results. There is no provision of any sort of locking mechanism within SI to prevent such operations. It is up to the client code to provide mechanisms to prevent this situation. The only situation in which multiple opens on the same file are required to work is the situation of multiple readers of the file.
SI declares a single data type FILE that is always used by Clients as a pointer to a FILE. All the routines in SI use a FILE pointer to refer to the file.
Before I/O operations can proceed on a file, the file must be opened with SIfopen. The open operation returns a FILE pointer to the Client for use with other SI routines. When a file is open, the Client must declare whether the file is to be used for reading or writing.
With the exception of SI_RACC type files, SI files are either "open for reading" or "open for writing". A file open for reading must exist in the System File System before the SIfopen. A file open for writing is created at the point of the open. If the file already exists in the System File System, it is superceded by the newly created file.
SI declares 3 FILE pointers stdin, stdout and stderr. Stdin is a FILE pointer to the System default input device, stdout is a FILE pointer for the System default output device, and stderr is a FILE pointer for the System default error device. The predefined file stdin is open for reading and ready for use once SIeqinit() has been called. Similarly, stdout and stderr are open for writing once SIeqinit() has been called.
After a file is successfully opened, read/write operations can proceed to/from the file as appropriate. When reading, the program can continue reading from the file until all the data has been read. Once all the data is read, any subsequent read operations will return the status ENDFILE.
When a file is open for writing, any write operation may be buffered in SI (this is an implementation choice, but the user has to assume that it may be buffered). When an SIflush operation is issued any buffers must be written to the System File System. As noted above, this does not guarantee that they become part of the System permanent storage.
After all desired read/write operations are done, the file is closed with an SIclose call.
Header File <si.h>
The header file <si.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
SIcat - copy file
Copy file with location pointed to by in to previously opened stream out. Out is usually standard output.
Inputs:
| in | location of file to copy |
| out | target of copy (must be already open) |
Outputs:
| in | potentially modified input file pointer. |
| out | potentially modified output file pointer. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| The file described by 'out' is appended. |
Definition:
STATUS SIcat(in, out) LOCATION *in; FILE *out;
SIcopy - copy binary file
Copy a file with location pointed to by in to location pointed to by out.
Inputs:
| in | location of file to copy from |
| out | target of copy (will be overwritten if it exists) |
Outputs:
| in | potentially modified input LOCATION pointer. |
| out | potentially modified output LOCATION pointer. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| If out already exists, it will be overwritten by a copy of in. |
Definition:
STATUS SIcopy(in, out) LOCATION *in; LOCATION *out;
SIclose - close stream
Close the stream s.
Inputs:
| s | file to be closed |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| The file is closed. |
Definition:
STATUS SIclose(s) FILE *s;
SIeqinit - Initialize standard streams for embedded language (3GL) programs
Open standard input (read), standard output (write) and standard error (write) for embedded language (3GL) programs. SIeqinit opens the streams if they are not already opened. This routine is a NO-OP on UNIX. This routine must be called before any reference to any of the 3 standard FILE pointers (stdin, stdout, stderr), whether the reference is explicit or implicit. This routine may be called repeatedly with no ill effect.
Inputs:
| None |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS SIeqinit()
SIflush - flush stream
Flush the stream s. When a file is open for writing, any write operation may be buffered in SI. (This is an implementation choice, but the user has to assume that it may be buffered.) When an SIflush operation is issued, any buffers must be written to the System File System. Since the SI module does not guarantee consistency, however, this does not guarantee that they become part of the System permanent storage. No assumptions can be made as to when data written to an SI file is actually written to permanent System storage.
Inputs:
| s | file to be flushed. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| Any data buffered in the SI implementation's data structures is written to the System File System. |
Definition:
STATUS SIflush(s) FILE *s;
SIfopen - open named stream
Open the named file and return a FILE* in "desc".
Allowed modes are READ ("r"), WRITE ("w"), and APPEND ("a"). READ and WRITE open the file and positions the stream pointer at the beginning of the file. APPEND opens the file for writing and positions the stream pointer at the end of the file. If file does not exist and the mode is "w" or "a" then SIfopen will create the file. If the file does not exist and the mode is "r" then SIfopen will return error status and return NULL desc. Types are SI_TXT, SI_VAR, SI_BIN and SI_RACC. Length is the record length of the SI_BIN or SI_RACC file, or the maximum record length of a SI_TXT or SI_VAR file. The length for a SI_TXT file cannot exceed SI_MAX_TXT_REC.
SI_RACC files, SI_VAR files, and SI_BIN files are "binary" on systems which distinguish between opening a file "binary" vs. "text", i.e. without or with translation of CR/LF pairs.
SI_RACC files are files that allow SIfseek() calls to be made, to reposition the file pointer for read/write operations. These files may also be opened the "rw" mode, which indicates an updatable file.
For the "rw" mode, a write following a seek may be used to overwrite previous data in the file, or a read following a seek used to read previously written bytes. If an existing file is opened "rw", the file pointer is initially positioned at the beginning of the file, ready to overwrite the first bytes. Seeks should be done before switching between read/write operations on update mode files. Seeking works on SI_RACC files opened in all modes.
I/O to SI_RACC files must be done through the SIread()/SIwrite() or SIgetc()/SIputc() calls. SIfopen(), SIclose(), SIread(), SIwrite(), SIgetc(), SIputc(), SIfseek(), SIftell(), SIflush(), SIgetattr(), and SIisopen() are the only calls which should be used with this file type.
Note: SI implementations which support multiple file types must insure that SIfopen() stores the attributes "filetype" and "record length" in the FILE structure for use by SIgetattr(). Not all operating systems will support all file types. Appropriate mapping to file types supported by a particular operating system are performed by this routine, e.g. on UNIX type will always be SI_TXT and length will always be 0.
Inputs:
| loc | LOCATION containing name of file to open |
| mode | mode to open file with - READ, WRITE, APPEND |
| type | set to SI file type - SI_VAR, SI_BIN, SI_TXT, SI_RACC |
| length | set to record length. |
Outputs:
| desc | pointer to FILE structure to be used by subsequent SI calls |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| The file is opened. |
Definition:
STATUS SIfopen(loc, mode, type, length, desc) LOCATION *loc; char *mode; i4 type; i4 length; FILE **desc;
SIfprintf - formatted Print to a Stream File
This routine converts, formats, and outputs its 3rd through nth arguments under control of the format string provided in its second argument to the stream pointed to by its first argument.
The second argument is a character string that contains two types of objects: plain characters, which are simply copied to the output stream, and conversion specifications (also called "formats"), each of which causes conversion and printing of the next successive argument.
NOTE: If the format string contains a floating point format (one of f, e, g, n) then its corresponding argument must be followed by the character to be used as the decimal point in the output (e.g. SIfprintf(stream, "float = %f", 10.5, '.') ). Each conversion specification is introduced by the character %. Following the %, there may be:
An optional minus sign '-' which specifies left adjustment of the converted value in the indicated field; An optional digit string specifying a field width; if the converted value has fewer characters than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width; if the field width begins with a zero, zero-padding will be done instead of blank-padding;
An optional period '.' which serves to separate the field width from the next digit string; An optional digit string specifying a precision which specifies the number of digits to appear after the decimal point, for e-,f-, g-, and n-conversion, or the maximum number of characters to be printed from a string;
The character l specifying that a following d, o, x, X, or u corresponds to a long integer arg. A character which indicates the type of conversion to be applied.
A field width or precision may be '*' instead of a digit string. In this case an integer argument supplies the field width or precision, e.g.
SIprintf("%*s",20,"string");
The conversion characters and their meanings are:
| d,o,x | The integer arg is converted to decimal, octal, or hexadecimal notation respectively. |
| X | The integer arg is converted to uppercase hexadecimal notation. |
| f | The float or double arg is converted to decimal notation in the style '[-]ddd.ddd' where the number of d's after the decimal point is equal to the precision specification for the argument. If the precision is missing, 6 digits are given; if the precision is explicitly 0, no digits and no decimal point are printed. |
| e | The float or double arg is converted in the style '[-]d.ddde+d' where there is one digit before the decimal point and the number after is equal to the precision specification for the argument; when the precision is missing, 6 digits are produced. |
| g | The float or double arg is printed in style d, in style f, or in style e, whichever gives full precision in minimum space. |
| n | Like 'g', but right justified (left justified if a leading '-' is used) |
| c | The character argument is printed. |
| p | Arg is taken to be a PTR and printed in a machine specific representation, usually hex. |
| s | Arg is taken to be a string (character pointer) and characters from the string are printed until a null character or until the number of characters indicated by the precision specification is reached; however if the precision is 0 or missing all characters up to a null are printed. |
| u | The unsigned integer argument is converted to decimal and printed. |
| % | Print a '%'; no argument is converted. In no case does a non-existent or small field width cause truncation of a field; padding takes place only if the specified field width exceeds the actual width. |
Inputs:
| stream | File to which to output characters |
| fmt | The format string that controls output and conversion of the subsequent arguments (see above). |
| args | A variable number of arguments of all types that will be converted and output. |
Outputs:
| None |
Returns:
| None |
Definition:
VOID SIfprintf(stream, fmt, args...) FILE *stream; char *fmt; ... . args;
SIfseek - seek file position
UNIX style fseek - reposition open SI_RACC type file fp to requested offset, in bytes. Illegal for any other type of file.
The mode argument indicates where the position is to be measured from. Three values are permissible: SI_P_START, SI_P_END, and SI_P_CURRENT, indicating that offset is to be measured from the start of the file, the end of the file, or the current position in the file. SI_P_END refers to a the character position immediately AFTER the last character in the file.
Negative values of offset indicate backwards movement through the file from the indicated position. An error is returned, and the current file position unchanged if the requested offset would result in a negative position, or extend beyond the current end of file. Zero offsets are legal and very useful with SI_P_START and SI_P_END, indicating "rewind", and "seek to end" respectively. A write operation following the latter will effectively append to the file.
Inputs:
| fp | file which is to be repositioned |
| offset | number of bytes to be repositioned |
| mode | One of SI_P_START, SI_P_END, or SI_P_CURRENT |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| The 'file position' associated with the SI_RACC file is changed. |
Definition:
STATUS SIfseek(fp,offset,mode) FILE *fp; i4 offset; i4 mode;
SIftell - return current file position
Return current byte offset for next read/write operation on open SI_RACC type file fp. Illegal for any other type of file. Byte offset is returned in offset.
Inputs:
| fp | file whose current position is desired |
| offset | address of a variable to hold the current position |
Outputs:
| offset | the current file position is returned. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS SIftell(fp,offset) FILE *fp; i4 *offset;
SIgetattr - get file attributes
SIgetattr returns the filetype and record length of "stream", a file which must have been opened by SIfopen().
SIgetattr must insure that the type and length values returned are "reasonable" for its underlying OS.
NOTE: Some implementations will always return default values, e.g. on UNIX, where file type is meaningless, type will always be SI_TXT and length will be 0
Inputs:
| stream | Pointer to SI structure FILE. |
Outputs:
| type | set to SI file type - SI_VAR, SI_BIN, SI_TXT, SI_RACC |
| length | set to record length. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| Because SIgetattr() may be implemented as a macro on some systems care must be taken to avoid "well-known" macro side-effects. |
Definition:
STATUS SIgetattr(stream, type, length) FILE *stream; i4 *type; i4 *length;
SIgetc - get character from stream
Return the next character from the input stream. Returns EOF at end of file or upon read error. This may be implemented as a macro.
Note that this function returns a value of type "i4", not of type "char". If the function return value is not EOF, then the returned value may be safely cast to a "char".
Inputs:
| stream | file which is to be read |
Outputs:
| None |
Returns:
| The next character in the file or EOF on end-of-file or error. |
Definition:
i4 SIgetc(stream) FILE *stream;
SIgetfd - get an external description of a FILE pointer
This routine is obsolete.
SIgetfd is only used by CFE FEs that are configured to run as several processes. It is used (along with SIinitfp) to share the FE test files among the various processes. SIgetfd takes a FILE pointer and returns an external representation of the FILE pointer that will be used by SIinitf to rebuild the FILE pointer in the other process. If SIgetfd fails, then it returns NULL. SIgetfd is called by the parent process which passes the string returned to the child who calls SIinitfp.
On UNIX systems, the external representation is a file descriptor which is shared between the parent and the child. Since the test files remain open across process invocations on UNIX, this permits these routines to be simple to implement.
Inputs:
| f | file whose external description is wanted. |
Outputs:
| None |
Returns:
| The external description of the FILE is returned. |
Definition:
char * SIgetfd(f) FILE *f;
SIgetrec - Get next input record
Get the next record from stream, previously opened for reading. SIgetrec reads n-1 characters, or up to a a full record, whichever comes first, into buf. A full record is defined as a string of bytes terminated by a newline. The output string, buf, is null-terminated.
This routine is only valid for SI_TXT type files.
Inputs:
| n | max number of characters to read (including the null terminator to be placed in the output string) |
| stream | file from which the record is to be read |
| buf | address of a buffer of at least n bytes in size. |
Outputs:
| buf | the record is placed into the buffer and the buffer is null terminated. |
Returns:
| ENDFILE | end of the file was reached, or error reading the file. |
| OK | record read successfully. No other errors are returned. |
Definition:
STATUS SIgetrec(buf, n, stream) char *buf; i4 n; FILE *stream;
SIinitfp - rebuild a FILE pointer
This routine is obsolete.
SIinitfp is only used by CFE FEs that are configured to run as several processes. It is used (along with SIgetfd) to share the FE test files among the various processes. SIinitfp takes a string returned by SIgetfd in a parent process and builds a FILE descriptor that points to the file. After SIinitfp is called, the file described by the string is open and can be used in any SI calls. Reads/Writes will proceed from the point the parent process last read/wrote.
On UNIX systems, the external representation is a file descriptor which is shared between the parent and the child. Since the test files remain open across process invocations on UNIX, this permits these routines to be simple to implement.
Inputs:
| s | external description of the file (from SIgetfd) |
Outputs:
| f | set to point to the FILE structure which results. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS SIinitfp(s, f) char *s; FILE **f;
SIisopen - is stream open?
Test whether this FILE* corresponds to an open stream. Not guaranteed to work, just tests whether pointer and referenced values look reasonable.
Inputs:
| streamptr | file to be tested to see if it is open |
Outputs:
| None |
Returns:
| FALSE | if the file does not appear to be open. |
Definition:
bool SIisopen(streamptr) FILE *streamptr;
SIopen - open named stream
NOTE: This routine is obsolescent. Use SIfopen instead. SIopen will be removed from the interface in a subsequent release.
Open the named file and return a FILE * in "desc". Allowed modes are READ ("r"), WRITE ("w") and APPEND ("a"). READ and WRITE opens the file and positions the stream pointer at the beginning of the file. APPEND opens the file for writing and positions the stream pointer at the end of the file. If file does not exist and the mode is "w" or "a" then SIopen will create the file. If the file not exist and the mode is "r" then SIopen will return an error status and place NULL in "desc".
SIopen() simply duplicates SIfopen() and is obsoleted with INGRES 6.0.
Inputs:
| loc | LOCATION containing name of file to open |
| mode | mode to open file with - "r" for READ, "w" for WRITE, or "a" for APPEND |
Outputs:
| desc | pointer to FILE structure to be used by subsequent SI calls |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS SIopen(loc, mode, desc) LOCATION *loc; char *mode; FILE **desc;
SIprintf - formatted Print to Standard Output Stream
Similar to 'SIfprintf()' except no stream argument is required since the output goes to the standard output stream by default.
Inputs:
| fmt | the format string that controls output and conversion of the subsequent arguments (See 'SIfprintf()'). |
| args | A variable number of arguments of all types that will be converted and output. |
Outputs:
| None |
Returns:
| None |
Definition:
VOID SIprintf(fmt, args...) char *fmt; ... . args;
SIputc - Put char on a stream
Appends the character c to the named output stream.
It returns the character written. Unlike many other compatibility routines SIputc does not return STATUS. It returns the character written, or EOF upon error. This may be implemented as a macro.
Inputs:
| c | character to be appended to the stream |
| stream | file to which the character is to be appended. |
Outputs:
| None |
Returns:
| The character written, or EOF upon error. |
Definition:
i4 SIputc(c, stream) char c; FILE *stream;
SIputrec - Write output record
Copy the Null terminated string in buf to stream, which has been previously opened for writing. The Null byte is not copied. On systems with formatted files, this call adds a record to the file. On UNIX, the bytes are just appended to the stream.
This routine is only valid for SI_TXT type files.
Inputs:
| buf | null terminated string to be written |
| stream | file to be written to. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS SIputrec(buf, stream) char *buf; FILE *stream;
SIread - read data from stream
Read numofbytes bytes from the stream f (already opened for read) into space starting at *pointer. The maximum number of bytes to read is specified in numofbytes. Return number of bytes read in actual_count. A return of ENDFILE sets actual_count to 0.
Inputs:
| stream | file to be read from | numofbytes | maximum number of bytes to read. |
Outputs:
| pointer | this buffer is filled with data from the file. |
| actual_count | the number of bytes read is filled in. |
Returns:
| ENDFILE | end of the file was reached |
| OK | data read successfully. No other values are returned. |
Side Effects:
| The 'file position' associated with the SI_RACC file is changed. It is advanced by *actual_count bytes. |
Definition:
STATUS SIread(stream, numofbytes, actual_count, pointer) FILE *stream; i4 numofbytes; i4 *actual_count; char *pointer;
SIterminal - is stream a terminal?
This routine returns FALSE if the opened stream is not known to be a terminal.
Inputs:
| s | file which is to be checked. |
Outputs:
| None |
Returns:
| FALSE | if file s is not a terminal. |
Definition:
bool SIterminal(s) FILE *s;
SIungetc - push character back into input stream
SIungetc pushes the character c back on an input stream. That character will be returned by the next SIgetc call on that stream. Ungetc returns c. One character of pushback is guaranteed provided something has been read from the stream and the stream is actually buffered.
Inputs:
| c | character to be pushed back |
| stream | file onto which the character is to be pushed. |
Outputs:
| None |
Returns:
| The character which was pushed back. No errors are reported. |
Definition:
i4 SIungetc(c, stream) char c; FILE *stream;
SIwrite - write data to stream
Write an item of size typesize to stream stream (already opened for write) starting from *pointer. count is useless but is being kept for historical purposes.
Inputs:
| typesize | size of the item to be written |
| pointer | address of the item to be written |
| stream | file to which the item is to be written |
| count | useless variable kept for historical purposes. |
Outputs:
| None |
Returns:
| OK | - if operation succeeded, otherwise system specific error status. |
Side Effects:
| The 'file position' associated with the SI_RACC file is changed. It is advanced by typesize bytes. |
Definition:
STATUS SIwrite(typesize, pointer, count, stream) i4 typesize; char *pointer; i4 *count; FILE *stream;
|
Ingres Compatability Library |
