sys/man/2/bio

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