diff options
Diffstat (limited to 'man2/posix_fadvise.2')
| -rw-r--r-- | man2/posix_fadvise.2 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 new file mode 100644 index 0000000..38e9745 --- /dev/null +++ b/man2/posix_fadvise.2 @@ -0,0 +1,227 @@ +.\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org> +.\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2005-04-08 mtk, noted kernel version and added BUGS +.\" 2010-10-09, mtk, document arm_fadvise64_64() +.\" +.TH posix_fadvise 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +posix_fadvise \- predeclare an access pattern for file data +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.PP +.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ +", int " advice ");" +.fi +.PP +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR posix_fadvise (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +Programs can use +.BR posix_fadvise () +to announce an intention to access +file data in a specific pattern in the future, thus allowing the kernel +to perform appropriate optimizations. +.PP +The \fIadvice\fP applies to a (not necessarily existent) region starting +at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of +the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. +The \fIadvice\fP is not binding; +it merely constitutes an expectation on behalf of +the application. +.PP +Permissible values for \fIadvice\fP include: +.TP +.B POSIX_FADV_NORMAL +Indicates that the application has no advice to give about its access +pattern for the specified data. +If no advice is given for an open file, +this is the default assumption. +.TP +.B POSIX_FADV_SEQUENTIAL +The application expects to access the specified data sequentially (with +lower offsets read before higher ones). +.TP +.B POSIX_FADV_RANDOM +The specified data will be accessed in random order. +.TP +.B POSIX_FADV_NOREUSE +The specified data will be accessed only once. +.IP +Before Linux 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the +same semantics as \fBPOSIX_FADV_WILLNEED\fP. +This was probably a bug; since Linux 2.6.18, this flag is a no-op. +.TP +.B POSIX_FADV_WILLNEED +The specified data will be accessed in the near future. +.IP +\fBPOSIX_FADV_WILLNEED\fP initiates a +nonblocking read of the specified region into the page cache. +The amount of data read may be decreased by the kernel depending +on virtual memory load. +(A few megabytes will usually be fully satisfied, +and more is rarely useful.) +.TP +.B POSIX_FADV_DONTNEED +The specified data will not be accessed in the near future. +.IP +\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with +the specified region. +This is useful, for example, while streaming large +files. +A program may periodically request the kernel to free cached data +that has already been used, so that more useful cached pages are not +discarded instead. +.IP +Requests to discard partial pages are ignored. +It is preferable to preserve needed data than discard unneeded data. +If the application requires that data be considered for discarding, then +.I offset +and +.I len +must be page-aligned. +.IP +The implementation +.I may +attempt to write back dirty pages in the specified region, +but this is not guaranteed. +Any unwritten dirty pages will not be freed. +If the application wishes to ensure that dirty pages will be released, +it should call +.BR fsync (2) +or +.BR fdatasync (2) +first. +.SH RETURN VALUE +On success, zero is returned. +On error, an error number is returned. +.SH ERRORS +.TP +.B EBADF +The \fIfd\fP argument was not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified for \fIadvice\fP. +.TP +.B ESPIPE +The specified file descriptor refers to a pipe or FIFO. +.RB ( ESPIPE +is the error specified by POSIX, +but before Linux 2.6.16, +.\" commit 87ba81dba431232548ce29d5d224115d0c2355ac +Linux returned +.B EINVAL +in this case.) +.SH VERSIONS +Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the +default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles +this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. +These changes affect the entire file, not just the specified region +(but other open file handles to the same file are unaffected). +.SS C library/kernel differences +The name of the wrapper function in the C library is +.BR posix_fadvise (). +The underlying system call is called +.BR fadvise64 () +(or, on some architectures, +.BR fadvise64_64 ()); +the difference between the two is that the former system call +assumes that the type of the \fIlen\fP argument is \fIsize_t\fP, +while the latter expects \fIloff_t\fP there. +.SS Architecture-specific variants +Some architectures require +64-bit arguments to be aligned in a suitable pair of registers (see +.BR syscall (2) +for further detail). +On such architectures, the call signature of +.BR posix_fadvise () +shown in the SYNOPSIS would force +a register to be wasted as padding between the +.I fd +and +.I offset +arguments. +Therefore, these architectures define a version of the +system call that orders the arguments suitably, +but is otherwise exactly the same as +.BR posix_fadvise (). +.PP +For example, since Linux 2.6.14, ARM has the following system call: +.PP +.in +4n +.EX +.BI "long arm_fadvise64_64(int " fd ", int " advice , +.BI " loff_t " offset ", loff_t " len ); +.EE +.in +.PP +These architecture-specific details are generally +hidden from applications by the glibc +.BR posix_fadvise () +wrapper function, +which invokes the appropriate architecture-specific system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP +Kernel support first appeared in Linux 2.5.60; +the underlying system call is called +.BR fadvise64 (). +.\" of fadvise64_64() +Library support has been provided since glibc 2.2, +via the wrapper function +.BR posix_fadvise (). +.PP +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for the underlying system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.PP +The type of the +.I len +argument was changed from +.I size_t +to +.I off_t +in POSIX.1-2001 TC1. +.SH NOTES +The contents of the kernel buffer cache can be cleared via the +.I /proc/sys/vm/drop_caches +interface described in +.BR proc (5). +.PP +One can obtain a snapshot of which pages of a file are resident +in the buffer cache by opening a file, mapping it with +.BR mmap (2), +and then applying +.BR mincore (2) +to the mapping. +.SH BUGS +Before Linux 2.6.6, if +.I len +was specified as 0, then this was interpreted literally as "zero bytes", +rather than as meaning "all bytes through to the end of the file". +.SH SEE ALSO +.BR fincore (1), +.BR mincore (2), +.BR readahead (2), +.BR sync_file_range (2), +.BR posix_fallocate (3), +.BR posix_madvise (3) |