SETBUF(3)                      Library Routines                      SETBUF(3)

NAME

       setbuf, setbuffer, setlinebuf, setvbuf - stream buffering operations

SYNOPSIS

       #include <stdio.h>

       void setbuf (FILE *stream, char *buf);
       void setbuffer (FILE *stream, char *buf, size_t size);

       int setlinebuf (FILE *stream);

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

DESCRIPTION

       The  three types of buffering available are unbuffered, block buffered,
       and line buffered.  When an output stream  is  unbuffered,  information
       appears on the destination file or terminal as soon as written; when it
       is block buffered many characters are saved up and written as a  block;
       when  it  is  line  buffered characters are saved up until a newline is
       output or input is read from any stream attached to a  terminal  device
       (typically  stdin).   The  function  fflush(3) may be used to force the
       block out early.  (See fclose(3).)

       Normally all files are block buffered.  When the  first  I/O  operation
       occurs on a file, malloc(3) is called, and an optimally-sized buffer is
       obtained.  If a stream refers to a terminal (as stdout  normally  does)
       it  is  line  buffered.  The standard error stream stderr is always un‐
       buffered.

       The setvbuf function may be used to alter the buffering behavior  of  a
       stream.  The mode parameter must be one of the following three macros:

              _IONBF    unbuffered
              _IOLBF    line buffered
              _IOFBF    fully buffered

       The size parameter may be given as zero to obtain deferred optimal-size
       buffer allocation as usual.  If it is not zero,  then  except  for  un‐
       buffered files, the buf argument should point to a buffer at least size
       bytes long; this buffer will be used instead  of  the  current  buffer.
       (If  the  size  argument  is  not zero but buf is NULL, a buffer of the
       given size will be allocated immediately, and released on close.   This
       is  an  extension  to ANSI C; portable code should use a size of 0 with
       any NULL buffer.)

       The setvbuf function may be used at any time,  but  may  have  peculiar
       side  effects  (such  as  discarding  input  or flushing output) if the
       stream is ``active''.  Portable applications should call it  only  once
       on any given stream, and before any I/O is performed.

       The  other  three  calls  are,  in  effect, simply aliases for calls to
       setvbuf.  Except for the lack of a return value, the setbuf function is
       exactly equivalent to the call

            setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

       The  setbuffer function is the same, except that the size of the buffer
       is up to the caller, rather than being determined by the  default  BUF����
       SIZ.  The setlinebuf function is exactly equivalent to the call:

            setvbuf(stream, (char *)NULL, _IOLBF, 0);

RETURN VALUES

       The setvbuf function returns 0 on success, or EOF if the request cannot
       be honored (note that the stream is still functional in this case).

       The setlinebuf function returns what the equivalent setvbuf would  have
       returned.

SEE ALSO

       fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3)

STANDARDS

       The setbuf and setvbuf functions conform to ANSI/C.

BUGS

       The  setbuffer and setlinebuf functions are not portable to versions of
       BSD before 4.2BSD.  On 4.2BSD and 4.3BSD systems, setbuf always uses  a
       suboptimal buffer size and should be avoided.



GNO                            15 September 1997                     SETBUF(3)