This topic describes buffering modes used by z/OS® XL C/C++ library
functions available to control buffering and methods of flushing buffers.
z/OS XL C/C++ uses
buffers to map C I/O to system-level I/O. When
z/OS XL C/C++ performs
I/O operations, it uses one of the following buffering modes:
- Line buffering - characters
are transmitted to the system as a block when a new-line character
is encountered. Line buffering is meaningful only for text streams
and UNIX file system files.
- Full buffering - characters are transmitted to the system
as a block when a buffer is filled.
- No buffering - characters are transmitted to the system
as they are written. Only regular memory files and UNIX file
system files support the no buffering mode.
The buffer mode affects the way the buffer is flushed. You
can use the
setvbuf() and
setbuf() library
functions to control buffering, but you cannot change the buffering
mode after an I/O operation has used the buffer, as all read, write,
and reposition operations do. In some circumstances, repositioning
alters the contents of the buffer. It is strongly recommended that
you only use
setbuf() and
setvbuf() before
any I/O,
to conform with ANSI, and to avoid any dependency on the current implementation.
If you use
setvbuf(),
z/OS XL C/C++ may
or may not accept your buffer for its internal use. For a hiperspace
memory file, if the size of the buffer specified to
setvbuf() is
8K or more, it will affect the number of hiperspace blocks read or
written on each call to the operating system; the size is rounded
down to the nearest multiple of 4K.
Full buffering is the default except in the following cases:
- If you are using an interactive terminal, z/OS XL C/C++ uses
line buffering.
- If you are running under CICS®, z/OS XL C/C++ also
uses line buffering.
- stderr is
line-buffered by default.
- If you are using a memory file, z/OS XL C/C++ does
not use any buffering.
For terminals, because I/O is always unblocked, line buffering
is equivalent to full buffering.
For record I/O files, buffering is meaningful only for blocked
files or for record I/O files in z/OS UNIX
file system using full buffering. For unblocked files, the buffer
is full after every write and is therefore written immediately, leaving
nothing to flush. For blocked files or fully-buffered UNIX file system
files, however, the buffer can contain one or more records that have
not been flushed and that require a flush operation for them to go
to the system.
For blocked I/O files, buffering is always meaningless.
You can flush buffers to the system in several different ways.
- If you are using full buffering, z/OS XL C/C++ automatically
flushes a buffer when it is filled.
- If you are using line buffering for a text file or a UNIX file
system file, z/OS XL C/C++ flushes
a buffer when you complete it with a control character. Except for
UNIX file system files, specifying line buffering for a record I/O,
blocked I/O, or binary file has no effect; z/OS XL C/C++ treats
the file as if you had specified full buffering.
- z/OS XL C/C++ flushes
buffers to the system when you close a file or end a program.
- z/OS XL C/C++ flushes
buffers to the system when you call the fflush() library
function, with the following restrictions:
- A file opened in text mode does not flush data if a record has
not been completed with a new-line.
- A file opened in fixed format does not flush incomplete records
to the file.
- An FBS file does not flush out a short block
unless it is a DISK file opened without the NOSEEK parameter.
- All streams are flushed across non-POSIX system() calls.
Streams are not flushed across POSIX system() calls.
For a POSIX system call, we recommend that you do a fflush() before
the system() call.
If you are reading a record that another user is writing to
at the same time, you can see the new data if you call
fflush() to
refresh the contents of the input buffer.
Note: This is not supported for VSAM files.
You may not see output if a program that is using input and output
fails, and the error handling routines cannot close all the open files.