bionic (3) qio.3.gz

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)