term% cat index.txt BIO(2) System Calls Manual BIO(2)
NAME
Bopen, Binit, Binits, Brdline, Bgetc, Bgetrune, Bgetd, Bungetc,
Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune,
Bprint, Bwrite, Bflush, Bterm, Bbuffered - buffered input/output
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, ...)
void* Brdline(Biobufhdr *bp, int delim)
int Blinelen(Biobufhdr *bp)
long 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)
long Bseek(Biobufhdr *bp, long 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)
/* Alef only */
adt Biobufhdr
{
/* ... */
int buffered(*Biobufhdr);
int term(*Biobufhdr);
int fildes(*Biobufhdr);
int flush(*Biobufhdr);
int getc(*Biobufhdr);
int getrune(*Biobufhdr);
int inits(*Biobufhdr, int, int, byte*, int);
int linelen(*Biobufhdr);
int offset(*Biobufhdr);
int print(*Biobufhdr, byte*, ...);
int putc(*Biobufhdr, int);
int putrune(*Biobufhdr, int);
void* rdline(*Biobufhdr, int);
int read(*Biobufhdr, void*, int);
int seek(*Biobufhdr, int, int);
int ungetc(*Biobufhdr);
int ungetrune(*Biobufhdr);
int write(*Biobufhdr, void*, int);
};
adt Biobuf
{
Biobufhdr;
/* ... */
int init(*Biobuf, int, int);
};
Biobuf* Bopen(byte*, int);
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.
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. 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. 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 Brd‐
line.
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, the number of bytes output is returned.
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.
The macros BGETC, BPUTC, BOFFSET, BFILDES, and BLINELEN are provided as
fast versions of the corresponding routines.
Alef
The Alef implementation has the same semantics but is structured as an
adt with functions named the same (except for a leading B) and taking
the buffer pointer as implicit first argument. The only exception is
Bopen, which is the same as in C. There is no getd in Alef Bio.
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 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.
The data returned by Brdline may be overwritten by calls to any other
bio routine on the same bp.
Alef Bopen should be part of the adt and written .Biobuf.open but its
implementation predates that syntax.
BIO(2)