BIO(2)                                                     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)

     Page 1                       Plan 9             (printed 3/19/24)

     BIO(2)                                                     BIO(2)

          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 *))

          void    Biofn(Biobufhdr *bp, int (*iof)(Biobufhdr *, void *,
          long))

     DESCRIPTION
          These routines implement fast buffered I/O.  I/O on differ-
          ent file descriptors 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 ini-
          tializes a non-standard 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 rou-
          tines.

          Bopen, Binit, or Binits should be called before any of the
          other routines 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 or Bfdopen, the
          buffer is freed and the file is closed.

     Page 2                       Plan 9             (printed 3/19/24)

     BIO(2)                                                     BIO(2)

          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 `0' 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 Brdline, 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, exclud-
          ing 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 for-
          matted 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.  Otherwise, 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

     Page 3                       Plan 9             (printed 3/19/24)

     BIO(2)                                                     BIO(2)

          (Beof) is returned.  Otherwise, 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 nega-
          tive 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.

          If Biofn is called with a non-nil iof function, then that
          function is called for I/O in lieu of read(2) and write. A
          nil argument for iof restores normal behaviour.

     SOURCE
          /sys/src/libbio

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

     DIAGNOSTICS
          Bio routines that return integers yield Beof if bp is not
          the descriptor 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 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.

     Page 4                       Plan 9             (printed 3/19/24)

     BIO(2)                                                     BIO(2)

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

     Page 5                       Plan 9             (printed 3/19/24)