glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/bio
term% cat index.txt
BIO(2)                        System Calls Manual                       BIO(2)



NAME
       Bopen, Bfdopen, 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

SYNOPSIS
       #include <u.h>
       #include <libc.h>
       #include <bio.h>

       Biobuf* Bopen(char *file, int mode)

       Biobuf* Bfdopen(int fd, int mode)

       int     Binit(Biobuf *bp, int fd, int mode)

       int     Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)

       int     Bterm(Biobufhdr *bp)

       int     Bprint(Biobufhdr *bp, char *format, ...)

       int     Bvprint(Biobufhdr *bp, char *format, va_list arglist);

       void*   Brdline(Biobufhdr *bp, int delim)

       char*   Brdstr(Biobufhdr *bp, int delim, int nulldelim)

       int     Blinelen(Biobufhdr *bp)

       vlong   Boffset(Biobufhdr *bp)

       int     Bfildes(Biobufhdr *bp)

       int     Bgetc(Biobufhdr *bp)

       long    Bgetrune(Biobufhdr *bp)

       int     Bgetd(Biobufhdr *bp, double *d)

       int     Bungetc(Biobufhdr *bp)

       int     Bungetrune(Biobufhdr *bp)

       vlong   Bseek(Biobufhdr *bp, vlong n, int type)

       int     Bputc(Biobufhdr *bp, int c)

       int     Bputrune(Biobufhdr *bp, long c)

       long    Bread(Biobufhdr *bp, void *addr, long nbytes)

       long    Bwrite(Biobufhdr *bp, void *addr, long nbytes)

       int     Bflush(Biobufhdr *bp)

       int     Bbuffered(Biobufhdr *bp)

       void    Blethal(Biobufhdr *bp, void (*errorf)(char *))

DESCRIPTION
       These routines implement fast buffered I/O.  I/O on different file  de‐
       scriptors is independent.

       Bopen  opens  file for mode OREAD or creates for mode OWRITE.  It calls
       malloc(2) to allocate a buffer.

       Bfdopen allocates a buffer for the already-open file descriptor fd  for
       mode OREAD or OWRITE.  It calls malloc(2) to allocate a buffer.

       Binit  initializes  a  standard size buffer, type Biobuf, with the open
       file descriptor passed in by the user.  Binits initializes a  non-stan‐
       dard size buffer, type Biobufhdr, with the open file descriptor, buffer
       area, and buffer size passed in by the user.  Biobuf and Biobufhdr  are
       related by the declaration:

              typedef struct Biobuf Biobuf;
              struct Biobuf
              {
                      Biobufhdr;
                      uchar b[Bungetsize+Bsize];
              };

       Arguments  of  types  pointer to Biobuf and pointer to Biobufhdr can be
       used interchangeably in the following routines.

       Bopen, Binit, or Binits should be called before any of the  other  rou‐
       tines  on  that buffer.  Bfildes returns the integer file descriptor of
       the associated open file.

       Bterm flushes the buffer for bp and returns Bflush's return value.   If
       the  buffer was allocated by Bopen, the buffer is freed and the file is
       closed.

       Brdline reads a string from the file associated with bp up to  and  in‐
       cluding  the first delim character.  The delimiter character at the end
       of the line is not altered, thus the returned string probably won't  be
       NUL-terminated.   Brdline returns a pointer to the start of the line or
       on end-of-file or read error.  Blinelen returns the  length  (including
       the delimiter) of the most recent string returned by Brdline.

       Brdstr returns a malloc(2)-allocated buffer containing the next line of
       input delimited by delim, terminated by a NUL (0)  byte.   Unlike  Brd‐
       line,  which  returns  when its buffer is full even if no delimiter has
       been found, Brdstr will return an arbitrarily long  line  in  a  single
       call.   If nulldelim is set, the terminal delimiter will be overwritten
       with a NUL.  After a successful call to Brdstr,  the  return  value  of
       Blinelen will be the length of the returned buffer, excluding the NUL.

       Bgetc returns the next character from bp, or a negative value at end of
       file.  Bungetc may be called immediately after Bgetc to allow the  same
       character to be reread.

       Bgetrune  calls Bgetc to read the bytes of the next UTF sequence in the
       input stream and returns the value of the rune represented by  the  se‐
       quence.  It returns a negative value at end of file.  Bungetrune may be
       called immediately after Bgetrune to allow the same UTF sequence to  be
       reread as either bytes or a rune.  Bungetc and Bungetrune may back up a
       maximum of five bytes.

       Bgetd uses charstod (see atof(2))  and  Bgetc  to  read  the  formatted
       floating-point  number in the input stream, skipping initial blanks and
       tabs.  The value is stored in *d.

       Bread reads nbytes of data from bp into memory starting at  addr.   The
       number of bytes read is returned on success and a negative value is re‐
       turned if a read error occurred.

       Bseek applies seek(2) to bp.  It returns the new file offset.   Boffset
       returns the file offset of the next character to be processed.

       Bputc  outputs the low order 8 bits of c on bp.  If this causes a write
       to occur and there is an error, a negative value is  returned.   Other‐
       wise, a zero is returned.

       Bputrune  calls Bputc to output the low order 16 bits of c as a rune in
       UTF format on the output stream.

       Bprint is a buffered interface to print(2).  If this causes a write  to
       occur and there is an error, a negative value (Beof) is returned.  Oth‐
       erwise, Bprint returns the number of bytes written.  Bvprint  does  the
       same  except  it  takes  as  argument a va_list parameter, so it can be
       called within a variadic function.

       Bwrite outputs nbytes of data starting at addr to bp.  If this causes a
       write  to  occur  and  there is an error, a negative value is returned.
       Otherwise, the number of bytes written is returned.

       Bflush causes any buffered output associated with  bp  to  be  written.
       The  return is as for Bputc.  Bflush is called on exit for every buffer
       still open for writing.

       Bbuffered returns the number of bytes in  the  buffer.   When  reading,
       this  is  the number of bytes still available from the last read on the
       file; when writing, it is the number of bytes ready to be written.

       Blethal arranges errorf to be called in case of an error  happening  on
       read/write.   An  argument  of  nil will have the program terminated in
       case of error.

SOURCE
       /sys/src/libbio

SEE ALSO
       open(2), print(2), exits(2), utf(6),

DIAGNOSTICS
       Bio routines that return integers yield Beof if bp is not the  descrip‐
       tor  of  an open file.  Bopen returns zero if the file cannot be opened
       in the given mode.  All routines set errstr on error.

       An error during read or write will call an error handler  specified  by
       Blethal, if any.

BUGS
       Brdline  returns  an error on strings longer than the buffer associated
       with the file and also if the end-of-file is encountered before  a  de‐
       limiter.  Blinelen will tell how many characters are available in these
       cases.  In the case of a true end-of-file, Blinelen will  return  zero.
       At the cost of allocating a buffer, Brdstr sidesteps these issues.

       Only  the low byte of Brdstr's delim is examined, so delim cannot be an
       arbitrary rune.

       The data returned by Brdline may be overwritten by calls to  any  other
       bio routine on the same bp.



                                                                        BIO(2)