Associates a buffer with an input or output file and potentially
    modifies the buffering behavior.

    Format

      #include  <stdio.h>

      int setvbuf  (FILE *file_ptr, char *buffer, int type, size_t size);

1  –  Arguments

 file_ptr

    A pointer to a file.

 buffer

    A pointer to a character array, or a NULL pointer.

 type

    The buffering type. Use one of the following values defined in
    <stdio.h>: _IOFBF or _IOLBF.

 size

    The number of bytes to be used in buffer by the C RTL for
    buffering this file. The buffer size must be a minimum of 8192
    bytes and a maximum of 32767 bytes.

2  –  Description

    You can use the setvbuf function after the file is opened but
    before any I/O operations are performed.

    The C RTL provides the following types of ANSI-conforming file
    buffering:

    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 _IOLBF and _IOFBF defined in <stdio.h> for the
    type argument to specify line-buffered and fully buffered I/O,
    respectively.

    If file_ptr specifies a terminal device, the C RTL uses
    line-buffered I/O; otherwise, it uses fully buffered I/O.

    Please note that the previously documented value _IONBF is not
    supported.

    The C RTL automatically allocates a buffer to use for each
    I/O stream, so there are several buffer allocation possibilities:

    o  If buffer is not a NULL pointer and size is not smaller than
       the automatically allocated buffer, then setvbuf uses buffer
       as the file buffer.

    o  If buffer is a NULL pointer or size is smaller than the
       automatically allocated buffer, the automatically allocated
       buffer is used as the buffer area.

    o  If buffer is a NULL pointer and size is larger than the
       automatically allocated buffer, then setvbuf allocates a new
       buffer equal to the specified size and uses that as the file
       buffer.

    User programs must not depend on the contents of buffer once I/O
    has been performed on the stream. The 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 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
    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 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.

3  –  Return Values

    0                  Indicates success.
    nonzero value      Indicates that an invalid input value was
                       specified for type or file_ptr, or because
                       file_ptr is being used by another thread.