The routines described in this manual page are part of libinn(3). They
are used to provide quick read access to files; the QIO routines use
buffering adapted to the block size of the device, similar to stdio, but
with a more convenient syntax for reading newline-terminated lines. QIO
is short for Quick I/O (a bit of a misnomer, as QIO provides read-only
access to files only).
The QIOSTATE structure returned by QIOopen and QIOfdopen is the
analog to stdios FILE structure and should be treated as a black box by
all users of these routines. Only the above API should be used.
QIOopen opens the given file for reading. For regular files, if your
system provides that information and the size is reasonable, QIO will use
the block size of the underlying file system as its buffer size;
otherwise, it will default to a buffer of 8 KB. Returns a pointer to use
for subsequent calls, or NULL on error. QIOfdopen performs the same
operation except on an already-open file descriptor (fd must designate
a file open for reading).
QIOclose closes the open file and releases any resources used by the
QIOSTATE structure. The QIOSTATE pointer should not be used again after
it has been passed to this function.
QIOread reads the next newline-terminated line in the file and returns
a pointer to it, with the trailing newline replaced by nul. The returned
pointer is a pointer into a buffer in the QIOSTATE object and therefore
will remain valid until QIOclose is called on that object. If EOF is
reached, an error occurs, or if the line is longer than the buffer size,
NULL is returned instead. To distinguish between the error cases, use
QIOerror and QIOtoolong.
QIOfileno returns the descriptor of the open file.
QIOlength returns the length in bytes of the last line returned by
QIOread. Its return value is only defined after a successful call to
QIOrewind sets the read pointer back to the beginning of the file and
reads the first block of the file in anticipation of future reads. It
returns 0 if successful and -1 on error.
QIOtell returns the current value of the read pointer (the lseek(2)
offset at which the next line will start).
QIOerror returns true if there was an error in the last call to
QIOread, false otherwise. QIOtoolong returns true if there was an
error and the error was that the line was too long. If QIOread returns
NULL, these functions should be called to determine what happened. If
QIOread returned NULL and QIOerror is false, EOF was reached. Note
that if QIOtoolong returns true, the next call to QIOread will try
to read the remainder of the line and will likely return a partial line;
users of this library should in general treat long lines as fatal errors.