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)

intBinit(Biobuf ∗bp, int fd, int mode)

intBinits(Biobufhdr ∗bp, int fd, int mode, uchar ∗buf, int size)

intBterm(Biobufhdr ∗bp)

intBprint(Biobufhdr ∗bp, char ∗format, ...) 

void∗Brdline(Biobufhdr ∗bp, int delim)

intBlinelen(Biobufhdr ∗bp)

longBoffset(Biobufhdr ∗bp)

intBfildes(Biobufhdr ∗bp)

intBgetc(Biobufhdr ∗bp)

longBgetrune(Biobufhdr ∗bp)

intBgetd(Biobufhdr ∗bp, double ∗d)

intBungetc(Biobufhdr ∗bp)

intBungetrune(Biobufhdr ∗bp)

longBseek(Biobufhdr ∗bp, long n, int type)

intBputc(Biobufhdr ∗bp, int c)

intBputrune(Biobufhdr ∗bp, long c)

longBread(Biobufhdr ∗bp, void ∗addr, long nbytes)

longBwrite(Biobufhdr ∗bp, void ∗addr, long nbytes)

intBflush(Biobufhdr ∗bp)

intBbuffered(Biobufhdr ∗bp)

/∗ Alef only ∗/

adtBiobufhdr
{
/∗ ... ∗/

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);
};

adtBiobuf
{
Biobufhdr;

/∗ ... ∗/

int   init(∗Biobuf, int, int);
};

Biobuf∗ Bopen(byte∗, int);

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.

­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. 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 ­0 on end-of-file or read error.  ­Blinelen returns the length (including the delimiter) of the most recent string returned by Brdline.

­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, 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 descriptor 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 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. 

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. 

Plan 9  —  April 04, 1995