man2/pkey_alloc.2

   1 .\" Copyright (C) 2016 Intel Corporation
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH PKEY_ALLOC 2 2022-09-09 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 pkey_alloc, pkey_free \- allocate or free a protection key
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  14 .B #include <sys/mman.h>
  15 .PP
  16 .BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");"
  17 .BI "int pkey_free(int " pkey ");"
  18 .fi
  19 .SH DESCRIPTION
  20 .BR pkey_alloc ()
  21 allocates a protection key (pkey) and allows it to be passed to
  22 .BR pkey_mprotect (2).
  23 .PP
  24 The
  25 .BR pkey_alloc ()
  26 .I flags
  27 is reserved for future use and currently must always be specified as 0.
  28 .PP
  29 The
  30 .BR pkey_alloc ()
  31 .I access_rights
  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.
  39 .PP
  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.
  45 .PP
  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)
  51 and which is still in use.
  52 The behavior in this case is undefined and may result in an error.
  53 .SH RETURN VALUE
  54 On success,
  55 .BR pkey_alloc ()
  56 returns a positive protection key value.
  57 On success,
  58 .BR pkey_free ()
  59 returns zero.
  60 On error, \-1 is returned, and
  61 .I errno
  62 is set to indicate the error.
  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
  73 .RB ( pkey_alloc ())
  74 All protection keys available for the current process have
  75 been allocated.
  76 The number of keys available is architecture-specific and
  77 implementation-specific and may be reduced by kernel-internal use
  78 of certain keys.
  79 There are currently 15 keys available to user programs on x86.
  80 .IP
  81 This error will also be returned if the processor or operating system
  82 does not support protection keys.
  83 Applications should always be prepared to handle this error, since
  84 factors outside of the application's control can reduce the number
  85 of available pkeys.
  86 .SH VERSIONS
  87 .BR pkey_alloc ()
  88 and
  89 .BR pkey_free ()
  90 were added to Linux in kernel 4.9;
  91 library support was added in glibc 2.27.
  92 .SH STANDARDS
  93 The
  94 .BR pkey_alloc ()
  95 and
  96 .BR pkey_free ()
  97 system calls are Linux-specific.
  98 .SH NOTES
  99 .BR pkey_alloc ()
 100 is always safe to call regardless of whether or not the operating system
 101 supports protection keys.
 102 It can be used in lieu of any other mechanism for detecting pkey support
 103 and will simply fail with the error
 104 .B ENOSPC
 105 if the operating system has no pkey support.
 106 .PP
 107 The kernel guarantees that the contents of the hardware rights
 108 register (PKRU) will be preserved only for allocated protection
 109 keys.
 110 Any time a key is unallocated (either before the first call
 111 returning that key from
 112 .BR pkey_alloc ()
 113 or after it is freed via
 114 .BR pkey_free ()),
 115 the kernel may make arbitrary changes to the parts of the
 116 rights register affecting access to that key.
 117 .SH EXAMPLES
 118 See
 119 .BR pkeys (7).
 120 .SH SEE ALSO
 121 .BR pkey_mprotect (2),
 122 .BR pkeys (7)