tbio.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tbio.3 (6792B)
---
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 <utf.h>
7 .br
8 .B #include <fmt.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 O_RDONLY
93 or creates for mode
94 .BR O_WRONLY .
95 It calls
96 .IR 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 O_RDONLY
104 or
105 .BR O_WRONLY .
106 It calls
107 .IR 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 .IR 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 fmtcharstod
227 (see
228 .IR fmtstrtod (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 .IR lseek (2)
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 .IR 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, the number of bytes output is returned.
289 .I Bvprint
290 does the same except it takes as argument a
291 .B va_list
292 parameter, so it can be called within a variadic function.
293 .PP
294 .I Bwrite
295 outputs
296 .I nbytes
297 of data starting at
298 .I addr
299 to
300 .IR bp .
301 If this causes a
302 .IR write
303 to occur and there is an error,
304 a negative value is returned.
305 Otherwise, the number of bytes written is returned.
306 .PP
307 .I Bflush
308 causes any buffered output associated with
309 .I bp
310 to be written.
311 The return is as for
312 .IR Bputc .
313 .I Bflush
314 is called on
315 exit for every buffer still open
316 for writing.
317 .PP
318 .I Bbuffered
319 returns the number of bytes in the buffer.
320 When reading, this is the number of bytes still available from the last
321 read on the file; when writing, it is the number of bytes ready to be
322 written.
323 .SH SOURCE
324 .B https://9fans.github.io/plan9port/unix
325 .SH SEE ALSO
326 .IR open (2),
327 .IR print (3),
328 .IR atexit (3),
329 .IR utf (7),
330 .SH DIAGNOSTICS
331 .I Bio
332 routines that return integers yield
333 .B Beof
334 if
335 .I bp
336 is not the descriptor of an open file.
337 .I Bopen
338 returns zero if the file cannot be opened in the given mode.
339 All routines set
340 .I errstr
341 on error.
342 .SH BUGS
343 .I Brdline
344 returns an error on strings longer than the buffer associated
345 with the file
346 and also if the end-of-file is encountered
347 before a delimiter.
348 .I Blinelen
349 will tell how many characters are available
350 in these cases.
351 In the case of a true end-of-file,
352 .I Blinelen
353 will return zero.
354 At the cost of allocating a buffer,
355 .I Brdstr
356 sidesteps these issues.
357 .PP
358 The data returned by
359 .I Brdline
360 may be overwritten by calls to any other
361 .I bio
362 routine on the same
363 .IR bp.