setvbuf() — Control buffering

Standards

Standards / Extensions C or C++ Dependencies

ISO C
POSIX.1
XPG4
XPG4.2
C99
Single UNIX Specification, Version 3

 both  

Format

#include <stdio.h>

int setvbuf(FILE * __restrict__stream, char * __restrict__buf, int type, size_t size);

General description

Controls the buffering strategy and buffer size for a specified stream. The stream pointer must refer to an open file, and setvbuf() must be the first operation on the file.

To provide an ASCII input/output format for applications using this function, define the feature test macro __LIBASCII as described in topic 2.1.

The location pointed to by buf designates an area that you provide that the z/OS® XL C/C++ Runtime Library may choose to use as a buffer for the stream. A buf value of NULL indicates that no such area is supplied and that the z/OS XL C/C++ Runtime Library is to assume responsibility for managing its own buffers for the stream. If you supply a buffer, it must exist until the stream is closed.

If type is _IOFBF or _IOLBF, size is the size of the supplied buffer. If buf is NULL, the C library will take size as the suggested size for its own buffer. If type is _IONBF, both buf and size are ignored. Unbuffered I/O is allowed for memory files and hierarchical file system (HFS) files. However, it is not permitted for Hiperspace™ memory files. If the size of the supplied buffer for hiperspace memory files is greater than 4k, only the first 4k of the buffer will be used.
Value
Meaning
_IONBF
No buffer is used.
_IOFBF
Full buffering is used for input and output. Use buf as the buffer and size as the size of the buffer.
_IOLBF
Line buffering is used for text stream I/O and terminal I/O. The buffer is flushed when a newline character is used (text stream), when the buffer is full, or when input is requested (terminal). The value for size must be greater than 0.

The value for size must be greater than 0.

Note: If you use setvbuf() or setbuf() to define your own buffer for a stream, you must ensure that either the buffer is available after program termination, or the stream is closed or flushed, before you call exit(). This can be done by defining the array with file scope or by dynamically allocating the storage for the array using malloc().

For example, if the buffer is declared within the scope of a function block, the stream must be closed before the function is terminated. This prevents the storage allocated to the buffer from being freed.

Returned value

If successful, even if it chooses not to use your buffer. setvbuf() returns 0.

If an invalid value was specified in the parameter list, or if the request cannot be performed, setvbuf() returns nonzero.

Example

/* This example sets up a buffer of buf for stream1 and specifies that
   input from stream2 is to be unbuffered.
 */
#include <stdio.h>
#define  BUF_SIZE  1024

char buf[BUF_SIZE];

int main(void)
{
   FILE *stream1, *stream2;

   stream1 = fopen("myfile1.dat", "r");
   stream2 = fopen("myfile2.dat", "r");

   /* stream1 uses a user-assigned buffer of BUF_SIZE bytes */
   if (setvbuf(stream1, buf, _IOFBF, sizeof(buf)) != 0)
      printf("Incorrect type or size of buffer 1");

   /* stream2 is unbuffered                                 */
   if (setvbuf(stream2, NULL, _IONBF, 0) != 0)
      printf("Incorrect type or size of buffer 2");
⋮
}

Related information

Parent topic: Library functions