1 files changed, 112 insertions, 0 deletions
diff --git a/man/man3/posix_madvise.3 b/man/man3/posix_madvise.3
new file mode 100644
index 000000000..967d52aec
--- /dev/null
+++ b/man/man3/posix_madvise.3
@@ -0,0 +1,112 @@
+.\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH posix_madvise 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+posix_madvise \- give advice about patterns of memory usage
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/mman.h>
+.P
+.BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR posix_madvise ():
+.nf
+    _POSIX_C_SOURCE >= 200112L
+.fi
+.SH DESCRIPTION
+The
+.BR posix_madvise ()
+function allows an application to advise the system about its expected
+patterns of usage of memory in the address range starting at
+.I addr
+and continuing for
+.I len
+bytes.
+The system is free to use this advice in order to improve the performance
+of memory accesses (or to ignore the advice altogether), but calling
+.BR posix_madvise ()
+shall not affect the semantics of access to memory in the specified range.
+.P
+The
+.I advice
+argument is one of the following:
+.TP
+.B POSIX_MADV_NORMAL
+The application has no special advice regarding its memory usage patterns
+for the specified address range.
+This is the default behavior.
+.TP
+.B POSIX_MADV_SEQUENTIAL
+The application expects to access the specified address range sequentially,
+running from lower addresses to higher addresses.
+Hence, pages in this region can be aggressively read ahead,
+and may be freed soon after they are accessed.
+.TP
+.B POSIX_MADV_RANDOM
+The application expects to access the specified address range randomly.
+Thus, read ahead may be less useful than normally.
+.TP
+.B POSIX_MADV_WILLNEED
+The application expects to access the specified address range
+in the near future.
+Thus, read ahead may be beneficial.
+.TP
+.B POSIX_MADV_DONTNEED
+The application expects that it will not access the specified address range
+in the near future.
+.SH RETURN VALUE
+On success,
+.BR posix_madvise ()
+returns 0.
+On failure, it returns a positive error number.
+.SH ERRORS
+.TP
+.B EINVAL
+.I addr
+is not a multiple of the system page size or
+.I len
+is negative.
+.TP
+.B EINVAL
+.I advice
+is invalid.
+.TP
+.B ENOMEM
+Addresses in the specified range are partially or completely outside
+the caller's address space.
+.SH VERSIONS
+POSIX.1 permits an implementation to generate an error if
+.I len
+is 0.
+On Linux, specifying
+.I len
+as 0 is permitted (as a successful no-op).
+.P
+In glibc, this function is implemented using
+.BR madvise (2).
+However, since glibc 2.6,
+.B POSIX_MADV_DONTNEED
+is treated as a no-op, because the corresponding
+.BR madvise (2)
+value,
+.BR MADV_DONTNEED ,
+has destructive semantics.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.2.
+POSIX.1-2001.
+.SH SEE ALSO
+.BR madvise (2),
+.BR posix_fadvise (2)