tbio.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tbio.3 (6762B)
---
1 .TH BIO 3
2 .SH NAME
3 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 .SH SYNOPSIS
5 .ta \w'\fLBiobuf* 'u
6 .B #include <u.h>
7 .br
8 .B #include <libc.h>
9 .br
10 .B #include <bio.h>
11 .PP
12 .B
13 Biobuf* Bopen(char *file, int mode)
14 .PP
15 .B
16 Biobuf* Bfdopen(int fd, int mode)
17 .PP
18 .B
19 int Binit(Biobuf *bp, int fd, int mode)
20 .PP
21 .B
22 int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)
23 .PP
24 .B
25 int Bterm(Biobufhdr *bp)
26 .PP
27 .B
28 int Bprint(Biobufhdr *bp, char *format, ...)
29 .PP
30 .B
31 int Bvprint(Biobufhdr *bp, char *format, va_list arglist);
32 .PP
33 .B
34 void* Brdline(Biobufhdr *bp, int delim)
35 .PP
36 .B
37 char* Brdstr(Biobufhdr *bp, int delim, int nulldelim)
38 .PP
39 .B
40 int Blinelen(Biobufhdr *bp)
41 .PP
42 .B
43 vlong Boffset(Biobufhdr *bp)
44 .PP
45 .B
46 int Bfildes(Biobufhdr *bp)
47 .PP
48 .B
49 int Bgetc(Biobufhdr *bp)
50 .PP
51 .B
52 long Bgetrune(Biobufhdr *bp)
53 .PP
54 .B
55 int Bgetd(Biobufhdr *bp, double *d)
56 .PP
57 .B
58 int Bungetc(Biobufhdr *bp)
59 .PP
60 .B
61 int Bungetrune(Biobufhdr *bp)
62 .PP
63 .B
64 vlong Bseek(Biobufhdr *bp, vlong n, int type)
65 .PP
66 .B
67 int Bputc(Biobufhdr *bp, int c)
68 .PP
69 .B
70 int Bputrune(Biobufhdr *bp, long c)
71 .PP
72 .B
73 long Bread(Biobufhdr *bp, void *addr, long nbytes)
74 .PP
75 .B
76 long Bwrite(Biobufhdr *bp, void *addr, long nbytes)
77 .PP
78 .B
79 int Bflush(Biobufhdr *bp)
80 .PP
81 .B
82 int Bbuffered(Biobufhdr *bp)
83 .PP
84 .SH DESCRIPTION
85 These routines implement fast buffered I/O.
86 I/O on different file descriptors is independent.
87 .PP
88 .I Bopen
89 opens
90 .I file
91 for mode
92 .B OREAD
93 or creates for mode
94 .BR OWRITE .
95 It calls
96 .MR malloc (3)
97 to allocate a buffer.
98 .PP
99 .I Bfdopen
100 allocates a buffer for the already-open file descriptor
101 .I fd
102 for mode
103 .B OREAD
104 or
105 .BR OWRITE .
106 It calls
107 .MR malloc (3)
108 to allocate a buffer.
109 .PP
110 .I Binit
111 initializes a standard size buffer, type
112 .IR Biobuf ,
113 with the open file descriptor passed in
114 by the user.
115 .I Binits
116 initializes a non-standard size buffer, type
117 .IR Biobufhdr ,
118 with the open file descriptor,
119 buffer area, and buffer size passed in
120 by the user.
121 .I Biobuf
122 and
123 .I Biobufhdr
124 are related by the declaration:
125 .IP
126 .EX
127 typedef struct Biobuf Biobuf;
128 struct Biobuf
129 {
130 Biobufhdr;
131 uchar b[Bungetsize+Bsize];
132 };
133 .EE
134 .PP
135 Arguments
136 of types pointer to Biobuf and pointer to Biobufhdr
137 can be used interchangeably in the following routines.
138 .PP
139 .IR Bopen ,
140 .IR Binit ,
141 or
142 .I Binits
143 should be called before any of the
144 other routines on that buffer.
145 .I Bfildes
146 returns the integer file descriptor of the associated open file.
147 .PP
148 .I Bterm
149 flushes the buffer for
150 .IR bp .
151 If the buffer was allocated by
152 .IR Bopen ,
153 the buffer is
154 .I freed
155 and the file is closed.
156 .PP
157 .I Brdline
158 reads a string from the file associated with
159 .I bp
160 up to and including the first
161 .I delim
162 character.
163 The delimiter character at the end of the line is
164 not altered.
165 .I Brdline
166 returns a pointer to the start of the line or
167 .L 0
168 on end-of-file or read error.
169 .I Blinelen
170 returns the length (including the delimiter)
171 of the most recent string returned by
172 .IR Brdline .
173 .PP
174 .I Brdstr
175 returns a
176 .MR malloc (3) -allocated
177 buffer containing the next line of input delimited by
178 .IR delim ,
179 terminated by a NUL (0) byte.
180 Unlike
181 .IR Brdline ,
182 which returns when its buffer is full even if no delimiter has been found,
183 .I Brdstr
184 will return an arbitrarily long line in a single call.
185 If
186 .I nulldelim
187 is set, the terminal delimiter will be overwritten with a NUL.
188 After a successful call to
189 .IR Brdstr ,
190 the return value of
191 .I Blinelen
192 will be the length of the returned buffer, excluding the NUL.
193 .PP
194 .I Bgetc
195 returns the next character from
196 .IR bp ,
197 or a negative value
198 at end of file.
199 .I Bungetc
200 may be called immediately after
201 .I Bgetc
202 to allow the same character to be reread.
203 .PP
204 .I Bgetrune
205 calls
206 .I Bgetc
207 to read the bytes of the next
208 .SM UTF
209 sequence in the input stream and returns the value of the rune
210 represented by the sequence.
211 It returns a negative value
212 at end of file.
213 .I Bungetrune
214 may be called immediately after
215 .I Bgetrune
216 to allow the same
217 .SM UTF
218 sequence to be reread as either bytes or a rune.
219 .I Bungetc
220 and
221 .I Bungetrune
222 may back up a maximum of five bytes.
223 .PP
224 .I Bgetd
225 uses
226 .I charstod
227 (see
228 .MR atof (3) )
229 and
230 .I Bgetc
231 to read the formatted
232 floating-point number in the input stream,
233 skipping initial blanks and tabs.
234 The value is stored in
235 .BR *d.
236 .PP
237 .I Bread
238 reads
239 .I nbytes
240 of data from
241 .I bp
242 into memory starting at
243 .IR addr .
244 The number of bytes read is returned on success
245 and a negative value is returned if a read error occurred.
246 .PP
247 .I Bseek
248 applies
249 .MR seek (3)
250 to
251 .IR bp .
252 It returns the new file offset.
253 .I Boffset
254 returns the file offset of the next character to be processed.
255 .PP
256 .I Bputc
257 outputs the low order 8 bits of
258 .I c
259 on
260 .IR bp .
261 If this causes a
262 .IR write
263 to occur and there is an error,
264 a negative value is returned.
265 Otherwise, a zero is returned.
266 .PP
267 .I Bputrune
268 calls
269 .I Bputc
270 to output the low order
271 16 bits of
272 .I c
273 as a rune
274 in
275 .SM UTF
276 format
277 on the output stream.
278 .PP
279 .I Bprint
280 is a buffered interface to
281 .MR print (3) .
282 If this causes a
283 .IR write
284 to occur and there is an error,
285 a negative value
286 .RB ( Beof )
287 is returned.
288 Otherwise,
289 .I Bprint
290 returns the number of bytes written.
291 .I Bvprint
292 does the same except it takes as argument a
293 .B va_list
294 parameter, so it can be called within a variadic function.
295 .PP
296 .I Bwrite
297 outputs
298 .I nbytes
299 of data starting at
300 .I addr
301 to
302 .IR bp .
303 If this causes a
304 .IR write
305 to occur and there is an error,
306 a negative value is returned.
307 Otherwise, the number of bytes written is returned.
308 .PP
309 .I Bflush
310 causes any buffered output associated with
311 .I bp
312 to be written.
313 The return is as for
314 .IR Bputc .
315 .I Bflush
316 is called on
317 exit for every buffer still open
318 for writing.
319 .PP
320 .I Bbuffered
321 returns the number of bytes in the buffer.
322 When reading, this is the number of bytes still available from the last
323 read on the file; when writing, it is the number of bytes ready to be
324 written.
325 .SH SOURCE
326 .B \*9/src/libbio
327 .SH SEE ALSO
328 .MR open (3) ,
329 .MR print (3) ,
330 .MR exits (3) ,
331 .MR utf (7) ,
332 .SH DIAGNOSTICS
333 .I Bio
334 routines that return integers yield
335 .B Beof
336 if
337 .I bp
338 is not the descriptor of an open file.
339 .I Bopen
340 returns zero if the file cannot be opened in the given mode.
341 All routines set
342 .I errstr
343 on error.
344 .SH BUGS
345 .I Brdline
346 returns an error on strings longer than the buffer associated
347 with the file
348 and also if the end-of-file is encountered
349 before a delimiter.
350 .I Blinelen
351 will tell how many characters are available
352 in these cases.
353 In the case of a true end-of-file,
354 .I Blinelen
355 will return zero.
356 At the cost of allocating a buffer,
357 .I Brdstr
358 sidesteps these issues.
359 .PP
360 The data returned by
361 .I Brdline
362 may be overwritten by calls to any other
363 .I bio
364 routine on the same
365 .IR bp.