    Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY
Copyright: (C) 1994 William Pierpoint
  Version: 1.10
     Date: March 28, 1994



1.0 RECORD INPUT/OUTPUT <recio.h>


1.1 Introduction

The header <recio.h> 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 <stdio.h> 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 <stdio.h> 
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 <stdio.h> 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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <errno.h>, 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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <errno.h>, 
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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <errno.h>

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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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 <recio.h>
     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
