DIRECTIO(3C) Standard C Library Functions DIRECTIO(3C)
NAME
directio - provide advice to file system
SYNOPSIS
#include <sys/types.h>
#include <sys/fcntl.h>
int directio(
int fildes,
int advice);
DESCRIPTION
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>.
DIRECTIO_OFF 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 write operation.
The system behavior for
DIRECTIO_OFF can change without
notice.
DIRECTIO_ON 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) operations. When such
transfers are not possible, the system switches back to
the default behavior, but just for that operation. In
general, the transfer is possible 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 without
notice.
RETURN VALUES
Upon successful completion,
directio() returns
0. Otherwise, it returns
-1 and sets
errno to indicate the error.
ERRORS
The
directio() function will fail if:
EBADF The
fildes argument is not a valid open file descriptor.
ENOTTY The
fildes argument is not associated with a file system that
accepts advisory functions.
EINVAL The value in
advice is invalid.
USAGE
Small sequential I/O generally performs best with
DIRECTIO_OFF.
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
open(2)).
The
directio() function is supported for the NFS, UFS and ZFS file system
types (see
fstyp(8)).
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+
SEE ALSO
mmap(2),
open(2),
read(2),
write(2),
fcntl.h(3HEAD),
attributes(7),
fstyp(8)WARNINGS
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.
February 28, 2020
DIRECTIO(3C)