setvbuf() — Control buffering
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C |
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.
- 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.
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
- One of the topics about I/O Operations in z/OS XL C/C++ Programming Guide.
- stdio.h
- fclose() — Close file
- fflush() — Write buffer to file
- fopen() — Open a file
- setbuf() — Control buffering