SYNOPSIS

       #include <inn/qio.h>

       QIOSTATE *QIOopen(const char *name);

       QIOSTATE *QIOfdopen(int fd);

       void QIOclose(QIOSTATE *qp);

       char *QIOread(QIOSTATE *qp);

       int QIOfileno(QIOSTATE *qp);

       size_t QIOlength(QIOSTATE *qp);

       int QIOrewind(QIOSTATE *qp);

       off_t QIOtell(QIOSTATE *qp);

       bool QIOerror(QIOSTATE *qp);

       bool QIOtoolong(QIOSTATE *qp);

DESCRIPTION

       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 stdio's 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 des-
       ignate 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
       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.

EXAMPLES

       This block of code opens /etc/motd and reads it a line at a time,
       printing out each line preceeded by its offset in the file.

           QIOSTATE *qp;
           off_t offset;
           char *p;

           qp = QIOopen("/etc/motd");
           if (qp == NULL) {
               perror("Open error");
               exit(1);
           }
           for (p = QIOread(qp); p != NULL; p = QIOread(qp))
               printf("%ld: %s\n", (unsigned long) QIOtell(qp), p);
           if (QIOerror(qp)) {
               perror("Read error");
               exit(1);
           }
           QIOclose(qp);

HISTORY

       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Updated by
       Russ Allbery <rra@stanford.edu>.

       $Id: qio.3 5912 2002-12-03 05:31:11Z vinocur $



INN 2.4.0                         2002-12-03                            qio(3)