glenda.party
term% ls -F
term% cat index.txt
BIO(2)                        System Calls Manual                       BIO(2)



NAME
       Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc,
       Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc,  Bputrune,
       Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered - buffered input/out‐
       put

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

       Biobuf* Bopen(char *file, 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)

DESCRIPTION
       These routines implement fast buffered  I/O.   I/O  on  different  file
       descriptors is independent.

       Bopen  opens  file for mode OREAD or creates for mode 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
       including 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 (includ‐
       ing 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
       sequence.  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
       returned 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 21 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.

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.

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
       delimiter.   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)