mirror of https://github.com/mkerrisk/man-pages
243 lines
7.5 KiB
Groff
243 lines
7.5 KiB
Groff
.\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org>
|
|
.\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 2005-04-08 mtk, noted kernel version and added BUGS
|
|
.\" 2010-10-09, mtk, document arm_fadvise64_64()
|
|
.\"
|
|
.TH POSIX_FADVISE 2 2019-03-06 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
posix_fadvise \- predeclare an access pattern for file data
|
|
.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
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.PP
|
|
.BR posix_fadvise ():
|
|
.RS 4
|
|
_POSIX_C_SOURCE\ >=\ 200112L
|
|
.RE
|
|
.ad
|
|
.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
|
|
In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the
|
|
same semantics as \fBPOSIX_FADV_WILLNEED\fP.
|
|
This was probably a bug; since kernel 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 kernel version 2.6.16,
|
|
.\" commit 87ba81dba431232548ce29d5d224115d0c2355ac
|
|
Linux returned
|
|
.B EINVAL
|
|
in this case.)
|
|
.SH VERSIONS
|
|
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 version 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.
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008.
|
|
Note that the type of the
|
|
.I len
|
|
argument was changed from
|
|
.I size_t
|
|
to
|
|
.I off_t
|
|
in POSIX.1-2003 TC1.
|
|
.SH NOTES
|
|
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).
|
|
.PP
|
|
The contents of the kernel buffer cache can be cleared via the
|
|
.IR /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.
|
|
.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 BUGS
|
|
In kernels before 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)
|