| blob | 2d163fa1a85ad3c82a0c1eaaef73af300f78deb6 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
44 .\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .TH POSIX_FADVISE 3C "Jul 14, 2008"
47 .SH NAME
48 posix_fadvise \- file advisory information
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <fcntl.h>
54 \fBint\fR \fBposix_fadvise\fR(\fBint\fR \fIfd\fR, \fBoff_t\fR \fIoffset\fR, \fBoff_t\fR \fIlen\fR, \fBint\fR \fIadvice\fR);
55 .fi
57 .SH DESCRIPTION
58 .sp
59 .LP
60 The \fBposix_fadvise()\fR function advises the system on the expected behavior
61 of the application with respect to the data in the file associated with the
62 open file descriptor, \fIfd\fR, starting at \fIoffset\fR and continuing for
63 \fIlen\fR bytes. The specified range need not currently exist in the file. If
64 \fIlen\fR is zero, all data following offset is specified. The system may use
65 this information to optimize handling of the specified data. The
66 \fBposix_fadvise()\fR function has no effect on the semantics of other
67 operations on the specified data, although it may affect the performance of
68 other operations.
69 .sp
70 .LP
71 The advice to be applied to the data is specified by the \fIadvice\fR parameter
72 and may be one of the following values:
73 .sp
74 .ne 2
75 .na
76 \fB\fBPOSIX_FADV_NORMAL\fR\fR
77 .ad
78 .RS 25n
79 Specifies that the application has no advice to give on its behavior with
80 respect to the specified data. It is the default characteristic if no advice is
81 given for an open file.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fBPOSIX_FADV_SEQUENTIAL\fR\fR
88 .ad
89 .RS 25n
90 Specifies that the application expects to access the specified data
91 sequentially from lower offsets to higher offsets.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fBPOSIX_FADV_RANDOM\fR\fR
98 .ad
99 .RS 25n
100 Specifies that the application expects to access the specified data in a random
101 order.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fBPOSIX_FADV_WILLNEED\fR\fR
108 .ad
109 .RS 25n
110 Specifies that the application expects to access the specified data in the near
111 future.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fBPOSIX_FADV_DONTNEED\fR\fR
118 .ad
119 .RS 25n
120 Specifies that the application expects that it will not access the specified
121 data in the near future.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBPOSIX_FADV_NOREUSE\fR\fR
128 .ad
129 .RS 25n
130 Specifies that the application expects to access the specified data once and
131 then not reuse it thereafter.
132 .RE
134 .sp
135 .LP
136 These values are defined in \fB<fcntl.h>\fR
137 .SH RETURN VALUES
138 .sp
139 .LP
140 Upon successful completion, \fBposix_fadvise()\fR returns zero. Otherwise, an
141 error number is returned to indicate the error.
142 .SH ERRORS
143 .sp
144 .LP
145 The \fBposix_fadvise()\fR function will fail if:
146 .sp
147 .ne 2
148 .na
149 \fB\fBEBADF\fR\fR
150 .ad
151 .RS 10n
152 The \fIfd\fR argument is not a valid file descriptor.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBEINVAL\fR\fR
159 .ad
160 .RS 10n
161 The value of \fIadvice\fR is invalid, or the value of \fIlen\fR is less than
162 zero.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBESPIPE\fR\fR
169 .ad
170 .RS 10n
171 The \fIfd\fR argument is associated with a pipe or FIFO.
172 .RE
174 .SH USAGE
175 .sp
176 .LP
177 The \fBposix_fadvise()\fR function has a transitional interface for 64-bit file
178 offsets. See \fBlf64\fR(5).
179 .SH ATTRIBUTES
180 .sp
181 .LP
182 See \fBattributes\fR(5) for descriptions of the following attributes:
183 .sp
185 .sp
186 .TS
187 box;
188 c | c
189 l | l .
190 ATTRIBUTE TYPE ATTRIBUTE VALUE
191 _
192 Interface Stability Committed
193 _
194 MT-Level MT-Safe
195 _
196 Standard See \fBstandards\fR(5).
197 .TE
199 .SH SEE ALSO
200 .sp
201 .LP
202 \fBposix_madvise\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)