Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY Copyright: (C) 1994 William Pierpoint Version: 1.10 Date: March 28, 1994 1.0 RECORD INPUT/OUTPUT 1.1 Introduction The header declares one type, several macros, and many functions for performing line oriented input. Note: This specification only covers input; output might be developed at a later date if there is a perceived need. Generally the functions available in are adequate for output. 1.1.1 Record Streams Input is mapped into logical data record streams. A record stream is an ordered sequence of characters composed into records, each record consisting of zero or more characters plus a terminating record delimiter character. The terminating record delimiter for a file is the newline character. Each record consists of zero or more fields. The record may be broken into fields in two different ways: (1) character delimited and (2) column delimited. For character delimited fields, each field consists of zero or more characters plus a terminating field delimiter character or, for the last field in the record, the record delimiter character. For column delimited fields, each field consists of one or more characters delimited by a single column position for fields consisting of one character, or by beginning and ending column positions for fields consisting of one or more characters. Three types of fields are defined: (1) character, (2) text, and (3) numeric. A character field consists of a single character. A text field consists of a sequence of zero or more characters delimited at each end by an optional text delimiter character. A numeric field consists of a sequence of one or more characters from the set of valid characters for the number type (integral or floating point) and radix. 1.1.2 Type The type is REC which is an object type capable of recording all information needed to control a record stream used for line oriented input, including its file pointer, pointers to its associated record and field buffers, field and text delimiting characters, an error indicator that records whether an error has occurred, and an end-of-file indicator that records whether the end of the file has been reached. 1.1.3 Macros The macros are RECBUFSIZ FLDBUFSIZ which expand to integral constant expressions, which are the initial sizes of the record buffer and the field buffer; RECFLDCH RECTXTCH which expand to integral constant expressions, which are the default values of the characters used to separate the fields and delimit text in a record and whose default value shall correspond to the value of the space character; ROPEN_MAX which expands to an integral constant expression that is the maximum number of files that can be open simultaneously; RECIN which expands to an integral constant expression that is the context number for the recin record stream that gets it's input from the standard input stream stdin. 1.1.4 Expressions The one expression is recin which is of type "pointer to REC" that points to the REC object associated with the FILE object stdin (standard input stream). The recin record stream is always open and is included in the count of ROPEN_MAX. 1.2 Record Access Functions 1.2.1 The rclose Function Synopsis #include int rclose(REC *rp); Description The rclose function causes the record stream pointed to by rp and the associated file to be closed. Any unread data is discarded. The record stream is disassociated from the file. If associated buffers were automatically allocated, they are deallocated. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rclose function returns EOF. Returns The rclose function returns zero if the record stream is successfully closed, or EOF if any errors were detected. 1.2.2 The rcloseall Function Synopsis #include int rcloseall(void); Description The rcloseall function causes all the open record streams, and all the files associated with the open record streams, to be closed. Any unread data is discarded. Each record stream is disassociated from its file. If associated buffers were automatically allocated, they are deallocated. If an error occurs, the rcloseall function returns EOF. Returns The rcloseall function returns the number of record streams successfully closed, or EOF if any errors were detected. 1.2.3 The ropen Function Synopsis #include REC *ropen(const char *filename, const char *mode); Description The ropen function opens the file whose name is the string pointed to by filename, and associates a record stream with it. The argument mode points to a string containing: "r" - open text file for input Note: This specification does not cover output modes at this time. When successfully opened, the error and end-of-file indicators for the record stream are clear. If an error occurs, errno is set to one of the error reporting macros as defined in , the callback error function is called (except when the file associated with filename is not able to be opened), and a null pointer is returned. Returns The ropen function returns a pointer to the object controlling the record stream. If the open operation fails, ropen returns a null pointer. 1.2.4 The rsetfldsiz Function Synopsis #include int rsetfldsiz(REC *rp, size_t fldsize); Description The rsetfldsiz function reallocates the field buffer associated with the record stream pointed to by rp to the new size of fldsize. The rsetfldsiz function may be used only after the record stream pointed to by rp has been opened and before any data is read into the record buffer. Data is read into the record buffer by the function rgetrec, or by calling a function that either skips a field or gets data from a field. If rsetfldsiz is not used, the initial size of the field buffer is set by the value of the macro FLDBUFSIZ. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsetfldsiz function returns EOF. Returns The rsetfldsiz function returns zero if the field buffer is successfully reallocated, or EOF if any errors were detected. 1.2.5 The rsetrecsiz Function Synopsis #include int rsetrecsiz(REC *rp, size_t recsize); Description The rsetrecsiz function reallocates the record buffer associated with the record stream pointed to by rp to the new size of recsize. The rsetrecsiz function may be used only after the record stream pointed to by rp has been opened and before any data is read into the record buffer. Data is read into the record buffer by the function rgetrec, or by calling a function that either skips a field or gets data from a field. If rsetrecsiz is not used, the initial size of the field buffer is set by the value of the macro RECBUFSIZ. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsetrecsiz function returns EOF. Returns The rsetrecsiz function returns zero if the record buffer is successfully reallocated, or EOF if any errors were detected. 1.3 Character Delimited Field Input Functions 1.3.1 The rbgeti Function Synopsis #include int rbgeti(REC *rp, int base); Description The rbgeti function reads a field consisting of one integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rbgeti function returns zero. Returns The rbgeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rbgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgeti returns zero. 1.3.2 The rbgetl Function Synopsis #include long rbgetl(REC *rp, int base); Description The rbgetl function reads a field consisting of one integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rbgetl function returns zero (0L). Returns The rbgetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rbgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetl returns zero (0L). 1.3.3 The rbgetui Function Synopsis #include unsigned int rbgetui(REC *rp, int base); Description The rbgetui function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rbgetui function returns zero. Returns The rbgetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rbgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetui returns zero. 1.3.4 The rbgetul Function Synopsis #include unsigned long rbgetul(REC *rp, int base); Description The rbgetul function reads a field consisting of one non-negative integral number represented by the radix determined by the value of base from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rbgetul function returns zero (0L). Returns The rbgetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rbgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rbgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rbgetul returns zero (0L). 1.3.5 The rgetc Function Synopsis #include int rgetc(REC *rp); Description The rgetc function reads a field consisting of one non-white space character from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetc function returns EOF. Returns The rgetc function returns a character from a single non-white space character field in the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, or if there is more than or less than one non-white character in the field, the error indicator for the record stream is set, and rgetc returns EOF. If the record stream is at end-of-file (end-of-file indicator set), rgetc returns EOF. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetc returns EOF. 1.3.6 The rgetd Function Synopsis #include double rgetd(REC *rp); Description The rgetd function reads a field consisting of one floating point number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetd function returns zero (0.0). Returns The rgetd function returns a double precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetd returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rgetd returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetd returns zero (0.0). 1.3.7 The rgetf Function Synopsis #include float rgetf(REC *rp); Description The rgetf function reads a field consisting of one floating point number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetf function returns zero (0.0). Returns The rgetf function returns a single precision floating point number from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetf returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rgetf returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetf returns zero (0.0). 1.3.8 The rgeti Function Synopsis #include int rgeti(REC *rp); Description The rgeti function reads a field consisting of one integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgeti function returns zero. Returns The rgeti function returns a signed integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgeti returns zero. 1.3.9 The rgetl Function Synopsis #include long rgetl(REC *rp); Description The rgetl function reads a field consisting of one integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetl function returns zero (0L). Returns The rgetl function returns a signed long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetl returns zero (0L). 1.3.10 The rgets Function Synopsis #include char *rgets(REC *rp); Description The rgets function reads a field consisting of one text string from the input record stream pointed to by rp. Any leading white space before the text delimiter and any trailing white space after the text delimiter in the field is ignored. The text delimiters are not returned as part of the string. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgets function returns a null pointer. Returns The rgets function returns a pointer to a character array from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rgets returns a null pointer. If the record stream is at end-of-file (end-of-file indicator set), rgets returns a null pointer. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgets returns a null pointer. 1.3.11 The rgetui Function Synopsis #include unsigned int rgetui(REC *rp); Description The rgetui function reads a field consisting of one non-negative integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetui function returns zero. Returns The rgetui function returns an unsigned integer from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetui returns zero. 1.3.12 The rgetul Function Synopsis #include unsigned long rgetul(REC *rp); Description The rgetul function reads a field consisting of one non-negative integral number from the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetul function returns zero (0L). Returns The rgetul function returns an unsigned long from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rgetul returns zero (0L). 1.3.13 The rsetfldch Function Synopsis #include int rsetfldch(REC *rp, int ch); Description The rsetfldch function sets the field delimiter to the character ch for the record stream pointed to by rp. If the character ch is the space character ' ', then the field is delimited by any white-space, and multiple contiguous white space characters are treated as a single delimiter. If the character ch is other than the space character, then multiple contiguous field delimiters are treated as a series of empty fields. If rsetfldch is not called, the field delimiter is set by the value of the macro RECFLDCH. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsetfldch function returns EOF. Returns The rsetfldch function returns zero if the field delimiter character was successfully set for the record stream, or EOF if any errors were detected. 1.3.14 The rsettxtch Function Synopsis #include int rsettxtch(REC *rp, int ch); Description The rsettxtch function sets the text delimiter to the character ch for the record stream pointed to by rp. If rsettxtch is not called, the text delimiter is set by the value of the macro RECTXTCH. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsettxtch function returns EOF. Returns The rsettxtch function returns zero if the text delimiter character was successfully set for the record stream, or EOF if any errors were detected. 1.3.15 The rskipfld Function Synopsis #include int rskipfld(REC *rp); Description The rskipfld function skips to the next field for the record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rskipfld function returns EOF. Returns The rskipfld function returns one if the field was successfully skipped, zero if the field could not be skipped (end of record), or EOF if any errors were detected. 1.3.16 The rskipnfld Function Synopsis #include int rskipnfld(REC *rp, size_t num); Description The rskipnfld function skips over num number of fields for the record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rskipnfld function returns EOF. Returns The rskipfld function returns the actual number of fields skipped, or EOF if any errors were detected. 1.4 Column Delimited Field Input Functions 1.4.1 The rcbgeti Function Synopsis #include int rcbgeti(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgeti function gets one integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgeti function returns zero. Returns The rcbgeti function returns a signed integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcbgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgeti returns zero. 1.4.2 The rcbgetl Function Synopsis #include long rcbgetl(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetl function gets one integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetl function returns zero (0L). Returns The rcbgetl function returns a signed long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcbgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetl returns zero (0L). 1.4.3 The rcbgetui Function Synopsis #include unsigned int rcbgetui(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetui function gets one non-negative integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetui function returns zero. Returns The rcbgetui function returns an unsigned integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcbgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetui returns zero. 1.4.4 The rcbgetul Function Synopsis #include unsigned long rcbgetul(REC *rp, size_t begcol, size_t endcol, int base); Description The rcbgetul function gets one non-negative integral number represented by the radix determined by the value of base and contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. Base may be zero or in the range of 2 to 36 inclusive. If the value of base is zero, the expected form of the integral number is described by section 3.1.3.2 of ANSI X3.159-1989. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetul function returns zero (0L). Returns The rcbgetul function returns an unsigned long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcbgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcbgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcbgetul returns zero (0L). 1.4.5 The rcgetc Function Synopsis #include int rcgetc(REC *rp, size_t col); Description The rcgetc function obtains from column position col the unsigned char converted to an int from the input record stream pointed to by rp. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rcgetc function returns EOF. Returns The rcgetc function returns a character from column position col from the input record stream pointed to by rp. If an attempt is made to read beyond the end-of-record, the error indicator for the record stream is set, and rcgetc returns EOF. If the record stream is at end-of-file (end-of-file indicator set), rcgetc returns EOF. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetc returns EOF. 1.4.6 The rcgetd Function Synopsis #include double rcgetd(REC *rp, size_t begcol, size_t endcol); Description The rcgetd function gets one floating point number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rcgetd function returns zero (0.0). Returns The rcgetd function returns a double precision floating point number from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetd returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rcgetd returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetd returns zero (0.0). 1.4.7 The rcgetf Function Synopsis #include float rcgetf(REC *rp, size_t begcol, size_t endcol); Description The rcgetd function gets one floating point number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rcgetf function returns zero (0.0). Returns The rcgetf function returns a single precision floating point number from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetf returns zero (0.0). If the record stream is at end-of-file (end-of-file indicator set), rcgetf returns zero (0.0). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetf returns zero (0.0). 1.4.8 The rcgeti Function Synopsis #include int rcgeti(REC *rp, size_t begcol, size_t endcol); Description The rcgeti function gets one integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgeti function returns zero. Returns The rcgeti function returns a signed integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgeti returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcgeti returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgeti returns zero. 1.4.9 The rcgetl Function Synopsis #include long rcgetl(REC *rp, size_t begcol, size_t endcol); Description The rcgetl function gets one integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetl function returns zero (0L). Returns The rcgetl function returns a signed long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetl returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcgetl returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetl returns zero (0L). 1.4.10 The rcgets Function Synopsis #include char *rcgets(REC *rp, size_t begcol, size_t endcol); Description The rcgets function gets a string contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. The rcgets function does not remove any leading or trailing white space, nor does it remove any text delimiter characters. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgets function returns a null pointer. Returns The rcgets function returns a pointer to a character array from the input record stream pointed to by rp. If begcol is beyond the end-of-record, the error indicator for the record stream is set, and rcgets returns a null pointer. If the record stream is at end-of-file (end-of-file indicator set), rcgets returns a null pointer. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgets returns a null pointer. 1.4.11 The rcgetui Function Synopsis #include unsigned int rcgetui(REC *rp, size_t begcol, size_t endcol); Description The rcgetui function gets one non-negative integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetui function returns zero. Returns The rcgetui function returns an unsigned integer from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetui returns zero. If the record stream is at end-of-file (end-of-file indicator set), rcgetui returns zero. If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetui returns zero. 1.4.12 The rcgetul Function Synopsis #include unsigned long rcgetul(REC *rp, size_t begcol, size_t endcol); Description The rcgetul function gets one non-negative integral number contained inclusively from column begcol to column endcol for the input record stream pointed to by rp. Any leading or trailing white space in the field is ignored. If an error occurs, the error indicator for the record stream is set, errno is set to one of the error reporting macros as defined in , the callback error function is called (if registered), and the rgetul function returns zero (0L). Returns The rcgetul function returns an unsigned long from the input record stream pointed to by rp. If begcol is beyond the end-of-record, if the field is empty, or if there is an illegal character in the field, the error indicator for the record stream is set, and rcgetul returns zero (0L). If the record stream is at end-of-file (end-of-file indicator set), rcgetul returns zero (0L). If a previous error has occurred on the record stream that has not been cleared (error indicator set), rcgetul returns zero (0L). 1.5 Current Position Functions 1.5.1 The rbegcolno Function Synopsis #include int rbegcolno(REC *rp); Description The rbegcolno function gets the current setting of the first column number in the record for the record stream pointed to by rp. Returns The rbegcolno function returns 0 if column numbering starts with zero or 1 if column numbering starts with one. 1.5.2 The rcolno Function Synopsis #include size_t rcolno(REC *rp); Description The rcolno function gets the current column number of the current record for the record stream pointed to by rp. Returns The rcolno function returns the current column number of the current record for the record stream pointed to by rp. The rcolno function returns zero prior to the reading of the first record. 1.5.3 The rflds Function Synopsis #include char *rflds(REC *rp); Description The rflds function gets a pointer to the field buffer associated with the record stream pointed to by rp. The last field read from the current record is stored in the field buffer. The field is terminated by a null character. Returns The rflds function returns a pointer to the field buffer associated with the record stream pointed to by rp. 1.5.4 The rfldno Function Synopsis #include size_t rfldno(REC *rp); Description The rfldno function gets the number of fields that have been read from the current record for the record stream pointed to by rp. Returns The rfldno function returns the number of fields that have been read from the current record for the record stream pointed to by rp. 1.5.5 The rnames Function Synopsis #include char *rnames(REC *rp); Description The rnames function gets a pointer to the name of the file associated with the record stream pointed to by rp. Returns The rnames function returns a pointer to the name of the file associated with the record stream pointed to by rp. 1.5.6 The rgetrec Function Synopsis #include char *rgetrec(REC *rp); Description The rgetrec function gets the next record from the record stream pointed to by rp. If the next record was successfully read, the rgetrec function increments the record number, clears the field and columns numbers to zero, and returns a pointer to the record buffer. If there are no more records, the record number is not incremented and the field and column numbers are cleared to zero. The first record is at one (1L), the first field at zero, and the first column is at zero. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rgetrec function returns a null pointer. If the end-of-file is reached, the end-of-file indicator for the record stream is set and the rgetrec function returns a null pointer. Returns The rgetrec function returns a pointer to the record buffer if the next record was successfully read. If there are no more records, the end-of-file indicator is set and rgetrec returns a null pointer. If an error occurred, the error indicator is set and rgetrec returns a null pointer. 1.5.7 The rrecs Function Synopsis #include char *rrecs(REC *rp); Description The rrecs function gets a pointer to the record buffer associated with the record stream pointed to by rp. The current record is stored in the record buffer. The record is terminated by a null character. Returns The rrecs function returns a pointer to the record buffer associated with the record stream pointed to by rp. 1.5.8 The rrecno Function Synopsis #include long rrecno(REC *rp); Description The rrecno function gets the number of records that have been read from the record stream pointed to by rp. Returns The rrecno function returns the number of records that have been read from the record stream pointed to by rp. 1.5.9 The rsetbegcolno Function Synopsis #include int rsetbegcolno(REC *rp, int colno); Description The rsetbegcolno function sets the first column number colno for the record stream pointed to by rp. Column numbering can start at either 0 or 1. If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsetbegcolno function returns EOF. Returns The rsetbegcolno function returns zero if the first column number was successfully set, or EOF if any errors were detected. 1.5.10 The rsetfldstr Function Synopsis #include int rsetfldstr(REC *rp, char *s); Description The rsetfldstr function copies the string s into the field buffer of the record stream pointed to by rp. Any existing string in the field buffer is overwritten. The field buffer size is increased, if necessary, to accommodate the string. A side effect of using the rsetfldstr function is that the error and end-of-file indicators for the record stream are cleared (provided rsetfldstr does not create an error). If an error occurs, the error indicator for the record stream is set, the callback error function is called (if registered), and the rsetfldstr function returns EOF. Returns The rsetfldstr function returns zero if the string is successfully copied into the field buffer, or EOF if any errors were detected. 1.6 Error-Handling Functions 1.6.1 The errno Macro Synopsis #include Description The errno macro "expands to a modifiable lvalue that has type int, the value of which is set to a positive error number by several library functions." -Section 4.1.3 of ANSI X3.159-1989. 1.6.2 The rclearerr Function Synopsis #include void rclearerr(REC *rp); Description The rclearerr function clears the end-of-file and error indicators for the record stream pointed to by rp. Returns The rclearerr function returns no value. 1.6.3 The rcxtno Function Synopsis #include int rcxtno(REC *rp); Description The rcxtno function gets the context number from the record stream pointed to by rp. Context numbers can be assigned to a record stream using the rsetcxtno function. A zero context number indicates that the context number has not been assigned. The recin stream returns the macro value of RECIN. Returns The rcxtno function returns the context number from the record stream pointed to by rp. 1.6.4 The rerror Function Synopsis #include unsigned int rerror(REC *rp); Description The rerror function tests the error indicator for the record stream pointed to by rp. Returns The rerror function returns nonzero if and only if the error indicator is set for the record stream pointed to by rp. 1.6.5 The reof Function Synopsis #include unsigned int reof(REC *rp); Description The reof function tests the end-of-file indicator for the record stream pointed to by rp. Returns The reof function returns nonzero if and only if the end-of-file indicator is set for the record stream pointed to by rp. 1.6.6 The risvalid Function Synopsis #include int risvalid(REC *rp); Description The risvalid function tests if rp is a valid pointer to a record stream. Returns The risvalid function returns a nonzero value if and only if rp is a valid pointer to an open record stream. 1.6.7 The rsetcxtno Function Synopsis #include int rsetcxtno(REC *rp, int cxtno); Description The rsetcxtno function sets the context number cxtno on the record stream pointed to by rp. Assigning a context number allows a file format to be more easily identified in the callback error function. Negative context numbers are reserved; a zero context number indicates an that the context has not been assigned. A macro value RECIN is preassigned to the recin stream. If an error occurs, the rsetcxtno function returns EOF. Returns The rsetcxtno returns zero if the context number was successfully assigned to the record stream, or EOF if any errors were detected. 1.6.8 The rseterr Function Synopsis #include int rseterr(REC *rp, int errnum); Description The rseterr function sets the global error number errno to the value of errnum and, if errnum is positive, sets the error indicator on the record stream pointed to by rp. The callback error function is called (if registered). If the record stream error indicator is already set on entry to the rseterr function, the rseterr function only sets errno. Returns The rseterr function returns the error number. If the callback error function corrects the error and clears the error number, the function returns zero. 1.6.9 The rseterrfn Function Synopsis #include void rseterrfn(void(*rerrfn)(REC *rp)); Description The rseterrfn function registers the callback error function rerrfn for the record stream pointed to by rp. Returns The rseterrfn function returns no value. The callback error function rerrfn returns no value. 2.0 PORTABILITY ISSUES The first six characters of this function are common to another function. Ref 3.1.2 of ANSI X3.159-1989. (1.2.1, 1.2.2, 1.2.4, 1.3.3, 1.3.4, 1.3.13, 1.4.1-1.4.4, 1.4.11, 1.4.12, 1.5.10, 1.6.8, 1.6.9) 3.0 INDEX errno macro ............ 1.6.1 FLDBUFSIZ macro ........ 1.1.3, 1.2.4 rbegcolno function ..... 1.5.1 rbgeti function ........ 1.3.1 rbgetl function ........ 1.3.2 rbgetui function ....... 1.3.3 rbgetul function ....... 1.3.4 rcbgeti function ....... 1.4.1 rcbgetl function ....... 1.4.2 rcbgetui function ...... 1.4.3 rcbgetul function ...... 1.4.4 rcgetc function ........ 1.4.5 rcgetd function ........ 1.4.6 rcgetf function ........ 1.4.7 rcgeti function ........ 1.4.8 rcgetl function ........ 1.4.9 rcgets function ........ 1.4.10 rcgetui function ....... 1.4.11 rcgetul function ....... 1.4.12 rclearerr function ..... 1.6.2 rclose function ........ 1.2.1 rcloseall function ..... 1.2.2 rcolno function ........ 1.5.2 rcxtno function ........ 1.6.3 REC object ............. 1.1.2 recin expression ....... 1.1.4 RECBUFSIZ macro ........ 1.1.3, 1.2.5 RECFLDCH macro ......... 1.1.3, 1.3.13 RECTXTCH macro ......... 1.1.3, 1.3.14 reof function .......... 1.6.5 rerror function ........ 1.6.4 rflds function ......... 1.5.3 rfldno function ........ 1.5.4 rgetc function ......... 1.3.5 rgetd function ......... 1.3.6 rgetf function ......... 1.3.7 rgeti function ......... 1.3.8 rgetl function ......... 1.3.9 rgetrec function ....... 1.5.6 rgets function ......... 1.3.10 rgetui function ........ 1.3.11 rgetul function ........ 1.3.12 risvalid function ...... 1.6.6 rnames function ........ 1.5.5 ropen function ........ 1.2.3 ROPEN_MAX macro ........ 1.1.3 rrecs function ......... 1.5.7 rrecno function ........ 1.5.8 rsetbegcolno function .. 1.5.9 rsetcxtno function ..... 1.6.7 rseterr function ....... 1.6.8 rseterrfn function ..... 1.6.9 rsetfldch function ..... 1.3.13 rsetfldsiz function .... 1.2.4 rsetfldstr function .... 1.5.10 rsetrecsiz function .... 1.2.5 rsettxtch function ..... 1.3.14 rskipfld function ..... 1.3.15 rskipnfld function ..... 1.3.16