gtpc2m6hC/C++ Language Support User's Guide

setvbuf-Control Buffering

This function controls the buffering strategy and buffer size for a specified stream.

Format

#include <stdio.h>
int setvbuf(FILE *stream, char *buf, int type, size_t size);

stream
The newly opened file.

buf
The user-supplied buffer.

type
The type of buffering for stream.

size
The size of the user-supplied buffer.

The stream pointer must refer to an open file and the setvbuf function must be the first operation on the file.

The setvbuf function is more flexible than the setbuf function because you can specify the type of buffering and the size of the buffer.

The location pointed to by buf designates an area that you provide that the C run-time library can choose to use as a buffer for the stream. A buf value of NULL indicates that no such area is supplied and that the C run-time 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.

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. The buffer is flushed when a new-line character is used (text stream) or when the buffer is full.

The value for size must be greater than 0.

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

For example, if the buffer is declared the scope of a function block, the stream must be closed before the function ends. This prevents the storage allocated to the buffer from being used after it has been deallocated.

Normal Return

If successful or if this function chooses not to use your buffer, setvbuf returns a value of 0.

Error Return

The setvbuf function returns a nonzero value if an incorrect value was specified in the parameter list or if the request cannot be performed.

Programming Considerations

None.

Examples

The following 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  256
 
char buf[BUF_SIZE];
 
int main(void)
{
   FILE *stream1 = fopen("myfile1.dat", "r");
   FILE *stream2 = fopen("myfile2.dat", "r");
 
   /* stream1 uses line buffering                           */
   if (setvbuf(stream1, buf, _IOLBF, 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

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.