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
       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  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)

Man(1) output converted with man2html