mirror of https://github.com/mkerrisk/man-pages
370 lines
9.0 KiB
Groff
370 lines
9.0 KiB
Groff
.\" Copyright (c) 1990, 1991 Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" @(#)stdio.3 6.5 (Berkeley) 5/6/91
|
|
.\"
|
|
.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu
|
|
.\" Modified, 2001-12-26, aeb
|
|
.\"
|
|
.TH STDIO 3 2017-11-26 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
stdio \- standard input/output library functions
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdio.h>
|
|
.PP
|
|
.BI "FILE *" stdin ;
|
|
.BI "FILE *" stdout ;
|
|
.BI "FILE *" stderr ;
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The standard I/O library provides a simple and efficient buffered stream
|
|
I/O interface.
|
|
Input and output is mapped into logical data streams and the
|
|
physical 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
|
|
.I 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
|
|
.I 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,
|
|
it is unspecified whether the position indicator will be placed at the
|
|
start or the end of the 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
|
|
.BR fgetc (3)
|
|
function; all output takes place as if all characters were written by
|
|
successive calls to the
|
|
.BR fputc (3)
|
|
function.
|
|
.PP
|
|
A file is disassociated from a stream by
|
|
.I 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
|
|
.I 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
|
|
.BR 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
|
|
.BR abort (3)
|
|
do not bother about closing files properly.
|
|
.PP
|
|
At program startup, three text streams are predefined and need not be
|
|
opened explicitly:
|
|
.I standard input
|
|
(for reading conventional input),
|
|
.I standard output
|
|
(for writing conventional output), and
|
|
.I standard error
|
|
(for writing diagnostic output).
|
|
These streams are abbreviated
|
|
.IR stdin ,
|
|
.IR stdout ,
|
|
and
|
|
.IR stderr .
|
|
When opened, the standard error stream is not fully buffered; the standard
|
|
input and output streams are fully buffered if and only if the streams do
|
|
not refer to an interactive device.
|
|
.PP
|
|
Output streams that refer to terminal devices are always line buffered by
|
|
default; pending output to such streams is written automatically whenever
|
|
an input stream that refers to a terminal device is read.
|
|
In cases where a
|
|
large amount of computation is done after printing part of a line on an
|
|
output terminal, it is necessary to
|
|
.BR fflush (3)
|
|
the standard output before going off and computing so that the output will
|
|
appear.
|
|
.PP
|
|
The
|
|
.I stdio
|
|
library is a part of the library
|
|
.B libc
|
|
and routines are automatically loaded as needed by
|
|
.BR cc (1).
|
|
The
|
|
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 reused without
|
|
first removing their current definitions with
|
|
.BR #undef :
|
|
.BR BUFSIZ ,
|
|
.BR EOF ,
|
|
.BR FILENAME_MAX ,
|
|
.BR FOPEN_MAX ,
|
|
.BR L_cuserid ,
|
|
.BR L_ctermid ,
|
|
.BR L_tmpnam ,
|
|
.BR NULL ,
|
|
.BR SEEK_END ,
|
|
.BR SEEK_SET ,
|
|
.BR SEEK_CUR ,
|
|
.BR TMP_MAX ,
|
|
.BR clearerr ,
|
|
.BR feof ,
|
|
.BR ferror ,
|
|
.BR fileno ,
|
|
.\" Not on Linux: .BR fropen ,
|
|
.\" Not on Linux: .BR fwopen ,
|
|
.BR getc ,
|
|
.BR getchar ,
|
|
.BR putc ,
|
|
.BR putchar ,
|
|
.BR stderr ,
|
|
.BR stdin ,
|
|
.BR stdout .
|
|
Function versions of the macro functions
|
|
.BR feof ,
|
|
.BR ferror ,
|
|
.BR clearerr ,
|
|
.BR fileno ,
|
|
.BR getc ,
|
|
.BR getchar ,
|
|
.BR putc ,
|
|
and
|
|
.B putchar
|
|
exist and will be used if the macros definitions are explicitly removed.
|
|
.SS List of functions
|
|
.nh
|
|
.ad l
|
|
.TS
|
|
;
|
|
lb lbx
|
|
l l.
|
|
Function Description
|
|
_
|
|
\fBclearerr\fP(3) T{
|
|
check and reset stream status
|
|
T}
|
|
\fBfclose\fP(3) T{
|
|
close a stream
|
|
T}
|
|
\fBfdopen\fP(3) T{
|
|
stream open functions
|
|
T}
|
|
\fBfeof\fP(3) T{
|
|
check and reset stream status
|
|
T}
|
|
\fBferror\fP(3) T{
|
|
check and reset stream status
|
|
T}
|
|
\fBfflush\fP(3) T{
|
|
flush a stream
|
|
T}
|
|
\fBfgetc\fP(3) T{
|
|
get next character or word from input stream
|
|
T}
|
|
\fBfgetpos\fP(3) T{
|
|
reposition a stream
|
|
T}
|
|
\fBfgets\fP(3) T{
|
|
get a line from a stream
|
|
T}
|
|
\fBfileno\fP(3) T{
|
|
return the integer descriptor of the argument stream
|
|
T}
|
|
\fBfopen\fP(3) T{
|
|
stream open functions
|
|
T}
|
|
\fBfprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBfpurge\fP(3) T{
|
|
flush a stream
|
|
T}
|
|
\fBfputc\fP(3) T{
|
|
output a character or word to a stream
|
|
T}
|
|
\fBfputs\fP(3) T{
|
|
output a line to a stream
|
|
T}
|
|
\fBfread\fP(3) T{
|
|
binary stream input/output
|
|
T}
|
|
\fBfreopen\fP(3) T{
|
|
stream open functions
|
|
T}
|
|
\fBfscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
\fBfseek\fP(3) T{
|
|
reposition a stream
|
|
T}
|
|
\fBfsetpos\fP(3) T{
|
|
reposition a stream
|
|
T}
|
|
\fBftell\fP(3) T{
|
|
reposition a stream
|
|
T}
|
|
\fBfwrite\fP(3) T{
|
|
binary stream input/output
|
|
T}
|
|
\fBgetc\fP(3) T{
|
|
get next character or word from input stream
|
|
T}
|
|
\fBgetchar\fP(3) T{
|
|
get next character or word from input stream
|
|
T}
|
|
\fBgets\fP(3) T{
|
|
get a line from a stream
|
|
T}
|
|
\fBgetw\fP(3) T{
|
|
get next character or word from input stream
|
|
T}
|
|
\fBmktemp\fP(3) T{
|
|
make temporary filename (unique)
|
|
T}
|
|
\fBperror\fP(3) T{
|
|
system error messages
|
|
T}
|
|
\fBprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBputc\fP(3) T{
|
|
output a character or word to a stream
|
|
T}
|
|
\fBputchar\fP(3) T{
|
|
output a character or word to a stream
|
|
T}
|
|
\fBputs\fP(3) T{
|
|
output a line to a stream
|
|
T}
|
|
\fBputw\fP(3) T{
|
|
output a character or word to a stream
|
|
T}
|
|
\fBremove\fP(3) T{
|
|
remove directory entry
|
|
T}
|
|
\fBrewind\fP(3) T{
|
|
reposition a stream
|
|
T}
|
|
\fBscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
\fBsetbuf\fP(3) T{
|
|
stream buffering operations
|
|
T}
|
|
\fBsetbuffer\fP(3) T{
|
|
stream buffering operations
|
|
T}
|
|
\fBsetlinebuf\fP(3) T{
|
|
stream buffering operations
|
|
T}
|
|
\fBsetvbuf\fP(3) T{
|
|
stream buffering operations
|
|
T}
|
|
\fBsprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBsscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
\fBstrerror\fP(3) T{
|
|
system error messages
|
|
T}
|
|
\fBsys_errlist\fP(3) T{
|
|
system error messages
|
|
T}
|
|
\fBsys_nerr\fP(3) T{
|
|
system error messages
|
|
T}
|
|
\fBtempnam\fP(3) T{
|
|
temporary file routines
|
|
T}
|
|
\fBtmpfile\fP(3) T{
|
|
temporary file routines
|
|
T}
|
|
\fBtmpnam\fP(3) T{
|
|
temporary file routines
|
|
T}
|
|
\fBungetc\fP(3) T{
|
|
un-get character from input stream
|
|
T}
|
|
\fBvfprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBvfscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
\fBvprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBvscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
\fBvsprintf\fP(3) T{
|
|
formatted output conversion
|
|
T}
|
|
\fBvsscanf\fP(3) T{
|
|
input format conversion
|
|
T}
|
|
.TE
|
|
.ad
|
|
.hy
|
|
.SH CONFORMING TO
|
|
The
|
|
.I stdio
|
|
library conforms to C89.
|
|
.SH SEE ALSO
|
|
.BR close (2),
|
|
.BR open (2),
|
|
.BR read (2),
|
|
.BR write (2),
|
|
.BR stdout (3),
|
|
.BR unlocked_stdio (3)
|