]>
Commit | Line | Data |
---|---|---|
d457be9d DH |
1 | .\" Copyright (C) 2016 Intel Corporation |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
d457be9d | 4 | .\" |
4c1c5274 | 5 | .TH pkey_alloc 2 (date) "Linux man-pages (unreleased)" |
d457be9d DH |
6 | .SH NAME |
7 | pkey_alloc, pkey_free \- allocate or free a protection key | |
ba7ea7d1 AC |
8 | .SH LIBRARY |
9 | Standard C library | |
8fc3b2cf | 10 | .RI ( libc ", " \-lc ) |
d457be9d DH |
11 | .SH SYNOPSIS |
12 | .nf | |
f92ea96b | 13 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
d457be9d | 14 | .B #include <sys/mman.h> |
c6d039a3 | 15 | .P |
6a4c9971 | 16 | .BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");" |
d457be9d DH |
17 | .BI "int pkey_free(int " pkey ");" |
18 | .fi | |
19 | .SH DESCRIPTION | |
20 | .BR pkey_alloc () | |
b638d220 MK |
21 | allocates a protection key (pkey) and allows it to be passed to |
22 | .BR pkey_mprotect (2). | |
c6d039a3 | 23 | .P |
e956ced8 | 24 | The |
d457be9d | 25 | .BR pkey_alloc () |
e956ced8 | 26 | .I flags |
88597984 | 27 | is reserved for future use and currently must always be specified as 0. |
c6d039a3 | 28 | .P |
2f694223 BL |
29 | The |
30 | .BR pkey_alloc () | |
31 | .I access_rights | |
e956ced8 MK |
32 | argument may contain zero or more disable operations: |
33 | .TP | |
34 | .B PKEY_DISABLE_ACCESS | |
35 | Disable all data access to memory covered by the returned protection key. | |
36 | .TP | |
37 | .B PKEY_DISABLE_WRITE | |
38 | Disable write access to memory covered by the returned protection key. | |
c6d039a3 | 39 | .P |
d457be9d DH |
40 | .BR pkey_free () |
41 | frees a protection key and makes it available for later | |
42 | allocations. | |
43 | After a protection key has been freed, it may no longer be used | |
44 | in any protection-key-related operations. | |
c6d039a3 | 45 | .P |
d457be9d DH |
46 | An application should not call |
47 | .BR pkey_free () | |
48 | on any protection key which has been assigned to an address | |
49 | range by | |
50 | .BR pkey_mprotect (2) | |
b638d220 MK |
51 | and which is still in use. |
52 | The behavior in this case is undefined and may result in an error. | |
d457be9d DH |
53 | .SH RETURN VALUE |
54 | On success, | |
55 | .BR pkey_alloc () | |
56 | returns a positive protection key value. | |
3e6695e0 | 57 | On success, |
d457be9d DH |
58 | .BR pkey_free () |
59 | returns zero. | |
60 | On error, \-1 is returned, and | |
61 | .I errno | |
f6a4078b | 62 | is set to indicate the error. |
d457be9d DH |
63 | .SH ERRORS |
64 | .TP | |
65 | .B EINVAL | |
66 | .IR pkey , | |
67 | .IR flags , | |
68 | or | |
69 | .I access_rights | |
70 | is invalid. | |
71 | .TP | |
72 | .B ENOSPC | |
b638d220 | 73 | .RB ( pkey_alloc ()) |
d457be9d DH |
74 | All protection keys available for the current process have |
75 | been allocated. | |
76 | The number of keys available is architecture-specific and | |
b638d220 | 77 | implementation-specific and may be reduced by kernel-internal use |
d457be9d DH |
78 | of certain keys. |
79 | There are currently 15 keys available to user programs on x86. | |
efeece04 | 80 | .IP |
b638d220 | 81 | This error will also be returned if the processor or operating system |
d457be9d | 82 | does not support protection keys. |
b638d220 | 83 | Applications should always be prepared to handle this error, since |
d457be9d DH |
84 | factors outside of the application's control can reduce the number |
85 | of available pkeys. | |
3113c7f3 | 86 | .SH STANDARDS |
4131356c AC |
87 | Linux. |
88 | .SH HISTORY | |
89 | Linux 4.9, | |
90 | glibc 2.27. | |
e956ced8 MK |
91 | .SH NOTES |
92 | .BR pkey_alloc () | |
93 | is always safe to call regardless of whether or not the operating system | |
94 | supports protection keys. | |
95 | It can be used in lieu of any other mechanism for detecting pkey support | |
96 | and will simply fail with the error | |
1b9d5819 | 97 | .B ENOSPC |
e956ced8 | 98 | if the operating system has no pkey support. |
c6d039a3 | 99 | .P |
e956ced8 MK |
100 | The kernel guarantees that the contents of the hardware rights |
101 | register (PKRU) will be preserved only for allocated protection | |
102 | keys. | |
103 | Any time a key is unallocated (either before the first call | |
104 | returning that key from | |
105 | .BR pkey_alloc () | |
106 | or after it is freed via | |
107 | .BR pkey_free ()), | |
108 | the kernel may make arbitrary changes to the parts of the | |
109 | rights register affecting access to that key. | |
a14af333 | 110 | .SH EXAMPLES |
a398e763 | 111 | See |
3e712e2a | 112 | .BR pkeys (7). |
d457be9d DH |
113 | .SH SEE ALSO |
114 | .BR pkey_mprotect (2), | |
3e712e2a | 115 | .BR pkeys (7) |