-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org>
+.\"
+.\" %%%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.
.\"
.\" 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 2003-02-14 "Linux" "Linux Programmer's Manual"
+.TH POSIX_FADVISE 2 2013-04-01 "Linux" "Linux Programmer's Manual"
.SH NAME
posix_fadvise \- predeclare an access pattern for file data
.SH SYNOPSIS
.nf
-.B #define _XOPEN_SOURCE 600
.B #include <fcntl.h>
.sp
.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \
", int " advice ");"
.fi
+.sp
+.ad l
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR posix_fadvise ():
+.RS 4
+_XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
+.RE
+.ad
.SH DESCRIPTION
Programs can use
.BR posix_fadvise ()
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 advice is not binding; it merely constitutes an expectation on behalf of
+The \fIadvice\fP is not binding;
+it merely constitutes an expectation on behalf of
the application.
Permissible values for \fIadvice\fP include:
.TP
.B POSIX_FADV_DONTNEED
The specified data will not be accessed in the near future.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success, zero is returned.
On error, an error number is returned.
.SH ERRORS
.B EINVAL
in this case.)
.SH VERSIONS
-.BR posix_fadvise ()
-appeared in kernel 2.5.60.
-Glibc support has been provided since version 2.2.
-.\" Actually as fadvise64() -- MTK
-.SH "CONFORMING TO"
+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 ().
+.SH CONFORMING TO
POSIX.1-2001.
Note that the type of the
.I len
or
.BR fdatasync (2)
first.
+.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 len
+arguments.
+Therefore, these architectures define a version of the
+system call that orders the arguments suitably,
+but otherwise is otherwise exactly the same as
+.BR posix_fadvise ().
+
+For example, since Linux 2.6.14, ARM has the following system call:
+.PP
+.in +4n
+.nf
+.BI "long arm_fadvise64_64(int " fd ", int " advice ,
+.BI " loff_t " offset ", loff_t " len );
+.fi
+.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"
+.SH SEE ALSO
.BR readahead (2),
+.BR sync_file_range (2),
.BR posix_fallocate (3),
-.BR posix_madvise (3),
+.BR posix_madvise (3)
.\" FIXME . Write a posix_fadvise(3) page.
-.BR feature_test_macros (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
