qio(3) [redhat man page]
QIO(3) Library Functions Manual QIO(3) NAME
qio - quick I/O part of InterNetNews library SYNOPSIS
#include "qio.h" QIOSTATE * QIOopen(name) char *name; QIOSTATE * QIOfdopen(fd) int fd; 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 libinn(3). They are used to provide quick read access to files. All routines are not available for token. The letters ``QIO'' stand for Quick I/O. QIOopen opens the file name for reading. If <HAVE_ST_BLKSIZE in include/config.h> is defined, QIOopen will call stat(2) and use the returned block size; if that fails (or <HAVE_ST_BLKSIZE in include/config.h> is not defined) 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 . 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 ", 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.6.2.1, dated 2000/08/17. QIO(3)
Check Out this Related Man Page
qio(3) InterNetNews Documentation qio(3) NAME
qio - Quick I/O routines for reading files SYNOPSIS
#include <inn/qio.h> QIOSTATE *QIOopen(const char *name); QIOSTATE *QIOfdopen(int fd); void QIOclose(QIOSTATE *qp); char *QIOread(QIOSTATE *qp); int QIOfileno(QIOSTATE *qp); size_t QIOlength(QIOSTATE *qp); int QIOrewind(QIOSTATE *qp); off_t QIOtell(QIOSTATE *qp); bool QIOerror(QIOSTATE *qp); bool QIOtoolong(QIOSTATE *qp); DESCRIPTION
The routines described in this manual page are part of libinn(3). They are used to provide quick read access to files; the QIO routines use buffering adapted to the block size of the device, similar to stdio, but with a more convenient syntax for reading newline-terminated lines. QIO is short for "Quick I/O" (a bit of a misnomer, as QIO provides read-only access to files only). The QIOSTATE structure returned by QIOopen and QIOfdopen is the analog to stdio's FILE structure and should be treated as a black box by all users of these routines. Only the above API should be used. QIOopen opens the given file for reading. For regular files, if your system provides that information and the size is reasonable, QIO will use the block size of the underlying file system as its buffer size; otherwise, it will default to a buffer of 8 KB. Returns a pointer to use for subsequent calls, or NULL on error. QIOfdopen performs the same operation except on an already-open file descriptor (fd must designate a file open for reading). QIOclose closes the open file and releases any resources used by the QIOSTATE structure. The QIOSTATE pointer should not be used again after it has been passed to this function. QIOread reads the next newline-terminated line in the file and returns a pointer to it, with the trailing newline replaced by nul. The returned pointer is a pointer into a buffer in the QIOSTATE object and therefore will remain valid until QIOclose is called on that object. If EOF is reached, an error occurs, or if the line is longer than the buffer size, NULL is returned instead. To distinguish between the error cases, use QIOerror and QIOtoolong. QIOfileno returns the descriptor of the open file. QIOlength returns the length in bytes of the last line returned by QIOread. Its return value is only defined after a successful call to QIOread. QIOrewind sets the read pointer back to the beginning of the file and reads the first block of the file in anticipation of future reads. It returns 0 if successful and -1 on error. QIOtell returns the current value of the read pointer (the lseek(2) offset at which the next line will start). QIOerror returns true if there was an error in the last call to QIOread, false otherwise. QIOtoolong returns true if there was an error and the error was that the line was too long. If QIOread returns NULL, these functions should be called to determine what happened. If QIOread returned NULL and QIOerror is false, EOF was reached. Note that if QIOtoolong returns true, the next call to QIOread will try to read the remainder of the line and will likely return a partial line; users of this library should in general treat long lines as fatal errors. EXAMPLES
This block of code opens /etc/motd and reads it a line at a time, printing out each line preceded by its offset in the file. QIOSTATE *qp; off_t offset; char *p; qp = QIOopen("/etc/motd"); if (qp == NULL) { perror("Open error"); exit(1); } for (p = QIOread(qp); p != NULL; p = QIOread(qp)) printf("%ld: %s ", (unsigned long) QIOtell(qp), p); if (QIOerror(qp)) { perror("Read error"); exit(1); } QIOclose(qp); HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Updated by Russ Allbery <rra@stanford.edu>. $Id: qio.pod 8517 2009-06-17 17:49:36Z iulius $ INN 2.5.2 2009-08-16 qio(3)