Subversion Repositories planix.SVN

.TH BIO 2

.SH 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/output

.SH SYNOPSIS

.ta \w'Biobuf* 'u

.B #include <u.h>

.br

.B #include <libc.h>

.br

.B #include <bio.h>

.PP

.B

Biobuf* Bopen(char *file, int mode)

.PP

.B

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

.PP

.B

int	Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size)

.PP

.B

int	Bterm(Biobufhdr *bp)

.PP

.B

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

.PP

.B

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

.PP

.B

void*	Brdline(Biobufhdr *bp, int delim)

.PP

.B

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

.PP

.B

int	Blinelen(Biobufhdr *bp)

.PP

.B

vlong	Boffset(Biobufhdr *bp)

.PP

.B

int	Bfildes(Biobufhdr *bp)

.PP

.B

int	Bgetc(Biobufhdr *bp)

.PP

.B

long	Bgetrune(Biobufhdr *bp)

.PP

.B

int	Bgetd(Biobufhdr *bp, double *d)

.PP

.B

int	Bungetc(Biobufhdr *bp)

.PP

.B

int	Bungetrune(Biobufhdr *bp)

.PP

.B

vlong	Bseek(Biobufhdr *bp, vlong n, int type)

.PP

.B

int	Bputc(Biobufhdr *bp, int c)

.PP

.B

int	Bputrune(Biobufhdr *bp, long c)

.PP

.B

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

.PP

.B

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

.PP

.B

int	Bflush(Biobufhdr *bp)

.PP

.B

int	Bbuffered(Biobufhdr *bp)

.PP

.SH DESCRIPTION

These routines implement fast buffered I/O.

I/O on different file descriptors is independent.

.PP

.I Bopen

opens

.I file

for mode

.B OREAD

or creates for mode

.BR OWRITE .

It calls

.IR malloc (2)

to allocate a buffer.

.PP

.I Binit

initializes a standard size buffer, type

.IR Biobuf ,

with the open file descriptor passed in

by the user.

.I Binits

initializes a non-standard size buffer, type

.IR Biobufhdr ,

with the open file descriptor,

buffer area, and buffer size passed in

by the user.

.I Biobuf

and

.I Biobufhdr

are related by the declaration:

.IP

.EX

typedef struct Biobuf Biobuf;

struct Biobuf

{

	Biobufhdr;

	uchar b[Bungetsize+Bsize];

};

.EE

.PP

Arguments

of types pointer to Biobuf and pointer to Biobufhdr

can be used interchangeably in the following routines.

.PP

.IR Bopen ,

.IR Binit ,

or

.I Binits

should be called before any of the

other routines on that buffer.

.I Bfildes

returns the integer file descriptor of the associated open file.

.PP

.I Bterm

flushes the buffer for

.IR bp

and returns

.IR Bflush 's

return value.

If the buffer was allocated by

.IR Bopen ,

the buffer is

.I freed

and the file is closed.

.PP

.I Brdline

reads a string from the file associated with

.I bp

up to and including the first

.I delim

character.

The delimiter character at the end of the line is

not altered, thus the returned string probably won't be NUL-terminated.

.I Brdline

returns a pointer to the start of the line or

.L 0

on end-of-file or read error.

.I Blinelen

returns the length (including the delimiter)

of the most recent string returned by

.IR Brdline .

.PP

.I Brdstr

returns a

.IR malloc (2)-allocated

buffer containing the next line of input delimited by

.IR delim ,

terminated by a NUL (0) byte.

Unlike

.IR Brdline ,

which returns when its buffer is full even if no delimiter has been found,

.I Brdstr

will return an arbitrarily long line in a single call.

If

.I nulldelim

is set, the terminal delimiter will be overwritten with a NUL.

After a successful call to

.IR Brdstr ,

the return value of

.I Blinelen

will be the length of the returned buffer, excluding the NUL.

.PP

.I Bgetc

returns the next character from

.IR bp ,

or a negative value

at end of file.

.I Bungetc

may be called immediately after

.I Bgetc

to allow the same character to be reread.

.PP

.I Bgetrune

calls

.I Bgetc

to read the bytes of the next

.SM 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.

.I Bungetrune

may be called immediately after

.I Bgetrune

to allow the same

.SM UTF

sequence to be reread as either bytes or a rune.

.I Bungetc

and

.I Bungetrune

may back up a maximum of five bytes.

.PP

.I Bgetd

uses

.I charstod

(see

.IR atof (2))

and

.I Bgetc

to read the formatted

floating-point number in the input stream,

skipping initial blanks and tabs.

The value is stored in

.BR *d.

.PP

.I Bread

reads

.I nbytes

of data from

.I bp

into memory starting at

.IR addr .

The number of bytes read is returned on success

and a negative value is returned if a read error occurred.

.PP

.I Bseek

applies

.IR seek (2)

to

.IR bp .

It returns the new file offset.

.I Boffset

returns the file offset of the next character to be processed.

.PP

.I Bputc

outputs the low order 8 bits of

.I c

on

.IR bp .

If this causes a

.IR write

to occur and there is an error,

a negative value is returned.

Otherwise, a zero is returned.

.PP

.I Bputrune

calls

.I Bputc

to output the low order

21 bits of

.I c

as a rune

in

.SM UTF

format

on the output stream.

.PP

.I Bprint

is a buffered interface to

.IR print (2).

If this causes a

.IR write

to occur and there is an error,

a negative value

.RB ( Beof )

is returned.

Otherwise, 

.I Bprint

returns the number of bytes written.

.I Bvprint

does the same except it takes as argument a

.B va_list

parameter, so it can be called within a variadic function.

.PP

.I Bwrite

outputs

.I nbytes

of data starting at

.I addr

to

.IR bp .

If this causes a

.IR write

to occur and there is an error,

a negative value is returned.

Otherwise, the number of bytes written is returned.

.PP

.I Bflush

causes any buffered output associated with

.I bp

to be written.

The return is as for

.IR Bputc .

.I Bflush

is called on

exit for every buffer still open

for writing.

.PP

.I 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.

.SH SOURCE

.B /sys/src/libbio

.SH SEE ALSO

.IR open (2),

.IR print (2),

.IR exits (2),

.IR utf (6),

.SH DIAGNOSTICS

.I Bio

routines that return integers yield

.B Beof

if 

.I bp

is not the descriptor of an open file.

.I Bopen

returns zero if the file cannot be opened in the given mode.

All routines set

.I errstr

on error.

.SH BUGS

.I 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.

.I Blinelen

will tell how many characters are available

in these cases.

In the case of a true end-of-file,

.I Blinelen

will return zero.

At the cost of allocating a buffer,

.I Brdstr

sidesteps these issues.

.PP

Only the low byte of

.IR Brdstr 's

.I delim

is examined, so

.I delim

cannot be an arbitrary rune.

.PP

The data returned by

.I Brdline

may be overwritten by calls to any other

.I bio

routine on the same

.IR bp.