summaryrefslogtreecommitdiffstats
path: root/man2/arch_prctl.2
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
commit399644e47874bff147afb19c89228901ac39340e (patch)
tree1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man2/arch_prctl.2
parentInitial commit. (diff)
downloadmanpages-399644e47874bff147afb19c89228901ac39340e.tar.xz
manpages-399644e47874bff147afb19c89228901ac39340e.zip
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/arch_prctl.2')
-rw-r--r--man2/arch_prctl.2176
1 files changed, 176 insertions, 0 deletions
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
new file mode 100644
index 0000000..04a3633
--- /dev/null
+++ b/man2/arch_prctl.2
@@ -0,0 +1,176 @@
+.\" Copyright (C) 2003 Andi Kleen
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH arch_prctl 2 2023-03-30 "Linux man-pages 6.05.01"
+.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>
+.PP
+.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr );
+.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr );
+.fi
+.PP
+.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 code
+selects a subfunction
+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.
+.PP
+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 code
+is not a valid subcommand.
+.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.
+.PP
+The 64-bit base changes when a new 32-bit segment selector is loaded.
+.PP
+.B ARCH_SET_GS
+is disabled in some kernels.
+.PP
+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.
+.PP
+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.
+.PP
+.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)
+.PP
+AMD X86-64 Programmer's manual