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.