wmii

git clone git://oldgit.suckless.org/wmii/
Log | Files | Refs | README | LICENSE

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.