BIO(3)

💖 BIO(3) — Library Functions Manual 💖

🌸 NAME 🌸

Buffered input/output — the whole squad is: Bopen, Bfdopen, Binit, Binits, Brdline, Brdstr, Bgetc, Bgetrune, Bgetd, Bungetc, Bungetrune, Bread, Bseek, Boffset, Bfildes, Blinelen, Bputc, Bputrune, Bprint, Bvprint, Bwrite, Bflush, Bterm, Bbuffered.

✨ 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)

🦋 DESCRIPTION 🦋

Okay so these routines are literally fast buffered I/O, and I/O on different file descriptors is independent. No cap.

• Bopen — opens file for mode OREAD or creates it for mode OWRITE. It calls malloc(3) to allocate a buffer. 💅
• Bfdopen — allocates a buffer for the already-open file descriptor fd for mode OREAD or OWRITE. It calls malloc(3) 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. It 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 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(3)) 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(3) 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(3). 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. 🌈

🍓 SOURCE 🍓

/src/libbio — that's where this lives, bestie.

🦋 SEE ALSO 🦋

open(3), print(3), exits(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.
• 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. 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. 🫠

💌 okay that's the whole BIO(3) page from the Library Functions Manual — footer vibes only, no extra date in sight. Catch you in the next one, bestie 💋