diff options
Diffstat (limited to 'static/plan9-4e/man2/fopen.2')
| -rw-r--r-- | static/plan9-4e/man2/fopen.2 | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/static/plan9-4e/man2/fopen.2 b/static/plan9-4e/man2/fopen.2 new file mode 100644 index 00000000..40abf9d7 --- /dev/null +++ b/static/plan9-4e/man2/fopen.2 @@ -0,0 +1,352 @@ +.TH FOPEN 2 +.SH NAME +fopen, freopen, fdopen, fileno, fclose, sopenr, sopenw, sclose, fflush, setvbuf, setbuf, fgetpos, ftell, fsetpos, fseek, rewind, feof, ferror, clearerr \- standard buffered input/output package +.SH SYNOPSIS +.B #include <stdio.h> +.PP +.ta \w'\fLFILE 'u +.B +FILE *fopen(char *filename, char *mode) +.PP +.B +FILE *freopen(char *filename, char *mode, FILE *f) +.PP +.B +FILE *fdopen(int fd, char *mode) +.PP +.B +int fileno(FILE *f) +.PP +.B +FILE *sopenr(char *s) +.PP +.B +FILE *sopenw(void) +.PP +.B +char *sclose(FILE *f) +.PP +.B +int fclose(FILE *f) +.PP +.B +int fflush(FILE *f) +.PP +.B +int setvbuf(FILE *f, char *buf, int type, long size) +.PP +.B +void setbuf(FILE *f, char *buf) +.PP +.B +int fgetpos(FILE *f, long *pos) +.PP +.B +long ftell(FILE *f) +.PP +.B +int fsetpos(FILE *f, long *pos) +.PP +.B +int fseek(FILE *f, long offset, int whence) +.PP +.B +void rewind(FILE *f) +.PP +.B +int feof(FILE *f) +.PP +.B +int ferror(FILE *f) +.PP +.B +void clearerr(FILE *f) +.SH DESCRIPTION +The functions described in this and related pages +.RI ( fgetc (2), +.IR fprintf (2), +.IR fscanf (2), +and +.IR tmpfile (2)) +implement the +ANSI C buffered I/O package with extensions. +.PP +A file with associated buffering is called a +.I stream +and is declared to be a pointer to a defined type +.BR FILE . +.IR Fopen (2) +creates certain descriptive data for a stream +and returns a pointer to designate the stream in all +further transactions. +There are three normally open streams with constant +pointers declared in +the include file and associated with the standard open files: +.TP 10n +.BR stdin +standard input file +.br +.ns +.TP +.B stdout +standard output file +.br +.ns +.TP +.B stderr +standard error file +.PP +A constant pointer +.B NULL +designates no stream at all. +.PP +.I Fopen +opens the file named by +.I filename +and associates a stream with it. +.I Fopen +returns a pointer to be used to identify +the stream in subsequent operations, or +.B NULL +if the open fails. +.I Mode +is a character string having one of the following values: +.nf +.ta 8n +\fL"r"\fP open for reading +\fL"w"\fP truncate to zero length or create for writing +\fL"a"\fP append; open or create for writing at end of file +\fL"r+"\fP open for update (reading and writing) +\fL"w+"\fP truncate to zero length or create for update +\fL"a+"\fP append; open or create for update at end of file +.fi +.PP +In addition, each of the above strings can have a +.L b +somewhere after the first character, +meaning `binary file', but this implementation makes no distinction +between binary and text files. +.PP +.I Fclose +causes the stream pointed to by +.I f +to be flushed (see below) and does a +.I close +(see +.IR open (2)) +on the associated file. +It frees any automatically allocated buffer. +.I Fclose +is called automatically on +.IR exits (2) +for all open streams. +.PP +.I Freopen +is like open except that it reuses stream pointer +.IR f . +.I Freopen +first attempts to close any file associated with +.IR f ; +it ignores any errors in that close. +.PP +.I Fdopen +associates a stream with an open Plan 9 file descriptor. +.PP +.I Fileno +returns the number of the Plan 9 file descriptor associated with the stream. +.PP +.I Sopenr +associates a read-only stream with a null-terminated string. +.PP +.I Sopenw +opens a stream for writing. +No file descriptor is associated with the stream; +instead, all output is written to the stream buffer. +.PP +.I Sclose +closes a stream opened with +.I sopenr +or +.IR sopenw . +It returns a pointer to the 0 terminated buffer associated with the stream. +.PP +By default, output to a stream is fully buffered: it is accumulated in +a buffer until the buffer is full, and then +.I write +(see +.IR read (2)) +is used to write the buffer. +An exception is standard error, which is line buffered: +output is accumulated in a buffer until +a newline is written. +Input is also fully buffered by default; this means that +.IR read (2) +is used to fill a buffer as much as it can, and then characters +are taken from that buffer until it empties. +.I Setvbuf +changes the buffering method for file +.I f +according to +.IR type: +either +.B _IOFBF +for fully buffered, +.B _IOLBF +for line buffered, +or +.B _IONBF +for unbuffered (each character causes a +.I read +or +.IR write). +If +.I buf +is supplied, it is used as the buffer and +.I size +should be its size; +If +.I buf +is zero, a buffer of the given size is allocated (except for the unbuffered case) using +.IR malloc (2). +.PP +.I Setbuf +is an older method for changing buffering. If +.I buf +is supplied, it changes to fully buffered with the given buffer, which should +be of size +.B BUFSIZ +(defined in +.BR stdio.h ). +If +.I buf +is zero, the buffering method changes to unbuffered. +.PP +.I Fflush +flushes the buffer of output stream +.IR f , +delivering any unwritten buffered data to the host file. +.PP +There is a +.I file position indicator +associated with each stream. +It starts out pointing at the first character (unless the file is opened +with append mode, in which case the indicator is always ignored). +The file position indicator is maintained by the reading and writing +functions described in +.IR fgetc (2). +.PP +.I Fgetpos +stores the current value of the file position indicator for stream +.I f +in the object pointed to by +.IR pos . +It returns zero on success, nonzero otherwise. +.I Ftell +returns the current value of the file position indicator. +The file position indicator is to +be used only as an argument to +.IR fseek. +.PP +.I Fsetpos +sets the file position indicator for stream +.I f +to the value of the object pointed to by +.IR pos , +which shall be a value returned by an earlier call to +.I fgetpos +on the same stream. +It returns zero on success, nonzero otherwise. +.I Fseek +obtains a new position, measured in characters from the beginning +of the file, by adding +.I offset +to the position specified by +.IR whence : +the beginning of the file if +.I whence +is +.BR SEEK_SET ; +the current value of the file position indicator for +.BR SEEK_CUR ; +and the end-of-file for +.BR SEEK_END . +.I Rewind +sets the file position indicator to the beginning of the file. +.PP +An integer constant +.B EOF +is returned +upon end of file or error by integer-valued functions that +deal with streams. +.I Feof +returns non-zero if and only if +.I f +is at its end of file. +.PP +.I Ferror +returns non-zero if and only if +.I f +is in the error state. It can get into the error state +if a system call failed on the associated file +or a memory allocation failed. +.I Clearerr +takes a stream out of the error state. +.SH SOURCE +.B /sys/src/libstdio +.SH "SEE ALSO" +.IR fprintf (2), +.IR fscanf (2), +.IR fgetc (2) +.br +.IR open (2), +.IR read (2) +.SH DIAGNOSTICS +The value +.B EOF +is returned uniformly to indicate that a +.B FILE +pointer has not been initialized with +.IR fopen , +input (output) has been attempted on an output (input) stream, +or a +.B FILE +pointer designates corrupt or otherwise unintelligible +.B FILE +data. +.br +Some of these functions set +.IR errstr . +.SH BUGS +Buffering of output can prevent output data +from being seen until long after it is computed \- perhaps +never, as when an abort occurs between buffer filling and flushing. +.br +Buffering of input can cause a process to consume +more input than it actually uses. +This can cause trouble across +.IR exec (2). +.br +Buffering may delay the receipt of a write error until a subsequent +.I stdio +writing, seeking, or file-closing call. +.br +ANSI says that a file can be fully buffered only if +the file is not attached to an interactive device. +In Plan 9 all are fully buffered except standard error. +.PP +.IR Fdopen , +.IR fileno , +.IR sopenr , +.IR sopenw , +and +.I sclose +are not ANSI Stdio functions. +.PP +Stdio offers no support for runes or +.SM UTF +characters. +Unless external compatibility is necessary, use +.IR bio (2), +which supports +.SM UTF +and is smaller, faster, and simpler than Stdio. |