Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "qio 3"
way too many mistakes in technical documents.
The \s-1QIOSTATE\s0 structure returned by QIOopen and QIOfdopen is the analog to stdio's \s-1FILE\s0 structure and should be treated as a black box by all users of these routines. Only the above \s-1API\s0 should be used.
\fBQIOopen opens the given file for reading with a buffer size of 32KiB. Returns a pointer to use for subsequent calls, or \s-1NULL\s0 on error. \fBQIOfdopen performs the same operation except on an already-open file descriptor (fd must designate a file open for reading).
\fBQIOclose closes the open file and releases any resources used by the \s-1QIOSTATE\s0 structure. The \s-1QIOSTATE\s0 pointer should not be used again after it has been passed to this function.
\fBQIOread 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 \s-1QIOSTATE\s0 object and therefore will remain valid until QIOclose is called on that object. If \s-1EOF\s0 is reached, an error occurs, or if the line is longer than the buffer size (32KiB), \s-1NULL\s0 is returned instead. To distinguish between the error cases, use QIOerror and QIOtoolong.
\fBQIOfileno returns the descriptor of the open file.
\fBQIOlength returns the length in bytes of the last line returned by \fBQIOread. Its return value is only defined after a successful call to \fBQIOread.
\fBQIOrewind 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.
\fBQIOtell returns the current value of the read pointer (the lseek\|(2) offset at which the next line will start).
\fBQIOerror returns true if there was an error in the last call to \fBQIOread, false otherwise. QIOtoolong returns true if there was an error and the error was that the line was too long. If QIOread returns \s-1NULL,\s0 these functions should be called to determine what happened. If \fBQIOread returned \s-1NULL\s0 and QIOerror is false, \s-1EOF\s0 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.
.Vb 3 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\en", (unsigned long) QIOtell(qp), p); if (QIOerror(qp)) { perror("Read error"); exit(1); } QIOclose(qp); .Ve
\f(CW$Id: qio.pod 10457 2020-12-19 06:10:49Z eagle $