pkey_alloc(2)

1PKEY_ALLOC(2)              Linux Programmer's Manual             PKEY_ALLOC(2)
2
3
4

NAME

6       pkey_alloc, pkey_free - allocate or free a protection key
7

SYNOPSIS

9       #define _GNU_SOURCE             /* See feature_test_macros(7) */
10       #include <sys/mman.h>
11
12       int pkey_alloc(unsigned int flags, unsigned int access_rights);
13       int pkey_free(int pkey);
14

DESCRIPTION

16       pkey_alloc()  allocates  a  protection  key  (pkey) and allows it to be
17       passed to pkey_mprotect(2).
18
19       The pkey_alloc() flags is reserved for future use  and  currently  must
20       always be specified as 0.
21
22       The  pkey_alloc()  access_rights argument may contain zero or more dis‐
23       able operations:
24
25       PKEY_DISABLE_ACCESS
26              Disable all data access to memory covered by the  returned  pro‐
27              tection key.
28
29       PKEY_DISABLE_WRITE
30              Disable  write  access to memory covered by the returned protec‐
31              tion key.
32
33       pkey_free() frees a protection key and makes it available for later al‐
34       locations.   After a protection key has been freed, it may no longer be
35       used in any protection-key-related operations.
36
37       An application should not call pkey_free() on any protection key  which
38       has  been assigned to an address range by pkey_mprotect(2) and which is
39       still in use.  The behavior in this case is undefined and may result in
40       an error.
41

RETURN VALUE

43       On  success,  pkey_alloc() returns a positive protection key value.  On
44       success, pkey_free() returns zero.  On error, -1 is returned, and errno
45       is set to indicate the error.
46

ERRORS

48       EINVAL pkey, flags, or access_rights is invalid.
49
50       ENOSPC (pkey_alloc())  All  protection  keys  available for the current
51              process have been allocated.  The number of  keys  available  is
52              architecture-specific and implementation-specific and may be re‐
53              duced by kernel-internal use of certain keys.   There  are  cur‐
54              rently 15 keys available to user programs on x86.
55
56              This  error  will also be returned if the processor or operating
57              system does not support protection  keys.   Applications  should
58              always  be  prepared to handle this error, since factors outside
59              of the application's control can reduce the number of  available
60              pkeys.
61

VERSIONS

63       pkey_alloc() and pkey_free() were added to Linux in kernel 4.9; library
64       support was added in glibc 2.27.
65

CONFORMING TO

67       The pkey_alloc() and pkey_free() system calls are Linux-specific.
68

NOTES

70       pkey_alloc() is always safe to call regardless of whether  or  not  the
71       operating  system  supports protection keys.  It can be used in lieu of
72       any other mechanism for detecting pkey support  and  will  simply  fail
73       with the error ENOSPC if the operating system has no pkey support.
74
75       The kernel guarantees that the contents of the hardware rights register
76       (PKRU) will be preserved only for allocated protection keys.  Any  time
77       a  key  is unallocated (either before the first call returning that key
78       from pkey_alloc() or after it is freed via pkey_free()), the kernel may
79       make  arbitrary  changes  to the parts of the rights register affecting
80       access to that key.
81

EXAMPLES

83       See pkeys(7).
84

COLOPHON

89       This page is part of release 5.13 of the Linux  man-pages  project.   A
90       description  of  the project, information about reporting bugs, and the
91       latest    version    of    this    page,    can     be     found     at
92       https://www.kernel.org/doc/man-pages/.
93
94
95
96Linux                             2021-03-22                     PKEY_ALLOC(2)