1qio(3) InterNetNews Documentation qio(3)
2
6 qio - Quick I/O routines for reading files
7
9 #include <inn/qio.h>
10 QIOSTATE *QIOopen(const char *name);
12 QIOSTATE *QIOfdopen(int> I<fd);
14 void QIOclose(QIOSTATE *qp);
16 char *QIOread(QIOSTATE *qp);
18 int QIOfileno(QIOSTATE *qp);
20 size_t QIOlength(QIOSTATE *qp);
22 int QIOrewind(QIOSTATE *qp);
24 off_t QIOtell(QIOSTATE *qp);
26 bool QIOerror(QIOSTATE *qp);
28 bool QIOtoolong(QIOSTATE *qp);
30
32 The routines described in this manual page are part of libinn(3). They
33 are used to provide quick read access to files; the QIO routines use
34 buffering adapted to the block size of the device, similar to stdio,
35 but with a more convenient syntax for reading newline-terminated lines.
36 QIO is short for "Quick I/O" (a bit of a misnomer, as QIO provides
37 read-only access to files only).
38 The QIOSTATE structure returned by QIOopen and QIOfdopen is the analog
40 to stdio's FILE structure and should be treated as a black box by all
41 users of these routines. Only the above API should be used.
42 QIOopen opens the given file for reading with a buffer size of 32KiB.
44 Returns a pointer to use for subsequent calls, or NULL on error.
45 QIOfdopen performs the same operation except on an already-open file
46 descriptor (fd must designate a file open for reading).
47 QIOclose closes the open file and releases any resources used by the
49 QIOSTATE structure. The QIOSTATE pointer should not be used again
50 after it has been passed to this function.
51 QIOread reads the next newline-terminated line in the file and returns
53 a pointer to it, with the trailing newline replaced by nul. The
54 returned pointer is a pointer into a buffer in the QIOSTATE object and
55 therefore will remain valid until QIOclose is called on that object.
56 If EOF is reached, an error occurs, or if the line is longer than the
57 buffer size (32KiB), NULL is returned instead. To distinguish between
58 the error cases, use QIOerror and QIOtoolong.
59 QIOfileno returns the descriptor of the open file.
61 QIOlength returns the length in bytes of the last line returned by
63 QIOread. Its return value is only defined after a successful call to
64 QIOread.
65 QIOrewind sets the read pointer back to the beginning of the file and
67 reads the first block of the file in anticipation of future reads. It
68 returns 0 if successful and -1 on error.
69 QIOtell returns the current value of the read pointer (the lseek(2)
71 offset at which the next line will start).
72 QIOerror returns true if there was an error in the last call to
74 QIOread, false otherwise. QIOtoolong returns true if there was an
75 error and the error was that the line was too long. If QIOread returns
76 NULL, these functions should be called to determine what happened. If
77 QIOread returned NULL and QIOerror is false, EOF was reached. Note
78 that if QIOtoolong returns true, the next call to QIOread will try to
79 read the remainder of the line and will likely return a partial line;
80 users of this library should in general treat long lines as fatal
81 errors.
82
84 This block of code opens /etc/motd and reads it a line at a time,
85 printing out each line preceded by its offset in the file.
86 QIOSTATE *qp;
88 off_t offset;
89 char *p;
90 qp = QIOopen("/etc/motd");
92 if (qp == NULL) {
93 perror("Open error");
94 exit(1);
95 }
96 for (p = QIOread(qp); p != NULL; p = QIOread(qp))
97 printf("%ld: %s\n", (unsigned long) QIOtell(qp), p);
98 if (QIOerror(qp)) {
99 perror("Read error");
100 exit(1);
101 }
102 QIOclose(qp);
103
105 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Updated by
106 Russ Allbery <eagle@eyrie.org>.
107 $Id: qio.pod 10457 2020-12-19 06:10:49Z eagle $
109INN 2.6.4 2021-01-04 qio(3)