summaryrefslogtreecommitdiffstats
path: root/man2/posix_fadvise.2
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
commit3d08cd331c1adcf0d917392f7e527b3f00511748 (patch)
tree312f0d1e1632f48862f044b8bb87e602dcffb5f9 /man2/posix_fadvise.2
parentAdding debian version 6.7-2. (diff)
downloadmanpages-3d08cd331c1adcf0d917392f7e527b3f00511748.tar.xz
manpages-3d08cd331c1adcf0d917392f7e527b3f00511748.zip
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/posix_fadvise.2')
-rw-r--r--man2/posix_fadvise.2227
1 files changed, 0 insertions, 227 deletions
diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2
deleted file mode 100644
index 96c06a7..0000000
--- a/man2/posix_fadvise.2
+++ /dev/null
@@ -1,227 +0,0 @@
-.\" 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-10-31 "Linux man-pages 6.7"
-.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)