| .\" Copyright 2003,2004 Andi Kleen, SuSE Labs. |
| .\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard |
| .\" |
| .\" %%%LICENSE_START(VERBATIM_PROF) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 Linux "Linux Programmer's Manual" |
| .SH NAME |
| get_mempolicy \- retrieve NUMA memory policy for a thread |
| .SH SYNOPSIS |
| .B "#include <numaif.h>" |
| .nf |
| .PP |
| .BI "long get_mempolicy(int *" mode ", unsigned long *" nodemask , |
| .BI " unsigned long " maxnode ", void *" addr , |
| .BI " unsigned long " flags ); |
| .PP |
| Link with \fI\-lnuma\fP. |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .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 . |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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 |
| 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 . |
| .PP |
| 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 . |
| .PP |
| 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)*8" . |
| .PP |
| 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. |
| .PP |
| If |
| .I flags |
| specifies |
| .BR MPOL_F_NODE , |
| but not |
| .BR MPOL_F_ADDR , |
| and the thread'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 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. |
| .PP |
| Other flag values are reserved. |
| .PP |
| 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 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 |
| Glibc does not provide a wrapper for this system call. |
| 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) |