]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org> |
26861234 | 2 | .\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk <mtk.manpages@gmail.com> |
2297bf0e | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da | 5 | .\" |
f21a10c8 | 6 | .\" 2005-04-08 mtk, noted kernel version and added BUGS |
dc30fdc6 | 7 | .\" 2010-10-09, mtk, document arm_fadvise64_64() |
f21a10c8 | 8 | .\" |
1d767b55 | 9 | .TH POSIX_FADVISE 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da MK |
10 | .SH NAME |
11 | posix_fadvise \- predeclare an access pattern for file data | |
325c7f22 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
17 | .B #include <fcntl.h> | |
68e4db0a | 18 | .PP |
34e8ac03 MK |
19 | .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ |
20 | ", int " advice ");" | |
fea681da | 21 | .fi |
68e4db0a | 22 | .PP |
9a30939e | 23 | .ad l |
d39ad78f | 24 | .RS -4 |
9a30939e MK |
25 | Feature Test Macro Requirements for glibc (see |
26 | .BR feature_test_macros (7)): | |
d39ad78f | 27 | .RE |
68e4db0a | 28 | .PP |
9a30939e | 29 | .BR posix_fadvise (): |
9d2adbae | 30 | .nf |
5c10d2c5 | 31 | _POSIX_C_SOURCE >= 200112L |
9d2adbae | 32 | .fi |
fea681da | 33 | .SH DESCRIPTION |
60a90ecd MK |
34 | Programs can use |
35 | .BR posix_fadvise () | |
36 | to announce an intention to access | |
fea681da | 37 | file data in a specific pattern in the future, thus allowing the kernel |
d9bfdb9c | 38 | to perform appropriate optimizations. |
efeece04 | 39 | .PP |
fea681da MK |
40 | The \fIadvice\fP applies to a (not necessarily existent) region starting |
41 | at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of | |
c13182ef | 42 | the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. |
b265f7bb YK |
43 | The \fIadvice\fP is not binding; |
44 | it merely constitutes an expectation on behalf of | |
fea681da | 45 | the application. |
efeece04 | 46 | .PP |
fea681da MK |
47 | Permissible values for \fIadvice\fP include: |
48 | .TP | |
49 | .B POSIX_FADV_NORMAL | |
50 | Indicates that the application has no advice to give about its access | |
c13182ef MK |
51 | pattern for the specified data. |
52 | If no advice is given for an open file, | |
fea681da MK |
53 | this is the default assumption. |
54 | .TP | |
55 | .B POSIX_FADV_SEQUENTIAL | |
56 | The application expects to access the specified data sequentially (with | |
57 | lower offsets read before higher ones). | |
58 | .TP | |
59 | .B POSIX_FADV_RANDOM | |
60 | The specified data will be accessed in random order. | |
61 | .TP | |
62 | .B POSIX_FADV_NOREUSE | |
63 | The specified data will be accessed only once. | |
efeece04 | 64 | .IP |
a6b80261 MK |
65 | In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the |
66 | same semantics as \fBPOSIX_FADV_WILLNEED\fP. | |
67 | This was probably a bug; since kernel 2.6.18, this flag is a no-op. | |
fea681da MK |
68 | .TP |
69 | .B POSIX_FADV_WILLNEED | |
70 | The specified data will be accessed in the near future. | |
efeece04 | 71 | .IP |
a6b80261 MK |
72 | \fBPOSIX_FADV_WILLNEED\fP initiates a |
73 | nonblocking read of the specified region into the page cache. | |
74 | The amount of data read may be decreased by the kernel depending | |
75 | on virtual memory load. | |
76 | (A few megabytes will usually be fully satisfied, | |
77 | and more is rarely useful.) | |
fea681da MK |
78 | .TP |
79 | .B POSIX_FADV_DONTNEED | |
80 | The specified data will not be accessed in the near future. | |
efeece04 | 81 | .IP |
a6b80261 MK |
82 | \fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with |
83 | the specified region. | |
84 | This is useful, for example, while streaming large | |
85 | files. | |
86 | A program may periodically request the kernel to free cached data | |
87 | that has already been used, so that more useful cached pages are not | |
88 | discarded instead. | |
efeece04 | 89 | .IP |
a6b80261 MK |
90 | Requests to discard partial pages are ignored. |
91 | It is preferable to preserve needed data than discard unneeded data. | |
92 | If the application requires that data be considered for discarding, then | |
93 | .I offset | |
94 | and | |
95 | .I len | |
96 | must be page-aligned. | |
efeece04 | 97 | .IP |
f90b94e3 MK |
98 | The implementation |
99 | .I may | |
100 | attempt to write back dirty pages in the specified region, | |
101 | but this is not guaranteed. | |
102 | Any unwritten dirty pages will not be freed. | |
103 | If the application wishes to ensure that dirty pages will be released, | |
104 | it should call | |
a6b80261 MK |
105 | .BR fsync (2) |
106 | or | |
107 | .BR fdatasync (2) | |
108 | first. | |
47297adb | 109 | .SH RETURN VALUE |
c13182ef | 110 | On success, zero is returned. |
b857d3da | 111 | On error, an error number is returned. |
fea681da MK |
112 | .SH ERRORS |
113 | .TP | |
114 | .B EBADF | |
115 | The \fIfd\fP argument was not a valid file descriptor. | |
116 | .TP | |
117 | .B EINVAL | |
118 | An invalid value was specified for \fIadvice\fP. | |
119 | .TP | |
120 | .B ESPIPE | |
682edefb | 121 | The specified file descriptor refers to a pipe or FIFO. |
e0f1f176 MK |
122 | .RB ( ESPIPE |
123 | is the error specified by POSIX, | |
77483b7c | 124 | but before kernel version 2.6.16, |
e0f1f176 MK |
125 | .\" commit 87ba81dba431232548ce29d5d224115d0c2355ac |
126 | Linux returned | |
682edefb MK |
127 | .B EINVAL |
128 | in this case.) | |
a1d5f77c | 129 | .SH VERSIONS |
e049eee8 MK |
130 | Kernel support first appeared in Linux 2.5.60; |
131 | the underlying system call is called | |
132 | .BR fadvise64 (). | |
133 | .\" of fadvise64_64() | |
134 | Library support has been provided since glibc version 2.2, | |
135 | via the wrapper function | |
136 | .BR posix_fadvise (). | |
efeece04 | 137 | .PP |
732df53e MK |
138 | Since Linux 3.18, |
139 | .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb | |
140 | support for the underlying system call is optional, | |
141 | depending on the setting of the | |
142 | .B CONFIG_ADVISE_SYSCALLS | |
143 | configuration option. | |
47297adb | 144 | .SH CONFORMING TO |
fc588289 | 145 | POSIX.1-2001, POSIX.1-2008. |
a1d5f77c MK |
146 | Note that the type of the |
147 | .I len | |
c4bb193f | 148 | argument was changed from |
a1d5f77c MK |
149 | .I size_t |
150 | to | |
151 | .I off_t | |
d645b01b | 152 | in POSIX.1-2001 TC1. |
a1d5f77c | 153 | .SH NOTES |
fea681da MK |
154 | Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the |
155 | default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles | |
156 | this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. | |
8c450534 | 157 | These changes affect the entire file, not just the specified region |
fea681da | 158 | (but other open file handles to the same file are unaffected). |
efeece04 | 159 | .PP |
38ca1220 | 160 | The contents of the kernel buffer cache can be cleared via the |
1ae6b2c7 | 161 | .I /proc/sys/vm/drop_caches |
38ca1220 MK |
162 | interface described in |
163 | .BR proc (5). | |
efeece04 | 164 | .PP |
ba759b3c MK |
165 | One can obtain a snapshot of which pages of a file are resident |
166 | in the buffer cache by opening a file, mapping it with | |
167 | .BR mmap (2), | |
168 | and then applying | |
169 | .BR mincore (2) | |
170 | to the mapping. | |
0722a578 | 171 | .SS C library/kernel differences |
a97b7078 MK |
172 | The name of the wrapper function in the C library is |
173 | .BR posix_fadvise (). | |
174 | The underlying system call is called | |
175 | .BR fadvise64 () | |
176 | (or, on some architectures, | |
3631bd72 MK |
177 | .BR fadvise64_64 ()); |
178 | the difference between the two is that the former system call | |
179 | assumes that the type of the \fIlen\fP argument is \fIsize_t\fP, | |
180 | while the latter expects \fIloff_t\fP there. | |
63ec43ae MK |
181 | .SS Architecture-specific variants |
182 | Some architectures require | |
183 | 64-bit arguments to be aligned in a suitable pair of registers (see | |
184 | .BR syscall (2) | |
185 | for further detail). | |
186 | On such architectures, the call signature of | |
dc30fdc6 | 187 | .BR posix_fadvise () |
63ec43ae MK |
188 | shown in the SYNOPSIS would force |
189 | a register to be wasted as padding between the | |
dc30fdc6 MK |
190 | .I fd |
191 | and | |
500bd052 | 192 | .I offset |
dc30fdc6 | 193 | arguments. |
63ec43ae MK |
194 | Therefore, these architectures define a version of the |
195 | system call that orders the arguments suitably, | |
416d9876 | 196 | but is otherwise exactly the same as |
63ec43ae | 197 | .BR posix_fadvise (). |
efeece04 | 198 | .PP |
63ec43ae | 199 | For example, since Linux 2.6.14, ARM has the following system call: |
dc30fdc6 MK |
200 | .PP |
201 | .in +4n | |
b8302363 | 202 | .EX |
dc30fdc6 | 203 | .BI "long arm_fadvise64_64(int " fd ", int " advice , |
503979fa | 204 | .BI " loff_t " offset ", loff_t " len ); |
b8302363 | 205 | .EE |
dc30fdc6 MK |
206 | .in |
207 | .PP | |
63ec43ae MK |
208 | These architecture-specific details are generally |
209 | hidden from applications by the glibc | |
210 | .BR posix_fadvise () | |
211 | wrapper function, | |
212 | which invokes the appropriate architecture-specific system call. | |
f21a10c8 | 213 | .SH BUGS |
c13182ef | 214 | In kernels before 2.6.6, if |
f21a10c8 MK |
215 | .I len |
216 | was specified as 0, then this was interpreted literally as "zero bytes", | |
217 | rather than as meaning "all bytes through to the end of the file". | |
47297adb | 218 | .SH SEE ALSO |
4cb046d3 | 219 | .BR fincore (1), |
250d41b9 | 220 | .BR mincore (2), |
ef276d2f | 221 | .BR readahead (2), |