STDIO(3V)

NAME
stdio - standard buffered input/output package

SYNOPSIS
#include <stdio.h>

FILE *stdin;
FILE *stdout;
FILE *stderr;

DESCRIPTION

The functions described in section 3S constitute a user-level I/O buffering scheme. The in-line macros getc(3V) and putc(3S) handle characters quickly. The macros getchar() (see getc(3V)) and putchar() (see putc(3S)), and the higher level routines fgetc(), getw() (see getc(3V)), gets(3S), fgets() (see gets(3S)), scanf(3V), fscanf() (see scanf(3V)), fread(3S), fputc(), putw() (see putc(3S)), puts(3S), fputs() (see puts(3S)), printf(3V), fprintf() (see printf(3V)), fwrite() (see fread(3S)) all use or act as if they use getc() and putc(). They can be freely intermixed.

A file with associated buffering is called a stream, and is declared to be a pointer to a defined type FILE. fopen(3V) 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> include file and associated with the standard open files:

stdin
    standard input file

stdout
    standard output file

stderr
    standard error file

A constant NULL (0) designates a nonexistent pointer.

An integer constant EOF (-1) is returned upon EOF or error by most integer functions that deal with streams (see the individual descriptions for details).

Any module that uses this package must include the header file of pertinent macro definitions, as follows:

    #include <stdio.h>

The functions and constants mentioned in sections labeled 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: getc(), getchar(), putc(), putchar(), feof(), ferror(), fileno(), and clearerr().

Output streams, with the exception of the standard error stream 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 stderr is by default unbuffered, but use of fopen() will cause it to become buffered or line-buffered. When an output stream is unbuffered, information is written to the destination file or terminal as soon as it is output to the stream; when it is buffered, many characters are saved up and written as a block. When it is line-buffered, each line of output is written to the destination file or terminal as soon as the line is completed (that is, as soon as a NEWLINE character is output or, if the output stream is stdout or stderr, as soon as input is read from stdin). setbuf(3V), setbuffer(), setlinebuf(), or setvbuf() (see setbuf(3V)) can be used to change the stream's buffering strategy.

SYSTEM V DESCRIPTION

When an output stream is line-buffered, each line of output is written to the destination file or terminal as soon as the line is completed (that is, as soon as a NEWLINE character is output or as soon as input is read from a line-buffered stream).

Output saved up on all line-buffered streams is written when input is read from any line-buffered stream. Input read from a stream that is not line-buffered does not flush output on line-buffered streams.

RETURN VALUES

The value EOF is returned uniformly to indicate that a FILE pointer has not been initialized with fopen(), input (output) has been attempted on an output (input) stream, or a FILE pointer designates corrupt or otherwise unintelligible FILE data.

SEE ALSO
open(2V), close(2V), lseek(2V), pipe(2V), read(2V), write(2V), ctermid(3V), cuserid(3V), fclose(3V), ferror(3V), fopen(3V), fread(3S), fseek(3S), getc(3V), gets(3S), popen(3S), printf(3V), putc(3S), puts(3S), scanf(3V), setbuf(3V), system(3), tmpfile(3S), tmpnam(3S), ungetc(3S)

NOTES

The line buffering of output to terminals is almost always transparent, but may cause confusion or malfunctioning of programs which use standard I/O routines but use read(2V) to read from the standard input, as calls to read() do not cause output to line-buffered streams to be flushed.

In cases where a large amount of computation is done after printing part of a line on an output terminal, it is necessary to call fflush() (see fclose(3V)) on the standard output before performing the computation so that the output will appear.

BUGS

The standard buffered functions do not interact well with certain other library and system functions, especially vfork(2).