Debian Codegraph @

upstream/fedora-44/man2/posix_fadvise.2

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