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