AuroraMiddleware/glibc
1
0
Fork 0
mirror of https://sourceware.org/git/glibc.git synced 2024-11-21 12:30:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

manual: Use more precise wording for memory protection keys

Browse Source 
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>
This commit is contained in:
Yury Khrustalev 2024-11-06 13:04:27 +00:00 committed by Wilco Dijkstra
parent c1560f3f75
commit 0c38c59f75
1 changed files with 31 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
manual/memory.texi
View File

@ -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