STDIO(3S)							     STDIO(3S)



NAME
     stdio - standard buffered input/output package

SYNOPSIS
     #include <stdio.h>

     FILE *stdin, *stdout, *stderr;

DESCRIPTION
     The functions described in	the entries of 
     sub-class 3S of this manual constitute an 
     efficient, user-level I/O buffering scheme.
     The in-line macros getc and putc  handle 
     characters quickly.  The macros getchar and 
     putchar, and the higher-level routines fgetc, 
     fgets, fprintf, fputc, fputs, fread, fscanf, 
     fwrite, gets, getw, printf, puts, putw, and
     scanf 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(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:

	  stdin	    standard input file
	  stdout    standard output file
	  stderr    standard error file

     The following symbolic values in <unistd.h> define 
     the file descriptors that will be associated with
     the C-language stdin, stdout and stderr
      when the application is started:

	  STDIN_FILENO	   Standard input 
               value, stdin. It has the value 
               of 0.
	  STDOUT_FILENO	   Standard output 
               value, stdout.  It has the value
               of 1.
	  STDERR_FILENO	   Standard error 
               value, stderr.  It has the value
               of 2.

     A constant	NULL (0) designates a nonexistent 
     pointer.

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

     An	integer	constant BUFSIZ specifies the size of 
     the buffers used by the particular	implementation.

     An	integer	constant FILENAME_MAX specifies the 
     size needed for an array of char large 
     enough to hold the longest file name string that
     the implementation guarantees can be opened.

     An	integer	constant 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 fopen,
     and only file descriptors 0 through 255 are valid.

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

	  #include <stdio.h>

     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):
     getc, getchar, putc, putchar, ferror, feof, 
     clearerr, and fileno.

     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 freopen [see 
     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). setbuf(3S) or setvbuf(3S)
     in setbuf(3S) may be used to change the 
     stream's buffering strategy.

DIAGNOSTICS
     Invalid stream pointers will usually cause grave 
     disorder, possibly including program termination.
     Individual function descriptions describe the 
     possible error conditions.