usr/src/man/man3c/directio.3c

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