1 files changed, 227 insertions, 0 deletions
diff --git a/man/man2/posix_fadvise.2 b/man/man2/posix_fadvise.2
new file mode 100644
index 000000000..7984f7989
--- /dev/null
+++ b/man/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 (date) "Linux man-pages (unreleased)"
+.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>
+.P
+.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \
+", int " advice ");"
+.fi
+.P
+.ad l
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.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.
+.P
+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.
+.P
+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 ().
+.P
+For example, since Linux 2.6.14, ARM has the following system call:
+.P
+.in +4n
+.EX
+.BI "long arm_fadvise64_64(int " fd ", int " advice ,
+.BI "                      loff_t " offset ", loff_t " len );
+.EE
+.in
+.P
+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.
+.P
+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 ().
+.P
+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.
+.P
+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).
+.P
+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)