From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/bio.html | 293 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 man/man3/bio.html (limited to 'man/man3/bio.html') 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 @@ + +bio(3) - Plan 9 from User Space + + + + +
+
+
BIO(3)BIO(3) +
+
+

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 + – 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) +
+ + +
+

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(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. 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(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, the number of bytes output is returned. 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
+ +
+ + /usr/local/plan9/src/libbio
+ +
+

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

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3