1 files changed, 176 insertions, 0 deletions
diff --git a/man/man2/arch_prctl.2 b/man/man2/arch_prctl.2
new file mode 100644
index 000000000..680d36395
--- /dev/null
+++ b/man/man2/arch_prctl.2
@@ -0,0 +1,176 @@
+.\" Copyright (C) 2003 Andi Kleen
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH arch_prctl 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+arch_prctl \- set architecture-specific thread state
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <asm/prctl.h>" "        /* Definition of " ARCH_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr );
+.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR arch_prctl (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+.BR arch_prctl ()
+sets architecture-specific process or thread state.
+.I op
+selects an operation
+and passes argument
+.I addr
+to it;
+.I addr
+is interpreted as either an
+.I "unsigned long"
+for the "set" operations, or as an
+.IR "unsigned long\ *" ,
+for the "get" operations.
+.P
+Subfunctions for both x86 and x86-64 are:
+.TP
+.BR ARCH_SET_CPUID " (since Linux 4.12)"
+.\" commit e9ea1e7f53b852147cbd568b0568c7ad97ec21a3
+Enable
+.RI ( "addr != 0" )
+or disable
+.RI ( "addr == 0" )
+the
+.I cpuid
+instruction for the calling thread.
+The instruction is enabled by default.
+If disabled, any execution of a
+.I cpuid
+instruction will instead generate a
+.B SIGSEGV
+signal.
+This feature can be used to emulate
+.I cpuid
+results that differ from what the underlying
+hardware would have produced (e.g., in a paravirtualization setting).
+.IP
+The
+.B ARCH_SET_CPUID
+setting is preserved across
+.BR fork (2)
+and
+.BR clone (2)
+but reset to the default (i.e.,
+.I cpuid
+enabled) on
+.BR execve (2).
+.TP
+.BR ARCH_GET_CPUID " (since Linux 4.12)"
+Return the setting of the flag manipulated by
+.B ARCH_SET_CPUID
+as the result of the system call (1 for enabled, 0 for disabled).
+.I addr
+is ignored.
+.TP
+Subfunctions for x86-64 only are:
+.TP
+.B ARCH_SET_FS
+Set the 64-bit base for the
+.I FS
+register to
+.IR addr .
+.TP
+.B ARCH_GET_FS
+Return the 64-bit base value for the
+.I FS
+register of the calling thread in the
+.I unsigned long
+pointed to by
+.IR addr .
+.TP
+.B ARCH_SET_GS
+Set the 64-bit base for the
+.I GS
+register to
+.IR addr .
+.TP
+.B ARCH_GET_GS
+Return the 64-bit base value for the
+.I GS
+register of the calling thread in the
+.I unsigned long
+pointed to by
+.IR addr .
+.SH RETURN VALUE
+On success,
+.BR arch_prctl ()
+returns 0; on error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.I addr
+points to an unmapped address or is outside the process address space.
+.TP
+.B EINVAL
+.I op
+is not a valid operation.
+.TP
+.B ENODEV
+.B ARCH_SET_CPUID
+was requested, but the underlying hardware does not support CPUID faulting.
+.TP
+.B EPERM
+.I addr
+is outside the process address space.
+.\" .SH AUTHOR
+.\" Man page written by Andi Kleen.
+.SH STANDARDS
+Linux/x86-64.
+.SH NOTES
+.BR arch_prctl ()
+is supported only on Linux/x86-64 for 64-bit programs currently.
+.P
+The 64-bit base changes when a new 32-bit segment selector is loaded.
+.P
+.B ARCH_SET_GS
+is disabled in some kernels.
+.P
+Context switches for 64-bit segment bases are rather expensive.
+As an optimization, if a 32-bit TLS base address is used,
+.BR arch_prctl ()
+may use a real TLS entry as if
+.BR set_thread_area (2)
+had been called, instead of manipulating the segment base register directly.
+Memory in the first 2\ GB of address space can be allocated by using
+.BR mmap (2)
+with the
+.B MAP_32BIT
+flag.
+.P
+Because of the aforementioned optimization, using
+.BR arch_prctl ()
+and
+.BR set_thread_area (2)
+in the same thread is dangerous, as they may overwrite each other's
+TLS entries.
+.P
+.I FS
+may be already used by the threading library.
+Programs that use
+.B ARCH_SET_FS
+directly are very likely to crash.
+.SH SEE ALSO
+.BR mmap (2),
+.BR modify_ldt (2),
+.BR prctl (2),
+.BR set_thread_area (2)
+.P
+AMD X86-64 Programmer's manual