3 b2cfc4e2 2003-09-30 devnull Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetd, Bungetc, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, 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 b2cfc4e2 2003-09-30 devnull .B #include <fmt.h>
7 b2cfc4e2 2003-09-30 devnull .B #include <bio.h>
10 b2cfc4e2 2003-09-30 devnull Biobuf* Bopen(char *file, int mode)
13 b2cfc4e2 2003-09-30 devnull int Binit(Biobuf *bp, int fd, int mode)
16 b2cfc4e2 2003-09-30 devnull int Bterm(Biobuf *bp)
19 b2cfc4e2 2003-09-30 devnull int Bprint(Biobuf *bp, char *format, ...)
22 b2cfc4e2 2003-09-30 devnull int Bvprint(Biobuf *bp, char *format, va_list arglist);
25 b2cfc4e2 2003-09-30 devnull void* Brdline(Biobuf *bp, int delim)
28 b2cfc4e2 2003-09-30 devnull char* Brdstr(Biobuf *bp, int delim, int nulldelim)
31 b2cfc4e2 2003-09-30 devnull int Blinelen(Biobuf *bp)
34 b2cfc4e2 2003-09-30 devnull off_t Boffset(Biobuf *bp)
37 b2cfc4e2 2003-09-30 devnull int Bfildes(Biobuf *bp)
40 b2cfc4e2 2003-09-30 devnull int Bgetc(Biobuf *bp)
43 b2cfc4e2 2003-09-30 devnull long Bgetrune(Biobufhdr *bp)
46 b2cfc4e2 2003-09-30 devnull int Bgetd(Biobuf *bp, double *d)
49 b2cfc4e2 2003-09-30 devnull int Bungetc(Biobuf *bp)
52 b2cfc4e2 2003-09-30 devnull int Bungetrune(Biobufhdr *bp)
55 b2cfc4e2 2003-09-30 devnull off_t Bseek(Biobuf *bp, off_t n, int type)
58 b2cfc4e2 2003-09-30 devnull int Bputc(Biobuf *bp, int c)
61 b2cfc4e2 2003-09-30 devnull int Bputrune(Biobufhdr *bp, long c)
64 b2cfc4e2 2003-09-30 devnull long Bread(Biobuf *bp, void *addr, long nbytes)
67 b2cfc4e2 2003-09-30 devnull long Bwrite(Biobuf *bp, void *addr, long nbytes)
70 b2cfc4e2 2003-09-30 devnull int Bflush(Biobuf *bp)
73 b2cfc4e2 2003-09-30 devnull int Bbuffered(Biobuf *bp)
75 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
76 b2cfc4e2 2003-09-30 devnull These routines implement fast buffered I/O.
77 b2cfc4e2 2003-09-30 devnull I/O on different file descriptors is independent.
83 b2cfc4e2 2003-09-30 devnull .B O_RDONLY
84 b2cfc4e2 2003-09-30 devnull or creates for mode
85 b2cfc4e2 2003-09-30 devnull .BR O_WRONLY .
87 b2cfc4e2 2003-09-30 devnull .IR malloc (3)
88 b2cfc4e2 2003-09-30 devnull to allocate a buffer.
91 b2cfc4e2 2003-09-30 devnull initializes a buffer
92 b2cfc4e2 2003-09-30 devnull with the open file descriptor passed in
93 b2cfc4e2 2003-09-30 devnull by the user.
95 b2cfc4e2 2003-09-30 devnull Arguments
96 b2cfc4e2 2003-09-30 devnull of types pointer to Biobuf and pointer to Biobuf
97 b2cfc4e2 2003-09-30 devnull can be used interchangeably in the following routines.
99 b2cfc4e2 2003-09-30 devnull .IR Bopen ,
100 b2cfc4e2 2003-09-30 devnull .IR Binit ,
102 b2cfc4e2 2003-09-30 devnull .I Binits
103 b2cfc4e2 2003-09-30 devnull should be called before any of the
104 b2cfc4e2 2003-09-30 devnull other routines on that buffer.
105 b2cfc4e2 2003-09-30 devnull .I Bfildes
106 b2cfc4e2 2003-09-30 devnull returns the integer file descriptor of the associated open file.
108 b2cfc4e2 2003-09-30 devnull .I Bterm
109 b2cfc4e2 2003-09-30 devnull flushes the buffer for
110 b2cfc4e2 2003-09-30 devnull .IR bp .
111 b2cfc4e2 2003-09-30 devnull If the buffer was allocated by
112 b2cfc4e2 2003-09-30 devnull .IR Bopen ,
113 b2cfc4e2 2003-09-30 devnull the buffer is
114 b2cfc4e2 2003-09-30 devnull .I freed
115 b2cfc4e2 2003-09-30 devnull and the file is closed.
117 b2cfc4e2 2003-09-30 devnull .I Brdline
118 b2cfc4e2 2003-09-30 devnull reads a string from the file associated with
120 b2cfc4e2 2003-09-30 devnull up to and including the first
121 b2cfc4e2 2003-09-30 devnull .I delim
122 b2cfc4e2 2003-09-30 devnull character.
123 b2cfc4e2 2003-09-30 devnull The delimiter character at the end of the line is
124 b2cfc4e2 2003-09-30 devnull not altered.
125 b2cfc4e2 2003-09-30 devnull .I Brdline
126 b2cfc4e2 2003-09-30 devnull returns a pointer to the start of the line or
128 b2cfc4e2 2003-09-30 devnull on end-of-file or read error.
129 b2cfc4e2 2003-09-30 devnull .I Blinelen
130 b2cfc4e2 2003-09-30 devnull returns the length (including the delimiter)
131 b2cfc4e2 2003-09-30 devnull of the most recent string returned by
132 b2cfc4e2 2003-09-30 devnull .IR Brdline .
134 b2cfc4e2 2003-09-30 devnull .I Brdstr
135 b2cfc4e2 2003-09-30 devnull returns a
136 b2cfc4e2 2003-09-30 devnull .IR malloc (3)-allocated
137 b2cfc4e2 2003-09-30 devnull buffer containing the next line of input delimited by
138 b2cfc4e2 2003-09-30 devnull .IR delim ,
139 b2cfc4e2 2003-09-30 devnull terminated by a NUL (0) byte.
141 b2cfc4e2 2003-09-30 devnull .IR Brdline ,
142 b2cfc4e2 2003-09-30 devnull which returns when its buffer is full even if no delimiter has been found,
143 b2cfc4e2 2003-09-30 devnull .I Brdstr
144 b2cfc4e2 2003-09-30 devnull will return an arbitrarily long line in a single call.
146 b2cfc4e2 2003-09-30 devnull .I nulldelim
147 b2cfc4e2 2003-09-30 devnull is set, the terminal delimiter will be overwritten with a NUL.
148 b2cfc4e2 2003-09-30 devnull After a successful call to
149 b2cfc4e2 2003-09-30 devnull .IR Brdstr ,
150 b2cfc4e2 2003-09-30 devnull the return value of
151 b2cfc4e2 2003-09-30 devnull .I Blinelen
152 b2cfc4e2 2003-09-30 devnull will be the length of the returned buffer, excluding the NUL.
154 b2cfc4e2 2003-09-30 devnull .I Bgetc
155 b2cfc4e2 2003-09-30 devnull returns the next byte from
156 b2cfc4e2 2003-09-30 devnull .IR bp ,
157 b2cfc4e2 2003-09-30 devnull or a negative value
158 b2cfc4e2 2003-09-30 devnull at end of file.
159 b2cfc4e2 2003-09-30 devnull .I Bungetc
160 b2cfc4e2 2003-09-30 devnull may be called immediately after
161 b2cfc4e2 2003-09-30 devnull .I Bgetc
162 b2cfc4e2 2003-09-30 devnull to allow the same byte to be reread.
164 b2cfc4e2 2003-09-30 devnull .I Bgetrune
166 b2cfc4e2 2003-09-30 devnull .I Bgetc
167 b2cfc4e2 2003-09-30 devnull to read the bytes of the next
169 b2cfc4e2 2003-09-30 devnull sequence in the input stream and returns the value of the rune
170 b2cfc4e2 2003-09-30 devnull represented by the sequence.
171 b2cfc4e2 2003-09-30 devnull It returns a negative value
172 b2cfc4e2 2003-09-30 devnull at end of file.
173 b2cfc4e2 2003-09-30 devnull .I Bungetrune
174 b2cfc4e2 2003-09-30 devnull may be called immediately after
175 b2cfc4e2 2003-09-30 devnull .I Bgetrune
176 b2cfc4e2 2003-09-30 devnull to allow the same
178 b2cfc4e2 2003-09-30 devnull sequence to be reread as either bytes or a rune.
179 b2cfc4e2 2003-09-30 devnull .I Bungetc
181 b2cfc4e2 2003-09-30 devnull .I Bungetrune
182 b2cfc4e2 2003-09-30 devnull may back up a maximum of five bytes.
184 b2cfc4e2 2003-09-30 devnull .I Bgetd
186 b2cfc4e2 2003-09-30 devnull .I fmtcharstod
187 b2cfc4e2 2003-09-30 devnull (undocumented)
189 b2cfc4e2 2003-09-30 devnull .I Bgetc
190 b2cfc4e2 2003-09-30 devnull to read the formatted
191 b2cfc4e2 2003-09-30 devnull floating-point number in the input stream,
192 b2cfc4e2 2003-09-30 devnull skipping initial blanks and tabs.
193 b2cfc4e2 2003-09-30 devnull The value is stored in
196 b2cfc4e2 2003-09-30 devnull .I Bread
198 b2cfc4e2 2003-09-30 devnull .I nbytes
199 b2cfc4e2 2003-09-30 devnull of data from
201 b2cfc4e2 2003-09-30 devnull into memory starting at
202 b2cfc4e2 2003-09-30 devnull .IR addr .
203 b2cfc4e2 2003-09-30 devnull The number of bytes read is returned on success
204 b2cfc4e2 2003-09-30 devnull and a negative value is returned if a read error occurred.
206 b2cfc4e2 2003-09-30 devnull .I Bseek
208 b2cfc4e2 2003-09-30 devnull .IR lseek (2)
210 b2cfc4e2 2003-09-30 devnull .IR bp .
211 b2cfc4e2 2003-09-30 devnull It returns the new file offset.
212 b2cfc4e2 2003-09-30 devnull .I Boffset
213 b2cfc4e2 2003-09-30 devnull returns the file offset of the next character to be processed.
215 b2cfc4e2 2003-09-30 devnull .I Bputc
216 b2cfc4e2 2003-09-30 devnull outputs the low order 8 bits of
219 b2cfc4e2 2003-09-30 devnull .IR bp .
220 b2cfc4e2 2003-09-30 devnull If this causes a
221 b2cfc4e2 2003-09-30 devnull .IR write
222 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
223 b2cfc4e2 2003-09-30 devnull a negative value is returned.
224 b2cfc4e2 2003-09-30 devnull Otherwise, a zero is returned.
226 b2cfc4e2 2003-09-30 devnull .I Bputrune
228 b2cfc4e2 2003-09-30 devnull .I Bputc
229 b2cfc4e2 2003-09-30 devnull to output the low order
230 b2cfc4e2 2003-09-30 devnull 16 bits of
232 b2cfc4e2 2003-09-30 devnull as a rune
236 b2cfc4e2 2003-09-30 devnull on the output stream.
238 b2cfc4e2 2003-09-30 devnull .I Bprint
239 b2cfc4e2 2003-09-30 devnull is a buffered interface to
240 b2cfc4e2 2003-09-30 devnull .IR print (2).
241 b2cfc4e2 2003-09-30 devnull If this causes a
242 b2cfc4e2 2003-09-30 devnull .IR write
243 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
244 b2cfc4e2 2003-09-30 devnull a negative value
245 b2cfc4e2 2003-09-30 devnull .RB ( Beof )
246 b2cfc4e2 2003-09-30 devnull is returned.
247 b2cfc4e2 2003-09-30 devnull Otherwise, the number of bytes output is returned.
248 b2cfc4e2 2003-09-30 devnull .I Bvprint
249 b2cfc4e2 2003-09-30 devnull does the same except it takes as argument a
250 b2cfc4e2 2003-09-30 devnull .B va_list
251 b2cfc4e2 2003-09-30 devnull parameter, so it can be called within a variadic function.
253 b2cfc4e2 2003-09-30 devnull .I Bwrite
255 b2cfc4e2 2003-09-30 devnull .I nbytes
256 b2cfc4e2 2003-09-30 devnull of data starting at
259 b2cfc4e2 2003-09-30 devnull .IR bp .
260 b2cfc4e2 2003-09-30 devnull If this causes a
261 b2cfc4e2 2003-09-30 devnull .IR write
262 b2cfc4e2 2003-09-30 devnull to occur and there is an error,
263 b2cfc4e2 2003-09-30 devnull a negative value is returned.
264 b2cfc4e2 2003-09-30 devnull Otherwise, the number of bytes written is returned.
266 b2cfc4e2 2003-09-30 devnull .I Bflush
267 b2cfc4e2 2003-09-30 devnull causes any buffered output associated with
269 b2cfc4e2 2003-09-30 devnull to be written.
270 b2cfc4e2 2003-09-30 devnull The return is as for
271 b2cfc4e2 2003-09-30 devnull .IR Bputc .
272 b2cfc4e2 2003-09-30 devnull .I Bflush
273 b2cfc4e2 2003-09-30 devnull is called on
274 b2cfc4e2 2003-09-30 devnull exit for every buffer still open
275 b2cfc4e2 2003-09-30 devnull for writing.
277 b2cfc4e2 2003-09-30 devnull .I Bbuffered
278 b2cfc4e2 2003-09-30 devnull returns the number of bytes in the buffer.
279 b2cfc4e2 2003-09-30 devnull When reading, this is the number of bytes still available from the last
280 b2cfc4e2 2003-09-30 devnull read on the file; when writing, it is the number of bytes ready to be
281 b2cfc4e2 2003-09-30 devnull written.
283 b2cfc4e2 2003-09-30 devnull This library uses
284 b2cfc4e2 2003-09-30 devnull .IR fmt (3)
285 b2cfc4e2 2003-09-30 devnull for diagnostic messages about internal errors,
286 b2cfc4e2 2003-09-30 devnull as well as for the implementation of
287 b2cfc4e2 2003-09-30 devnull .I Bprint
289 b2cfc4e2 2003-09-30 devnull .IR Bvprint .
291 b2cfc4e2 2003-09-30 devnull .IR utf (3)
292 b2cfc4e2 2003-09-30 devnull for the implementation of
293 b2cfc4e2 2003-09-30 devnull .I Bgetrune
295 b2cfc4e2 2003-09-30 devnull .IR Bputrune .
296 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
297 b2cfc4e2 2003-09-30 devnull .IR atexit (3).
298 b2cfc4e2 2003-09-30 devnull .IR open (2),
299 b2cfc4e2 2003-09-30 devnull .IR print (3),
300 b2cfc4e2 2003-09-30 devnull .IR utf (7)
301 b2cfc4e2 2003-09-30 devnull .SH DIAGNOSTICS
303 b2cfc4e2 2003-09-30 devnull routines that return integers yield
307 b2cfc4e2 2003-09-30 devnull is not the descriptor of an open file.
308 b2cfc4e2 2003-09-30 devnull .I Bopen
309 b2cfc4e2 2003-09-30 devnull returns zero if the file cannot be opened in the given mode.
310 b2cfc4e2 2003-09-30 devnull .SH HISTORY
312 b2cfc4e2 2003-09-30 devnull .IR bio (3)
313 b2cfc4e2 2003-09-30 devnull library originally appeared in Plan 9.
314 b2cfc4e2 2003-09-30 devnull This is a port of the Plan 9 bio library.
315 b2cfc4e2 2003-09-30 devnull .SH BUGS
316 b2cfc4e2 2003-09-30 devnull .I Brdline
317 b2cfc4e2 2003-09-30 devnull returns an error on strings longer than the buffer associated
318 b2cfc4e2 2003-09-30 devnull with the file
319 b2cfc4e2 2003-09-30 devnull and also if the end-of-file is encountered
320 b2cfc4e2 2003-09-30 devnull before a delimiter.
321 b2cfc4e2 2003-09-30 devnull .I Blinelen
322 b2cfc4e2 2003-09-30 devnull will tell how many characters are available
323 b2cfc4e2 2003-09-30 devnull in these cases.
324 b2cfc4e2 2003-09-30 devnull In the case of a true end-of-file,
325 b2cfc4e2 2003-09-30 devnull .I Blinelen
326 b2cfc4e2 2003-09-30 devnull will return zero.
327 b2cfc4e2 2003-09-30 devnull At the cost of allocating a buffer,
328 b2cfc4e2 2003-09-30 devnull .I Brdstr
329 b2cfc4e2 2003-09-30 devnull sidesteps these issues.
331 b2cfc4e2 2003-09-30 devnull The data returned by
332 b2cfc4e2 2003-09-30 devnull .I Brdline
333 b2cfc4e2 2003-09-30 devnull may be overwritten by calls to any other
335 b2cfc4e2 2003-09-30 devnull routine on the same
