Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
Copyright 2020 Joyent, Inc.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#include <sys/types.h> #include <sys/fcntl.h> 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>. 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.
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.
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 descriptor.
The fildes argument is not associated with a file system that accepts advisory functions.
The value in advice is invalid.
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)).
See attributes(7) for descriptions of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| MT-Level MT-Safe |
mmap (2), open (2), read (2), write (2), fcntl.h (3HEAD), attributes (7), fstyp (8)
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.