get_mempolicy.2 man page patch

[Michael Kerrisk <mtk-manpages@gmx.net>]

Andi, Christoph

Could you please review these changes by Lee to the get_mempolicy.2 page?
Patch against man-pages-2.63 (available from
http://www.kernel.org/pub/linux/docs/manpages).

Andi/ Christoph / Lee: There are a few points marked FIXME about which I'd
particularly like some input.

Cheers,

Michael


--- get_mempolicy.2.orig        2007-06-23 09:18:02.000000000 +0200
+++ get_mempolicy.2     2007-07-21 09:18:46.000000000 +0200
@@ -1,4 +1,5 @@
 .\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
+.\" and Copyright (C) 2007 Lee Schermerhorn <Lee.Schermerhorn@hp.com>
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -18,19 +19,22 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
 .\" 2006-02-03, mtk, substantial wording changes and other improvements
+.\" 2007-06-01, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
+.\"     more precise specification of behavior.
 .\"
-.TH GET_MEMPOLICY 2 2006-02-07 "Linux" "Linux Programmer's Manual"
+.TH GET_MEMPOLICY 2 2007-07-20 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 *" policy ", unsigned long *" nodemask ,
+.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
-.\" FIXME rewrite this DESCRIPTION. it is confusing.
 .SH DESCRIPTION
 .BR get_mempolicy ()
 retrieves the NUMA policy of the calling process or of a memory address,
@@ -39,7 +43,7 @@

 A NUMA machine has different
 memory controllers with different distances to specific CPUs.
-The memory policy defines in which node memory is allocated for
+The memory policy defines the node on which memory is allocated for
 the process.

 If
@@ -58,58 +62,84 @@
 address given in
 .IR addr .
 This policy may be different from the process's default policy if
-.BR set_mempolicy (2)
-has been used to establish a policy for the page containing
+.\" FIXME Lee changed "set_mempolicy" to "mbind" in the following;
+.\" is that correct?
+.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
-.I policy
-is not NULL, then it is used to return the policy.
+If the
+.I mode
+argument is not NULL, then
+.BR get_mempolicy ()
+will store the policy mode of the requested NUMA policy in the location
+pointed to by this argument.
 If
 .IR nodemask
-is not NULL, then it is used to return the nodemask associated
-with the policy.
+is not NULL, then the nodemask associated with the policy will be stored
+in the location pointed to by this argument.
 .I maxnode
-is the maximum bit number plus one that can be stored into
-.IR nodemask .
-The bit number is always rounded to a multiple of
-.IR "unsigned long" .
-.\"
-.\" If
-.\" .I flags
-.\" specifies both
-.\" .B MPOL_F_NODE
-.\" and
-.\" .BR MPOL_F_ADDR ,
-.\" then
-.\" .I policy
-.\" instead returns the number of the node on which the address
-.\" .I addr
-.\" is allocated.
-.\"
-.\" If
-.\" .I flags
-.\" specifies
-.\" .B MPOL_F_NODE
-.\" but not
-.\" .BR MPOL_F_ADDR ,
-.\" and the process's current policy is
-.\" .BR MPOL_INTERLEAVE ,
-.\" then
-.\" checkme: Andi's text below says that the info is returned in
-.\" 'nodemask', not 'policy':
-.\" .I policy
-.\" instead returns the number of the next node that will be used for
-.\" interleaving allocation.
-.\" FIXME .
-.\" The other valid flag is
-.\" .I MPOL_F_NODE.
-.\" It is only valid when the policy is
-.\" .I MPOL_INTERLEAVE.
-.\" In this case not the interleave mask, but an unsigned long with the next
-.\" node that would be used for interleaving is returned in
-.\" .I nodemask.
-.\" Other flag values are reserved.
+specifies the number of node IDs
+that can be stored into
+.IR nodemask
+(i.e.,
+the maximum node ID plus one).
+The value specified by
+.I maxnode
+is always rounded up to a multiple of
+.IR "sizeof(unsigned long)" .
+.\" FIXME: does the preceding sentence mean that if maxnode is (say)
+.\" 22, then the call could neverthless return node IDs in node mask
+.\" up to 31 -- e.g., node 26?
+
+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.
+The node ID is returned in 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 at 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
+.IR 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).
@@ -120,49 +150,89 @@
 on error, \-1 is returned and
 .I errno
 is set to indicate the error.
-.\" .SH ERRORS
-.\" FIXME -- no errors are listed on this page
-.\" .
-.\" .TP
-.\" .B EINVAL
-.\" .I nodemask
-.\" is non-NULL, and
-.\" .I maxnode
-.\" is too small;
-.\" 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.
-.\" (And there are other
-.\" .B EINVAL
-.\" cases.)
+.SH ERRORS
+.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 .
+.TP
+.B EFAULT
+Part or all of the memory range specified by
+.I nodemask
+and
+.I maxnode
+points outside your accessible address space.
 .SH CONFORMING TO
 This system call is Linux specific.
 .SH NOTES
-This manual page is incomplete:
-it does not document the details the
-.BR MPOL_F_NODE
-flag,
-which modifies the operation of
-.BR get_mempolicy ().
-This is deliberate: this flag is not intended for application use,
-and its operation may change or it may be removed altogether in
-future kernel versions.
-.B Do not use it.
+If the mode of the process policy or the policy governing allocations
+at the specified address is
+.B MPOL_PREFERRED
+and this policy was installed with an empty
+.IR nodemask
+(i.e., specifying local allocation),
+.BR get_mempolicy ()
+will return the mask of on-line node IDs, in the location pointed to by
+a non-NULL
+.I nodemask
+argument.
+This mask does not take into consideration any adminstratively imposed
+restrictions on the process's context.
+.\" "context" above refers to cpusets.
+.\" No man page to reference. -- Lee Schermerhorn
+.\"
+.\" FIXME: Andi / Lee -- can you please resolve the following (mtk):
+.\"
+.\"  Christoph says the following is untrue.  These are "fully supported."
+.\"  Andi concedes that he has lost this battle and approves [?]
+.\"  updating the man pages to document the behavior.  -- Lee Schermerhorn
+.\" This manual page is incomplete:
+.\" it does not document the details the
+.\" .BR MPOL_F_NODE
+.\" flag,
+.\" which modifies the operation of
+.\" .BR get_mempolicy ().
+.\" This is deliberate: this flag is not intended for application use,
+.\" and its operation may change or it may be removed altogether in
+.\" future kernel versions.
+.\" .B Do not use it.
 .SS "Versions and Library Support"
 See
 .BR mbind (2).
+.SH CONFORMING TO
+This system call is Linux specific.
 .SH SEE ALSO
 .BR mbind (2),
+.BR mmap (2),
 .BR set_mempolicy (2),
-.BR numactl (8),
-.BR numa (3)
+.BR numa (3),
+.BR numactl (8)


--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>