Commit | Line | Data |
---|---|---|
5b62e993 MW |
1 | .TH substdio 3 |
2 | .SH NAME | |
3 | substdio \- the Sub-Standard Input/Output Library | |
4 | .SH SYNTAX | |
5 | .B #include <substdio.h> | |
6 | ||
7 | void \fBsubstdio_fdbuf\fP(&\fIs\fR,\fIop\fR,\fIfd\fR,\fIbuf\fR,\fIlen\fR); | |
8 | ||
9 | int \fBsubstdio_fileno\fP(&\fIs\fR); | |
10 | ||
11 | substdio \fIs\fR; | |
12 | .br | |
13 | int (*\fIop\fR)(); | |
14 | .br | |
15 | int \fIfd\fR; | |
16 | .br | |
17 | char *\fIbuf\fR; | |
18 | .br | |
19 | int \fIlen\fR; | |
20 | .SH DESCRIPTION | |
21 | .B substdio | |
22 | is the Sub-Standard I/O Library. | |
23 | .B substdio | |
24 | contains only a few of the features of stdio; | |
25 | it is a fast, lightweight, low-level library, | |
26 | suitable for use as a component of higher-level I/O libraries. | |
27 | ||
28 | The point of | |
29 | .B substdio | |
30 | is to provide buffered I/O. | |
31 | The basic object in | |
32 | .B substdio | |
33 | is the | |
34 | .B substdio | |
35 | structure; | |
36 | a | |
37 | .B substdio | |
38 | variable stores | |
39 | an operation, | |
40 | a descriptor, | |
41 | and | |
42 | a pointer into a buffer of some nonzero length. | |
43 | The | |
44 | .B substdio | |
45 | operations read data from the buffer, | |
46 | filling the buffer as necessary using the operation on the descriptor, | |
47 | or write data to the buffer, | |
48 | flushing the buffer as necessary using the operation on the descriptor. | |
49 | Input and output operations cannot be mixed. | |
50 | ||
51 | .B substdio_fdbuf | |
52 | initializes a | |
53 | .B substdio | |
54 | variable. | |
55 | The operation is | |
56 | .IR op . | |
57 | The descriptor is | |
58 | .IR fd . | |
59 | The buffer is | |
60 | .IR buf , | |
61 | an array of | |
62 | .I len | |
63 | chars. | |
64 | ||
65 | .I op | |
66 | will be called as | |
67 | .I op\fR(\fIfd\fR,\fIx\fR,\fIn\fR). | |
68 | Here | |
69 | .I x | |
70 | is a pointer to an array of characters of length | |
71 | .IR n ; | |
72 | .I op | |
73 | must read some characters from | |
74 | .I fd | |
75 | to that array, or write some characters to | |
76 | .I fd | |
77 | from that array. | |
78 | The return value from | |
79 | .I op | |
80 | must be the number of characters read or written. | |
81 | 0 characters read means end of input; | |
82 | 0 characters written means that the write operation | |
83 | should be tried again immediately. | |
84 | On error, | |
85 | .I op | |
86 | must return -1, | |
87 | setting | |
88 | .B errno | |
89 | appropriately, without reading or writing anything. | |
90 | Most errors are returned directly to the | |
91 | .B substdio | |
92 | caller, but an error of | |
93 | .B error_intr | |
94 | means that the operation should be tried again immediately. | |
95 | ||
96 | There is a | |
97 | .B SUBSTDIO_FDBUF | |
98 | macro that can be used to statically initialize a | |
99 | .B substdio | |
100 | variable: | |
101 | ||
102 | .EX | |
103 | substdio s = SUBSTDIO_FDBUF(op,fd,buf,len); | |
104 | .EE | |
105 | ||
106 | .B substdio_fileno | |
107 | returns the | |
108 | descriptor for an initialized | |
109 | .B substdio | |
110 | variable. | |
111 | .SH "SEE ALSO" | |
112 | substdio_in(3), | |
113 | substdio_out(3), | |
114 | substdio_copy(3), | |
115 | error(3) |