+++ /dev/null
-.\" 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. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
-.\" 4. 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
-.\" $FreeBSD: src/lib/libc/stdio/stdio.3,v 1.18 2001/10/01 16:08:59 ru Exp $
-.\"
-.Dd April 19, 1994
-.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.
-The functions and macros are listed
-below; more information is available from the individual man pages.
-.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 will be 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 (garbage) after a file is closed.
-.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 may not close files properly and hence
-buffered output may be lost. In particular,
-.Xr _exit 2
-does not flush stdio files. Neither does an exit due to a signal.
-Buffers are flushed by
-.Xr abort 3
-as required by POSIX, although previous implementations did not.
-.Pp
-This implementation 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 -bullet -compact -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
-These streams are abbreviated
-.Em stdin , stdout
-and
-.Em stderr .
-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.
-.Pp
-The
-.Nm
-library is a part of the library
-.Nm libc
-and routines are automatically loaded as needed by the C compiler.
-The
-.Tn SYNOPSIS
-sections of the following manual pages indicate which include files
-are to be used, what the compiler declaration for the function
-looks like and which external variables are of interest.
-.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 P_tmpdir ,
-.Dv SEEK_CUR ,
-.Dv SEEK_END ,
-.Dv SEEK_SET ,
-.Dv TMP_MAX ,
-.Dv clearerr ,
-.Dv feof ,
-.Dv ferror ,
-.Dv fileno ,
-.Dv fropen ,
-.Dv fwopen ,
-.Dv getc ,
-.Dv getchar ,
-.Dv putc ,
-.Dv putchar ,
-.Dv stderr ,
-.Dv stdin ,
-.Dv stdout ,
-.Dv vfscanf .
-Function versions of the macro functions
-.Fn clearerr ,
-.Fn feof ,
-.Fn ferror ,
-.Fn fileno ,
-.Fn getc ,
-.Fn getchar ,
-.Fn putc ,
-and
-.Fn putchar
-exist and will be used if the macro
-definitions are explicitly removed.
-.Sh SEE ALSO
-.Xr close 2 ,
-.Xr open 2 ,
-.Xr read 2 ,
-.Xr write 2
-.Sh BUGS
-The standard buffered functions do not interact well with certain other
-library and system functions, especially
-.Xr vfork 2 .
-.Sh STANDARDS
-The
-.Nm
-library conforms to
-.St -isoC .
-.Sh LIST OF FUNCTIONS
-.Bl -column "Description"
-.It Sy "Function Description"
-.It "asprintf formatted output conversion"
-.It "clearerr check and reset stream status"
-.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 "fileno check and reset stream status"
-.It "fopen stream open functions"
-.It "fprintf 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 "fread binary stream input/output"
-.It "freopen stream open functions"
-.It "fropen open a stream"
-.It "fscanf input format conversion"
-.It "fseek reposition a stream"
-.It "fsetpos reposition a stream"
-.It "ftell reposition a stream"
-.It "funopen open a stream"
-.It "fwopen open a stream"
-.It "fwrite binary stream input/output"
-.It "getc get next character or word from input stream"
-.It "getchar get next character or word from input stream"
-.It "gets get a line from a stream"
-.It "getw get next character or word from input stream"
-.It "mkdtemp create unique temporary file"
-.It "mkstemp create unique temporary file"
-.It "mktemp create unique temporary file"
-.It "perror system error messages"
-.It "printf formatted output conversion"
-.It "putc output a character or word to a stream"
-.It "putchar output a character or word to a stream"
-.It "puts output a line to a stream"
-.It "putw output a character or word to a stream"
-.It "remove remove directory entry"
-.It "rewind reposition a stream"
-.It "scanf 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 "sprintf formatted output conversion"
-.It "sscanf 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 "vasprintf formatted output conversion"
-.It "vfprintf formatted output conversion"
-.It "vfscanf input format conversion"
-.It "vprintf formatted output conversion"
-.It "vscanf input format conversion"
-.It "vsnprintf formatted output conversion"
-.It "vsprintf formatted output conversion"
-.It "vsscanf input format conversion"
-.El
projects / apple / libc.git / blobdiff