1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
132 .TH qio 3 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
134 qio \- Quick I/O routines for reading files
136 .IX Header "SYNOPSIS"
137 \&\fB#include <inn/qio.h>\fR
139 \&\fB\s-1QIOSTATE\s0 *QIOopen(const char *\fR\fIname\fR\fB);\fR
141 \&\fB\s-1QIOSTATE\s0 *QIOfdopen(int\fR \fIfd\fR\fB);\fR
143 \&\fBvoid QIOclose(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
145 \&\fBchar *QIOread(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
147 \&\fBint QIOfileno(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
149 \&\fBsize_t QIOlength(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
151 \&\fBint QIOrewind(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
153 \&\fBoff_t QIOtell(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
155 \&\fBbool QIOerror(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
157 \&\fBbool QIOtoolong(\s-1QIOSTATE\s0 *\fR\fIqp\fR\fB);\fR
159 .IX Header "DESCRIPTION"
160 The routines described in this manual page are part of \fIlibinn\fR\|(3). They
161 are used to provide quick read access to files; the \s-1QIO\s0 routines use
162 buffering adapted to the block size of the device, similar to stdio, but
163 with a more convenient syntax for reading newline-terminated lines. \s-1QIO\s0
164 is short for \*(L"Quick I/O\*(R" (a bit of a misnomer, as \s-1QIO\s0 provides read-only
165 access to files only).
167 The \s-1QIOSTATE\s0 structure returned by \fBQIOopen\fR and \fBQIOfdopen\fR is the
168 analog to stdio's \s-1FILE\s0 structure and should be treated as a black box by
169 all users of these routines. Only the above \s-1API\s0 should be used.
171 \&\fBQIOopen\fR opens the given file for reading. For regular files, if your
172 system provides that information and the size is reasonable, \s-1QIO\s0 will use
173 the block size of the underlying file system as its buffer size;
174 otherwise, it will default to a buffer of 8 \s-1KB\s0. Returns a pointer to use
175 for subsequent calls, or \s-1NULL\s0 on error. \fBQIOfdopen\fR performs the same
176 operation except on an already-open file descriptor (\fIfd\fR must designate
177 a file open for reading).
179 \&\fBQIOclose\fR closes the open file and releases any resources used by the
180 \&\s-1QIOSTATE\s0 structure. The \s-1QIOSTATE\s0 pointer should not be used again after
181 it has been passed to this function.
183 \&\fBQIOread\fR reads the next newline-terminated line in the file and returns
184 a pointer to it, with the trailing newline replaced by nul. The returned
185 pointer is a pointer into a buffer in the \s-1QIOSTATE\s0 object and therefore
186 will remain valid until \fBQIOclose\fR is called on that object. If \s-1EOF\s0 is
187 reached, an error occurs, or if the line is longer than the buffer size,
188 \&\s-1NULL\s0 is returned instead. To distinguish between the error cases, use
189 \&\fBQIOerror\fR and \fBQIOtoolong\fR.
191 \&\fBQIOfileno\fR returns the descriptor of the open file.
193 \&\fBQIOlength\fR returns the length in bytes of the last line returned by
194 \&\fBQIOread\fR. Its return value is only defined after a successful call to
197 \&\fBQIOrewind\fR sets the read pointer back to the beginning of the file and
198 reads the first block of the file in anticipation of future reads. It
199 returns 0 if successful and \-1 on error.
201 \&\fBQIOtell\fR returns the current value of the read pointer (the \fIlseek\fR\|(2)
202 offset at which the next line will start).
204 \&\fBQIOerror\fR returns true if there was an error in the last call to
205 \&\fBQIOread\fR, false otherwise. \fBQIOtoolong\fR returns true if there was an
206 error and the error was that the line was too long. If \fBQIOread\fR returns
207 \&\s-1NULL\s0, these functions should be called to determine what happened. If
208 \&\fBQIOread\fR returned \s-1NULL\s0 and \fBQIOerror\fR is false, \s-1EOF\s0 was reached. Note
209 that if \fBQIOtoolong\fR returns true, the next call to \fBQIOread\fR will try
210 to read the remainder of the line and will likely return a partial line;
211 users of this library should in general treat long lines as fatal errors.
213 .IX Header "EXAMPLES"
214 This block of code opens \fI/etc/motd\fR and reads it a line at a time,
215 printing out each line preceeded by its offset in the file.
224 \& qp = QIOopen("/etc/motd");
226 \& perror("Open error");
229 \& for (p = QIOread(qp); p != NULL; p = QIOread(qp))
230 \& printf("%ld: %s\en", (unsigned long) QIOtell(qp), p);
231 \& if (QIOerror(qp)) {
232 \& perror("Read error");
239 Written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews. Updated by
240 Russ Allbery <rra@stanford.edu>.
242 $Id: qio.3 7880 2008-06-16 20:37:13Z iulius $