directio - provide advice to file system
int directio(int fildes, int advice);
The directio() function provides advice to the system about
the expected behavior of the application when accessing the
data in the file associated with the open file descriptor
fildes. The system uses this information to help optimize
accesses to the file's data. The directio() function has no
effect on the semantics of the other operations on the data,
though it may affect the performance of other operations.
The advice argument is kept per file; the last caller of
directio() sets the advice for all applications using the
file associated with fildes.
Values for advice are defined in <sys/fcntl.h>.
Applications get the default system behavior when
accessing file data.
When an application reads data from a file, the data
is first cached in system memory and then copied into
the application's buffer (see read(2)). If the system
detects that the application is reading sequentially
from a file, the system will asynchronously "read
ahead" from the file into system memory so the data is
immediately available for the next read(2) operation.
When an application writes data into a file, the data
is first cached in system memory and is written to the
device at a later time (see write(2)). When possible,
the system increases the performance of write(2)
operations by cacheing the data in memory pages. The
data is copied into system memory and the write(2)
operation returns immediately to the application. The
data is later written asynchronously to the device.
When possible, the cached data is "clustered" into
large chunks and written to the device in a single
The system behavior for DIRECTIO_OFF can change
The system behaves as though the application is not
going to reuse the file data in the near future. In
other words, the file data is not cached in the
system's memory pages.
When possible, data is read or written directly
between the application's memory and the device when
the data is accessed with read(2) and write(2) opera-
tions. When such transfers are not possible, the sys-
tem switches back to the default behavior, but just
for that operation. In general, the transfer is pos-
sible when the application's buffer is aligned on a
two-byte (short) boundary, the offset into the file is
on a device sector boundary, and the size of the
operation is a multiple of device sectors.
This advisory is ignored while the file associated
with fildes is mapped (see mmap(2)).
The system behavior for DIRECTIO_ON can change
Upon successful completion, directio() returns 0. Otherwise,
it returns -1 and sets errno to indicate the error.
The directio() function will fail if:
EBADF The fildes argument is not a valid open file descrip-
The fildes argument is not associated with a file sys-
tem that accepts advisory functions.
The value in advice is invalid.
Small sequential I/O generally performs best with
Large sequential I/O generally performs best with
DIRECTIO_ON, except when a file is sparse or is being
extended and is opened with O_SYNC or O_DSYNC (see
The directio() function is supported for the ufs file system
type (see fstyp(1M)).
See attributes(5) for descriptions of the following attri-
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe |
fstyp(1M), mmap(2), open(2), read(2), write(2), attri-
Switching between DIRECTIO_OFF and DIRECTIO_ON can slow
the system because each switch to DIRECTIO_ON might entail
flushing the file's data from the system's memory.
Man(1) output converted with