bio.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.