Debian Codegraph @

upstream/debian-unstable/man2/posix_fadvise.2

raw
1 .\" Copyright 2003, Abhijit Menon-Sen <[email protected]>
2 .\" Copyright 2010-2017, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH posix_fadvise 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 posix_fadvise \- predeclare an access pattern for file data
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <fcntl.h>
16 .P
17 .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " size \
18 ", int " advice ");"
19 .fi
20 .P
21 .ad l
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR posix_fadvise ():
28 .nf
29 _POSIX_C_SOURCE >= 200112L
30 .fi
31 .SH DESCRIPTION
32 Programs can use
33 .BR posix_fadvise ()
34 to announce an intention to access
35 file data in a specific pattern in the future, thus allowing the kernel
36 to perform appropriate optimizations.
37 .P
38 The
39 .I advice
40 applies to a (not necessarily existent) region
41 starting at
42 .I offset
43 and extending for
44 .I size
45 bytes
46 (or until the end of the file if
47 .I size
48 is 0)
49 within the file referred to by
50 .IR fd .
51 The
52 .I advice
53 is not binding;
54 it merely constitutes an expectation on behalf of
55 the application.
56 .P
57 Permissible values for
58 .I advice
59 include:
60 .TP
61 .B POSIX_FADV_NORMAL
62 Indicates that the application has no advice to give about its access
63 pattern for the specified data.
64 If no advice is given for an open file,
65 this is the default assumption.
66 .TP
67 .B POSIX_FADV_SEQUENTIAL
68 The application expects to access the specified data sequentially (with
69 lower offsets read before higher ones).
70 .TP
71 .B POSIX_FADV_RANDOM
72 The specified data will be accessed in random order.
73 .TP
74 .B POSIX_FADV_NOREUSE
75 The specified data will be accessed only once.
76 .IP
77 Before Linux 2.6.18,
78 .B POSIX_FADV_NOREUSE
79 had the
80 same semantics as
81 .BR POSIX_FADV_WILLNEED .
82 This was probably a bug;
83 from Linux 2.6.18 until Linux 6.2 this flag was a no-op.
84 Since Linux 6.3,
85 .B POSIX_FADV_NOREUSE
86 signals that the kernel page replacement algorithm
87 can ignore access to mapped page cache marked by this flag.
88 This is useful, for example, while streaming large files.
89 .TP
90 .B POSIX_FADV_WILLNEED
91 The specified data will be accessed in the near future.
92 .IP
93 .B POSIX_FADV_WILLNEED
94 initiates a
95 nonblocking read of the specified region into the page cache.
96 The amount of data read may be decreased by the kernel depending
97 on virtual memory load.
98 (A few megabytes will usually be fully satisfied,
99 and more is rarely useful.)
100 .TP
101 .B POSIX_FADV_DONTNEED
102 The specified data will not be accessed in the near future.
103 .IP
104 .B POSIX_FADV_DONTNEED
105 attempts to free cached pages associated with
106 the specified region.
107 This is useful, for example, while streaming large
108 files.
109 A program may periodically request the kernel to free cached data
110 that has already been used, so that more useful cached pages are not
111 discarded instead.
112 .IP
113 Requests to discard partial pages are ignored.
114 It is preferable to preserve needed data than discard unneeded data.
115 If the application requires that data be considered for discarding, then
116 .I offset
117 and
118 .I size
119 must be page-aligned.
120 .IP
121 The implementation
122 .I may
123 attempt to write back dirty pages in the specified region,
124 but this is not guaranteed.
125 Any unwritten dirty pages will not be freed.
126 If the application wishes to ensure that dirty pages will be released,
127 it should call
128 .BR fsync (2)
129 or
130 .BR fdatasync (2)
131 first.
132 .SH RETURN VALUE
133 On success, zero is returned.
134 On error, an error number is returned.
135 .SH ERRORS
136 .TP
137 .B EBADF
138 The
139 .I fd
140 argument was not a valid file descriptor.
141 .TP
142 .B EINVAL
143 An invalid value was specified for
144 .IR advice .
145 .TP
146 .B ESPIPE
147 The specified file descriptor refers to a pipe or FIFO.
148 .RB ( ESPIPE
149 is the error specified by POSIX,
150 but before Linux 2.6.16,
151 .\" commit 87ba81dba431232548ce29d5d224115d0c2355ac
152 Linux returned
153 .B EINVAL
154 in this case.)
155 .SH VERSIONS
156 Under Linux,
157 .B POSIX_FADV_NORMAL
158 sets the readahead window to the
159 default size for the backing device;
160 .B POSIX_FADV_SEQUENTIAL
161 doubles this size,
162 and
163 .B POSIX_FADV_RANDOM
164 disables file readahead entirely.
165 .B POSIX_FADV_NOREUSE
166 does not modify the readahead window size.
167 These changes affect the entire file, not just the specified region
168 (but other open file handles to the same file are unaffected).
169 .SS C library/kernel differences
170 The name of the wrapper function in the C library is
171 .BR posix_fadvise ().
172 The underlying system call is called
173 .BR fadvise64 ()
174 (or, on some architectures,
175 .BR fadvise64_64 ());
176 the difference between the two is that the former system call
177 assumes that the type of the
178 .I size
179 argument is
180 .IR size_t ,
181 while the latter expects
182 .I loff_t
183 there.
184 .SS Architecture-specific variants
185 Some architectures require
186 64-bit arguments to be aligned in a suitable pair of registers (see
187 .BR syscall (2)
188 for further detail).
189 On such architectures, the call signature of
190 .BR posix_fadvise ()
191 shown in the SYNOPSIS would force
192 a register to be wasted as padding between the
193 .I fd
194 and
195 .I offset
196 arguments.
197 Therefore, these architectures define a version of the
198 system call that orders the arguments suitably,
199 but is otherwise exactly the same as
200 .BR posix_fadvise ().
201 .P
202 For example, since Linux 2.6.14, ARM has the following system call:
203 .P
204 .in +4n
205 .EX
206 .BI "long arm_fadvise64_64(int " fd ", int " advice ,
207 .BI " loff_t " offset ", loff_t " size );
208 .EE
209 .in
210 .P
211 These architecture-specific details are generally
212 hidden from applications by the glibc
213 .BR posix_fadvise ()
214 wrapper function,
215 which invokes the appropriate architecture-specific system call.
216 .SH STANDARDS
217 POSIX.1-2024.
218 .SH HISTORY
219 POSIX.1-2001.
220 .P
221 Kernel support first appeared in Linux 2.5.60;
222 the underlying system call is called
223 .BR fadvise64 ().
224 .\" of fadvise64_64()
225 Library support has been provided since glibc 2.2,
226 via the wrapper function
227 .BR posix_fadvise ().
228 .P
229 Since Linux 3.18,
230 .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
231 support for the underlying system call is optional,
232 depending on the setting of the
233 .B CONFIG_ADVISE_SYSCALLS
234 configuration option.
235 .P
236 The type of the
237 .I size
238 argument was changed from
239 .I size_t
240 to
241 .I off_t
242 in POSIX.1-2001 TC1.
243 .SH NOTES
244 The contents of the kernel buffer cache can be cleared via the
245 .I /proc/sys/vm/drop_caches
246 interface described in
247 .BR proc (5).
248 .P
249 One can obtain a snapshot of which pages of a file are resident
250 in the buffer cache by opening a file, mapping it with
251 .BR mmap (2),
252 and then applying
253 .BR mincore (2)
254 to the mapping.
255 .SH BUGS
256 Before Linux 2.6.6, if
257 .I size
258 was specified as 0, then this was interpreted literally as "zero bytes",
259 rather than as meaning "all bytes through to the end of the file".
260 .SH SEE ALSO
261 .BR fincore (1),
262 .BR mincore (2),
263 .BR readahead (2),
264 .BR sync_file_range (2),
265 .BR posix_fallocate (3),
266 .BR posix_madvise (3)