BIO(3)                    OpenBSD Programmer's Manual                   BIO(3)



NAME
       Bopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetd, Bungetc, Bread,
       Bseek, Boffset, Bfildes, Blinelen, Bputc, Bprint, Bvprint, Bwrite,
       Bflush, Bterm, Bbuffered - buffered input/output

SYNOPSIS
       #include <fmt.h> #include <bio.h>

       Biobuf* Bopen(char *file, int mode)

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

       int     Bterm(Biobuf *bp)

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

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

       void*   Brdline(Biobuf *bp, int delim)

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

       int     Blinelen(Biobuf *bp)

       off_t   Boffset(Biobuf *bp)

       int     Bfildes(Biobuf *bp)

       int     Bgetc(Biobuf *bp)

       long    Bgetrune(Biobufhdr *bp)

       int     Bgetd(Biobuf *bp, double *d)

       int     Bungetc(Biobuf *bp)

       int     Bungetrune(Biobufhdr *bp)

       off_t   Bseek(Biobuf *bp, off_t n, int type)

       int     Bputc(Biobuf *bp, int c)

       int     Bputrune(Biobufhdr *bp, long c)

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

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

       int     Bflush(Biobuf *bp)

       int     Bbuffered(Biobuf *bp)

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

       Bopen opens file for mode O_RDONLY or creates for mode O_WRONLY.  It
       calls malloc(3) to allocate a buffer.

       Binit initializes a buffer with the open file descriptor passed in by
       the user.

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

       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.  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.  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(3)-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, excluding the NUL.

       Bgetc returns the next byte from bp, or a negative value at end of
       file.  Bungetc may be called immediately after Bgetc to allow the same
       byte 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 fmtcharstod (undocumented) 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 lseek(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 (Beof) is returned.
       Otherwise, the number of bytes output is returned.  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.

       This library uses fmt(3) for diagnostic messages about internal errors,
       as well as for the implementation of Bprint and Bvprint.  It uses
       utf(3) for the implementation of Bgetrune and Bputrune.

SEE ALSO
       atexit(3).  open(2), print(3), utf(7)

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.

HISTORY
       The bio(3) library originally appeared in Plan 9.  This is a port of
       the Plan 9 bio library.

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.

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



                                                                        BIO(3)
