225 lines
4.6 KiB
Plaintext
225 lines
4.6 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3s.stdio @(#)stdio 30.3 of 3/25/86
|
|
.nr X
|
|
.if \nX=0 .ds x} STDIO 3S "C Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} STDIO 3S "C Programming Language Utilities"
|
|
.if \nX=2 .ds x} STDIO 3S "" "\&"
|
|
.if \nX=3 .ds x} STDIO "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
stdio \- standard buffered input/output package
|
|
.SH SYNOPSIS
|
|
.B #include <stdio.h>
|
|
.PP
|
|
.SM
|
|
.B FILE
|
|
.B \(**stdin, \(**stdout, \(**stderr;
|
|
.SH DESCRIPTION
|
|
The functions described in the entries of sub-class\ 3S of this manual constitute an efficient,
|
|
user-level
|
|
.SM I/O
|
|
buffering scheme.
|
|
The in-line macros
|
|
.IR getc (3S)
|
|
and
|
|
.IR putc (3S)
|
|
handle characters quickly.
|
|
The macros
|
|
.IR getchar " and " putchar ,
|
|
and
|
|
the higher-level routines
|
|
.IR fgetc ,
|
|
.IR fgets ,
|
|
.IR fprintf ,
|
|
.IR fputc ,
|
|
.IR fputs ,
|
|
.IR fread ,
|
|
.IR fscanf ,
|
|
.IR fwrite ,
|
|
.IR gets ,
|
|
.IR getw ,
|
|
.IR printf ,
|
|
.IR puts ,
|
|
.IR putw ,
|
|
and
|
|
.I scanf\^
|
|
all use or act as if they use
|
|
.I getc\^
|
|
and
|
|
.IR putc ;
|
|
they can be freely intermixed.
|
|
.PP
|
|
A file with associated buffering is called a
|
|
.I stream\^
|
|
and is declared to be a pointer to a defined type
|
|
.SM
|
|
.BR FILE\*S .
|
|
.IR fopen (3S)
|
|
creates certain descriptive data for a stream
|
|
and returns a pointer to designate the stream in all
|
|
further transactions.
|
|
Normally, there are three open streams with constant
|
|
pointers declared in
|
|
the <stdio.h> header file and associated with the standard open files:
|
|
.RS
|
|
.PP
|
|
.PD 0
|
|
.TP 10
|
|
.B stdin
|
|
standard input file
|
|
.TP
|
|
.B stdout
|
|
standard output file
|
|
.TP
|
|
.B stderr
|
|
standard error file
|
|
.RE
|
|
.PD
|
|
.PP
|
|
The following symbolic values in \f2<unistd.h>\fP define the file descriptors
|
|
that will be associated with the C-language \f2stdin\f1, \f2stdout\f1 and
|
|
\f2stderr\f1 when the application is started:
|
|
.RS
|
|
.PP
|
|
.PD 0
|
|
.TP 17
|
|
.B STDIN_FILENO
|
|
Standard input value, \f2stdin\fP.
|
|
It has the value of 0.
|
|
.TP
|
|
.B STDOUT_FILENO
|
|
Standard output value, \f2stdout\fP.
|
|
It has the value of 1.
|
|
.TP
|
|
.B STDERR_FILENO
|
|
Standard error value, \f2stderr\fP.
|
|
It has the value of 2.
|
|
.RE
|
|
.PD
|
|
.PP
|
|
A constant
|
|
.SM
|
|
.B NULL
|
|
(0)
|
|
designates a nonexistent pointer.
|
|
.PP
|
|
An integer-constant
|
|
.SM
|
|
.B EOF
|
|
(\-1) is returned
|
|
upon end-of-file or error by most integer functions that
|
|
deal with streams
|
|
(see the individual descriptions for details).
|
|
.PP
|
|
An integer constant
|
|
.SM
|
|
.B BUFSIZ
|
|
specifies the size of the buffers used by the particular implementation.
|
|
.PP
|
|
An integer constant
|
|
.B FILENAME_MAX
|
|
specifies the size needed for an array of \f2char\fP large enough to hold
|
|
the longest file name string that the implementation guarantees can be
|
|
opened.
|
|
.PP
|
|
An integer constant
|
|
.B FOPEN_MAX
|
|
specifies the minimum number of files that the implementation guarantees
|
|
can be open simultaneously.
|
|
Note that no more than 255 files
|
|
may be opened via
|
|
\f2fopen\f1, and only file descriptors 0 through 255
|
|
are valid.
|
|
.PP
|
|
Any program that uses this package
|
|
must include the header file of pertinent macro definitions,
|
|
as follows:
|
|
.PP
|
|
.RS
|
|
#include \|<stdio.h>
|
|
.RE
|
|
.PP
|
|
The functions and constants mentioned in the entries of sub-class\ 3S
|
|
of this manual
|
|
are declared in that header file
|
|
and need no further declaration.
|
|
The constants and the following ``functions'' are
|
|
implemented as macros (redeclaration of these names
|
|
is perilous):
|
|
.IR getc ,
|
|
.IR getchar ,
|
|
.IR putc ,
|
|
.IR putchar ,
|
|
.IR ferror ,
|
|
.IR feof ,
|
|
.IR clearerr ,
|
|
and
|
|
.IR fileno .
|
|
.PP
|
|
Output streams, with the exception of the standard error stream
|
|
.IR stderr ,
|
|
are by default buffered if the output refers to a file
|
|
and line-buffered if the
|
|
output refers to a terminal.
|
|
The standard error output stream
|
|
.I stderr\^
|
|
is by default unbuffered,
|
|
but use of
|
|
.I freopen
|
|
[see
|
|
.IR fopen (3S)]
|
|
will cause it to become buffered or line-buffered.
|
|
When an output stream is unbuffered,
|
|
information is queued for writing on the
|
|
destination file or terminal as soon as written;
|
|
when it is buffered,
|
|
many characters are saved up and written as a block.
|
|
When it is
|
|
line-buffered,
|
|
each line of output is queued for writing on the
|
|
destination terminal as soon as the line is completed
|
|
(that is, as soon as a new-line character is written
|
|
or terminal input is requested).
|
|
.IR setbuf (3S)
|
|
or
|
|
.IR setvbuf (3S)
|
|
in
|
|
.IR setbuf (3S)
|
|
may be used to change the
|
|
stream's buffering strategy.
|
|
.SH SEE ALSO
|
|
open(2),
|
|
close(2),
|
|
lseek(2),
|
|
pipe(2),
|
|
read(2),
|
|
write(2),
|
|
ctermid(3S),
|
|
cuserid(3S),
|
|
fclose(3S),
|
|
ferror(3S),
|
|
fopen(3S),
|
|
fread(3S),
|
|
fseek(3S),
|
|
getc(3S),
|
|
gets(3S),
|
|
popen(3S),
|
|
printf(3S),
|
|
putc(3S),
|
|
puts(3S),
|
|
scanf(3S),
|
|
setbuf(3S),
|
|
system(3S),
|
|
tmpfile(3S),
|
|
tmpnam(3S),
|
|
ungetc(3S).
|
|
.SH DIAGNOSTICS
|
|
Invalid
|
|
.I stream\^
|
|
pointers will usually cause grave disorder, possibly including
|
|
program termination.
|
|
Individual function descriptions describe the possible error conditions.
|
|
'\".so /pubs/tools/origin.att
|
|
.\" @(#)stdio.3s 6.2 of 10/20/83
|
|
.Ee
|