setbuf(3F)

NAME
     setbuf, setvbuf, setbuffer, setlinebuf - assign buffering to a stream
     logical unit

FORTRAN SYNOPSIS
     #include <stdio.h>

     character *(BUFSIZ+8) buf
     integer type, size, setbuf, setvbuf, setbuffer,

     setbuf (lun, buf)

     setvbuf (lun, buf, size)

     setbuffer (lun, buf, size)

     setlinebuf (lun)

C SYNOPSIS
     #include <stdio.h>

     void setbuf (FILE *stream, char *buf);

     int setvbuf (FILE *stream, char *buf, int type, size_t size);

     int setbuffer (FILE *stream, char *buf, int size);

     int setlinebuf (FILE *stream);

DESCRIPTION
     The three types of buffering available are unbuffered, fully buffered,
     and line buffered.  When an output stream unit is unbuffered, information
     appears on the destination file or terminal as soon as written; when it
     is fully buffered many characters are saved up and written as a block;
     when it is line buffered characters are saved up until a newline is
     encountered or input is read from stdin.  Fflush(3S) flush(3F) may be
     used to force the block out early.  By default, output to a terminal is
     line buffered and all other input/output is fully buffered.

     Setbuf may be used after a stream unit has been opened but before it is
     read or written.  It causes the array pointed to by buf to be used
     instead of an automatically allocated buffer.  If buf is the NULL pointer
     input/output will be completely unbuffered.  If buf is not the NULL
     pointer and the indicated stream lun is open to a terminal, output will
     be line buffered.

     A constant BUFSIZ, defined in the <stdio.h> header file, indicates the
     assumed minimum length of buf.  It is wise to allocate a few words of
     extra space for buf, to allow for any synchronization problems resulting
     from signals occurring at inopportune times.  A good choice (and the one
     used by default in stdio(3s)) is

          char buf[BUFSIZ + 8]; character *(BUFSIZ + 8) buf

     Setvbuf may be used after a stream unit has been opened but before it is
     read or written.  Type determines how stream lun will be buffered.  Legal
     values for type (defined in <stdio.h>) are:

     _IOFBF  causes input/output to be fully buffered.

     _IOLBF  causes output to be line buffered; the buffer will be flushed
             when a newline is written, the buffer is full, or input is
             requested.

     _IONBF  causes input/output to be completely unbuffered.

     If input/output is unbuffered, buf and size are ignored.  For buffered
     input/output, if buf is not the NULL pointer and size is greater than
     eight, the array it points to will be used for buffering.  In this case,
     size specifies the length of this array. The actual buffer will consist
     of the first size-8 bytes of buf (see the discussion of BUFSIZ above).
     If buf is the NULL pointer, or size is less than eight, space will be
     allocated to accommodate a buffer.  This buffer will be of length BUFSIZ.
     (The actual space allocated will be eight bytes longer.)

     Setbuffer and setlinebuf are provided for compatibility with 4.3BSD.
     Setbuffer, an alternate form of setbuf, is used after a stream unit has
     been opened but before it is read or written.  The character array buf
     whose size is determined by the size argument is used instead of an
     automatically allocated buffer.  If buf is the constant pointer NULL,
     input/output will be completely unbuffered.

     Setlinebuf is used to change stdout or stderr from fully buffered or
     unbuffered to line buffered.  Unlike the other routines, it can be used
     at any time that the file descriptor is active.

SEE ALSO
     fopen(3S), fflush(3S), getc(3S), malloc(3C), putc(3S), stdio(3S).
     flush(3F), perror(3F).

DIAGNOSTICS
     Success is indicated by setvbuf and setbuffer returning zero.  a zero
     return value.  A non-zero return value indicates an error.  The value of
     errno can be examined to determine the cause of the error.  If it is
     necessary to allocate a buffer and the attempt is unsuccessful, setvbuf
     and setbuffer return a non-zero value. Setvbuf will also return non-zero
     if the value of type is not one of _IONBF, _IOLBF, or _IOFBF.

NOTES
     A common source of error is allocating buffer space as an ``automatic''
     variable in a code block, and then failing to close the stream unit in
     the same block.

     These functions cannot be used on direct unformatted units.