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)
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 different 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
initializes 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 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
and returns
Bflush’s
return value.
If the buffer was allocated by
Bopen
or
Bfdopen,
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
0
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
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 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.
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,
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.
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
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.
The data returned by
Brdline
may be overwritten by calls to any other
bio
routine on the same
bp.