Associates a buffer with an input or output file and potentially modifies the buffering behavior.
#include <stdio.h>
int setvbuf (FILE *file_ptr, char *buffer, int
type, size_t size);
The ANSI C standard defines the following types of file buffering. In unbuffered I/O, each I/O operation is performed immediately. Output characters or lines are written to the output device before control is returned to the program. Input characters or lines are sent directly to the program without read-ahead by the DEC C RTL.
In line-buffered I/O, characters are buffered in an area of memory until a new-line character is seen, at which point the appropriate RMS routine is called to transmit the entire buffer. Line buffering is more efficient than unbuffered I/O since it reduces the system overhead, but it delays the availability of the data to the user or disk on output.
In fully buffered I/O, characters are buffered in an area of memory until the buffer is full, regardless of the presence of break characters. Full buffering is more efficient than line buffering or unbuffered I/O, but it delays the availability of output data even longer than line buffering.
Use the values _IONBF, _IOLBF, and _IOFBF defined in <stdio.h> for the type argument to specify unbuffered, line-buffered, and fully buffered I/O, respectively.
If _IONBF is specified for type, I/O will be unbuffered and the buffer and size arguments are ignored.
If _IOLBF or _IOFBF is specified for type, the DEC C RTL will use line-buffered I/O if file_ptr specifies a terminal device; otherwise, it will use fully buffered I/O.
The DEC C RTL automatically allocates a buffer to use for each I/O stream. So there are several buffer allocation possibilities:
User programs must not depend on the contents of buffer once I/O has been performed on the stream. The DEC C RTL might or might not use buffer for any given I/O operation.
Generally, it is unnecessary to use setvbuf or setbuf to control the buffer size used by the DEC C RTL. The automatically allocated buffer sizes are chosen for efficiency based on the kind of I/O operations performed and the device characteristics (such as terminal, disk, or socket).
The setvbuf and setbuf functions are useful to introduce buffering for improved performance when writing a large amount of text to the stdout stream. This stream is unbuffered by default when bound to a terminal device (the normal case), and therefore incurs a large number of OpenVMS buffered I/O operations unless DEC C RTL buffering is introduced by a call to setvbuf or setbuf.
The setvbuf function is used only to control the buffering used by the DEC C RTL, not the buffering used by the underlying RMS I/O operations. You can modify RMS default buffering behavior by specifying various values for the ctx, fop, rat, gbc, mbc, mbf, rfm, and rop RMS keywords when the file is opened by the creat, freopen or open functions.
| 0 | Indicates success. |
| nonzero value | Indicates that an invalid input value was specifed for type or file_ptr, or because file_ptr is being used by another thread (see Section 1.7.1). |