Commit | Line | Data |
---|---|---|
5b62e993 MW |
1 | .TH substdio_in 3 |
2 | .SH NAME | |
3 | substdio_in \- substdio input routines | |
4 | .SH SYNTAX | |
5 | .B #include <substdio.h> | |
6 | ||
7 | int \fBsubstdio_get\fP(&\fIs\fR,\fIto\fR,\fIlen\fR); | |
8 | ||
9 | int \fBsubstdio_bget\fP(&\fIs\fR,\fIto\fR,\fIlen\fR); | |
10 | ||
11 | int \fBsubstdio_feed\fP(&\fIs\fR); | |
12 | ||
13 | char *\fBsubstdio_peek\fP(&\fIs\fR); | |
14 | ||
15 | void \fBsubstdio_seek\fP(&\fIs\fR,\fIlen\fR); | |
16 | ||
17 | substdio \fIs\fR; | |
18 | .br | |
19 | char *\fIto\fR; | |
20 | .br | |
21 | int \fIlen\fR; | |
22 | .SH DESCRIPTION | |
23 | .B substdio_get | |
24 | reads at most | |
25 | .I len | |
26 | characters from | |
27 | .I s | |
28 | into the character array | |
29 | .IR to . | |
30 | It returns the number of characters read, | |
31 | 0 for end of file, | |
32 | or -1 for error, | |
33 | setting | |
34 | .B errno | |
35 | appropriately. | |
36 | ||
37 | .B substdio_bget | |
38 | has the same function as | |
39 | .BR substdio_get . | |
40 | The difference is what happens when there is no buffered data and | |
41 | .I len | |
42 | exceeds the buffer size: | |
43 | .B substdio_get | |
44 | tries to read | |
45 | .I len | |
46 | characters, whereas | |
47 | .B substdio_bget | |
48 | tries to read one buffer of characters. | |
49 | In some cases | |
50 | .B substdio_bget | |
51 | will be more efficient than | |
52 | .BR substdio_get . | |
53 | ||
54 | .B substdio_feed | |
55 | makes sure that there is buffered data, | |
56 | so that the next | |
57 | .B substdio_get | |
58 | or | |
59 | .B substdio_bget | |
60 | will succeed. | |
61 | If the buffer is empty, | |
62 | .B substdio_feed | |
63 | tries to fill it; | |
64 | it returns 0 for end of file, -1 for error, | |
65 | or the number of buffered characters on success. | |
66 | If the buffer already had data, | |
67 | .B substdio_feed | |
68 | leaves it alone and returns the number of buffered characters. | |
69 | ||
70 | .B substdio_peek | |
71 | returns a pointer to the buffered data. | |
72 | ||
73 | .B substdio_seek | |
74 | throws away | |
75 | .I len | |
76 | buffered characters, | |
77 | as if they had been read. | |
78 | .I len | |
79 | must be at least 0 and at most the amount of buffered data. | |
80 | ||
81 | The | |
82 | .B substdio_PEEK | |
83 | and | |
84 | .B substdio_SEEK | |
85 | macros behave the same way as | |
86 | .B substdio_peek | |
87 | and | |
88 | .B substdio_seek | |
89 | but may evaluate their arguments several times. | |
90 | ||
91 | The point of | |
92 | .B substdio_peek | |
93 | and | |
94 | .B substdio_seek | |
95 | is to read data without unnecessary copies. | |
96 | Sample code: | |
97 | ||
98 | .EX | |
99 | for (;;) { | |
100 | .br | |
101 | n = substdio_feed(s); | |
102 | .br | |
103 | if (n <= 0) return n; | |
104 | .br | |
105 | x = substdio_PEEK(s); | |
106 | .br | |
107 | handle(x,n); | |
108 | .br | |
109 | substdio_SEEK(s,n); | |
110 | .br | |
111 | } | |
112 | .EE | |
113 | ||
114 | The | |
115 | .B SUBSTDIO_INSIZE | |
116 | macro is defined as a reasonably large input buffer size for | |
117 | .BR substdio_fdbuf . | |
118 | .SH "INTERNALS" | |
119 | When a | |
120 | .B substdio | |
121 | variable | |
122 | .I s | |
123 | is used for input, | |
124 | there is free buffer space from | |
125 | .I s\fB.x | |
126 | to | |
127 | .I s\fB.x\fR + | |
128 | .I s\fB.n\fR; | |
129 | data is buffered from | |
130 | .I s\fB.x\fR + | |
131 | .I s\fB.n | |
132 | to | |
133 | .I s\fB.x\fR + | |
134 | .I s\fB.n\fR + | |
135 | .I s\fB.p\fR; | |
136 | the total buffer length is | |
137 | .I s\fB.n\fR + | |
138 | .I s\fB.p\fR. | |
139 | .SH "SEE ALSO" | |
140 | substdio(3) |