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)