1 files changed, 239 insertions, 0 deletions
diff --git a/man/man2/get_mempolicy.2 b/man/man2/get_mempolicy.2
new file mode 100644
index 000000000..f6f80ab3e
--- /dev/null
+++ b/man/man2/get_mempolicy.2
@@ -0,0 +1,239 @@
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft-var
+.\"
+.\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
+.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
+.\"
+.\" 2006-02-03, mtk, substantial wording changes and other improvements
+.\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
+.\"     more precise specification of behavior.
+.\"
+.TH get_mempolicy 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+get_mempolicy \- retrieve NUMA memory policy for a thread
+.SH LIBRARY
+NUMA (Non-Uniform Memory Access) policy library
+.RI ( libnuma ", " \-lnuma )
+.SH SYNOPSIS
+.B "#include <numaif.h>"
+.nf
+.P
+.BI "long get_mempolicy(int *" mode ,
+.BI "                   unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)"
+.B "                                          / ULONG_WIDTH],"
+.BI "                   unsigned long " maxnode ", void *" addr ,
+.BI "                   unsigned long " flags );
+.fi
+.SH DESCRIPTION
+.BR get_mempolicy ()
+retrieves the NUMA policy of the calling thread or of a memory address,
+depending on the setting of
+.IR flags .
+.P
+A NUMA machine has different
+memory controllers with different distances to specific CPUs.
+The memory policy defines from which node memory is allocated for
+the thread.
+.P
+If
+.I flags
+is specified as 0,
+then information about the calling thread's default policy
+(as set by
+.BR set_mempolicy (2))
+is returned, in the buffers pointed to by
+.I mode
+and
+.IR nodemask .
+The value returned in these arguments
+may be used to restore the thread's policy to its state at
+the time of the call to
+.BR get_mempolicy ()
+using
+.BR set_mempolicy (2).
+When
+.I flags
+is 0,
+.I addr
+must be specified as NULL.
+.P
+If
+.I flags
+specifies
+.B MPOL_F_MEMS_ALLOWED
+(available since Linux 2.6.24), the
+.I mode
+argument is ignored and the set of nodes (memories) that the
+thread is allowed to specify in subsequent calls to
+.BR mbind (2)
+or
+.BR set_mempolicy (2)
+(in the absence of any
+.IR "mode flags" )
+is returned in
+.IR nodemask .
+It is not permitted to combine
+.B MPOL_F_MEMS_ALLOWED
+with either
+.B MPOL_F_ADDR
+or
+.BR MPOL_F_NODE .
+.P
+If
+.I flags
+specifies
+.BR MPOL_F_ADDR ,
+then information is returned about the policy governing the memory
+address given in
+.IR addr .
+This policy may be different from the thread's default policy if
+.BR mbind (2)
+or one of the helper functions described in
+.BR numa (3)
+has been used to establish a policy for the memory range containing
+.IR addr .
+.P
+If the
+.I mode
+argument is not NULL, then
+.BR get_mempolicy ()
+will store the policy mode and any optional
+.I "mode flags"
+of the requested NUMA policy in the location pointed to by this argument.
+If
+.I nodemask
+is not NULL, then the nodemask associated with the policy will be stored
+in the location pointed to by this argument.
+.I maxnode
+specifies the number of node IDs
+that can be stored into
+.IR nodemask \[em]that
+is, the maximum node ID plus one.
+The value specified by
+.I maxnode
+is always rounded to a multiple of
+.IR "sizeof(unsigned\ long)*8" .
+.P
+If
+.I flags
+specifies both
+.B MPOL_F_NODE
+and
+.BR MPOL_F_ADDR ,
+.BR get_mempolicy ()
+will return the node ID of the node on which the address
+.I addr
+is allocated into the location pointed to by
+.IR mode .
+If no page has yet been allocated for the specified address,
+.BR get_mempolicy ()
+will allocate a page as if the thread had performed a read
+(load) access to that address, and return the ID of the node
+where that page was allocated.
+.P
+If
+.I flags
+specifies
+.BR MPOL_F_NODE ,
+but not
+.BR MPOL_F_ADDR ,
+and the thread's current policy is
+.B MPOL_INTERLEAVE
+or
+.BR MPOL_WEIGHTED_INTERLEAVE ,
+then
+.BR get_mempolicy ()
+will return in the location pointed to by a non-NULL
+.I mode
+argument,
+the node ID of the next node that will be used for
+interleaving of internal kernel pages allocated on behalf of the thread.
+.\" Note:  code returns next interleave node via 'mode' argument -Lee Schermerhorn
+These allocations include pages for memory-mapped files in
+process memory ranges mapped using the
+.BR mmap (2)
+call with the
+.B MAP_PRIVATE
+flag for read accesses, and in memory ranges mapped with the
+.B MAP_SHARED
+flag for all accesses.
+.P
+Other flag values are reserved.
+.P
+For an overview of the possible policies see
+.BR set_mempolicy (2).
+.SH RETURN VALUE
+On success,
+.BR get_mempolicy ()
+returns 0;
+on error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+Part of all of the memory range specified by
+.I nodemask
+and
+.I maxnode
+points outside your accessible address space.
+.TP
+.B EINVAL
+The value specified by
+.I maxnode
+is less than the number of node IDs supported by the system.
+Or
+.I flags
+specified values other than
+.B MPOL_F_NODE
+or
+.BR MPOL_F_ADDR ;
+or
+.I flags
+specified
+.B MPOL_F_ADDR
+and
+.I addr
+is NULL,
+or
+.I flags
+did not specify
+.B MPOL_F_ADDR
+and
+.I addr
+is not NULL.
+Or,
+.I flags
+specified
+.B MPOL_F_NODE
+but not
+.B MPOL_F_ADDR
+and the current thread policy is neither
+.B MPOL_INTERLEAVE
+nor
+.BR MPOL_WEIGHTED_INTERLEAVE .
+Or,
+.I flags
+specified
+.B MPOL_F_MEMS_ALLOWED
+with either
+.B MPOL_F_ADDR
+or
+.BR MPOL_F_NODE .
+(And there are other
+.B EINVAL
+cases.)
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.7.
+.SH NOTES
+For information on library support, see
+.BR numa (7).
+.SH SEE ALSO
+.BR getcpu (2),
+.BR mbind (2),
+.BR mmap (2),
+.BR set_mempolicy (2),
+.BR numa (3),
+.BR numa (7),
+.BR numactl (8)