diff options
Diffstat (limited to 'static/netbsd/man3/stdio.3')
| -rw-r--r-- | static/netbsd/man3/stdio.3 | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/static/netbsd/man3/stdio.3 b/static/netbsd/man3/stdio.3 new file mode 100644 index 00000000..7c206bc7 --- /dev/null +++ b/static/netbsd/man3/stdio.3 @@ -0,0 +1,347 @@ +.\" $NetBSD: stdio.3,v 1.28 2020/08/29 15:25:57 rillig Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 +.\" +.Dd August 29, 2020 +.Dt STDIO 3 +.Os +.Sh NAME +.Nm stdio +.Nd standard input/output library functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Vt FILE *stdin; +.Vt FILE *stdout; +.Vt FILE *stderr; +.Sh DESCRIPTION +The standard +.Tn I/O +library provides a simple and efficient buffered stream +.Tn I/O +interface. +Input and output is mapped into logical data streams +and the physical +.Tn I/O +characteristics are concealed. +.Pp +A stream is associated with an external file (which may be a physical +device) by +.Em opening +a file, which may involve creating a new file. +Creating an existing file causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, as opposed +to a terminal) then a +.Em file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. +If append mode is used, the position indicator is placed at the end-of-file. +The position indicator is maintained by subsequent reads, writes +and positioning requests. +All input occurs as if the characters were read by successive calls to the +.Xr fgetc 3 +function; all output takes place as if all characters were +written by successive calls to the +.Xr fputc 3 +function. +.Pp +A file is disassociated from a stream by +.Em closing +the file. +Output streams are flushed (any unwritten buffer contents are transferred +to the host environment) before the stream is disassociated from the file. +The value of a pointer to a +.Dv FILE +object is indeterminate after a file is closed (garbage). +.Pp +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be repositioned +at the start). +If the main function returns to its original caller, or the +.Xr exit 3 +function is called, all open files are closed (hence all output +streams are flushed) before program termination. +Other methods of program termination, such as +.Xr abort 3 +do not bother about closing files properly. +.Pp +This implementation needs and makes +no distinction between +.Dq text +and +.Dq binary +streams. +In effect, all streams are binary. +No translation is performed and no extra padding appears on any stream. +.Pp +At program startup, three streams are predefined and need not be +opened explicitly: +.Bl -enum -offset indent +.It +.Em standard input +for reading conventional input, +.It +.Em standard output +for writing conventional output, and +.It +.Em standard error +for writing diagnostic output. +.El +.Pp +These streams are abbreviated +.Em stdin , +.Em stdout , +and +.Em stderr . +.Pp +Initially, the standard error stream +is unbuffered; the standard input and output streams are +fully buffered if and only if the streams do not refer to +an interactive or +.Dq terminal +device, as determined by the +.Xr isatty 3 +function. +In fact, +.Em all +freshly-opened streams that refer to terminal devices +default to line buffering, and +pending output to such streams is written automatically +whenever such an input stream is read. +Note that this applies only to +.Dq "true reads" ; +if the read request can be satisfied by existing buffered data, +no automatic flush will occur. +In these cases, +or when a large amount of computation is done after printing +part of a line on an output terminal, it is necessary to +.Xr fflush 3 +the standard output before going off and computing so that the output +will appear. +Alternatively, these defaults may be modified via the +.Xr setvbuf 3 +function. +.Sh IMPLEMENTATION NOTES +In multi-threaded applications, operations on streams perform implicit +locking, except for the +.Fn getc_unlocked , +.Fn getchar_unlocked , +.Fn putc_unlocked , +and +.Fn putchar_unlocked +functions. +Explicit control of stream locking is available through the +.Fn flockfile , +.Fn ftrylockfile , +and +.Fn funlockfile +functions . +.Pp +The following are defined as macros; these names may not be re-used +without first removing their current definitions with +.Dv #undef : +.Dv BUFSIZ , +.Dv EOF , +.Dv FILENAME_MAX , +.Dv FOPEN_MAX , +.Dv L_cuserid , +.Dv L_ctermid , +.Dv L_tmpnam , +.Dv NULL , +.Dv SEEK_END , +.Dv SEEK_SET , +.Dv SEE_CUR , +.Dv TMP_MAX , +.Fn clearerr , +.Fn feof , +.Fn ferror , +.Fn fileno , +.Fn freopen , +.Fn fwopen , +.Fn getc , +.Fn getc_unlocked , +.Fn getchar , +.Fn getchar_unlocked , +.Fn putc , +.Fn putc_unlocked , +.Fn putchar , +.Fn putchar_unlocked , +.Dv stderr , +.Dv stdin , +.Dv stdout . +.Pp +Function versions of the macro functions +.Fn feof , +.Fn ferror , +.Fn clearerr , +.Fn fileno , +.Fn getc , +.Fn getc_unlocked , +.Fn getchar , +.Fn getchar_unlocked , +.Fn putc , +.Fn putc_unlocked , +.Fn putchar , +and +.Fn putchar_unlocked +exist and will be used if the macros definitions are explicitly removed. +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 +.Sh STANDARDS +The +.Nm +library conforms to +.St -ansiC . +.Sh LIST OF FUNCTIONS +.Bl -column "putchar_unlocked" "Description" +.It Sy Function Description +.It asprintf formatted output conversion with allocation +.It asprintf_l formatted output conversion with allocation +.It clearerr check and reset stream status +.It dprintf formatted output conversion +.It dprintf_l formatted output conversion +.It fclose close a stream +.It fdopen stream open functions +.It feof check and reset stream status +.It ferror check and reset stream status +.It fflush flush a stream +.It fgetc get next character or word from input stream +.It fgetln get a line from a stream +.It fgetpos reposition a stream +.It fgets get a line from a stream +.It fgetwc get next wide character from input stream +.It fileno check and reset stream status +.It flockfile lock a stream +.It fmemopen open a stream that points to a memory buffer +.It fopen stream open functions +.It fprintf formatted output conversion +.It fprintf_l formatted output conversion +.It fpurge flush a stream +.It fputc output a character or word to a stream +.It fputs output a line to a stream +.It fputwc output a wide character to a stream +.It fread binary stream input/output +.It freopen stream open functions +.It fropen open a stream +.It fscanf input format conversion +.It fscanf_l input format conversion +.It fseek reposition a stream +.It fseeko reposition a stream +.It fsetpos reposition a stream +.It ftell reposition a stream +.It ftello reposition a stream +.It ftrylockfile lock a stream (non-blocking) +.It funlockfile unlock a stream +.It funopen open a stream +.It funopen2 open a stream, with flush support +.It fwide set/get orientation of a stream +.It fwopen open a stream +.It fwrite binary stream input/output +.It getc get next character or word from input stream +.It getc_unlocked get next character or word from input stream +.It Ta (no implicit locking) +.It getchar get next character or word from input stream +.It getchar_unlocked get next character or word from input stream +.It Ta (no implicit locking) +.It getdelim get a delimited record from a stream +.It getline get a line from a stream +.It gets get a line from a stream +.It getw get next character or word from input stream +.It getwc get next wide character from input stream +.It getwchar get next wide character from input stream +.It mkstemp create unique temporary file +.It mktemp create unique temporary file +.It open_memstream open memory as a stream +.It popen open a program as a stream +.It popenve open a program as a stream +.It pclose close an opened program stream +.It perror system error messages +.It printf formatted output conversion +.It printf_l formatted output conversion +.It putc output a character or word to a stream +.It putc_unlocked output a character or word to a stream +.It Ta (no implicit locking) +.It putchar output a character or word to a stream +.It putchar_unlocked output a character or word to a stream +.It Ta (no implicit locking) +.It puts output a line to a stream +.It putw output a character or word to a stream +.It putwc output a wide character to a stream +.It putwchar output a wide character to a stream +.It remove remove directory entry +.It rewind reposition a stream +.It scanf input format conversion +.It scanf_l input format conversion +.It setbuf stream buffering operations +.It setbuffer stream buffering operations +.It setlinebuf stream buffering operations +.It setvbuf stream buffering operations +.It snprintf formatted output conversion +.It snprintf_l formatted output conversion +.It sprintf formatted output conversion +.It sscanf input format conversion +.It sscanf_l input format conversion +.It strerror system error messages +.It sys_errlist system error messages +.It sys_nerr system error messages +.It tempnam temporary file routines +.It tmpfile temporary file routines +.It tmpnam temporary file routines +.It ungetc un-get character from input stream +.It ungetwc un-get wide character from input stream +.It vasprintf formatted output conversion with allocation +.It vasprintf_l formatted output conversion with allocation +.It vdprintf formatted output conversion +.It vdprintf_l formatted output conversion +.It vfprintf formatted output conversion +.It vfprintf_l formatted output conversion +.It vfscanf input format conversion +.It vfscanf_l input format conversion +.It vprintf formatted output conversion +.It vprintf_l formatted output conversion +.It vscanf input format conversion +.It vscanf_l input format conversion +.It vsnprintf formatted output conversion +.It vsnprintf_l formatted output conversion +.It vsprintf formatted output conversion +.It vsprintf_l formatted output conversion +.It vsscanf input format conversion +.It vsscanf_l input format conversion +.El +.Sh BUGS +The standard buffered functions do not interact well with certain other +library and system functions, especially +.Xr vfork 2 +and +.Xr abort 3 . |