mirror of https://github.com/mkerrisk/man-pages
245 lines
5.8 KiB
Groff
245 lines
5.8 KiB
Groff
.\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
|
|
.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 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 2008-08-15 Linux "Linux Programmer's Manual"
|
|
.SH NAME
|
|
get_mempolicy \- Retrieve NUMA memory policy for a process
|
|
.SH SYNOPSIS
|
|
.B "#include <numaif.h>"
|
|
.nf
|
|
.sp
|
|
.BI "int get_mempolicy(int *" mode ", unsigned long *" nodemask ,
|
|
.BI " unsigned long " maxnode ", unsigned long " addr ,
|
|
.BI " unsigned long " flags );
|
|
.sp
|
|
Link with \fI\-lnuma\fP.
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR get_mempolicy ()
|
|
retrieves the NUMA policy of the calling process or of a memory address,
|
|
depending on the setting of
|
|
.IR flags .
|
|
|
|
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 process.
|
|
|
|
If
|
|
.I flags
|
|
is specified as 0,
|
|
then information about the calling process's default policy
|
|
(as set by
|
|
.BR set_mempolicy (2))
|
|
is returned.
|
|
The policy returned
|
|
.RI [ mode
|
|
and
|
|
.IR nodemask ]
|
|
may be used to restore the process's policy to its state at
|
|
the time of the call to
|
|
.BR get_mempolicy ()
|
|
using
|
|
.BR set_mempolicy (2).
|
|
|
|
If
|
|
.I flags
|
|
specifies
|
|
.BR MPOL_F_MEMS_ALLOWED
|
|
(available since Linux 2.6.24), the
|
|
.I mode
|
|
argument is ignored and the set of nodes [memories] that the
|
|
process is allowed to specify in subsequent calls to
|
|
.BR mbind (2)
|
|
or
|
|
.BR set_mempolicy (2)
|
|
[in the absense 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 .
|
|
|
|
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 process'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 .
|
|
|
|
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 \(emthat
|
|
is, the maximum node ID plus one.
|
|
The value specified by
|
|
.I maxnode
|
|
is always rounded to a multiple of
|
|
.IR "sizeof(unsigned long)" .
|
|
|
|
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 process had performed a read
|
|
[load] access to that address, and return the ID of the node
|
|
where that page was allocated.
|
|
|
|
If
|
|
.I flags
|
|
specifies
|
|
.BR MPOL_F_NODE ,
|
|
but not
|
|
.BR MPOL_F_ADDR ,
|
|
and the process's current policy is
|
|
.BR MPOL_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 process.
|
|
.\" 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.
|
|
|
|
Other flag values are reserved.
|
|
|
|
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 process policy is not
|
|
.BR MPOL_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 VERSIONS
|
|
The
|
|
.BR get_mempolicy ()
|
|
system call was added to the Linux kernel in version 2.6.7.
|
|
.SH CONFORMING TO
|
|
This system call is Linux-specific.
|
|
.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)
|