man2/posix_fadvise.2

   1 .\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org>
   2 .\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   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 2021-03-22 "Linux" "Linux Programmer's Manual"
  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 .PP
  19 .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \
  20 ", int " advice ");"
  21 .fi
  22 .PP
  23 .ad l
  24 .RS -4
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .RE
  28 .PP
  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 .PP
  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 .PP
  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 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.
  68 .TP
  69 .B POSIX_FADV_WILLNEED
  70 The specified data will be accessed in the near future.
  71 .IP
  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.)
  78 .TP
  79 .B POSIX_FADV_DONTNEED
  80 The specified data will not be accessed in the near future.
  81 .IP
  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.
  89 .IP
  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.
  97 .IP
  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
 105 .BR fsync (2)
 106 or
 107 .BR fdatasync (2)
 108 first.
 109 .SH RETURN VALUE
 110 On success, zero is returned.
 111 On error, an error number is returned.
 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
 121 The specified file descriptor refers to a pipe or FIFO.
 122 .RB ( ESPIPE
 123 is the error specified by POSIX,
 124 but before kernel version 2.6.16,
 125 .\" commit 87ba81dba431232548ce29d5d224115d0c2355ac
 126 Linux returned
 127 .B EINVAL
 128 in this case.)
 129 .SH VERSIONS
 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 ().
 137 .PP
 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.
 144 .SH CONFORMING TO
 145 POSIX.1-2001, POSIX.1-2008.
 146 Note that the type of the
 147 .I len
 148 argument was changed from
 149 .I size_t
 150 to
 151 .I off_t
 152 in POSIX.1-2001 TC1.
 153 .SH NOTES
 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.
 157 These changes affect the entire file, not just the specified region
 158 (but other open file handles to the same file are unaffected).
 159 .PP
 160 The contents of the kernel buffer cache can be cleared via the
 161 .IR /proc/sys/vm/drop_caches
 162 interface described in
 163 .BR proc (5).
 164 .PP
 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.
 171 .SS C library/kernel differences
 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,
 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.
 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
 187 .BR posix_fadvise ()
 188 shown in the SYNOPSIS would force
 189 a register to be wasted as padding between the
 190 .I fd
 191 and
 192 .I offset
 193 arguments.
 194 Therefore, these architectures define a version of the
 195 system call that orders the arguments suitably,
 196 but is otherwise exactly the same as
 197 .BR posix_fadvise ().
 198 .PP
 199 For example, since Linux 2.6.14, ARM has the following system call:
 200 .PP
 201 .in +4n
 202 .EX
 203 .BI "long arm_fadvise64_64(int " fd ", int " advice ,
 204 .BI "                      loff_t " offset ", loff_t " len );
 205 .EE
 206 .in
 207 .PP
 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.
 213 .SH BUGS
 214 In kernels before 2.6.6, if
 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".
 218 .SH SEE ALSO
 219 .BR fincore (1),
 220 .BR mincore (2),
 221 .BR readahead (2),
 222 .BR sync_file_range (2),
 223 .BR posix_fallocate (3),
 224 .BR posix_madvise (3)