NAME

       qio - quick I/O part of InterNetNews library

SYNOPSIS

       #include "qio.h"

       QIOSTATE *
       QIOopen(name, size)
           char             *name;
           int              size;

       QIOSTATE *
       QIOfdopen(fd, size)
           int              fd;
           int              size;

       void
       QIOclose(qp)
           QIOSTATE         *qp;

       char *
       QIOread(qp)
           QIOSTATE         *qp;

       int
       QIOlength(qp)
           QIOSTATE         *qp;

       int
       QIOtoolong(qp)
           QIOSTATE         *qp;

       int
       QIOerror(qp)
           QIOSTATE         *qp;

       int
       QIOtell(qp)
           QIOSTATE         *qp;

       int
       QIOrewind(qp)
           QIOSTATE         *qp;

       int
       QIOfileno(qp)
           QIOSTATE         *qp;

DESCRIPTION

       The  routines  described  in  this  manual  page  are  part  of  the InterNetNews library,
       libinn(3).  They are used to provide quick read access  to  files.   The  letters  ``QIO''
       stand for Quick I/O.

       QIOopen  opens the file name for reading.  It uses a buffer of size bytes, which must also
       be larger then the longest expected line.  The header file defines the constant QIO_BUFFER
       as  a  reasonable  default.   If  size is zero, then QIOopen will call stat(2) and use the
       returned block size; if that fails it will use QIO_BUFFER.  It returns NULL on error, or a
       pointer  to  a  handle  to  be  used in other calls.  QIOfdopen performs the same function
       except that fd refers to an already-open descriptor.

       QIOclose closes the open file and releases any resources used by it.

       QIOread returns a pointer to the next line in the file.   The  trailing  newline  will  be
       replaced with a \0.  If EOF is reached, an error occurs, or if the line is longer than the
       buffer, QIOread returns NULL.

       After a successful call to QIOread, QIOlength will return the length of the current line.

       The functions QIOtoolong and  QIOerror  can  be  called  after  QIOread  returns  NULL  to
       determine  if there was an error, or if the line was too long.  If QIOtoolong returns non-
       zero, then the current line did not fit in the buffer, and the next call to  QIOread  will
       try  read  the  rest  of the line.  Long lines can only be discarded.  If QIOerror returns
       non-zero, then a serious I/O error occurred.

       QIOtell returns the lseek(2) offset at which the next line will start.

       QIOrewind sets the read pointer back to the beginning of the file.

       QIOfileno returns the descriptor of the open file.

       QIOlength, QIOtoolong, QIOerror, QIOtell, and QIOfileno are implemented as macro's defined
       in the header file.

EXAMPLE

              QIOSTATE             *h;
              long                 offset;
              char                 *p;

              h = QIOopen("/etc/motd", QIO_BUFFER);
              for (offset = QIOtell(h); (p = QIOread(h)) != NULL; offset = QIOtell(h))
                  printf("At %ld, %s\n", offset, p);
              if (QIOerror(h)) {
                  perror("Read error");
                  exit(1);
              }
              QIOclose(h);

HISTORY

       Written  by  Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  This is revision 1.7, dated
       1993/01/29.

                                                                                           QIO(3)