1 files changed, 115 insertions, 0 deletions
diff --git a/man/man2/pkey_alloc.2 b/man/man2/pkey_alloc.2
new file mode 100644
index 000000000..0f706e7da
--- /dev/null
+++ b/man/man2/pkey_alloc.2
@@ -0,0 +1,115 @@
+.\" Copyright (C) 2016 Intel Corporation
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pkey_alloc 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+pkey_alloc, pkey_free \- allocate or free a protection key
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
+.B #include <sys/mman.h>
+.P
+.BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");"
+.BI "int pkey_free(int " pkey ");"
+.fi
+.SH DESCRIPTION
+.BR pkey_alloc ()
+allocates a protection key (pkey) and allows it to be passed to
+.BR pkey_mprotect (2).
+.P
+The
+.BR pkey_alloc ()
+.I flags
+is reserved for future use and currently must always be specified as 0.
+.P
+The
+.BR pkey_alloc ()
+.I access_rights
+argument may contain zero or more disable operations:
+.TP
+.B PKEY_DISABLE_ACCESS
+Disable all data access to memory covered by the returned protection key.
+.TP
+.B PKEY_DISABLE_WRITE
+Disable write access to memory covered by the returned protection key.
+.P
+.BR pkey_free ()
+frees a protection key and makes it available for later
+allocations.
+After a protection key has been freed, it may no longer be used
+in any protection-key-related operations.
+.P
+An application should not call
+.BR pkey_free ()
+on any protection key which has been assigned to an address
+range by
+.BR pkey_mprotect (2)
+and which is still in use.
+The behavior in this case is undefined and may result in an error.
+.SH RETURN VALUE
+On success,
+.BR pkey_alloc ()
+returns a positive protection key value.
+On success,
+.BR pkey_free ()
+returns zero.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.IR pkey ,
+.IR flags ,
+or
+.I access_rights
+is invalid.
+.TP
+.B ENOSPC
+.RB ( pkey_alloc ())
+All protection keys available for the current process have
+been allocated.
+The number of keys available is architecture-specific and
+implementation-specific and may be reduced by kernel-internal use
+of certain keys.
+There are currently 15 keys available to user programs on x86.
+.IP
+This error will also be returned if the processor or operating system
+does not support protection keys.
+Applications should always be prepared to handle this error, since
+factors outside of the application's control can reduce the number
+of available pkeys.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 4.9,
+glibc 2.27.
+.SH NOTES
+.BR pkey_alloc ()
+is always safe to call regardless of whether or not the operating system
+supports protection keys.
+It can be used in lieu of any other mechanism for detecting pkey support
+and will simply fail with the error
+.B ENOSPC
+if the operating system has no pkey support.
+.P
+The kernel guarantees that the contents of the hardware rights
+register (PKRU) will be preserved only for allocated protection
+keys.
+Any time a key is unallocated (either before the first call
+returning that key from
+.BR pkey_alloc ()
+or after it is freed via
+.BR pkey_free ()),
+the kernel may make arbitrary changes to the parts of the
+rights register affecting access to that key.
+.SH EXAMPLES
+See
+.BR pkeys (7).
+.SH SEE ALSO
+.BR pkey_mprotect (2),
+.BR pkeys (7)