| 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) |