Standard C Library Functions directio(3C)
NAME
directio - provide advice to file system
SYNOPSIS
#include
#include
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 .
DIRECTIOF 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) opera-
tions 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 writ-
ten asynchronously to the device. When pos-
sible, the cached data is "clustered" into
large chunks and written to the device in a
SunOS 5.11 Last change: 9 Apr 2003 1
Standard C Library Functions directio(3C)
single write operation.
The system behavior for DIRECTIOF can
change without notice.
DIRECTION 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 DIRECTION can
change without notice.
RETURN VALUES
Upon successful completion, directio() returns 0. Otherwise,
it returns -1 and sets errno to indicate the error.
ERORS
The directio() function will fail if:
EBADF The fildes argument is not a valid open file
descriptor.
ENOTY The fildes argument is not associated with a file
system that accepts advisory functions.
EINVAL The value in advice is invalid.
USAGE
SunOS 5.11 Last change: 9 Apr 2003 2
Standard C Library Functions directio(3C)
Small sequential I/O generally performs best with
DIRECTIOF.
Large sequential I/O generally performs best with
DIRECTION, except when a file is sparse or is being
extended and is opened with OSYNC or ODSYNC (see
open(2)).
The directio() function is supported for the NFS and UFS
file system types (see fstyp(1M)).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
fstyp(1M), mmap(2), open(2), read(2), write(2),
fcntl.h(3HEAD), attributes(5)
WARNINGS
Switching between DIRECTIOF and DIRECTION can slow
the system because each switch to DIRECTION might entail
flushing the file's data from the system's memory.
SunOS 5.11 Last change: 9 Apr 2003 3
|
