1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.\" 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]
.TH DIRECTIO 3C "Apr 9, 2003"
.SH NAME
directio \- provide advice to file system
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/fcntl.h>
\fBint\fR \fBdirectio\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIadvice\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBdirectio()\fR 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 \fIfildes\fR. The system uses this information to help
optimize accesses to the file's data. The \fBdirectio()\fR function has no
effect on the semantics of the other operations on the data, though it may
affect the performance of other operations.
.sp
.LP
The \fIadvice\fR argument is kept per file; the last caller of \fBdirectio()\fR
sets the \fIadvice\fR for all applications using the file associated with
\fIfildes\fR.
.sp
.LP
Values for \fIadvice\fR are defined in \fB<sys/fcntl.h>\fR\&.
.sp
.ne 2
.na
\fB\fBDIRECTIO_OFF\fR\fR
.ad
.RS 16n
Applications get the default system behavior when accessing file data.
.sp
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 \fBread\fR(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 \fBread\fR(2) operation.
.sp
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 \fBwrite\fR(2)). When
possible, the system increases the performance of \fBwrite\fR(2) operations by
cacheing the data in memory pages. The data is copied into system memory and
the \fBwrite\fR(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.
.sp
The system behavior for \fBDIRECTIO_OFF\fR can change without notice.
.RE
.sp
.ne 2
.na
\fB\fBDIRECTIO_ON\fR\fR
.ad
.RS 16n
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.
.sp
When possible, data is read or written directly between the application's
memory and the device when the data is accessed with \fBread\fR(2) and
\fBwrite\fR(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.
.sp
This advisory is ignored while the file associated with \fIfildes\fR is mapped
(see \fBmmap\fR(2)).
.sp
The system behavior for \fBDIRECTIO_ON\fR can change without notice.
.RE
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBdirectio()\fR returns \fB0\fR. Otherwise, it
returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBdirectio()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
The \fIfildes\fR argument is not a valid open file descriptor.
.RE
.sp
.ne 2
.na
\fB\fBENOTTY\fR\fR
.ad
.RS 10n
The \fIfildes\fR argument is not associated with a file system that accepts
advisory functions.
.RE
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The value in \fIadvice\fR is invalid.
.RE
.SH USAGE
.sp
.LP
Small sequential I/O generally performs best with \fBDIRECTIO_OFF\fR.
.sp
.LP
Large sequential I/O generally performs best with \fBDIRECTIO_ON\fR, except
when a file is sparse or is being extended and is opened with \fBO_SYNC\fR or
\fBO_DSYNC\fR (see \fBopen\fR(2)).
.sp
.LP
The \fBdirectio()\fR function is supported for the NFS and UFS file system
types (see \fBfstyp\fR(1M)).
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
MT-Level MT-Safe
.TE
.SH SEE ALSO
.sp
.LP
\fBfstyp\fR(1M), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2),
\fBfcntl.h\fR(3HEAD), \fBattributes\fR(5)
.SH WARNINGS
.sp
.LP
Switching between \fBDIRECTIO_OFF\fR and \fBDIRECTIO_ON\fR can slow the
system because each switch to \fBDIRECTIO_ON\fR might entail flushing the
file's data from the system's memory.
|
