4.4BSD/usr/src/contrib/news/inn/doc/qio.3

.\" $Revision: 1.7 $
.TH QIO 3
.SH NAME
qio \- quick I/O part of InterNetNews library
.SH SYNOPSIS
.nf
.ta \w'    unsigned long    'u
.B
#include "qio.h"

.B "QIOSTATE *"
.B "QIOopen(name, size)"
.B "    char	*name;"
.B "    int	size;"

.B "QIOSTATE *"
.B "QIOfdopen(fd, size)"
.B "    int	fd;"
.B "    int	size;"

.B "void"
.B "QIOclose(qp)"
.B "    QIOSTATE	*qp;"

.B "char *"
.B "QIOread(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOlength(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOtoolong(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOerror(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOtell(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOrewind(qp)"
.B "    QIOSTATE	*qp;"

.B "int"
.B "QIOfileno(qp)"
.B "    QIOSTATE	*qp;"
.SH DESCRIPTION
The routines described in this manual page are part of the InterNetNews
library,
.IR libinn (3).
They are used to provide quick read access to files.
The letters ``QIO'' stand for
.IR Q uick
.IR I/O .
.PP
.I QIOopen
opens the file
.I name
for reading.
It uses a buffer of
.I 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
.I size
is zero, then
.\" =()<.if '@<HAVE_ST_BLKSIZE>@'DO' \{\>()=
.if 'DO'DO' \{\
.I QIOopen
will call
.IR 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.
.I QIOfdopen
performs the same function except that
.I fd
refers to an already-open descriptor.
.PP
.I QIOclose
closes the open file and releases any resources used by it.
.PP
.I QIOread
returns a pointer to the next line in the file.
The trailing newline will be replaced with a \e0.
If EOF is reached, an error occurs, or if the line is longer than the
buffer,
.I QIOread
returns NULL.
.PP
After a successful call to
.IR QIOread ,
.I QIOlength
will return the length of the current line.
.PP
The functions
.I QIOtoolong
and
.I QIOerror
can be called after
.I QIOread
returns NULL to determine if there was an error, or if the line was
too long.
If
.I QIOtoolong
returns non-zero, then the current line did not fit in the buffer, and the
next call to
.I QIOread
will try read the rest of the line.
Long lines can only be discarded.
If
.I QIOerror
returns non-zero, then a serious I/O error occurred.
.PP
.I QIOtell
returns the
.IR lseek (2)
offset at which the next line will start.
.PP
.I QIOrewind
sets the read pointer back to the beginning of the file.
.PP
.I QIOfileno
returns the descriptor of the open file.
.PP
.IR QIOlength ,
.IR QIOtoolong ,
.IR QIOerror ,
.IR QIOtell ,
and
.I QIOfileno
are implemented as macro's defined in the header file.
.SH EXAMPLE
.RS
.nf
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\en", offset, p);
if (QIOerror(h)) {
    perror("Read error");
    exit(1);
}
QIOclose(h);
.fi
.RE
.SH HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
.de R$
This is revision \\$3, dated \\$4.
..
.R$ $Id: qio.3,v 1.7 1993/01/29 16:43:14 rsalz Exp $