GNU Info

(libc.info)Controlling Buffering

---

Prev: Flushing Buffers Up: Stream Buffering

---

Enter node , (file) or (file)node

Controlling Which Kind of Buffering
-----------------------------------

   After opening a stream (but before any other operations have been
performed on it), you can explicitly specify what kind of buffering you
want it to have using the `setvbuf' function.

   The facilities listed in this section are declared in the header
file `stdio.h'.

 - Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
          SIZE)
     This function is used to specify that the stream STREAM should
     have the buffering mode MODE, which can be either `_IOFBF' (for
     full buffering), `_IOLBF' (for line buffering), or `_IONBF' (for
     unbuffered input/output).

     If you specify a null pointer as the BUF argument, then `setvbuf'
     allocates a buffer itself using `malloc'.  This buffer will be
     freed when you close the stream.

     Otherwise, BUF should be a character array that can hold at least
     SIZE characters.  You should not free the space for this array as
     long as the stream remains open and this array remains its buffer.
     You should usually either allocate it statically, or `malloc'
     (Note: Unconstrained Allocation) the buffer.  Using an automatic
     array is not a good idea unless you close the file before exiting
     the block that declares the array.

     While the array remains a stream buffer, the stream I/O functions
     will use the buffer for their internal purposes.  You shouldn't
     try to access the values in the array directly while the stream is
     using it for buffering.

     The `setvbuf' function returns zero on success, or a nonzero value
     if the value of MODE is not valid or if the request could not be
     honored.

 - Macro: int _IOFBF
     The value of this macro is an integer constant expression that can
     be used as the MODE argument to the `setvbuf' function to specify
     that the stream should be fully buffered.

 - Macro: int _IOLBF
     The value of this macro is an integer constant expression that can
     be used as the MODE argument to the `setvbuf' function to specify
     that the stream should be line buffered.

 - Macro: int _IONBF
     The value of this macro is an integer constant expression that can
     be used as the MODE argument to the `setvbuf' function to specify
     that the stream should be unbuffered.

 - Macro: int BUFSIZ
     The value of this macro is an integer constant expression that is
     good to use for the SIZE argument to `setvbuf'.  This value is
     guaranteed to be at least `256'.

     The value of `BUFSIZ' is chosen on each system so as to make stream
     I/O efficient.  So it is a good idea to use `BUFSIZ' as the size
     for the buffer when you call `setvbuf'.

     Actually, you can get an even better value to use for the buffer
     size by means of the `fstat' system call: it is found in the
     `st_blksize' field of the file attributes.  Note: Attribute
     Meanings.

     Sometimes people also use `BUFSIZ' as the allocation size of
     buffers used for related purposes, such as strings used to receive
     a line of input with `fgets' (Note: Character Input).  There is
     no particular reason to use `BUFSIZ' for this instead of any other
     integer, except that it might lead to doing I/O in chunks of an
     efficient size.

 - Function: void setbuf (FILE *STREAM, char *BUF)
     If BUF is a null pointer, the effect of this function is
     equivalent to calling `setvbuf' with a MODE argument of `_IONBF'.
     Otherwise, it is equivalent to calling `setvbuf' with BUF, and a
     MODE of `_IOFBF' and a SIZE argument of `BUFSIZ'.

     The `setbuf' function is provided for compatibility with old code;
     use `setvbuf' in all new programs.

 - Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
     If BUF is a null pointer, this function makes STREAM unbuffered.
     Otherwise, it makes STREAM fully buffered using BUF as the buffer.
     The SIZE argument specifies the length of BUF.

     This function is provided for compatibility with old BSD code.  Use
     `setvbuf' instead.

 - Function: void setlinebuf (FILE *STREAM)
     This function makes STREAM be line buffered, and allocates the
     buffer for you.

     This function is provided for compatibility with old BSD code.  Use
     `setvbuf' instead.

   It is possible to query whether a given stream is line buffered or
not using a non-standard function introduced in Solaris and available
in the GNU C library.

 - Function: int __flbf (FILE *STREAM)
     The `__flbf' function will return a nonzero value in case the
     stream STREAM is line buffered.  Otherwise the return value is
     zero.

     This function is declared in the `stdio_ext.h' header.

   Two more extensions allow to determine the size of the buffer and how
much of it is used.  These functions were also introduced in Solaris.

 - Function: size_t __fbufsize (FILE *STREAM)
     The `__fbufsize' function return the size of the buffer in the
     stream STREAM.  This value can be used to optimize the use of the
     stream.

     This function is declared in the `stdio_ext.h' header.

 - Function: size_t __fpending (FILE *STREAM) The `__fpending'
     function returns the number of bytes currently in the output
     buffer.  For wide-oriented stream the measuring unit is wide
     characters.  This function should not be used on buffers in read
     mode or opened read-only.

     This function is declared in the `stdio_ext.h' header.