3 cfa37a7b 2004-04-10 devnull Bopen, 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 b2cfc4e2 2003-09-30 devnull .ta \w'Biobuf* '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 b2cfc4e2 2003-09-30 devnull Biobuf* Bopen(char *file, int mode)
16 b2cfc4e2 2003-09-30 devnull int Binit(Biobuf *bp, int fd, int mode)
19 cfa37a7b 2004-04-10 devnull int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)
22 cfa37a7b 2004-04-10 devnull int Bterm(Biobufhdr *bp)
25 cfa37a7b 2004-04-10 devnull int Bprint(Biobufhdr *bp, char *format, ...)
28 cfa37a7b 2004-04-10 devnull int Bvprint(Biobufhdr *bp, char *format, va_list arglist);
31 cfa37a7b 2004-04-10 devnull void* Brdline(Biobufhdr *bp, int delim)
34 cfa37a7b 2004-04-10 devnull char* Brdstr(Biobufhdr *bp, int delim, int nulldelim)
37 cfa37a7b 2004-04-10 devnull int Blinelen(Biobufhdr *bp)
40 cfa37a7b 2004-04-10 devnull vlong Boffset(Biobufhdr *bp)
43 cfa37a7b 2004-04-10 devnull int Bfildes(Biobufhdr *bp)
46 cfa37a7b 2004-04-10 devnull int Bgetc(Biobufhdr *bp)
49 b2cfc4e2 2003-09-30 devnull long Bgetrune(Biobufhdr *bp)
52 cfa37a7b 2004-04-10 devnull int Bgetd(Biobufhdr *bp, double *d)
55 cfa37a7b 2004-04-10 devnull int Bungetc(Biobufhdr *bp)
58 b2cfc4e2 2003-09-30 devnull int Bungetrune(Biobufhdr *bp)
61 cfa37a7b 2004-04-10 devnull vlong Bseek(Biobufhdr *bp, vlong n, int type)
64 cfa37a7b 2004-04-10 devnull int Bputc(Biobufhdr *bp, int c)
67 b2cfc4e2 2003-09-30 devnull int Bputrune(Biobufhdr *bp, long c)
70 cfa37a7b 2004-04-10 devnull long Bread(Biobufhdr *bp, void *addr, long nbytes)
73 cfa37a7b 2004-04-10 devnull long Bwrite(Biobufhdr *bp, void *addr, long nbytes)
76 cfa37a7b 2004-04-10 devnull int Bflush(Biobufhdr *bp)
79 cfa37a7b 2004-04-10 devnull int Bbuffered(Biobufhdr *bp)
81 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
82 b2cfc4e2 2003-09-30 devnull These routines implement fast buffered I/O.
83 b2cfc4e2 2003-09-30 devnull I/O on different file descriptors is independent.
90 b2cfc4e2 2003-09-30 devnull or creates for mode
91 cfa37a7b 2004-04-10 devnull .BR OWRITE .
93 bf8a59fa 2004-04-11 devnull .IR malloc (3)
94 b2cfc4e2 2003-09-30 devnull to allocate a buffer.
97 cfa37a7b 2004-04-10 devnull initializes a standard size buffer, type
98 cfa37a7b 2004-04-10 devnull .IR Biobuf ,
99 b2cfc4e2 2003-09-30 devnull with the open file descriptor passed in
100 b2cfc4e2 2003-09-30 devnull by the user.
101 cfa37a7b 2004-04-10 devnull .I Binits
102 cfa37a7b 2004-04-10 devnull initializes a non-standard size buffer, type
103 cfa37a7b 2004-04-10 devnull .IR Biobufhdr ,
104 cfa37a7b 2004-04-10 devnull with the open file descriptor,
105 cfa37a7b 2004-04-10 devnull buffer area, and buffer size passed in
106 cfa37a7b 2004-04-10 devnull by the user.
107 cfa37a7b 2004-04-10 devnull .I Biobuf
109 cfa37a7b 2004-04-10 devnull .I Biobufhdr
110 cfa37a7b 2004-04-10 devnull are related by the declaration:
113 cfa37a7b 2004-04-10 devnull typedef struct Biobuf Biobuf;
114 cfa37a7b 2004-04-10 devnull struct Biobuf
116 cfa37a7b 2004-04-10 devnull Biobufhdr;
117 cfa37a7b 2004-04-10 devnull uchar b[Bungetsize+Bsize];
121 b2cfc4e2 2003-09-30 devnull Arguments
122 cfa37a7b 2004-04-10 devnull of types pointer to Biobuf and pointer to Biobufhdr
123 b2cfc4e2 2003-09-30 devnull can be used interchangeably in the following routines.
125 b2cfc4e2 2003-09-30 devnull .IR Bopen ,
126 b2cfc4e2 2003-09-30 devnull .IR Binit ,
128 b2cfc4e2 2003-09-30 devnull .I Binits
129 b2cfc4e2 2003-09-30 devnull should be called before any of the
130 b2cfc4e2 2003-09-30 devnull other routines on that buffer.
131 b2cfc4e2 2003-09-30 devnull .I Bfildes
132 b2cfc4e2 2003-09-30 devnull returns the integer file descriptor of the associated open file.
134 b2cfc4e2 2003-09-30 devnull .I Bterm
135 b2cfc4e2 2003-09-30 devnull flushes the buffer for
136 b2cfc4e2 2003-09-30 devnull .IR bp .
137 b2cfc4e2 2003-09-30 devnull If the buffer was allocated by
138 b2cfc4e2 2003-09-30 devnull .IR Bopen ,
139 b2cfc4e2 2003-09-30 devnull the buffer is
140 b2cfc4e2 2003-09-30 devnull .I freed
141 b2cfc4e2 2003-09-30 devnull and the file is closed.
143 b2cfc4e2 2003-09-30 devnull .I Brdline
144 b2cfc4e2 2003-09-30 devnull reads a string from the file associated with
146 b2cfc4e2 2003-09-30 devnull up to and including the first
147 b2cfc4e2 2003-09-30 devnull .I delim
148 b2cfc4e2 2003-09-30 devnull character.
149 b2cfc4e2 2003-09-30 devnull The delimiter character at the end of the line is
150 b2cfc4e2 2003-09-30 devnull not altered.
151 b2cfc4e2 2003-09-30 devnull .I Brdline
152 b2cfc4e2 2003-09-30 devnull returns a pointer to the start of the line or
154 b2cfc4e2 2003-09-30 devnull on end-of-file or read error.
155 b2cfc4e2 2003-09-30 devnull .I Blinelen
156 b2cfc4e2 2003-09-30 devnull returns the length (including the delimiter)
157 b2cfc4e2 2003-09-30 devnull of the most recent string returned by
158 b2cfc4e2 2003-09-30 devnull .IR Brdline .
160 b2cfc4e2 2003-09-30 devnull .I Brdstr
161 b2cfc4e2 2003-09-30 devnull returns a
162 bf8a59fa 2004-04-11 devnull .IR malloc (3)-allocated
163 b2cfc4e2 2003-09-30 devnull buffer containing the next line of input delimited by
164 b2cfc4e2 2003-09-30 devnull .IR delim ,
165 b2cfc4e2 2003-09-30 devnull terminated by a NUL (0) byte.
167 b2cfc4e2 2003-09-30 devnull .IR Brdline ,
168 b2cfc4e2 2003-09-30 devnull which returns when its buffer is full even if no delimiter has been found,
169 b2cfc4e2 2003-09-30 devnull .I Brdstr
170 b2cfc4e2 2003-09-30 devnull will return an arbitrarily long line in a single call.
172 b2cfc4e2 2003-09-30 devnull .I nulldelim
173 b2cfc4e2 2003-09-30 devnull is set, the terminal delimiter will be overwritten with a NUL.
174 b2cfc4e2 2003-09-30 devnull After a successful call to
175 b2cfc4e2 2003-09-30 devnull .IR Brdstr ,
176 b2cfc4e2 2003-09-30 devnull the return value of
177 b2cfc4e2 2003-09-30 devnull .I Blinelen
178 b2cfc4e2 2003-09-30 devnull will be the length of the returned buffer, excluding the NUL.
180 b2cfc4e2 2003-09-30 devnull .I Bgetc
181 cfa37a7b 2004-04-10 devnull returns the next character from
182 b2cfc4e2 2003-09-30 devnull .IR bp ,
183 b2cfc4e2 2003-09-30 devnull or a negative value
184 b2cfc4e2 2003-09-30 devnull at end of file.
185 b2cfc4e2 2003-09-30 devnull .I Bungetc
186 b2cfc4e2 2003-09-30 devnull may be called immediately after
187 b2cfc4e2 2003-09-30 devnull .I Bgetc
188 cfa37a7b 2004-04-10 devnull to allow the same character to be reread.
190 b2cfc4e2 2003-09-30 devnull .I Bgetrune
192 b2cfc4e2 2003-09-30 devnull .I Bgetc
193 b2cfc4e2 2003-09-30 devnull to read the bytes of the next
195 b2cfc4e2 2003-09-30 devnull sequence in the input stream and returns the value of the rune
196 b2cfc4e2 2003-09-30 devnull represented by the sequence.
197 b2cfc4e2 2003-09-30 devnull It returns a negative value
198 b2cfc4e2 2003-09-30 devnull at end of file.
199 b2cfc4e2 2003-09-30 devnull .I Bungetrune
200 b2cfc4e2 2003-09-30 devnull may be called immediately after
201 b2cfc4e2 2003-09-30 devnull .I Bgetrune
202 b2cfc4e2 2003-09-30 devnull to allow the same
204 b2cfc4e2 2003-09-30 devnull sequence to be reread as either bytes or a rune.
205 b2cfc4e2 2003-09-30 devnull .I Bungetc
207 b2cfc4e2 2003-09-30 devnull .I Bungetrune
208 b2cfc4e2 2003-09-30 devnull may back up a maximum of five bytes.
210 b2cfc4e2 2003-09-30 devnull .I Bgetd
212 cfa37a7b 2004-04-10 devnull .I charstod
214 bf8a59fa 2004-04-11 devnull .IR atof (3))
216 b2cfc4e2 2003-09-30 devnull .I Bgetc
217 b2cfc4e2 2003-09-30 devnull to read the formatted
218 b2cfc4e2 2003-09-30 devnull floating-point number in the input stream,
219 b2cfc4e2 2003-09-30 devnull skipping initial blanks and tabs.
220 b2cfc4e2 2003-09-30 devnull The value is stored in
223 b2cfc4e2 2003-09-30 devnull .I Bread
225 b2cfc4e2 2003-09-30 devnull .I nbytes
226 b2cfc4e2 2003-09-30 devnull of data from
228 b2cfc4e2 2003-09-30 devnull into memory starting at
229 b2cfc4e2 2003-09-30 devnull .IR addr .
230 b2cfc4e2 2003-09-30 devnull The number of bytes read is returned on success
231 b2cfc4e2 2003-09-30 devnull and a negative value is returned if a read error occurred.
233 b2cfc4e2 2003-09-30 devnull .I Bseek
235 bf8a59fa 2004-04-11 devnull .IR seek (3)
237 b2cfc4e2 2003-09-30 devnull .IR bp .
238 b2cfc4e2 2003-09-30 devnull It returns the new file offset.
239 b2cfc4e2 2003-09-30 devnull .I Boffset
240 b2cfc4e2 2003-09-30 devnull returns the file offset of the next character to be processed.
242 b2cfc4e2 2003-09-30 devnull .I Bputc
243 b2cfc4e2 2003-09-30 devnull outputs the low order 8 bits of
246 b2cfc4e2 2003-09-30 devnull .IR bp .
247 b2cfc4e2 2003-09-30 devnull If this causes a
248 b2cfc4e2 2003-09-30 devnull .IR write
249 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
250 b2cfc4e2 2003-09-30 devnull a negative value is returned.
251 b2cfc4e2 2003-09-30 devnull Otherwise, a zero is returned.
253 b2cfc4e2 2003-09-30 devnull .I Bputrune
255 b2cfc4e2 2003-09-30 devnull .I Bputc
256 b2cfc4e2 2003-09-30 devnull to output the low order
257 b2cfc4e2 2003-09-30 devnull 16 bits of
259 b2cfc4e2 2003-09-30 devnull as a rune
263 b2cfc4e2 2003-09-30 devnull on the output stream.
265 b2cfc4e2 2003-09-30 devnull .I Bprint
266 b2cfc4e2 2003-09-30 devnull is a buffered interface to
267 bf8a59fa 2004-04-11 devnull .IR print (3).
268 b2cfc4e2 2003-09-30 devnull If this causes a
269 b2cfc4e2 2003-09-30 devnull .IR write
270 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
271 b2cfc4e2 2003-09-30 devnull a negative value
272 b2cfc4e2 2003-09-30 devnull .RB ( Beof )
273 b2cfc4e2 2003-09-30 devnull is returned.
274 b2cfc4e2 2003-09-30 devnull Otherwise, the number of bytes output is returned.
275 b2cfc4e2 2003-09-30 devnull .I Bvprint
276 b2cfc4e2 2003-09-30 devnull does the same except it takes as argument a
277 b2cfc4e2 2003-09-30 devnull .B va_list
278 b2cfc4e2 2003-09-30 devnull parameter, so it can be called within a variadic function.
280 b2cfc4e2 2003-09-30 devnull .I Bwrite
282 b2cfc4e2 2003-09-30 devnull .I nbytes
283 b2cfc4e2 2003-09-30 devnull of data starting at
286 b2cfc4e2 2003-09-30 devnull .IR bp .
287 b2cfc4e2 2003-09-30 devnull If this causes a
288 b2cfc4e2 2003-09-30 devnull .IR write
289 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
290 b2cfc4e2 2003-09-30 devnull a negative value is returned.
291 b2cfc4e2 2003-09-30 devnull Otherwise, the number of bytes written is returned.
293 b2cfc4e2 2003-09-30 devnull .I Bflush
294 b2cfc4e2 2003-09-30 devnull causes any buffered output associated with
296 b2cfc4e2 2003-09-30 devnull to be written.
297 b2cfc4e2 2003-09-30 devnull The return is as for
298 b2cfc4e2 2003-09-30 devnull .IR Bputc .
299 b2cfc4e2 2003-09-30 devnull .I Bflush
300 b2cfc4e2 2003-09-30 devnull is called on
301 b2cfc4e2 2003-09-30 devnull exit for every buffer still open
302 b2cfc4e2 2003-09-30 devnull for writing.
304 b2cfc4e2 2003-09-30 devnull .I Bbuffered
305 b2cfc4e2 2003-09-30 devnull returns the number of bytes in the buffer.
306 b2cfc4e2 2003-09-30 devnull When reading, this is the number of bytes still available from the last
307 b2cfc4e2 2003-09-30 devnull read on the file; when writing, it is the number of bytes ready to be
308 b2cfc4e2 2003-09-30 devnull written.
309 cfa37a7b 2004-04-10 devnull .SH SOURCE
310 cfa37a7b 2004-04-10 devnull .B /sys/src/libbio
311 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
312 bf8a59fa 2004-04-11 devnull .IR open (3),
313 bf8a59fa 2004-04-11 devnull .IR print (3),
314 bf8a59fa 2004-04-11 devnull .IR exits (3),
315 cfa37a7b 2004-04-10 devnull .IR utf (6),
316 b2cfc4e2 2003-09-30 devnull .SH DIAGNOSTICS
318 b2cfc4e2 2003-09-30 devnull routines that return integers yield
322 b2cfc4e2 2003-09-30 devnull is not the descriptor of an open file.
323 b2cfc4e2 2003-09-30 devnull .I Bopen
324 b2cfc4e2 2003-09-30 devnull returns zero if the file cannot be opened in the given mode.
325 cfa37a7b 2004-04-10 devnull All routines set
326 cfa37a7b 2004-04-10 devnull .I errstr
327 cfa37a7b 2004-04-10 devnull on error.
328 b2cfc4e2 2003-09-30 devnull .SH BUGS
329 b2cfc4e2 2003-09-30 devnull .I Brdline
330 b2cfc4e2 2003-09-30 devnull returns an error on strings longer than the buffer associated
331 b2cfc4e2 2003-09-30 devnull with the file
332 b2cfc4e2 2003-09-30 devnull and also if the end-of-file is encountered
333 b2cfc4e2 2003-09-30 devnull before a delimiter.
334 b2cfc4e2 2003-09-30 devnull .I Blinelen
335 b2cfc4e2 2003-09-30 devnull will tell how many characters are available
336 b2cfc4e2 2003-09-30 devnull in these cases.
337 b2cfc4e2 2003-09-30 devnull In the case of a true end-of-file,
338 b2cfc4e2 2003-09-30 devnull .I Blinelen
339 b2cfc4e2 2003-09-30 devnull will return zero.
340 b2cfc4e2 2003-09-30 devnull At the cost of allocating a buffer,
341 b2cfc4e2 2003-09-30 devnull .I Brdstr
342 b2cfc4e2 2003-09-30 devnull sidesteps these issues.
344 b2cfc4e2 2003-09-30 devnull The data returned by
345 b2cfc4e2 2003-09-30 devnull .I Brdline
346 b2cfc4e2 2003-09-30 devnull may be overwritten by calls to any other
348 b2cfc4e2 2003-09-30 devnull routine on the same
