diff options
Diffstat (limited to 'man/man3/bio.html')
| -rw-r--r-- | man/man3/bio.html | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/man/man3/bio.html b/man/man3/bio.html new file mode 100644 index 00000000..78259922 --- /dev/null +++ b/man/man3/bio.html @@ -0,0 +1,293 @@ +<head> +<title>bio(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>BIO(3)</b><td align=right><b>BIO(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Bopen, Bfdopen, 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<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h><br> + #include <bio.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Biobuf* Bopen(char *file, int mode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Biobuf* Bfdopen(int fd, int mode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Binit(Biobuf *bp, int fd, int mode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Binits(Biobufhdr *bp, int fd, int mode, uchar *buf, int size) + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bterm(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bprint(Biobufhdr *bp, char *format, ...) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bvprint(Biobufhdr *bp, char *format, va_list arglist); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void* Brdline(Biobufhdr *bp, int delim) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* Brdstr(Biobufhdr *bp, int delim, int nulldelim) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Blinelen(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>vlong Boffset(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bfildes(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bgetc(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long Bgetrune(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bgetd(Biobufhdr *bp, double *d) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bungetc(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bungetrune(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>vlong Bseek(Biobufhdr *bp, vlong n, int type) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bputc(Biobufhdr *bp, int c) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bputrune(Biobufhdr *bp, long c) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long Bread(Biobufhdr *bp, void *addr, long nbytes) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long Bwrite(Biobufhdr *bp, void *addr, long nbytes) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bflush(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int Bbuffered(Biobufhdr *bp) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + These routines implement fast buffered I/O. I/O on different file + descriptors is independent. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bopen</i> opens <i>file</i> for mode <tt><font size=+1>OREAD</font></tt> or creates for mode <tt><font size=+1>OWRITE</font></tt>. It + calls <a href="../man3/malloc.html"><i>malloc</i>(3)</a> to allocate a buffer. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bfdopen</i> allocates a buffer for the already-open file descriptor + <i>fd</i> for mode <tt><font size=+1>OREAD</font></tt> or <tt><font size=+1>OWRITE</font></tt>. It calls <a href="../man3/malloc.html"><i>malloc</i>(3)</a> to allocate a + buffer. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Binit</i> initializes a standard size buffer, type <i>Biobuf</i>, with the + open file descriptor passed in by the user. <i>Binits</i> initializes + a non-standard size buffer, type <i>Biobufhdr</i>, with the open file + descriptor, buffer area, and buffer size passed in by the user. + <i>Biobuf</i> and <i>Biobufhdr</i> are related by the declaration: + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>typedef struct Biobuf Biobuf;<br> + struct Biobuf<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Biobufhdr;<br> + uchar b[Bungetsize+Bsize];<br> + + </table> + };<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Arguments of types pointer to Biobuf and pointer to Biobufhdr + can be used interchangeably in the following routines. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bopen</i>, <i>Binit</i>, or <i>Binits</i> should be called before any of the other + routines on that buffer. <i>Bfildes</i> returns the integer file descriptor + of the associated open file. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bterm</i> flushes the buffer for <i>bp</i>. If the buffer was allocated by + <i>Bopen</i>, the buffer is <i>freed</i> and the file is closed. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Brdline</i> reads a string from the file associated with <i>bp</i> up to + and including the first <i>delim</i> character. The delimiter character + at the end of the line is not altered. <i>Brdline</i> returns a pointer + to the start of the line or <tt><font size=+1>0</font></tt> on end-of-file or read error. <i>Blinelen</i> + returns the length (including the delimiter) of the most recent + string + returned by <i>Brdline</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Brdstr</i> returns a <a href="../man3/malloc.html"><i>malloc</i>(3)</a>-allocated buffer containing the next + line of input delimited by <i>delim</i>, terminated by a NUL (0) byte. + Unlike <i>Brdline</i>, which returns when its buffer is full even if + no delimiter has been found, <i>Brdstr</i> will return an arbitrarily + long line in a single call. If <i>nulldelim</i> is set, the terminal + delimiter will be + overwritten with a NUL. After a successful call to <i>Brdstr</i>, the + return value of <i>Blinelen</i> will be the length of the returned buffer, + excluding the NUL. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bgetc</i> returns the next character from <i>bp</i>, or a negative value + at end of file. <i>Bungetc</i> may be called immediately after <i>Bgetc</i> + to allow the same character to be reread. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bgetrune</i> calls <i>Bgetc</i> 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. <i>Bungetrune</i> + may be called immediately after <i>Bgetrune</i> to allow the same UTF + sequence to be reread as either bytes or a rune. + <i>Bungetc</i> and <i>Bungetrune</i> may back up a maximum of five bytes. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bgetd</i> uses <i>charstod</i> (see <a href="../man3/atof.html"><i>atof</i>(3)</a>) and <i>Bgetc</i> to read the formatted + floating-point number in the input stream, skipping initial blanks + and tabs. The value is stored in <tt><font size=+1>*d. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <i>Bread</i> reads <i>nbytes</i> of data from <i>bp</i> into memory starting at <i>addr</i>. + The number of bytes read is returned on success and a negative + value is returned if a read error occurred. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bseek</i> applies <a href="../man3/seek.html"><i>seek</i>(3)</a> to <i>bp</i>. It returns the new file offset. <i>Boffset</i> + returns the file offset of the next character to be processed. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bputc</i> outputs the low order 8 bits of <i>c</i> on <i>bp</i>. If this causes + a <i>write</i> to occur and there is an error, a negative value is returned. + Otherwise, a zero is returned. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bputrune</i> calls <i>Bputc</i> to output the low order 16 bits of <i>c</i> as a + rune in UTF format on the output stream. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bprint</i> is a buffered interface to <a href="../man3/print.html"><i>print</i>(3)</a>. If this causes a <i>write</i> + to occur and there is an error, a negative value (<tt><font size=+1>Beof</font></tt>) is returned. + Otherwise, the number of bytes output is returned. <i>Bvprint</i> does + the same except it takes as argument a <tt><font size=+1>va_list</font></tt> parameter, so it + can be called within a variadic function. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bwrite</i> outputs <i>nbytes</i> of data starting at <i>addr</i> to <i>bp</i>. If this + causes a <i>write</i> to occur and there is an error, a negative value + is returned. Otherwise, the number of bytes written is returned. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bflush</i> causes any buffered output associated with <i>bp</i> to be written. + The return is as for <i>Bputc</i>. <i>Bflush</i> is called on exit for every + buffer still open for writing. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bbuffered</i> 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.<br> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/libbio<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man3/open.html"><i>open</i>(3)</a>, <a href="../man3/print.html"><i>print</i>(3)</a>, <a href="../man3/exits.html"><i>exits</i>(3)</a>, <a href="../man7/utf.html"><i>utf</i>(7)</a>,<br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Bio</i> routines that return integers yield <tt><font size=+1>Beof</font></tt> if <i>bp</i> is not the + descriptor of an open file. <i>Bopen</i> returns zero if the file cannot + be opened in the given mode. All routines set <i>errstr</i> on error.<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Brdline</i> 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</i> will tell how many characters are available + in these cases. In the case of a true end-of-file, <i>Blinelen</i> will + return zero. At the cost of allocating a buffer, <i>Brdstr</i> sidesteps + these issues. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The data returned by <i>Brdline</i> may be overwritten by calls to any + other <i>bio</i> routine on the same <i>bp.</i><br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |