manual: Use more precise wording for memory protection keys

Update the name of the argument in several pkey_*() functions that refers
to access restrictions rather than access rights: change access "rights"
to access "restrictions".

Specify that the result of the pkey_get() should be checked using bitwise
operations rather than plain equals comparison.

Reviewed-by: Adhemerval Zanella  <adhemerval.zanella@linaro.org>

1 files changed, 31 insertions, 27 deletions

diff --git a/manual/memory.texi b/manual/memory.texi
index 58683ee93d..a39805a8dd 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -3077,7 +3077,7 @@ returned by @code{mmap} or @code{mmap64}.
 @cindex memory protection key
 @cindex protection key
 @cindex MPK
-On some systems, further restrictions can be added to specific pages
+On some systems, further access restrictions can be added to specific pages
 using @dfn{memory protection keys}.  These restrictions work as follows:
 
 @itemize @bullet
@@ -3089,27 +3089,27 @@ during memory accesses.  New keys can be allocated with the
 @code{pkey_mprotect}.
 
 @item
-Each thread has a set of separate access right restriction for each
-protection key.  These access rights can be manipulated using the
+Each thread has a set of separate access restrictions for each
+protection key.  These access restrictions can be manipulated using the
 @code{pkey_set} and @code{pkey_get} functions.
 
 @item
 During a memory access, the system obtains the protection key for the
-accessed page and uses that to determine the applicable access rights,
+accessed page and uses that to determine the applicable access restrictions,
 as configured for the current thread.  If the access is restricted, a
 segmentation fault is the result ((@pxref{Program Error Signals}).
 These checks happen in addition to the @code{PROT_}* protection flags
 set by @code{mprotect} or @code{pkey_mprotect}.
 @end itemize
 
-New threads and subprocesses inherit the access rights of the current
+New threads and subprocesses inherit the access restrictions of the current
 thread.  If a protection key is allocated subsequently, existing threads
 (except the current) will use an unspecified system default for the
-access rights associated with newly allocated keys.
+access restrictions associated with newly allocated keys.
 
-Upon entering a signal handler, the system resets the access rights of
+Upon entering a signal handler, the system resets the access restrictions of
 the current thread so that pages with the default key can be accessed,
-but the access rights for other protection keys are unspecified.
+but the access restrictions for other protection keys are unspecified.
 
 Applications are expected to allocate a key once using
 @code{pkey_alloc}, and apply the key to memory regions which need
@@ -3151,24 +3151,24 @@ it again:
 
 In this example, a negative key value indicates that no key had been
 allocated, which means that the system lacks support for memory
-protection keys and it is not necessary to change the the access rights
+protection keys and it is not necessary to change the the access restrictions
 of the current thread (because it always has access).
 
 Compared to using @code{mprotect} to change the page protection flags,
 this approach has two advantages: It is thread-safe in the sense that
-the access rights are only changed for the current thread, so another
-thread which changes its own access rights concurrently to gain access
-to the mapping will not suddenly see its access rights revoked.  And
+the access restrictions are only changed for the current thread, so another
+thread which changes its own access restrictions concurrently to gain access
+to the mapping will not suddenly see its access restrictions updated.  And
 @code{pkey_set} typically does not involve a call into the kernel and a
 context switch, so it is more efficient.
 
-@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{restrictions})
+@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{access_restrictions})
 @standards{Linux, sys/mman.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
 Allocate a new protection key.  The @var{flags} argument is reserved and
-must be zero.  The @var{restrictions} argument specifies access rights
+must be zero.  The @var{access_restrictions} argument specifies access restrictions
 which are applied to the current thread (as if with @code{pkey_set}
-below).  Access rights of other threads are not changed.
+below).  Access restrictions of other threads are not changed.
 
 The function returns the new protection key, a non-negative number, or
 @math{-1} on error.
@@ -3183,7 +3183,7 @@ The system does not implement memory protection keys.
 @item EINVAL
 The @var{flags} argument is not zero.
 
-The @var{restrictions} argument is invalid.
+The @var{access_restrictions} argument is invalid.
 
 The system does not implement memory protection keys or runs in a mode
 in which memory protection keys are disabled.
@@ -3203,7 +3203,7 @@ in which memory protection keys are disabled.
 Deallocate the protection key, so that it can be reused by
 @code{pkey_alloc}.
 
-Calling this function does not change the access rights of the freed
+Calling this function does not change the access restrictions of the freed
 protection key.  The calling thread and other threads may retain access
 to it, even if it is subsequently allocated again.  For this reason, it
 is not recommended to call the @code{pkey_free} function.
@@ -3251,14 +3251,14 @@ not @math{-1}.
 @end table
 @end deftypefun
 
-@deftypefun int pkey_set (int @var{key}, unsigned int @var{rights})
+@deftypefun int pkey_set (int @var{key}, unsigned int @var{access_restrictions})
 @standards{Linux, sys/mman.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-Change the access rights of the current thread for memory pages with the
-protection key @var{key} to @var{rights}.  If @var{rights} is zero, no
-additional access restrictions on top of the page protection flags are
-applied.  Otherwise, @var{rights} is a combination of the following
-flags:
+Change the access restrictions of the current thread for memory pages with
+the protection key @var{key} to @var{access_restrictions}.  If
+@var{access_restrictions} is zero, no additional access restrictions on top of
+the page protection flags are applied.  Otherwise, @var{access_restrictions} is
+a combination of the following flags:
 
 @vtable @code
 @item PKEY_DISABLE_WRITE
@@ -3290,18 +3290,22 @@ function:
 
 @table @code
 @item EINVAL
-The system does not support the access rights restrictions expressed in
-the @var{rights} argument.
+The system does not support the access restrictions expressed in
+the @var{access_restrictions} argument.
 @end table
 @end deftypefun
 
 @deftypefun int pkey_get (int @var{key})
 @standards{Linux, sys/mman.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-Return the access rights of the current thread for memory pages with
-protection key @var{key}.  The return value is zero or a combination of
+Return the access restrictions of the current thread for memory pages
+with protection key @var{key}.  The return value is zero or a combination of
 the @code{PKEY_DISABLE_}* flags; see the @code{pkey_set} function.
 
+The returned value should be checked for presence or absence of specific flags
+using bitwise operations.  Comparing the returned value with any of the flags
+or their combination using equals will almost certainly fail.
+
 Calling the @code{pkey_get} function with a protection key which was not
 allocated by @code{pkey_alloc} results in undefined behavior.  This
 means that calling this function on systems which do not support memory