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