3 78e51a8c 2005-01-14 devnull Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered \- buffered input/output
4 78e51a8c 2005-01-14 devnull .SH SYNOPSIS
5 78e51a8c 2005-01-14 devnull .ta \w'\fLBiobuf* 'u
6 78e51a8c 2005-01-14 devnull .B #include <utf.h>
8 78e51a8c 2005-01-14 devnull .B #include <fmt.h>
10 78e51a8c 2005-01-14 devnull .B #include <bio.h>
13 78e51a8c 2005-01-14 devnull Biobuf* Bopen(char *file, int mode)
16 78e51a8c 2005-01-14 devnull Biobuf* Bfdopen(int fd, int mode)
19 78e51a8c 2005-01-14 devnull int Binit(Biobuf *bp, int fd, int mode)
22 78e51a8c 2005-01-14 devnull int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)
25 78e51a8c 2005-01-14 devnull int Bterm(Biobufhdr *bp)
28 78e51a8c 2005-01-14 devnull int Bprint(Biobufhdr *bp, char *format, ...)
31 78e51a8c 2005-01-14 devnull int Bvprint(Biobufhdr *bp, char *format, va_list arglist);
34 78e51a8c 2005-01-14 devnull void* Brdline(Biobufhdr *bp, int delim)
37 78e51a8c 2005-01-14 devnull char* Brdstr(Biobufhdr *bp, int delim, int nulldelim)
40 78e51a8c 2005-01-14 devnull int Blinelen(Biobufhdr *bp)
43 78e51a8c 2005-01-14 devnull vlong Boffset(Biobufhdr *bp)
46 78e51a8c 2005-01-14 devnull int Bfildes(Biobufhdr *bp)
49 78e51a8c 2005-01-14 devnull int Bgetc(Biobufhdr *bp)
52 78e51a8c 2005-01-14 devnull long Bgetrune(Biobufhdr *bp)
55 78e51a8c 2005-01-14 devnull int Bgetd(Biobufhdr *bp, double *d)
58 78e51a8c 2005-01-14 devnull int Bungetc(Biobufhdr *bp)
61 78e51a8c 2005-01-14 devnull int Bungetrune(Biobufhdr *bp)
64 78e51a8c 2005-01-14 devnull vlong Bseek(Biobufhdr *bp, vlong n, int type)
67 78e51a8c 2005-01-14 devnull int Bputc(Biobufhdr *bp, int c)
70 78e51a8c 2005-01-14 devnull int Bputrune(Biobufhdr *bp, long c)
73 78e51a8c 2005-01-14 devnull long Bread(Biobufhdr *bp, void *addr, long nbytes)
76 78e51a8c 2005-01-14 devnull long Bwrite(Biobufhdr *bp, void *addr, long nbytes)
79 78e51a8c 2005-01-14 devnull int Bflush(Biobufhdr *bp)
82 78e51a8c 2005-01-14 devnull int Bbuffered(Biobufhdr *bp)
84 78e51a8c 2005-01-14 devnull .SH DESCRIPTION
85 78e51a8c 2005-01-14 devnull These routines implement fast buffered I/O.
86 78e51a8c 2005-01-14 devnull I/O on different file descriptors is independent.
92 78e51a8c 2005-01-14 devnull .B O_RDONLY
93 78e51a8c 2005-01-14 devnull or creates for mode
94 78e51a8c 2005-01-14 devnull .BR O_WRONLY .
96 78e51a8c 2005-01-14 devnull .IR malloc (3)
97 78e51a8c 2005-01-14 devnull to allocate a buffer.
99 78e51a8c 2005-01-14 devnull .I Bfdopen
100 78e51a8c 2005-01-14 devnull allocates a buffer for the already-open file descriptor
102 78e51a8c 2005-01-14 devnull for mode
103 78e51a8c 2005-01-14 devnull .B O_RDONLY
105 78e51a8c 2005-01-14 devnull .BR O_WRONLY .
106 78e51a8c 2005-01-14 devnull It calls
107 78e51a8c 2005-01-14 devnull .IR malloc (3)
108 78e51a8c 2005-01-14 devnull to allocate a buffer.
110 78e51a8c 2005-01-14 devnull .I Binit
111 78e51a8c 2005-01-14 devnull initializes a standard size buffer, type
112 78e51a8c 2005-01-14 devnull .IR Biobuf ,
113 78e51a8c 2005-01-14 devnull with the open file descriptor passed in
114 78e51a8c 2005-01-14 devnull by the user.
115 78e51a8c 2005-01-14 devnull .I Binits
116 78e51a8c 2005-01-14 devnull initializes a non-standard size buffer, type
117 78e51a8c 2005-01-14 devnull .IR Biobufhdr ,
118 78e51a8c 2005-01-14 devnull with the open file descriptor,
119 78e51a8c 2005-01-14 devnull buffer area, and buffer size passed in
120 78e51a8c 2005-01-14 devnull by the user.
121 78e51a8c 2005-01-14 devnull .I Biobuf
123 78e51a8c 2005-01-14 devnull .I Biobufhdr
124 78e51a8c 2005-01-14 devnull are related by the declaration:
127 78e51a8c 2005-01-14 devnull typedef struct Biobuf Biobuf;
128 78e51a8c 2005-01-14 devnull struct Biobuf
130 78e51a8c 2005-01-14 devnull Biobufhdr;
131 78e51a8c 2005-01-14 devnull uchar b[Bungetsize+Bsize];
135 78e51a8c 2005-01-14 devnull Arguments
136 78e51a8c 2005-01-14 devnull of types pointer to Biobuf and pointer to Biobufhdr
137 78e51a8c 2005-01-14 devnull can be used interchangeably in the following routines.
139 78e51a8c 2005-01-14 devnull .IR Bopen ,
140 78e51a8c 2005-01-14 devnull .IR Binit ,
142 78e51a8c 2005-01-14 devnull .I Binits
143 78e51a8c 2005-01-14 devnull should be called before any of the
144 78e51a8c 2005-01-14 devnull other routines on that buffer.
145 78e51a8c 2005-01-14 devnull .I Bfildes
146 78e51a8c 2005-01-14 devnull returns the integer file descriptor of the associated open file.
148 78e51a8c 2005-01-14 devnull .I Bterm
149 78e51a8c 2005-01-14 devnull flushes the buffer for
150 78e51a8c 2005-01-14 devnull .IR bp .
151 78e51a8c 2005-01-14 devnull If the buffer was allocated by
152 78e51a8c 2005-01-14 devnull .IR Bopen ,
153 78e51a8c 2005-01-14 devnull the buffer is
154 78e51a8c 2005-01-14 devnull .I freed
155 78e51a8c 2005-01-14 devnull and the file is closed.
157 78e51a8c 2005-01-14 devnull .I Brdline
158 78e51a8c 2005-01-14 devnull reads a string from the file associated with
160 78e51a8c 2005-01-14 devnull up to and including the first
161 78e51a8c 2005-01-14 devnull .I delim
162 78e51a8c 2005-01-14 devnull character.
163 78e51a8c 2005-01-14 devnull The delimiter character at the end of the line is
164 78e51a8c 2005-01-14 devnull not altered.
165 78e51a8c 2005-01-14 devnull .I Brdline
166 78e51a8c 2005-01-14 devnull returns a pointer to the start of the line or
168 78e51a8c 2005-01-14 devnull on end-of-file or read error.
169 78e51a8c 2005-01-14 devnull .I Blinelen
170 78e51a8c 2005-01-14 devnull returns the length (including the delimiter)
171 78e51a8c 2005-01-14 devnull of the most recent string returned by
172 78e51a8c 2005-01-14 devnull .IR Brdline .
174 78e51a8c 2005-01-14 devnull .I Brdstr
175 78e51a8c 2005-01-14 devnull returns a
176 78e51a8c 2005-01-14 devnull .IR malloc (3)-allocated
177 78e51a8c 2005-01-14 devnull buffer containing the next line of input delimited by
178 78e51a8c 2005-01-14 devnull .IR delim ,
179 78e51a8c 2005-01-14 devnull terminated by a NUL (0) byte.
181 78e51a8c 2005-01-14 devnull .IR Brdline ,
182 78e51a8c 2005-01-14 devnull which returns when its buffer is full even if no delimiter has been found,
183 78e51a8c 2005-01-14 devnull .I Brdstr
184 78e51a8c 2005-01-14 devnull will return an arbitrarily long line in a single call.
186 78e51a8c 2005-01-14 devnull .I nulldelim
187 78e51a8c 2005-01-14 devnull is set, the terminal delimiter will be overwritten with a NUL.
188 78e51a8c 2005-01-14 devnull After a successful call to
189 78e51a8c 2005-01-14 devnull .IR Brdstr ,
190 78e51a8c 2005-01-14 devnull the return value of
191 78e51a8c 2005-01-14 devnull .I Blinelen
192 78e51a8c 2005-01-14 devnull will be the length of the returned buffer, excluding the NUL.
194 78e51a8c 2005-01-14 devnull .I Bgetc
195 78e51a8c 2005-01-14 devnull returns the next character from
196 78e51a8c 2005-01-14 devnull .IR bp ,
197 78e51a8c 2005-01-14 devnull or a negative value
198 78e51a8c 2005-01-14 devnull at end of file.
199 78e51a8c 2005-01-14 devnull .I Bungetc
200 78e51a8c 2005-01-14 devnull may be called immediately after
201 78e51a8c 2005-01-14 devnull .I Bgetc
202 78e51a8c 2005-01-14 devnull to allow the same character to be reread.
204 78e51a8c 2005-01-14 devnull .I Bgetrune
206 78e51a8c 2005-01-14 devnull .I Bgetc
207 78e51a8c 2005-01-14 devnull to read the bytes of the next
209 78e51a8c 2005-01-14 devnull sequence in the input stream and returns the value of the rune
210 78e51a8c 2005-01-14 devnull represented by the sequence.
211 78e51a8c 2005-01-14 devnull It returns a negative value
212 78e51a8c 2005-01-14 devnull at end of file.
213 78e51a8c 2005-01-14 devnull .I Bungetrune
214 78e51a8c 2005-01-14 devnull may be called immediately after
215 78e51a8c 2005-01-14 devnull .I Bgetrune
216 78e51a8c 2005-01-14 devnull to allow the same
218 78e51a8c 2005-01-14 devnull sequence to be reread as either bytes or a rune.
219 78e51a8c 2005-01-14 devnull .I Bungetc
221 78e51a8c 2005-01-14 devnull .I Bungetrune
222 78e51a8c 2005-01-14 devnull may back up a maximum of five bytes.
224 78e51a8c 2005-01-14 devnull .I Bgetd
226 78e51a8c 2005-01-14 devnull .I fmtcharstod
228 78e51a8c 2005-01-14 devnull .IR fmtstrtod (3))
230 78e51a8c 2005-01-14 devnull .I Bgetc
231 78e51a8c 2005-01-14 devnull to read the formatted
232 78e51a8c 2005-01-14 devnull floating-point number in the input stream,
233 78e51a8c 2005-01-14 devnull skipping initial blanks and tabs.
234 78e51a8c 2005-01-14 devnull The value is stored in
237 78e51a8c 2005-01-14 devnull .I Bread
239 78e51a8c 2005-01-14 devnull .I nbytes
240 78e51a8c 2005-01-14 devnull of data from
242 78e51a8c 2005-01-14 devnull into memory starting at
243 78e51a8c 2005-01-14 devnull .IR addr .
244 78e51a8c 2005-01-14 devnull The number of bytes read is returned on success
245 78e51a8c 2005-01-14 devnull and a negative value is returned if a read error occurred.
247 78e51a8c 2005-01-14 devnull .I Bseek
249 78e51a8c 2005-01-14 devnull .IR lseek (2)
251 78e51a8c 2005-01-14 devnull .IR bp .
252 78e51a8c 2005-01-14 devnull It returns the new file offset.
253 78e51a8c 2005-01-14 devnull .I Boffset
254 78e51a8c 2005-01-14 devnull returns the file offset of the next character to be processed.
256 78e51a8c 2005-01-14 devnull .I Bputc
257 78e51a8c 2005-01-14 devnull outputs the low order 8 bits of
260 78e51a8c 2005-01-14 devnull .IR bp .
261 78e51a8c 2005-01-14 devnull If this causes a
262 78e51a8c 2005-01-14 devnull .IR write
263 78e51a8c 2005-01-14 devnull to occur and there is an error,
264 78e51a8c 2005-01-14 devnull a negative value is returned.
265 78e51a8c 2005-01-14 devnull Otherwise, a zero is returned.
267 78e51a8c 2005-01-14 devnull .I Bputrune
269 78e51a8c 2005-01-14 devnull .I Bputc
270 78e51a8c 2005-01-14 devnull to output the low order
271 78e51a8c 2005-01-14 devnull 16 bits of
273 78e51a8c 2005-01-14 devnull as a rune
277 78e51a8c 2005-01-14 devnull on the output stream.
279 78e51a8c 2005-01-14 devnull .I Bprint
280 78e51a8c 2005-01-14 devnull is a buffered interface to
281 78e51a8c 2005-01-14 devnull .IR print (3).
282 78e51a8c 2005-01-14 devnull If this causes a
283 78e51a8c 2005-01-14 devnull .IR write
284 78e51a8c 2005-01-14 devnull to occur and there is an error,
285 78e51a8c 2005-01-14 devnull a negative value
286 78e51a8c 2005-01-14 devnull .RB ( Beof )
287 78e51a8c 2005-01-14 devnull is returned.
288 78e51a8c 2005-01-14 devnull Otherwise, the number of bytes output is returned.
289 78e51a8c 2005-01-14 devnull .I Bvprint
290 78e51a8c 2005-01-14 devnull does the same except it takes as argument a
291 78e51a8c 2005-01-14 devnull .B va_list
292 78e51a8c 2005-01-14 devnull parameter, so it can be called within a variadic function.
294 78e51a8c 2005-01-14 devnull .I Bwrite
296 78e51a8c 2005-01-14 devnull .I nbytes
297 78e51a8c 2005-01-14 devnull of data starting at
300 78e51a8c 2005-01-14 devnull .IR bp .
301 78e51a8c 2005-01-14 devnull If this causes a
302 78e51a8c 2005-01-14 devnull .IR write
303 78e51a8c 2005-01-14 devnull to occur and there is an error,
304 78e51a8c 2005-01-14 devnull a negative value is returned.
305 78e51a8c 2005-01-14 devnull Otherwise, the number of bytes written is returned.
307 78e51a8c 2005-01-14 devnull .I Bflush
308 78e51a8c 2005-01-14 devnull causes any buffered output associated with
310 78e51a8c 2005-01-14 devnull to be written.
311 78e51a8c 2005-01-14 devnull The return is as for
312 78e51a8c 2005-01-14 devnull .IR Bputc .
313 78e51a8c 2005-01-14 devnull .I Bflush
314 78e51a8c 2005-01-14 devnull is called on
315 78e51a8c 2005-01-14 devnull exit for every buffer still open
316 78e51a8c 2005-01-14 devnull for writing.
318 78e51a8c 2005-01-14 devnull .I Bbuffered
319 78e51a8c 2005-01-14 devnull returns the number of bytes in the buffer.
320 78e51a8c 2005-01-14 devnull When reading, this is the number of bytes still available from the last
321 78e51a8c 2005-01-14 devnull read on the file; when writing, it is the number of bytes ready to be
322 78e51a8c 2005-01-14 devnull written.
323 78e51a8c 2005-01-14 devnull .SH SOURCE
324 a3993885 2017-09-01 rsc .B https://9fans.github.io/plan9port/unix
325 78e51a8c 2005-01-14 devnull .SH SEE ALSO
326 78e51a8c 2005-01-14 devnull .IR open (2),
327 78e51a8c 2005-01-14 devnull .IR print (3),
328 78e51a8c 2005-01-14 devnull .IR atexit (3),
329 78e51a8c 2005-01-14 devnull .IR utf (7),
330 78e51a8c 2005-01-14 devnull .SH DIAGNOSTICS
332 78e51a8c 2005-01-14 devnull routines that return integers yield
336 78e51a8c 2005-01-14 devnull is not the descriptor of an open file.
337 78e51a8c 2005-01-14 devnull .I Bopen
338 78e51a8c 2005-01-14 devnull returns zero if the file cannot be opened in the given mode.
339 78e51a8c 2005-01-14 devnull All routines set
340 78e51a8c 2005-01-14 devnull .I errstr
341 78e51a8c 2005-01-14 devnull on error.
342 78e51a8c 2005-01-14 devnull .SH BUGS
343 78e51a8c 2005-01-14 devnull .I Brdline
344 78e51a8c 2005-01-14 devnull returns an error on strings longer than the buffer associated
345 78e51a8c 2005-01-14 devnull with the file
346 78e51a8c 2005-01-14 devnull and also if the end-of-file is encountered
347 78e51a8c 2005-01-14 devnull before a delimiter.
348 78e51a8c 2005-01-14 devnull .I Blinelen
349 78e51a8c 2005-01-14 devnull will tell how many characters are available
350 78e51a8c 2005-01-14 devnull in these cases.
351 78e51a8c 2005-01-14 devnull In the case of a true end-of-file,
352 78e51a8c 2005-01-14 devnull .I Blinelen
353 78e51a8c 2005-01-14 devnull will return zero.
354 78e51a8c 2005-01-14 devnull At the cost of allocating a buffer,
355 78e51a8c 2005-01-14 devnull .I Brdstr
356 78e51a8c 2005-01-14 devnull sidesteps these issues.
358 78e51a8c 2005-01-14 devnull The data returned by
359 78e51a8c 2005-01-14 devnull .I Brdline
360 78e51a8c 2005-01-14 devnull may be overwritten by calls to any other
362 78e51a8c 2005-01-14 devnull routine on the same
