QIO(3)

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  lt;rsalz@uunet.uu.net  for  InterNet-
       News.  This is revision 1.7, dated 1993/01/29.