NAME    [Toc]    [Back]

     setbuf, setbuffer, setlinebuf, setvbuf  -  stream  buffering
operations

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     The  three  types  of  stream  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  line buffered, characters are saved up until a
newline (`0)
     is output or input is read from any  stream  attached  to  a
terminal device
     (typically stdin).

     The  fflush(3)  function  may be used to force the block out
early.

     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 initially unbuffered.

     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 unbuffered
 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 BUFSIZ.
     The setlinebuf() function is exactly equivalent to the call:

           setvbuf(stream, NULL, _IOLBF, 0);

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

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

STANDARDS    [Toc]    [Back]

     The  setbuf()  and  setvbuf()  functions  conform  to   ANSI
X3.159-1989 (``ANSI
     C'').

BUGS    [Toc]    [Back]

     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.

OpenBSD      3.6                           June      4,      1993