Plus some other found in the process.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH LDD 1 2021-08-27 "" "Linux Programmer's Manual"
+.TH LDD 1 2021-08-27 GNU "Linux Programmer's Manual"
.SH NAME
ldd \- print shared object dependencies
.SH SYNOPSIS
include also the name of that keyword,
so that the output has the format:
.IP
- \fIkeyword\fP="\fIvalue\fP"
+.in +4n
+.EX
+.IR keyword =\(dq value \(dq
+.EE
+.in
.PP
The
.B locale
pixels high.
.SH EXIT STATUS
The exit status of
-.BR memusage
+.B memusage
is equal to the exit status of the profiled program.
.SH BUGS
To report bugs, see
.BR mtrace (3).
.SH OPTIONS
.TP
-.BI \fB\-\-help
+.B \-\-help
Print help and exit.
.TP
-.BI \fB\-\-version
+.B \-\-version
Print version information and exit.
.SH BUGS
For bug reporting instructions, please see:
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH TIME 1 2019-03-06 "" "Linux User's Manual"
+.TH TIME 1 2019-03-06 GNU "Linux User's Manual"
.SH NAME
time \- time a simple command or give resource usage
.SH SYNOPSIS
nonblocking and no pending connections are present on the queue,
.BR accept ()
fails with the error
-.BR EAGAIN
+.B EAGAIN
or
.BR EWOULDBLOCK .
.PP
for details.
.PP
If
-.IR flags
+.I flags
is 0, then
.BR accept4 ()
is the same as
.BR accept ().
The following values can be bitwise ORed in
-.IR flags
+.I flags
to obtain different behavior:
.TP 16
.B SOCK_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
-.BI "int syscall(SYS_faccessat2,"
+.B int syscall(SYS_faccessat2,
.BI " int " dirfd ", const char *" pathname ", int " mode \
", int " flags );
.fi
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SH BUGS
Because the Linux kernel's
If the destination
.I keyring
already contains a key that matches the specified
-.IR type
+.I type
and
.IR description ,
then, if the key type supports it,
.I plen
should be zero.
.TP
-.IR """user"""
+.I """user"""
This is a general purpose key type whose payload may be read and updated
by user-space applications.
The key is kept entirely within kernel memory.
The payload data was invalid.
.TP
.B EINVAL
-.IR type
+.I type
was
-.IR """logon"""
+.I """logon"""
and the
.I description
was not qualified with a prefix string of the form
.SH NOTES
Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
-.IR libkeyutils
+.I libkeyutils
library.
(The accompanying package provides the
.I <keyutils.h>
.BR user\-session\-keyring (7)
.PP
The kernel source files
-.IR Documentation/security/keys/core.rst
+.I Documentation/security/keys/core.rst
and
-.IR Documentation/keys/request\-key.rst
+.I Documentation/keys/request\-key.rst
(or, before Linux 4.13, in the files
.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
-.IR Documentation/security/keys.txt
+.I Documentation/security/keys.txt
and
.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
.IR Documentation/security/keys\-request\-key.txt ).
.RI bitwise- or
combination of zero or more of the following bits:
.TP
-.BR ADJ_OFFSET
+.B ADJ_OFFSET
Set time offset from
.IR buf.offset .
Since Linux 2.6.26,
.B EINVAL
error occurs if the supplied value is out of range.
.TP
-.BR ADJ_FREQUENCY
+.B ADJ_FREQUENCY
Set frequency offset from
.IR buf.freq .
Since Linux 2.6.26,
.B EINVAL
error occurs if the supplied value is out of range.
.TP
-.BR ADJ_MAXERROR
+.B ADJ_MAXERROR
Set maximum time error from
.IR buf.maxerror .
.TP
-.BR ADJ_ESTERROR
+.B ADJ_ESTERROR
Set estimated time error from
.IR buf.esterror .
.TP
-.BR ADJ_STATUS
+.B ADJ_STATUS
Set clock status bits from
.IR buf.status .
A description of these bits is provided below.
.TP
-.BR ADJ_TIMECONST
+.B ADJ_TIMECONST
Set PLL time constant from
.IR buf.constant .
If the
.\" Author: Roman Zippel <zippel@linux-m68k.org>
Select nanosecond resolution.
Only one of
-.BR ADJ_MICRO
+.B ADJ_MICRO
and
-.BR ADJ_NANO
+.B ADJ_NANO
should be specified.
.TP
.BR ADJ_TAI " (since Linux 2.6.26)"
Set TAI (Atomic International Time) offset from
.IR buf.constant .
.IP
-.BR ADJ_TAI
+.B ADJ_TAI
should not be used in conjunction with
.BR ADJ_TIMECONST ,
since the latter mode also employs the
-.IR buf.constant
+.I buf.constant
field.
.IP
For a complete explanation of TAI
.I BIPM
.UE
.TP
-.BR ADJ_TICK
+.B ADJ_TICK
Set tick value from
.IR buf.tick .
.PP
.\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
.\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
.TP
-.BR ADJ_OFFSET_SINGLESHOT
+.B ADJ_OFFSET_SINGLESHOT
.\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
.\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
Old-fashioned
Return (in
.IR buf.offset )
the remaining amount of time to be adjusted after an earlier
-.BR ADJ_OFFSET_SINGLESHOT
+.B ADJ_OFFSET_SINGLESHOT
operation.
This feature was added in Linux 2.6.24,
.\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
system call (added in Linux 2.6.39) behaves like
.BR adjtimex ()
but takes an additional
-.IR clk_id
+.I clk_id
argument to specify the particular clock on which to act.
.SS ntp_adjtime ()
The
.BR MOD_FREQUENCY ,
and so on), other than the exceptions noted in the following points.
.IP *
-.BR MOD_CLKA
+.B MOD_CLKA
is the synonym for
.BR ADJ_OFFSET_SINGLESHOT .
.IP *
-.BR MOD_CLKB
+.B MOD_CLKB
is the synonym for
.BR ADJ_TICK .
.IP *
.BR ntp_adjtime ()
return the clock state; that is, one of the following values:
.TP 12
-.BR TIME_OK
+.B TIME_OK
Clock synchronized, no leap second adjustment pending.
.TP
-.BR TIME_INS
+.B TIME_INS
Indicates that a leap second will be added at the end of the UTC day.
.TP
-.BR TIME_DEL
+.B TIME_DEL
Indicates that a leap second will be deleted at the end of the UTC day.
.TP
-.BR TIME_OOP
+.B TIME_OOP
Insertion of a leap second is in progress.
.TP
-.BR TIME_WAIT
+.B TIME_WAIT
A leap-second insertion or deletion has been completed.
This value will be returned until the next
-.BR ADJ_STATUS
+.B ADJ_STATUS
operation clears the
.B STA_INS
and
.B STA_DEL
flags.
.TP
-.BR TIME_ERROR
+.B TIME_ERROR
The system clock is not synchronized to a reliable server.
This value is returned when any of the following holds true:
.RS
not reflect a state change caused by the call itself.
.PP
On failure, these calls return \-1 and set
-.IR errno
+.I errno
to indicate the error.
.SH ERRORS
.TP
hardware would have produced (e.g., in a paravirtualization setting).
.IP
The
-.BR ARCH_SET_CPUID
+.B ARCH_SET_CPUID
setting is preserved across
.BR fork (2)
and
From Linux 4.4 onwards,
.\" commit 1be7f75d1668d6296b80bf35dcf6762393530afc
an unprivileged user may create limited programs of type
-.BR BPF_PROG_TYPE_SOCKET_FILTER
+.B BPF_PROG_TYPE_SOCKET_FILTER
and associated maps.
However they may not store kernel pointers within
the maps and are presently limited to the following helper functions:
.BR ICACHE ,
.BR DCACHE ,
or
-.BR BCACHE
+.B BCACHE
(but see BUGS).
.SH CONFORMING TO
Historically, this system call was available on all MIPS UNIX variants
Therefore, the whole cache is always flushed.
.PP
This function always behaves as if
-.BR BCACHE
+.B BCACHE
has been passed for the
.I cache
argument and does not do any error checking on the
Linux 2.6.25 added 64-bit capability sets, with version
.BR _LINUX_CAPABILITY_VERSION_2 .
There was, however, an API glitch, and Linux 2.6.26 added
-.BR _LINUX_CAPABILITY_VERSION_3
+.B _LINUX_CAPABILITY_VERSION_3
to fix the problem.
.PP
Note that 64-bit capabilities use
On older kernels that do not provide VFS capabilities support
.BR capset ()
can, if the caller has the
-.BR CAP_SETPCAP
+.B CAP_SETPCAP
capability, be used to change not only the caller's own capabilities,
but also the capabilities of other threads.
The call operates on the capabilities of the thread specified by the
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SH SEE ALSO
.BR chmod (1),
If
.I pathname
is an empty string, operate on the file referred to by
-.IR dirfd
+.I dirfd
(which may have been obtained using the
.BR open (2)
.B O_PATH
the same as that of the parent directory.
.IP *
If the filesystem is mounted with
-.BR "\-o\ nogrpid"
+.B \-o\ nogrpid
and the set-group-ID bit is disabled on the parent directory,
then the group of a new file is made the same as the
process's filesystem GID.
.IP *
If the filesystem is mounted with
-.BR "\-o\ nogrpid"
+.B \-o\ nogrpid
and the set-group-ID bit is enabled on the parent directory,
then the group of a new file is made
the same as that of the parent directory.
.PP
As at Linux 4.12,
the
-.BR "\-o\ grpid"
+.B \-o\ grpid
and
-.BR "\-o\ nogrpid"
+.B \-o\ nogrpid
mount options are supported by ext2, ext3, ext4, and XFS.
Filesystems that don't support these mount options follow the
-.BR "\-o\ nogrpid"
+.B \-o\ nogrpid
rules.
.SS Glibc notes
On older kernels where
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SS NFS
The
.\" 2003-08-24 aeb, large parts rewritten
.\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note
.\"
-.TH CLOCK_GETRES 2 2021-03-22 "" "Linux Programmer's Manual"
+.TH CLOCK_GETRES 2 2021-03-22 Linux "Linux Programmer's Manual"
.SH NAME
clock_getres, clock_gettime, clock_settime \- clock and time functions
.SH LIBRARY
This clock does
not experience discontinuities and backwards jumps caused by NTP
inserting leap seconds as
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
does.
.IP
The acronym TAI refers to International Atomic Time.
.\" Look in time/posix-timers.c (kernel 5.6 sources) for the
.\" 'struct k_clock' structures that have an 'nsleep' method
.TP
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
A settable system-wide real-time clock.
.TP
.BR CLOCK_TAI " (since Linux 3.10)"
A system-wide clock derived from wall-clock time but ignoring leap seconds.
.TP
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
A nonsettable, monotonically increasing clock that measures time
since some unspecified point in the past that does not change after
system startup.
.BR CLOCK_MONOTONIC ,
except that it also includes any time that the system is suspended.
.TP
-.BR CLOCK_PROCESS_CPUTIME_ID
+.B CLOCK_PROCESS_CPUTIME_ID
A settable per-process clock that measures CPU time consumed
by all threads in the process.
.\" There is some trickery between glibc and the kernel
.BR clock_nanosleep ()
suspends the execution of the calling thread
until either at least the time specified by
-.IR request
+.I request
has elapsed,
or a signal is delivered that causes a signal handler to be called or
that terminates the process.
(The existence of the
.I size
argument permits future extensions to the
-.IR clone_args
+.I clone_args
structure.)
.PP
The stack for the child process is specified via
.IR cl_args.stack_size ,
which specifies the size of the stack in bytes.
In the case where the
-.BR CLONE_VM
+.B CLONE_VM
flag (see below) is specified, a stack must be explicitly allocated
and specified.
Otherwise, these two fields can be specified as NULL and 0,
The
.I set_tid
feature requires
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
or
(since Linux 5.9)
.\" commit 124ea650d3072b005457faed69909221c2905a1f
.\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6
-.BR CAP_CHECKPOINT_RESTORE
+.B CAP_CHECKPOINT_RESTORE
in all owning user namespaces of the target PID namespaces.
.PP
Callers may only choose a PID greater than 1 in a given PID namespace
if an
-.BR init
+.B init
process (i.e., a process with PID 1) already exists in that namespace.
Otherwise the PID
entry for this PID namespace must be 1.
returns control to user space in the child process.
(Note that the store operation may not have completed before the clone call
returns in the parent process, which is relevant if the
-.BR CLONE_VM
+.B CLONE_VM
flag is also employed.)
.TP
.BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)"
flag,
which caused the parent not to receive a signal when the child terminated.
Ultimately, the effect of this flag was subsumed under the
-.BR CLONE_THREAD
+.B CLONE_THREAD
flag and by the time Linux 2.6.0 was released, this flag had no effect.
Starting in Linux 2.6.2, the need to give this flag together with
.B CLONE_THREAD
This flag is still defined, but it is usually ignored when calling
.BR clone ().
However, see the description of
-.BR CLONE_PIDFD
+.B CLONE_PIDFD
for some exceptions.
.TP
.BR CLONE_FILES " (since Linux 2.0)"
.B CLONE_INTO_CGROUP
flag allows the child process to be created in a different version 2 cgroup.
(Note that
-.BR CLONE_INTO_CGROUP
+.B CLONE_INTO_CGROUP
has effect only for version 2 cgroups.)
.IP
In order to place the child process in a different cgroup,
the caller specifies
-.BR CLONE_INTO_CGROUP
+.B CLONE_INTO_CGROUP
in
.I cl_args.flags
and passes a file descriptor that refers to a version 2 cgroup in the
on placing a process into a version 2 cgroup apply.
.IP
Among the possible use cases for
-.BR CLONE_INTO_CGROUP
+.B CLONE_INTO_CGROUP
are the following:
.RS
.IP * 3
the target cgroup after it has been created.
.IP *
The
-.BR CLONE_INTO_CGROUP
+.B CLONE_INTO_CGROUP
flag also allows the creation of
frozen child processes by spawning them into a frozen cgroup.
(See
If several threads are doing I/O on behalf of the same process
.RB ( aio_read (3),
for instance), they should employ
-.BR CLONE_IO
+.B CLONE_IO
to get better I/O performance.
.\" with CFQ and AS.
.IP
can employ
.BR CLONE_NEWPID .
This flag can't be specified in conjunction with
-.BR CLONE_THREAD
+.B CLONE_THREAD
or
.BR CLONE_PARENT .
.TP
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
(This flag first became meaningful for
.BR clone ()
in Linux 2.6.23,
.BR user_namespaces (7).
.IP
Before Linux 3.8, use of
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
required that the caller have three capabilities:
.BR CAP_SYS_ADMIN ,
.BR CAP_SETUID ,
no privileges are needed to create a user namespace.
.IP
This flag can't be specified in conjunction with
-.BR CLONE_THREAD
+.B CLONE_THREAD
or
.BR CLONE_PARENT .
For security reasons,
.\" The fix actually went into 3.9 and into 3.8.3. However, user namespaces
.\" were, for practical purposes, unusable in earlier 3.8.x because of the
.\" various filesystems that didn't support userns.
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
cannot be specified in conjunction with
.BR CLONE_FS .
.TP
specified only by the system boot process (PID 0).
The flag disappeared completely from the kernel sources in Linux 2.5.16.
Subsequently, the kernel silently ignored this bit if it was specified in the
-.IR flags
+.I flags
mask.
Much later, the same bit was recycled for use as the
.B CLONE_PIDFD
If the obsolete
.B CLONE_DETACHED
flag is specified alongside
-.BR CLONE_PIDFD
+.B CLONE_PIDFD
when calling
.BR clone (),
an error is returned.
is specified when calling
.BR clone3 ().
This error behavior ensures that the bit corresponding to
-.BR CLONE_DETACHED
+.B CLONE_DETACHED
can be reused for further PID file descriptor features in the future.
.TP
.BR CLONE_PTRACE " (since Linux 2.2)"
On x86,
.I tls
is interpreted as a
-.IR "struct user_desc\ *"
+.I struct user_desc\~*
(see
.BR set_thread_area (2)).
On x86-64 it is the new value to be set for the %fs base register
Since then, the kernel silently ignores it without error.
.\" glibc 2.8 removed this defn from bits/sched.h
Starting with Linux 4.6, the same bit was reused for the
-.BR CLONE_NEWCGROUP
+.B CLONE_NEWCGROUP
flag.
.TP
.BR CLONE_SYSVSEM " (since Linux 2.5.10)"
is specified
(and note that, since Linux 2.6.0,
.\" Precisely: Linux 2.6.0-test6
-.BR CLONE_SIGHAND
+.B CLONE_SIGHAND
also requires
-.BR CLONE_VM
+.B CLONE_VM
to be included).
.IP
Signal dispositions and actions are process-wide:
or because the thread executed a machine language instruction that triggered
a hardware exception
(e.g., invalid memory access triggering
-.BR SIGSEGV
+.B SIGSEGV
or a floating-point exception triggering
.BR SIGFPE ).
.IP
.BR fork (2).
.IP
If the
-.BR CLONE_VM
+.B CLONE_VM
flag is specified and the
-.BR CLONE_VFORK
+.B CLONE_VFORK
flag is not specified,
then any alternate signal stack that was established by
.BR sigaltstack (2)
was specified in
.IR cl_args.flags ,
but the file descriptor specified in
-.IR cl_args.cgroup
+.I cl_args.cgroup
refers to a version 2 cgroup in which a domain controller is enabled.
.TP
.BR EEXIST " (" clone3 "() only)"
and
.B CLONE_NEWNS
were specified in the
-.IR flags
+.I flags
mask.
.TP
.BR EINVAL " (since Linux 3.9)"
and
.B CLONE_FS
were specified in the
-.IR flags
+.I flags
mask.
.TP
.B EINVAL
and
.B CLONE_SYSVSEM
were specified in the
-.IR flags
+.I flags
mask.
.TP
.B EINVAL
One (or both) of
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
or
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
and one (or both) of
-.BR CLONE_THREAD
+.B CLONE_THREAD
or
-.BR CLONE_PARENT
+.B CLONE_PARENT
were specified in the
-.IR flags
+.I flags
mask.
.TP
.BR EINVAL " (since Linux 2.6.32)"
.\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c
-.BR CLONE_PARENT
+.B CLONE_PARENT
was specified, and the caller is an init process.
.TP
.B EINVAL
Returned by the glibc
.BR clone ()
wrapper function when
-.IR fn
+.I fn
or
-.IR stack
+.I stack
is specified as NULL.
.TP
.B EINVAL
-.BR CLONE_NEWIPC
+.B CLONE_NEWIPC
was specified in the
-.IR flags
+.I flags
mask,
but the kernel was not configured with the
.B CONFIG_SYSVIPC
and
-.BR CONFIG_IPC_NS
+.B CONFIG_IPC_NS
options.
.TP
.B EINVAL
-.BR CLONE_NEWNET
+.B CLONE_NEWNET
was specified in the
-.IR flags
+.I flags
mask,
but the kernel was not configured with the
.B CONFIG_NET_NS
option.
.TP
.B EINVAL
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
was specified in the
-.IR flags
+.I flags
mask,
but the kernel was not configured with the
.B CONFIG_PID_NS
option.
.TP
.B EINVAL
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
was specified in the
-.IR flags
+.I flags
mask,
but the kernel was not configured with the
.B CONFIG_USER_NS
option.
.TP
.B EINVAL
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
was specified in the
-.IR flags
+.I flags
mask,
but the kernel was not configured with the
.B CONFIG_UTS_NS
.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
.B CLONE_NEWUSER
was specified in the
-.IR flags
+.I flags
mask, and the call would cause the limit on the number of
nested user namespaces to be exceeded.
See
.I flags
mask specified the creation of a new user namespace,
but doing so would have caused the limit defined by the corresponding file in
-.IR /proc/sys/user
+.I /proc/sys/user
to be exceeded.
For further details, see
.BR namespaces (7).
was specified in
.IR cl_args.flags ,
but the file descriptor specified in
-.IR cl_args.cgroup
+.I cl_args.cgroup
refers to a version 2 cgroup that is in the
-.IR "domain invalid"
+.I domain invalid
state.
.TP
.B EPERM
.BR CLONE_NEWNS ,
.BR CLONE_NEWPID ,
or
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
.TP
.B EPERM
(This error occurs only on Linux 2.5.15 and earlier.)
.TP
.B EPERM
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
was specified in the
-.IR flags
+.I flags
mask,
but either the effective user ID or the effective group ID of the caller
does not have a mapping in the parent namespace (see
.BR EUSERS " (Linux 3.11 to Linux 4.8)"
.B CLONE_NEWUSER
was specified in the
-.IR flags
+.I flags
mask,
and the limit on the number of nested user namespaces would be exceeded.
See the discussion of the
-.BR ENOSPC
+.B ENOSPC
error above.
.SH VERSIONS
The
(If the child
.I shares
the parent's memory because of the use of the
-.BR CLONE_VM
+.B CLONE_VM
flag,
then no copy-on-write duplication occurs and chaos is likely to result.)
.PP
.BR mprotect (2).
.IP *
We can specify the
-.BR MAP_STACK
+.B MAP_STACK
flag to request a mapping that is suitable for a stack.
For the moment, this flag is a no-op on Linux,
but it exists and has effect on some other systems,
.TP
.B EMFILE
The number of open file descriptors exceeds the limit specified in
-.IR /proc/sys/fs/nr_open
+.I /proc/sys/fs/nr_open
(see
.BR proc (5)).
This error can occur in situations where that limit was lowered before
.B EINPROGRESS
The socket is nonblocking and the connection cannot be completed immediately.
(UNIX domain sockets failed with
-.BR EAGAIN
+.B EAGAIN
instead.)
It is possible to
.BR select (2)
.BR copy_file_range ()
in a loop, and using the
.BR lseek (2)
-.BR SEEK_DATA
+.B SEEK_DATA
and
-.BR SEEK_HOLE
+.B SEEK_HOLE
operations to find the locations of data segments.
.PP
.BR copy_file_range ()
.nf
.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.BR "#include <unistd.h>
+.B #include <unistd.h>
.PP
.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
.fi
.I exit
function, then that function is executed before unloading the module.
The
-.IR flags
+.I flags
argument is used to modify the behavior of the system call,
as described below.
This system call requires privilege.
then the behavior depends on the bits set in
.IR flags .
In normal usage (see NOTES), the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag is always specified, and the
-.BR O_TRUNC
+.B O_TRUNC
flag may additionally be specified.
.\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library
.\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library
.I exit
function, then an attempt to remove the module fails.
However, if
-.BR O_TRUNC
+.B O_TRUNC
was specified, this requirement is bypassed.
.PP
Using the
.BR CONFIG_MODULE_FORCE_UNLOAD ,
this flag is silently ignored.
(Normally,
-.BR CONFIG_MODULE_FORCE_UNLOAD
+.B CONFIG_MODULE_FORCE_UNLOAD
is enabled.)
Using this flag taints the kernel (TAINT_FORCED_RMMOD).
.SH RETURN VALUE
capability),
or module unloading is disabled
(see
-.IR /proc/sys/kernel/modules_disabled
+.I /proc/sys/kernel/modules_disabled
in
.BR proc (5)).
.TP
.B EWOULDBLOCK
Other modules depend on this module;
or,
-.BR O_NONBLOCK
+.B O_NONBLOCK
was specified in
.IR flags ,
but the reference count of this module is nonzero and
.BR syscall (2).
.PP
The uninterruptible sleep that may occur if
-.BR O_NONBLOCK
+.B O_NONBLOCK
is omitted from
-.IR flags
+.I flags
is considered undesirable, because the sleeping process is left
in an unkillable state.
As at Linux 3.7, specifying
-.BR O_NONBLOCK
+.B O_NONBLOCK
is optional, but in future kernels it is likely to become mandatory.
.SS Linux 2.4 and earlier
In Linux 2.4 and earlier, the system call took only one argument:
.IR oldfd .
.PP
If the file descriptor
-.IR newfd
+.I newfd
was previously open, it is closed before being reused;
the close is performed silently
(i.e., any errors during the close are not reported by
.BR dup2 ()).
.PP
The steps of closing and reusing the file descriptor
-.IR newfd
+.I newfd
are performed
.IR atomically .
This is important, because trying to implement equivalent functionality using
.IP * 3
The caller can force the close-on-exec flag to be set
for the new file descriptor by specifying
-.BR O_CLOEXEC
+.B O_CLOEXEC
in
.IR flags .
See the description of the same flag in
.\" We deliberately decided on this change. Otherwise, what is the
.\" result of dup3(fd, fd, O_CLOEXEC)?
If
-.IR oldfd
+.I oldfd
equals
.IR newfd ,
then
.B EBADF
.I newfd
is out of the allowed range for file descriptors (see the discussion of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached
(see the discussion of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.SH VERSIONS
is the same as
.BR epoll_create ().
The following value can be included in
-.IR flags
+.I flags
to obtain different behavior:
.TP
.B EPOLL_CLOEXEC
.TP
.B EPOLL_CTL_MOD
Change the settings associated with
-.IR fd
+.I fd
in the interest list to the new settings specified in
.IR event .
.TP
.IP
.BR epoll_wait (2)
will always report for this event; it is not necessary to set it in
-.IR events
+.I events
when calling
.BR epoll_ctl ().
.TP
.IP
.BR epoll_wait (2)
will always wait for this event; it is not necessary to set it in
-.IR events
+.I events
when calling
.BR epoll_ctl ().
.IP
one or more of the epoll file descriptors will receive an event with
.BR epoll_wait (2).
The default in this scenario (when
-.BR EPOLLEXCLUSIVE
+.B EPOLLEXCLUSIVE
is not set) is for all epoll file descriptors to receive an event.
-.BR EPOLLEXCLUSIVE
+.B EPOLLEXCLUSIVE
is thus useful for avoiding thundering herd problems in certain scenarios.
.IP
If the same file descriptor is in multiple epoll instances,
some with the
-.BR EPOLLEXCLUSIVE
+.B EPOLLEXCLUSIVE
flag, and others without, then events will be provided to all epoll
instances that did not specify
.BR EPOLLEXCLUSIVE ,
.BR EPOLLWAKEUP ,
and
.BR EPOLLET .
-.BR EPOLLHUP
+.B EPOLLHUP
and
-.BR EPOLLERR
+.B EPOLLERR
can also be specified, but this is not required:
as usual, these events are always reported if they occur,
regardless of whether they are specified in
then a subsequent
.B EPOLL_CTL_MOD
on the same
-.IR epfd ",\ " fd
+.IR epfd ,\~ fd
pair yields an error.
A call to
.BR epoll_ctl ()
was
.B EPOLL_CTL_MOD
and
-.IR events
+.I events
included
.BR EPOLLEXCLUSIVE .
.TP
was
.B EPOLL_CTL_MOD
and the
-.BR EPOLLEXCLUSIVE
+.B EPOLLEXCLUSIVE
flag has previously been applied to this
-.IR epfd ",\ " fd
+.IR epfd ,\~ fd
pair.
.TP
.B EINVAL
-.BR EPOLLEXCLUSIVE
+.B EPOLLEXCLUSIVE
was specified in
-.IR event
+.I event
and
.I fd
refers to an epoll instance.
is specified in
.IR flags ,
but the caller does not have the
-.BR CAP_BLOCK_SUSPEND
+.B CAP_BLOCK_SUSPEND
capability, then the
.B EPOLLWAKEUP
flag is
.IR "silently ignored" .
This unfortunate behavior is necessary because no validity
checks were performed on the
-.IR flags
+.I flags
argument in the original implementation, and the addition of the
.B EPOLLWAKEUP
with a check that caused the call to fail if the caller did not have the
system calls have a sixth argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the
-.IR sigmask
+.I sigmask
argument.
The glibc
.BR epoll_pwait ()
eventfd object.
.PP
The following values may be bitwise ORed in
-.IR flags
+.I flags
to change the behavior of
.BR eventfd ():
.TP
.TP
.BR EFD_NONBLOCK " (since Linux 2.6.27)"
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
.BR read (2)
depend on whether the eventfd counter currently has a nonzero value
and whether the
-.BR EFD_SEMAPHORE
+.B EFD_SEMAPHORE
flag was specified when creating the eventfd file descriptor:
.RS
.IP * 3
If
-.BR EFD_SEMAPHORE
+.B EFD_SEMAPHORE
was not specified and the eventfd counter has a nonzero value, then a
.BR read (2)
returns 8 bytes containing that value,
and the counter's value is reset to zero.
.IP *
If
-.BR EFD_SEMAPHORE
+.B EFD_SEMAPHORE
was specified and the eventfd counter has a nonzero value, then a
.BR read (2)
returns 8 bytes containing the value 1,
.PP
The current value of an eventfd counter can be viewed
via the entry for the corresponding file descriptor in the process's
-.IR /proc/[pid]/fdinfo
+.IR /proc/ pid /fdinfo
directory.
See
.BR proc (5)
.PP
For details of the latter case, see "Interpreter scripts" below.
.PP
-\fIargv\fP is an array of pointers to strings passed to the new program
+.I argv
+is an array of pointers to strings passed to the new program
as its command-line arguments.
By convention, the first of these strings (i.e.,
.IR argv[0] )
.I argv
array must be terminated by a NULL pointer.
(Thus, in the new program,
-.IR argv[argc]
+.I argv[argc]
will be NULL.)
.PP
-\fIenvp\fP is an array of pointers to strings, conventionally of the form
-\fBkey=value\fP, which are passed as the environment of the new program.
+.I envp
+is an array of pointers to strings, conventionally of the form
+.BR key=value ,
+which are passed as the environment of the new program.
The
.I envp
array must be terminated by a NULL pointer.
in which case the dumpable flag may instead be reset to the value in
.IR /proc/sys/fs/suid_dumpable ,
in the circumstances described under
-.BR PR_SET_DUMPABLE
+.B PR_SET_DUMPABLE
in
.BR prctl (2).
Note that changes to the "dumpable" attribute may cause ownership
of files in the process's
-.IR /proc/[pid]
+.IR /proc/ pid
directory to change to
.IR root:root ,
as described in
starting at
.IR argv[1] .
Note that there is no way to get the
-.IR argv[0]
+.I argv[0]
that was passed to the
.BR execve ()
call.
Since Linux 2.6.25,
the kernel also places a floor of 32 pages on this size limit,
so that, even when
-.BR RLIMIT_STACK
+.B RLIMIT_STACK
is set very low,
applications are guaranteed to have at least as much argument and
environment space as was provided by Linux 2.6.22 and earlier.
Having changed its real UID using one of the
.BR set*uid ()
calls, the caller was\(emand is now still\(emabove its
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
resource limit (see
.BR setrlimit (2)).
For a more detailed explanation of this error, see NOTES.
.BR sysconf (3)
should be invariant over the lifetime of a process.
However, since Linux 2.6.23, if the
-.BR RLIMIT_STACK
+.B RLIMIT_STACK
resource limit changes, then the value reported by
.B _SC_ARG_MAX
will also change,
but the new image could not be completely built.
In such cases, the kernel kills the process with a
.\" commit 19d860a140beac48a1377f179e693abe86a9dac9
-.BR SIGSEGV
+.B SIGSEGV
.RB ( SIGKILL
until Linux 3.17)
signal.
.\" ELF binary. There are no known problems with 2.0.34 or 2.2.15.
.SS execve() and EAGAIN
A more detailed explanation of the
-.BR EAGAIN
+.B EAGAIN
error that can occur (since Linux 3.1) when calling
.BR execve ()
is as follows.
.PP
The
-.BR EAGAIN
+.B EAGAIN
error can occur when a
.I preceding
call to
.BR setresuid (2)
caused the real user ID of the process to change,
and that change caused the process to exceed its
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
resource limit (i.e., the number of processes belonging
to the new real UID exceeds the resource limit).
From Linux 2.6.0 to 3.0, this caused the
but the kernel sets an internal flag, named
.BR PF_NPROC_EXCEEDED ,
to note that the
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
resource limit has been exceeded.
If the
-.BR PF_NPROC_EXCEEDED
+.B PF_NPROC_EXCEEDED
flag is set and the resource limit is still
exceeded at the time of a subsequent
.BR execve ()
call, that call fails with the error
.BR EAGAIN .
This kernel logic ensures that the
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
resource limit is still enforced for the
common privileged daemon workflow\(emnamely,
.BR fork (2)
call), then the
.BR execve ()
call succeeds and the kernel clears the
-.BR PF_NPROC_EXCEEDED
+.B PF_NPROC_EXCEEDED
process flag.
The flag is also cleared if a subsequent call to
.BR fork (2)
If
.I pathname
is an empty string and the
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
flag is specified, then the file descriptor
.I dirfd
specifies the file to be executed (i.e.,
-.IR dirfd
+.I dirfd
refers to an executable file, rather than a directory).
.PP
The
.I flags
argument is a bit mask that can include zero or more of the following flags:
.TP
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
If
.I pathname
is an empty string, operate on the file referred to by
-.IR dirfd
+.I dirfd
(which may have been obtained using the
.BR open (2)
.B O_PATH
.B ELOOP
.I flags
includes
-.BR AT_SYMLINK_NOFOLLOW
+.B AT_SYMLINK_NOFOLLOW
and the file identified by
.I dirfd
and a non-NULL
filesystem mounted.
.PP
When asked to execute a script file, the
-.IR argv[0]
+.I argv[0]
that is passed to the script interpreter is a string of the form
-.IR /dev/fd/N
+.I /dev/fd/N
or
.IR /dev/fd/N/P ,
where
.I N
is the number of the file descriptor passed via the
-.IR dirfd
+.I dirfd
argument.
A string of the first form occurs when
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
is employed.
A string of the second form occurs when the script is specified via both
-.IR dirfd
+.I dirfd
and
.IR pathname ;
in this case,
-.IR P
+.I P
is the value given in
.IR pathname .
.PP
error described above means that it is not possible to set the
close-on-exec flag on the file descriptor given to a call of the form:
.PP
- execveat(fd, "", argv, envp, AT_EMPTY_PATH);
+.in +4n
+.EX
+execveat(fd, "", argv, envp, AT_EMPTY_PATH);
+.EE
+.in
.PP
However, the inability to set the close-on-exec flag means that a file
descriptor referring to the script leaks through to the script itself.
Any subregion within the range specified by
.I offset
and
-.IR len
+.I len
that did not contain data before the call will be initialized to zero.
This default behavior closely resembles the behavior of the
.BR posix_fallocate (3)
and is intended as a method of optimally implementing that function.
.PP
After a successful call, subsequent writes into the range specified by
-.IR offset
+.I offset
and
-.IR len
+.I len
are guaranteed not to fail because of lack of disk space.
.PP
If the
may allocate a larger range of disk space than was specified.
.SS Deallocating file space
Specifying the
-.BR FALLOC_FL_PUNCH_HOLE
+.B FALLOC_FL_PUNCH_HOLE
flag (available since Linux 2.6.38) in
.I mode
deallocates space (i.e., creates a hole)
subsequent reads from this range will return zeros.
.PP
The
-.BR FALLOC_FL_PUNCH_HOLE
+.B FALLOC_FL_PUNCH_HOLE
flag must be ORed with
-.BR FALLOC_FL_KEEP_SIZE
+.B FALLOC_FL_KEEP_SIZE
in
.IR mode ;
in other words, even when punching off the end of the file, the file size
.SS Collapsing file space
.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
Specifying the
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
flag (available since Linux 3.15) in
.I mode
removes a byte range from a file, without leaving a hole.
If a filesystem has such a requirement,
.BR fallocate ()
fails with the error
-.BR EINVAL
+.B EINVAL
if this requirement is violated.
.PP
If the region specified by
to truncate a file.
.PP
No other flags may be specified in
-.IR mode
+.I mode
in conjunction with
.BR FALLOC_FL_COLLAPSE_RANGE .
.PP
.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
.SS Zeroing file space
Specifying the
-.BR FALLOC_FL_ZERO_RANGE
+.B FALLOC_FL_ZERO_RANGE
flag (available since Linux 3.15)
.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
in
.\" commit f27451f229966874a8793995b8e6b74326d125df
.SS Increasing file space
Specifying the
-.BR FALLOC_FL_INSERT_RANGE
+.B FALLOC_FL_INSERT_RANGE
flag
(available since Linux 4.1)
.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d
bytes.
.PP
This mode has the same limitations as
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
regarding the granularity of the operation.
If the granularity requirements are not met,
.BR fallocate ()
should be used.
.PP
No other flags may be specified in
-.IR mode
+.I mode
in conjunction with
.BR FALLOC_FL_INSERT_RANGE .
.PP
.B EINVAL
.I mode
is
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
and the range specified by
.I offset
plus
.B EINVAL
.I mode
is
-.BR FALLOC_FL_INSERT_RANGE
+.B FALLOC_FL_INSERT_RANGE
and the range specified by
.I offset
reaches or passes the end of the file.
.B EINVAL
.I mode
is
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
or
.BR FALLOC_FL_INSERT_RANGE ,
but either
.B FALLOC_FL_INSERT_RANGE
and also other flags;
no other flags are permitted with
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
or
.BR FALLOC_FL_INSERT_RANGE .
.TP
.B EINVAL
.I mode
is
-.BR FALLOC_FL_COLLAPSE_RANGE
-or
-.BR FALLOC_FL_ZERO_RANGE
+.BR FALLOC_FL_COLLAPSE_RANGE ,
+.BR FALLOC_FL_ZERO_RANGE ,
or
.BR FALLOC_FL_INSERT_RANGE ,
but the file referred to by
.B EPERM
.I mode
specifies
-.BR FALLOC_FL_PUNCH_HOLE
+.BR FALLOC_FL_PUNCH_HOLE ,
+.BR FALLOC_FL_COLLAPSE_RANGE ,
or
-.BR FALLOC_FL_COLLAPSE_RANGE
-or
-.BR FALLOC_FL_INSERT_RANGE
+.B FALLOC_FL_INSERT_RANGE
and
the file referred to by
.I fd
.B ETXTBSY
.I mode
specifies
-.BR FALLOC_FL_COLLAPSE_RANGE
+.B FALLOC_FL_COLLAPSE_RANGE
or
.BR FALLOC_FL_INSERT_RANGE ,
but the file referred to by
-.IR fd
+.I fd
is currently being executed.
.SH VERSIONS
.BR fallocate ()
is available on Linux since kernel 2.6.23.
Support is provided by glibc since version 2.10.
The
-.BR FALLOC_FL_*
+.B FALLOC_FL_*
flags are defined in glibc headers only since version 2.18.
.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
.SH CONFORMING TO
This value allows the receipt of events which contain additional information
about the underlying filesystem object correlated to an event.
An additional record of type
-.BR FAN_EVENT_INFO_TYPE_FID
+.B FAN_EVENT_INFO_TYPE_FID
encapsulates the information about the object and is included alongside the
generic event metadata structure.
The file descriptor that is used to represent the object correlated to an
identifies the modified directory and not the created/deleted/moved child
object.
The use of
-.BR FAN_CLASS_CONTENT
+.B FAN_CLASS_CONTENT
or
-.BR FAN_CLASS_PRE_CONTENT
+.B FAN_CLASS_PRE_CONTENT
is not permitted with this flag and will result in the error
.BR EINVAL .
See
(see exceptions below) additional information about a directory object
correlated to an event.
An additional record of type
-.BR FAN_EVENT_INFO_TYPE_DFID
+.B FAN_EVENT_INFO_TYPE_DFID
encapsulates the information about the directory object and is included
alongside the generic event metadata structure.
For events that occur on a non-directory object, the additional structure
Note that in some cases, a filesystem object does not have a parent,
for example, when an event occurs on an unlinked but open file.
In that case, with the
-.BR FAN_REPORT_FID
+.B FAN_REPORT_FID
flag, the event will be reported with only one record to identify the
non-directory object itself, because there is no directory associated with
the event.
Without the
-.BR FAN_REPORT_FID
+.B FAN_REPORT_FID
flag, no event will be reported.
See
.BR fanotify (7)
This flag must be provided in conjunction with the flag
.BR FAN_REPORT_DIR_FID .
Providing this flag value without
-.BR FAN_REPORT_DIR_FID
+.B FAN_REPORT_DIR_FID
will result in the error
.BR EINVAL .
This flag may be combined with the flag
the reported name can be used to call
.BR fstatat (2).
The same rule that applies to record type
-.BR FAN_EVENT_INFO_TYPE_DFID
+.B FAN_EVENT_INFO_TYPE_DFID
also applies to record type
.BR FAN_EVENT_INFO_TYPE_DFID_NAME :
if a non-directory object has no parent, either the event will not be reported
and
.BR FAN_DELETE_SELF ,
cannot be provided as a
-.IR mask
+.I mask
when
.I flags
contains
and
.BR FAN_MOVED_TO ,
specifying the flag
-.BR FAN_ONDIR
+.B FAN_ONDIR
is required in order to create events when subdirectory entries are
modified (i.e.,
.BR mkdir (2)/
.BR FAN_DELETE ,
.BR FAN_MOVED_FROM ,
and
-.BR FAN_MOVED_TO
+.B FAN_MOVED_TO
are not generated for any entry modifications performed inside subdirectories
of marked directories.
Note that the events
-.BR FAN_DELETE_SELF
+.B FAN_DELETE_SELF
and
-.BR FAN_MOVE_SELF
+.B FAN_MOVE_SELF
are not generated for children of marked directories.
To monitor complete directory trees it is necessary to mark the relevant
mount or filesystem.
.TP
.B EINVAL
An invalid value was passed in
-.IR flags
+.I flags
or
.IR mask ,
or
.TP
.B ENOENT
The filesystem object indicated by
-.IR dirfd
+.I dirfd
and
-.IR pathname
+.I pathname
does not exist.
This error also occurs when trying to remove a mark from an object
which is not marked.
.BR execveat (2).
.PP
For example, if the following ELF binary were to be invoked and a
-.BR FAN_OPEN_EXEC
+.B FAN_OPEN_EXEC
mark has been placed on /:
.PP
.in +4n
.in
.PP
The listening application in this case would receive
-.BR FAN_OPEN_EXEC
+.B FAN_OPEN_EXEC
events for both the ELF binary and interpreter, respectively:
.PP
.in +4n
a particular operation is to invoke
.BR fcntl ()
with the desired
-.IR cmd
+.I cmd
value and then test whether the call failed with
.BR EINVAL ,
indicating that the kernel does not recognize this value.
.TP
.BR F_DUPFD " (\fIint\fP)"
Duplicate the file descriptor
-.IR fd
+.I fd
using the lowest-numbered available file descriptor greater than or equal to
.IR arg .
This is different from
is vulnerable to a race condition that may unintentionally leak
the file descriptor to the program executed in the child process.
See the discussion of the
-.BR O_CLOEXEC
+.B O_CLOEXEC
flag in
.BR open (2)
for details and a remedy to the problem.
.B O_NONBLOCK
flags.
It is not possible to change the
-.BR O_DSYNC
+.B O_DSYNC
and
-.BR O_SYNC
+.B O_SYNC
flags; see BUGS, below.
.SS Advisory record locking
Linux implements traditional ("process-associated") UNIX record locks,
.BR F_SETLK ,
.BR F_SETLKW ,
and
-.BR F_GETLK
+.B F_GETLK
are used to acquire, release, and test for the existence of record
locks (also known as byte-range, file-segment, or file-region locks).
The third argument,
.BR fcntl (),
.IR lock ,
is a pointer to an
-.IR flock
+.I flock
structure.
By contrast with traditional record locks, the
.I l_pid
silently discarded.
.IR Note :
The
-.BR F_SETOWN
+.B F_SETOWN
operation records the caller's credentials at the time of the
.BR fcntl ()
call,
The above behavior was accidentally dropped in Linux 2.6.12,
and won't be restored.
From Linux 2.6.32 onward, use
-.BR F_SETOWN_EX
+.B F_SETOWN_EX
to target
.B SIGIO
and
.BR F_GETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)"
Return the current file descriptor owner settings
as defined by a previous
-.BR F_SETOWN_EX
+.B F_SETOWN_EX
operation.
The information is returned in the structure pointed to by
.IR arg ,
The caller specifies the target of signals via
.IR arg ,
which is a pointer to a
-.IR f_owner_ex
+.I f_owner_ex
structure.
The
.I type
is interpreted:
.RS
.TP
-.BR F_OWNER_TID
+.B F_OWNER_TID
Send the signal to the thread whose thread ID
(the value returned by a call to
.BR clone (2)
is specified in
.IR pid .
.TP
-.BR F_OWNER_PID
+.B F_OWNER_PID
Send the signal to the process whose ID
is specified in
.IR pid .
.TP
-.BR F_OWNER_PGRP
+.B F_OWNER_PGRP
Send the signal to the process group whose ID
is specified in
.IR pid .
Note that the file descriptor provided in
.I si_fd
is the one that was specified during the
-.BR F_SETSIG
+.B F_SETSIG
operation.
This can lead to an unusual corner case.
If the file descriptor is duplicated
most of the time.
.PP
The use of
-.BR O_ASYNC
+.B O_ASYNC
is specific to BSD and Linux.
The only use of
-.BR F_GETOWN
+.B F_GETOWN
and
.B F_SETOWN
specified in POSIX.1 is in conjunction with the use of the
.B SIGURG
signal on sockets.
(POSIX does not specify the
-.BR SIGIO
+.B SIGIO
signal.)
.BR F_GETOWN_EX ,
.BR F_SETOWN_EX ,
bytes.
An unprivileged process can adjust the pipe capacity to any value
between the system page size and the limit defined in
-.IR /proc/sys/fs/pipe\-max\-size
+.I /proc/sys/fs/pipe\-max\-size
(see
.BR proc (5)).
Attempts to set the pipe capacity below the page size are silently
rounded up to the page size.
Attempts by an unprivileged process to set the pipe capacity above the limit in
-.IR /proc/sys/fs/pipe\-max\-size
+.I /proc/sys/fs/pipe\-max\-size
yield the error
.BR EPERM ;
a privileged process
Seals cannot be removed again.
Once this call succeeds, the seals are enforced by the kernel immediately.
If the current set of seals includes
-.BR F_SEAL_SEAL
+.B F_SEAL_SEAL
(see below), then this call will be rejected with
.BR EPERM .
Adding a seal that is already set is a no-op, in case
.PP
The following seals are available:
.TP
-.BR F_SEAL_SEAL
+.B F_SEAL_SEAL
If this seal is set, any further call to
.BR fcntl ()
with
.BR F_SEAL_SEAL ,
then this effectively causes the set of seals to be constant and locked.
.TP
-.BR F_SEAL_SHRINK
+.B F_SEAL_SHRINK
If this seal is set, the file in question cannot be reduced in size.
This affects
.BR open (2)
if you try to shrink the file in question.
Increasing the file size is still possible.
.TP
-.BR F_SEAL_GROW
+.B F_SEAL_GROW
If this seal is set, the size of the file in question cannot be increased.
This affects
.BR write (2)
if you use them to increase the file size.
If you keep the size or shrink it, those calls still work as expected.
.TP
-.BR F_SEAL_WRITE
+.B F_SEAL_WRITE
If this seal is set, you cannot modify the contents of the file.
Note that shrinking or growing the size of the file is
still possible and allowed.
The following read/write
hints are valid since Linux 4.13:
.TP
-.BR RWH_WRITE_LIFE_NOT_SET
+.B RWH_WRITE_LIFE_NOT_SET
No specific hint has been set.
This is the default value.
.TP
-.BR RWH_WRITE_LIFE_NONE
+.B RWH_WRITE_LIFE_NONE
No specific write lifetime is associated with this file or inode.
.TP
-.BR RWH_WRITE_LIFE_SHORT
+.B RWH_WRITE_LIFE_SHORT
Data written to this inode or via this open file description
is expected to have a short lifetime.
.TP
-.BR RWH_WRITE_LIFE_MEDIUM
+.B RWH_WRITE_LIFE_MEDIUM
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_SHORT .
.TP
-.BR RWH_WRITE_LIFE_LONG
+.B RWH_WRITE_LIFE_LONG
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_MEDIUM .
.TP
-.BR RWH_WRITE_LIFE_EXTREME
+.B RWH_WRITE_LIFE_EXTREME
Data written to this inode or via this open file description
is expected to have a lifetime longer than
data written with
.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ
The pipe capacity.
.TP
-.BR F_GET_SEALS
+.B F_GET_SEALS
A bit mask identifying the seals that have been set
for the inode referred to by
.IR fd .
and the file descriptor open mode doesn't match with the
type of lock requested.
.TP
-.BR EBUSY
+.B EBUSY
.I cmd
is
-.BR F_SETPIPE_SZ
+.B F_SETPIPE_SZ
and the new pipe capacity specified in
.I arg
is smaller than the amount of buffer space currently
.I cmd
is
.BR F_ADD_SEALS ,
-.IR arg
+.I arg
includes
.BR F_SEAL_WRITE ,
and there exists a writable, shared mapping on the file referred to by
.B EINTR
.I cmd
is
-.BR F_SETLKW
+.B F_SETLKW
or
-.BR F_OFD_SETLKW
+.B F_OFD_SETLKW
and the operation was interrupted by a signal; see
.BR signal (7).
.TP
.B EINVAL
.I cmd
is
-.BR F_ADD_SEALS
+.B F_ADD_SEALS
and
.I arg
includes an unrecognized sealing bit.
.TP
-.BR EINVAL
+.B EINVAL
.I cmd
is
-.BR F_ADD_SEALS
+.B F_ADD_SEALS
or
-.BR F_GET_SEALS
+.B F_GET_SEALS
and the filesystem containing the inode referred to by
.I fd
does not support sealing.
.B EINVAL
.I cmd
is
-.BR F_DUPFD
+.B F_DUPFD
and
.I arg
is negative or is greater than the maximum allowable value
(see the discussion of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
.B EINVAL
.I cmd
is
-.BR F_SETSIG
+.B F_SETSIG
and
.I arg
is not an allowable signal number.
.B EMFILE
.I cmd
is
-.BR F_DUPFD
+.B F_DUPFD
and the per-process limit on the number of open file descriptors
has been reached.
.TP
was specified in
.IR cmd ,
but
-.IR fd
+.I fd
does not refer to a directory.
.TP
-.BR EPERM
+.B EPERM
.I cmd
is
-.BR F_SETPIPE_SZ
+.B F_SETPIPE_SZ
and the soft or hard user pipe limit has been reached; see
.BR pipe (7).
.TP
.BR F_GETLK ,
.BR F_SETLK ,
and
-.BR F_SETLKW
+.B F_SETLKW
are specified in POSIX.1-2001.
.PP
-.BR F_GETOWN
+.B F_GETOWN
and
.B F_SETOWN
are specified in POSIX.1-2001.
(To get their definitions, define either
.\" .BR _BSD_SOURCE ,
.\" or
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with the value 500 or greater, or
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
with the value 200809L or greater.)
.PP
.B F_DUPFD_CLOEXEC
.BR F_OFD_SETLK ,
.BR F_OFD_SETLKW ,
and
-.BR F_OFD_GETLK
+.B F_OFD_GETLK
are Linux-specific (and one must define
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
to obtain their definitions),
but work is being done to have them included in the next version of POSIX.1.
.PP
-.BR F_ADD_SEALS
+.B F_ADD_SEALS
and
-.BR F_GET_SEALS
+.B F_GET_SEALS
are Linux-specific.
.\" FIXME . Once glibc adds support, add a note about FTM requirements
.SH NOTES
Several systems have more fields in
.I "struct flock"
such as, for example,
-.IR l_sysid
+.I l_sysid
(to identify the machine where the lock is held).
.\" e.g., Solaris 8 documents this field in fcntl(2), and Irix 6.5
.\" documents it in fcntl(5). mtk, May 2007
.SH BUGS
.SS F_SETFL
It is not possible to use
-.BR F_SETFL
+.B F_SETFL
to change the state of the
-.BR O_DSYNC
+.B O_DSYNC
and
-.BR O_SYNC
+.B O_SYNC
flags.
.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable
.\" via fcntl(2), but currently Linux does not permit this
.I errno
will contain the (positive) process group ID.
The Linux-specific
-.BR F_GETOWN_EX
+.B F_GETOWN_EX
operation avoids this problem.
.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to
.\" indicate that ANY negative PGID value will cause F_GETOWN
.\"
.SS Deadlock detection
The deadlock-detection algorithm employed by the kernel when dealing with
-.BR F_SETLKW
+.B F_SETLKW
requests can yield both
false negatives (failures to detect deadlocks,
leaving a set of deadlocked processes blocked indefinitely)
and
.I dnotify.txt
in the Linux kernel source directory
-.IR Documentation/filesystems/
+.I Documentation/filesystems/
(on older kernels, these files are directly under the
.I Documentation/
directory, and
locks interact with one another.
Another important side-effect is that the locks are not advisory anymore:
any IO on a locked file will always fail with
-.BR EACCES
+.B EACCES
when done from a separate file descriptor.
This difference originates from the design of locks in the SMB protocol,
which provides mandatory locking semantics.
The default timer slack value is set to the parent's
current timer slack value.
See the description of
-.BR PR_SET_TIMERSLACK
+.B PR_SET_TIMERSLACK
in
.BR prctl (2).
.IP *
.RS
.IP * 3
the
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
soft resource limit (set via
.BR setrlimit (2)),
which limits the number of processes and threads for a real user ID,
.TP
.B EAGAIN
The caller is operating under the
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
scheduling policy and does not have the reset-on-fork flag set.
See
.BR sched (7).
The operation to perform on the futex is specified in the
.I futex_op
argument;
-.IR val
+.I val
is a value whose meaning and purpose depends on
.IR futex_op .
.PP
For several blocking operations, the
.I timeout
argument is a pointer to a
-.IR timespec
+.I timespec
structure that specifies a timeout for the operation.
However, notwithstanding the prototype shown above, for some operations,
the least significant four bytes of this argument are instead
when interpreted in this fashion.
.PP
Where it is required, the
-.IR uaddr2
+.I uaddr2
argument is a pointer to a second futex word that is employed
by the operation.
.PP
.\" except the obsolete FUTEX_FD, for which the "private" flag was
.\" meaningless
but with the
-.BR FUTEX_PRIVATE_FLAG
+.B FUTEX_PRIVATE_FLAG
ORed into the constant value.
Thus, there are
.BR FUTEX_WAIT_PRIVATE ,
If another thread changed the value of the futex word after the
calling thread decided to block based on the prior value,
and if the other thread executed a
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
operation (or similar wake-up) after the value change and before this
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
operation, then the calling thread will observe the
value change and will not start to sleep.
.IP
(This interval will be rounded up to the system clock granularity,
and is guaranteed not to expire early.)
The timeout is by default measured according to the
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
clock, but, since Linux 4.5, the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock can be selected by specifying
-.BR FUTEX_CLOCK_REALTIME
+.B FUTEX_CLOCK_REALTIME
in
.IR futex_op .
If
.IR Note :
for
.BR FUTEX_WAIT ,
-.IR timeout
+.I timeout
is interpreted as a
-.IR relative
+.I relative
value.
This differs from other futex operations, where
.I timeout
is interpreted as an absolute value.
To obtain the equivalent of
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
with an absolute timeout, employ
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
with
-.IR val3
+.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY .
.IP
Most commonly,
.I val
is specified as either 1 (wake up a single waiter) or
-.BR INT_MAX
+.B INT_MAX
(wake up all waiters).
No guarantee is provided about which waiters are awoken
(e.g., a waiter with a higher scheduling priority is not guaranteed
.IR uaddr .
The caller must close the returned file descriptor after use.
When another process or thread performs a
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
on the futex word, the file descriptor indicates as being readable with
.BR select (2),
.BR poll (2),
.TP
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
This operation performs the same task as
-.BR FUTEX_CMP_REQUEUE
+.B FUTEX_CMP_REQUEUE
(see below), except that no check is made using the value in
.IR val3 .
(The argument
.I val
are 0 or 1.
(Specifying
-.BR INT_MAX
+.B INT_MAX
is not useful, because it would make the
-.BR FUTEX_CMP_REQUEUE
+.B FUTEX_CMP_REQUEUE
operation equivalent to
.BR FUTEX_WAKE .)
The limit value specified via
is typically either 1 or
.BR INT_MAX .
(Specifying the argument as 0 is not useful, because it would make the
-.BR FUTEX_CMP_REQUEUE
+.B FUTEX_CMP_REQUEUE
operation equivalent to
.BR FUTEX_WAIT .)
.IP
.\" Subject: Re: Add futex wrapper to glibc?
.IP
Both
-.BR FUTEX_REQUEUE
+.B FUTEX_REQUEUE
and
-.BR FUTEX_CMP_REQUEUE
+.B FUTEX_CMP_REQUEUE
can be used to avoid "thundering herd" wake-ups that could occur when using
.B FUTEX_WAKE
in cases where all of the waiters that are woken need to acquire
which requires operations on two futexes,
the one used to implement the mutex and the one used in the implementation
of the wait queue associated with the condition variable.
-.BR FUTEX_WAKE_OP
+.B FUTEX_WAKE_OP
allows such cases to be implemented without leading to
high rates of contention and context switching.
.IP
The
-.BR FUTEX_WAKE_OP
+.B FUTEX_WAKE_OP
operation is equivalent to executing the following code atomically
and totally ordered with respect to other futex operations on
any of the two supplied futex words:
.in
.IP
In other words,
-.BR FUTEX_WAKE_OP
+.B FUTEX_WAKE_OP
does the following:
.RS
.IP * 3
saves the original value of the futex word at
-.IR uaddr2
+.I uaddr2
and performs an operation to modify the value of the futex at
.IR uaddr2 ;
this is an atomic read-modify-write memory access (i.e., using atomic
In addition, bitwise ORing the following value into
.I op
causes
-.IR "(1\ <<\ oparg)"
+.I (1\~<<\~oparg)
to be used as the operand:
.IP
.in +4n
.in
.IP
The return value of
-.BR FUTEX_WAKE_OP
+.B FUTEX_WAKE_OP
is the sum of the number of waiters woken on the futex
-.IR uaddr
+.I uaddr
plus the number of waiters woken on the futex
.IR uaddr2 .
.\"
.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
This operation is like
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
except that
.I val3
is used to provide a 32-bit bit mask to the kernel.
This bit mask, in which at least one bit must be set,
is stored in the kernel-internal state of the waiter.
See the description of
-.BR FUTEX_WAKE_BITSET
+.B FUTEX_WAKE_BITSET
for further details.
.IP
If
.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
This operation is the same as
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
except that the
.I val3
argument is used to provide a 32-bit bit mask to the kernel.
the remaining waiters are left sleeping.
.IP
The effect of
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
and
-.BR FUTEX_WAKE_BITSET
+.B FUTEX_WAKE_BITSET
is to allow selective wake-ups among multiple waiters that are blocked
on the same futex.
However, note that, depending on the use case,
which corresponds to all 32 bits set in the bit mask, can be used as the
.I val3
argument for
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
and
.BR FUTEX_WAKE_BITSET .
Other than differences in the handling of the
.I timeout
argument, the
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
operation is equivalent to
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
with
-.IR val3
+.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, allow a wake-up by any waker.
The
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
operation is equivalent to
-.BR FUTEX_WAKE_BITSET
+.B FUTEX_WAKE_BITSET
with
-.IR val3
+.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, wake up any waiter(s).
.B FUTEX_WAITERS
bit shall be set in the futex word's value; in other words, this value is:
.IP
- FUTEX_WAITERS | TID
+.in +4n
+.EX
+FUTEX_WAITERS | TID
+.EE
+.in
.IP
(Note that is invalid for a PI futex word to have no owner and
-.BR FUTEX_WAITERS
+.B FUTEX_WAITERS
set.)
.PP
With this policy in place,
.BR SCHED_DEADLINE ,
.BR SCHED_FIFO ,
and
-.BR SCHED_RR
+.B SCHED_RR
scheduling policies in
.BR sched (7).)
The owner inherits either the waiter's CPU bandwidth
(if the waiter is scheduled under the
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
policy) or the waiter's priority (if the waiter is scheduled under the
-.BR SCHED_RR
+.B SCHED_RR
or
-.BR SCHED_FIFO
+.B SCHED_FIFO
policy).
.\" August 2015:
.\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL)
.I timeout
is not NULL, the structure it points to specifies
an absolute timeout, measured against the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock.
.\" 2016-07-07 response from Thomas Gleixner on LKML:
.\" From: Thomas Gleixner <tglx@linutronix.de>
.IR val ,
.IR timeout ,
and
-.IR val3
+.I val3
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.IR val ,
.IR timeout ,
and
-.IR val3
+.I val3
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Wait on a non-PI futex at
.I uaddr
and potentially be requeued (via a
-.BR FUTEX_CMP_REQUEUE_PI
+.B FUTEX_CMP_REQUEUE_PI
operation in another task) onto a PI futex at
.IR uaddr2 .
The wait operation on
The waiter can be removed from the wait on
.I uaddr
without requeueing on
-.IR uaddr2
+.I uaddr2
via a
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
operation in another task.
In this case, the
-.BR FUTEX_WAIT_REQUEUE_PI
+.B FUTEX_WAIT_REQUEUE_PI
operation fails with the error
.BR EAGAIN .
.IP
argument is ignored.
.IP
The
-.BR FUTEX_WAIT_REQUEUE_PI
+.B FUTEX_WAIT_REQUEUE_PI
and
-.BR FUTEX_CMP_REQUEUE_PI
+.B FUTEX_CMP_REQUEUE_PI
were added to support a fairly specific use case:
support for priority-inheritance-aware POSIX threads condition variables.
The idea is that these operations should always be paired,
in order to ensure that user space and the kernel remain in sync.
Thus, in the
-.BR FUTEX_WAIT_REQUEUE_PI
+.B FUTEX_WAIT_REQUEUE_PI
operation, the user-space application pre-specifies the target
of the requeue that takes place in the
-.BR FUTEX_CMP_REQUEUE_PI
+.B FUTEX_CMP_REQUEUE_PI
operation.
.\"
.\" Darren Hart notes that a patch to allow glibc to fully support
.I uaddr
is already locked by the caller.
.TP
-.BR EDEADLK
+.B EDEADLK
.\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some
.\" places, and EDEADLOCK in others. On almost all architectures
.\" these constants are synonymous. Is there a reason that both
shared anonymous mapping to synchronize access to a shared resource:
the terminal.
The two processes each write
-.IR nloops
+.I nloops
(a command-line argument that defaults to 5 if omitted)
messages to the terminal and employ a synchronization protocol
that ensures that they alternate in writing messages.
If
.I flags
specifies
-.BR MPOL_F_MEMS_ALLOWED
+.B MPOL_F_MEMS_ALLOWED
(available since Linux 2.6.24), the
.I mode
argument is ignored and the set of nodes (memories) that the
.PP
.BI "long syscall(SYS_get_robust_list, int " pid ,
.BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr );
-.BI "long syscall(SYS_set_robust_list,"
+.B long syscall(SYS_set_robust_list,
.BI " struct robust_list_head *" head ", size_t " len );
.fi
.PP
another thread that is waiting on that futex is notified that
the former owner of the futex has died.
This notification consists of two pieces: the
-.BR FUTEX_OWNER_DIED
+.B FUTEX_OWNER_DIED
bit is set in the futex word, and the kernel performs a
.BR futex (2)
-.BR FUTEX_WAKE
+.B FUTEX_WAKE
operation on one of the threads waiting on the futex.
.PP
The
the thread with the thread ID
.IR pid ,
and does not have the
-.BR CAP_SYS_PTRACE
+.B CAP_SYS_PTRACE
capability.
.TP
.B ESRCH
.BR futex (2),
.BR pthread_mutexattr_setrobust (3)
.PP
-.IR Documentation/robust\-futexes.txt
+.I Documentation/robust\-futexes.txt
and
-.IR Documentation/robust\-futex\-ABI.txt
+.I Documentation/robust\-futex\-ABI.txt
in the Linux kernel source tree
.\" http://lwn.net/Articles/172149/
.BI " unsigned int " count );
.PP
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.BR "#include <dirent.h>"
+.B #include <dirent.h>
.PP
.BI "ssize_t getdents64(int " fd ", void *" dirp ", size_t " count );
.fi
.I d_type
field is implemented since Linux 2.6.4.
It occupies a space that was previously a zero-filled padding byte in the
-.IR linux_dirent
+.I linux_dirent
structure.
Thus, on kernels up to and including 2.6.3,
attempting to access this field always provides the value 0
.BR setgroups ()
sets the supplementary group IDs for the calling process.
Appropriate privileges are required (see the description of the
-.BR EPERM
+.B EPERM
error, below).
The
.I size
.B EPERM
The calling process has insufficient privilege
(the caller does not have the
-.BR CAP_SETGID
+.B CAP_SETGID
capability in the user namespace in which it resides).
.TP
.BR EPERM " (since Linux 3.19)"
.BR setgroups ()
is denied in this user namespace.
See the description of
-.IR /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
in
.BR user_namespaces (7).
.SH CONFORMING TO
.I len
is smaller than the actual size.
(Before version 2.1, glibc uses
-.BR EINVAL
+.B EINVAL
for this case.)
.TP
.B EPERM
(if the interval is nonzero).
.PP
Three types of timers\(emspecified via the
-.IR which
+.I which
argument\(emare provided,
each of which counts against a different clock and
generates a different signal on timer expiration:
The function
.BR getitimer ()
places the current value of the timer specified by
-.IR which
+.I which
in the buffer pointed to by
.IR curr_value .
.PP
The
-.IR it_value
+.I it_value
substructure is populated with the amount of time remaining until
the next expiration of the specified timer.
This value changes as the timer counts down, and will be reset to
-.IR it_interval
+.I it_interval
when the timer expires.
If both fields of
-.IR it_value
+.I it_value
are zero, then this timer is currently disarmed (inactive).
.PP
The
-.IR it_interval
+.I it_interval
substructure is populated with the timer interval.
If both fields of
-.IR it_interval
+.I it_interval
are zero, then this is a single-shot timer (i.e., it expires just once).
.SS setitimer()
The function
.BR getitimer ()).
.PP
If either field in
-.IR new_value.it_value
+.I new_value.it_value
is nonzero,
then the timer is armed to initially expire at the specified time.
If both fields in
-.IR new_value.it_value
+.I new_value.it_value
are zero, then the timer is disarmed.
.PP
The
-.IR new_value.it_interval
+.I new_value.it_interval
field specifies the new interval for the timer;
if both of its subfields are zero, the timer is single-shot.
.SH RETURN VALUE
.PP
The standards are silent on the meaning of the call:
.PP
- setitimer(which, NULL, &old_value);
+.in +4n
+.EX
+setitimer(which, NULL, &old_value);
+.EE
+.in
.PP
Many systems (Solaris, the BSDs, and perhaps others)
treat this as equivalent to:
.PP
- getitimer(which, &old_value);
+.in +4n
+.EX
+getitimer(which, &old_value);
+.EE
+.in
.PP
In Linux, this is treated as being equivalent to a call in which the
.I new_value
.BR init (1)
or a "subreaper" process defined via the
.BR prctl (2)
-.BR PR_SET_CHILD_SUBREAPER
+.B PR_SET_CHILD_SUBREAPER
operation).
.SH ERRORS
These functions are always successful.
For further details, see
.BR gettid (2)
and the discussion of the
-.BR CLONE_THREAD
+.B CLONE_THREAD
flag in
.BR clone (2).
.\"
(i.e., set a higher priority).
However, since Linux 2.6.12, an unprivileged process can decrease
the nice value of a target process that has a suitable
-.BR RLIMIT_NICE
+.B RLIMIT_NICE
soft limit; see
.BR getrlimit (2)
for details.
draws entropy from the
.I urandom
source (i.e., the same source as the
-.IR /dev/urandom
+.I /dev/urandom
device).
This behavior can be changed via the
.I flags
.I random
source
(i.e., the same source as the
-.IR /dev/random
+.I /dev/random
device)
instead of the
.I urandom
.TP
.B GRND_NONBLOCK
By default, when reading from the
-.IR random
+.I random
source,
.BR getrandom ()
blocks if no random bytes are available,
and when reading from the
-.IR urandom
+.I urandom
source, it blocks if the entropy pool has not yet been initialized.
If the
.B GRND_NONBLOCK
This may be less than the number of bytes requested via
.I buflen
if either
-.BR GRND_RANDOM
+.B GRND_RANDOM
was specified in
-.IR flags
+.I flags
and insufficient entropy was present in the
-.IR random
+.I random
source or the system call was interrupted by a signal.
.PP
On error, \-1 is returned, and
.BR random (7).
.PP
Unlike
-.IR /dev/random
+.I /dev/random
and
.IR /dev/urandom ,
.BR getrandom ()
As of Linux 3.19 the following limits apply:
.IP * 3
When reading from the
-.IR urandom
+.I urandom
source, a maximum of 33554431 bytes is returned by a single call to
.BR getrandom ()
on systems where
has a size of 32 bits.
.IP *
When reading from the
-.IR random
+.I random
source, a maximum of 512 bytes is returned.
.SS Interruption by a signal handler
When reading from the
.BR getrandom ()
will block until the entropy pool has been initialized
(unless the
-.BR GRND_NONBLOCK
+.B GRND_NONBLOCK
flag was specified).
If a request is made to read a large number of bytes (more than 256),
.BR getrandom ()
.BR getrandom ()
will block until some random bytes become available
(unless the
-.BR GRND_NONBLOCK
+.B GRND_NONBLOCK
flag was specified).
.PP
The behavior when a call to
Instead, it will return all of the bytes that have been requested.
.PP
When reading from the
-.IR random
+.I random
source, blocking requests of any size can be interrupted by a signal handler
(the call fails with the error
.BR EINTR ).
Since Linux 4.5,
this limit also defines the maximum number of file descriptors that
an unprivileged process (one without the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability) may have "in flight" to other processes,
by being passed across UNIX domain sockets.
This limit applies to the
.BR getrlimit ().
.PP
If the
-.IR new_limit
+.I new_limit
argument is a not NULL, then the
.I rlimit
structure to which it points is used to set new values for
the soft and hard limits for
.IR resource .
If the
-.IR old_limit
+.I old_limit
argument is a not NULL, then a successful call to
.BR prlimit ()
places the previous soft and hard limits for
The caller tried to increase the hard
.B RLIMIT_NOFILE
limit above the maximum defined by
-.IR /proc/sys/fs/nr_open
+.I /proc/sys/fs/nr_open
(see
.BR proc (5))
.TP
its consumption of the resource).
.PP
One can set the resource limits of the shell using the built-in
-.IR ulimit
+.I ulimit
command
.RI ( limit
in
it creates to execute commands.
.PP
Since Linux 2.6.24, the resource limits of any process can be inspected via
-.IR /proc/[pid]/limits ;
+.IR /proc/ pid /limits ;
see
.BR proc (5).
.PP
.\" Subject: [PATCH 7/7] make RLIMIT_CPU/SIGXCPU per-process
.\" Date: 2005-01-23 23:27:46 GMT
if a process reaches its soft
-.BR RLIMIT_CPU
+.B RLIMIT_CPU
limit and has a handler installed for
.BR SIGXCPU ,
then, in addition to invoking the signal handler,
Other implementations
.\" Tested Solaris 10, FreeBSD 9, OpenBSD 5.0
do not change the
-.BR RLIMIT_CPU
+.B RLIMIT_CPU
soft limit in this manner,
and the Linux behavior is probably not standards conformant;
portable applications should avoid relying on this Linux-specific behavior.
.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=50951
The Linux-specific
-.BR RLIMIT_RTTIME
+.B RLIMIT_RTTIME
limit exhibits the same behavior when the soft limit is encountered.
.PP
Kernels before 2.4.22 did not diagnose the error
and
.BR setrlimit ()
wrapper functions use a 64-bit
-.IR rlim_t
+.I rlim_t
data type, even on 32-bit platforms.
However, the
.I rlim_t
to be useful, this limit must be represented using a type
that is as wide as the type used to
represent file offsets\(emthat is, as wide as a 64-bit
-.BR off_t
+.B off_t
(assuming a program compiled with
.IR _FILE_OFFSET_BITS=64 ).
.PP
implementation.)
.PP
See also the description of
-.IR /proc/[pid]/stat
+.IR /proc/ pid /stat
in
.BR proc (5).
.SH SEE ALSO
invalid in
.BR setsockopt ().
In some cases this error can also occur for an invalid value in
-.IR optval
+.I optval
(e.g., for the
.B IP_ADD_MEMBERSHIP
option described in
In a multithreaded process, all threads
have the same PID, but each one has a unique TID.
For further details, see the discussion of
-.BR CLONE_THREAD
+.B CLONE_THREAD
in
.BR clone (2).
.SH RETURN VALUE
In a new thread group created by a
.BR clone (2)
call that does not specify the
-.BR CLONE_THREAD
+.B CLONE_THREAD
flag (or, equivalently, a new process created by
.BR fork (2)),
the new process is a thread group leader,
capability),
or module loading is disabled
(see
-.IR /proc/sys/kernel/modules_disabled
+.I /proc/sys/kernel/modules_disabled
in
.BR proc (5)).
.PP
.B EINVAL
.I param_values
is invalid, or some part of the ELF image in
-.IR module_image
+.I module_image
contains inconsistencies.
.\" .TP
.\" .BR EINVAL " (Linux 2.4 and earlier)"
.BR syscall (2).
.PP
Information about currently loaded modules can be found in
-.IR /proc/modules
+.I /proc/modules
and in the file trees under the per-module subdirectories under
.IR /sys/module .
.PP
is available by calling
.BR query_module ();
the latter call fails with the error
-.BR ENOSYS
+.B ENOSYS
on Linux 2.6 and later.)
.PP
The older version of the system call
is the same as
.BR inotify_init ().
The following values can be bitwise ORed in
-.IR flags
+.I flags
to obtain different behavior:
.TP
.B IN_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
set to a (positive) value that indicates the error.
.SH BUGS
An invalid
-.IR ctx_id
+.I ctx_id
may cause a segmentation fault instead of generating the error
.BR EINVAL .
.SH SEE ALSO
.B EAGAIN
The specified \fInr_events\fP exceeds the limit of available events,
as defined in
-.IR /proc/sys/fs/aio\-max\-nr
+.I /proc/sys/fs/aio\-max\-nr
(see
.BR proc (5)).
.TP
The
.I iocb
(I/O control block) structure defined in
-.IR linux/aio_abi.h
+.I linux/aio_abi.h
defines the parameters that control the I/O operation.
.PP
.in +4n
The valid values are:
.RS
.TP
-.BR IOCB_FLAG_RESFD
+.B IOCB_FLAG_RESFD
Asynchronous I/O control must signal the file
descriptor mentioned in
.I aio_resfd
.I kb_table
< MAX_NR_KEYMAPS),
and
-.IR kb_index
+.I kb_index
is the keycode (0 <=
.I kb_index
< NR_KEYS).
.TP
.B VT_ACTIVATE
Switch to vt
-.IR argp
+.I argp
(1 <=
.I argp
<= MAX_NR_CONSOLES).
For further error values, see
.BR ioctl (2).
.SH VERSIONS
-.BR VFAT_IOCTL_READDIR_BOTH
+.B VFAT_IOCTL_READDIR_BOTH
and
.B VFAT_IOCTL_READDIR_SHORT
first appeared in Linux 2.0.
.PP
-.BR FAT_IOCTL_GET_ATTRIBUTES
+.B FAT_IOCTL_GET_ATTRIBUTES
and
-.BR FAT_IOCTL_SET_ATTRIBUTES
+.B FAT_IOCTL_SET_ATTRIBUTES
first appeared
.\" just before we got Git history
in Linux 2.6.12.
This behavior is commonly referred to as "copy on write".
.PP
This ioctl reflinks up to
-.IR src_length
+.I src_length
bytes from file descriptor
-.IR src_fd
+.I src_fd
at offset
-.IR src_offset
+.I src_offset
into the file
-.IR dest_fd
+.I dest_fd
at offset
.IR dest_offset ,
provided that both are files.
If
-.IR src_length
+.I src_length
is zero, the ioctl reflinks to the end of the source file.
This information is conveyed in a structure of
the following form:
Error codes can be one of, but are not limited to, the following:
.TP
.B EBADF
-.IR src_fd
+.I src_fd
is not open for reading;
-.IR dest_fd
+.I dest_fd
is not open for writing or is open for append-only writes;
or the filesystem which
-.IR src_fd
+.I src_fd
resides on does not support reflink.
.TP
.B EINVAL
descriptor, or if either file descriptor refers to special inodes.
.TP
.B EPERM
-.IR dest_fd
+.I dest_fd
is immutable.
.TP
.B ETXTBSY
This behavior is commonly referred to as "copy on write".
.PP
This ioctl performs the "compare and share if identical" operation on up to
-.IR src_length
+.I src_length
bytes from file descriptor
-.IR src_fd
+.I src_fd
at offset
.IR src_offset .
This information is conveyed in a structure of the following form:
.in
.PP
Each deduplication operation targets
-.IR src_length
+.I src_length
bytes in file descriptor
-.IR dest_fd
+.I dest_fd
at offset
.IR dest_offset .
The field
-.IR reserved
+.I reserved
must be zero.
During the call,
-.IR src_fd
+.I src_fd
must be open for reading and
-.IR dest_fd
+.I dest_fd
must be open for writing.
The combined size of the struct
-.IR file_dedupe_range
+.I file_dedupe_range
and the struct
-.IR file_dedupe_range_info
+.I file_dedupe_range_info
array must not exceed the system page size.
The maximum size of
-.IR src_length
-is filesystem dependent and is typically 16\ MiB.
+.I src_length
+is filesystem dependent and is typically 16\~MiB.
This limit will be enforced silently by the filesystem.
By convention, the storage used by
-.IR src_fd
+.I src_fd
is mapped into
-.IR dest_fd
+.I dest_fd
and the previous contents in
-.IR dest_fd
+.I dest_fd
are freed.
.PP
Upon successful completion of this ioctl, the number of bytes successfully
deduplicated is returned in
-.IR bytes_deduped
+.I bytes_deduped
and a status code for the deduplication operation is returned in
.IR status .
If even a single byte in the range does not match, the deduplication
request will be ignored and
-.IR status
+.I status
set to
.BR FILE_DEDUPE_RANGE_DIFFERS .
The
-.IR status
+.I status
code is set to
.B FILE_DEDUPE_RANGE_SAME
for success, a negative error code in case of error, or
Possible errors include (but are not limited to) the following:
.TP
.B EBADF
-.IR src_fd
+.I src_fd
is not open for reading;
-.IR dest_fd
+.I dest_fd
is not open for writing or is open for append-only writes; or the filesystem
which
-.IR src_fd
+.I src_fd
resides on does not support deduplication.
.TP
.B EINVAL
.B ENOMEM
The kernel was unable to allocate sufficient memory to perform the
operation or
-.IR dest_count
+.I dest_count
is so large that the input argument description spans more than a single
page of memory.
.TP
descriptor, or if either file descriptor refers to special inodes.
.TP
.B EPERM
-.IR dest_fd
+.I dest_fd
is immutable.
.TP
.B ETXTBSY
Swap files cannot share storage.
.TP
.B EXDEV
-.IR dest_fd " and " src_fd
+.I dest_fd
+and
+.I src_fd
are not on the same mounted filesystem.
.SH VERSIONS
This ioctl operation first appeared in Linux 4.5.
can be one of, but is not limited to, the following:
.TP
.B EBADF
-.IR fd
+.I fd
is not open for reading.
.TP
.B EBADMSG
about the accuracy of this timestamp.
This flag provides functionality similar to the
.BR mount (2)
-.BR MS_NOATIME
+.B MS_NOATIME
flag, but on a per-file basis.
.\" .TP
.\" .BR FS_NOCOMP_FL " \(aq\(aq"
Make file updates synchronous.
For files, this makes all writes synchronous
(as though all opens of the file were with the
-.BR O_SYNC
+.B O_SYNC
flag).
For directories, this has the same effect as the
-.BR FS_DIRSYNC_FL
+.B FS_DIRSYNC_FL
flag.
.TP
.BR FS_TOPDIR_FL " \(aqT\(aq"
Inode flags are a nonstandard Linux extension.
.SH NOTES
In order to change the inode flags of a file using the
-.BR FS_IOC_SETFLAGS
+.B FS_IOC_SETFLAGS
operation,
the effective user ID of the caller must match the owner of the file,
or the caller must have the
-.BR CAP_FOWNER
+.B CAP_FOWNER
capability.
.PP
The type of the argument given to the
-.BR FS_IOC_GETFLAGS
+.B FS_IOC_GETFLAGS
and
-.BR FS_IOC_SETFLAGS
+.B FS_IOC_SETFLAGS
operations is
-.IR "int\ *" ,
+.IR int\~* ,
notwithstanding the implication in the kernel source file
.I include/uapi/linux/fs.h
that the argument is
-.IR "long\ *" .
+.IR long\~* .
.SH SEE ALSO
.BR chattr (1),
.BR lsattr (1),
In each case,
.I fd
refers to a
-.IR /proc/[pid]/ns/*
+.IR /proc/ pid /ns/*
file.
Both operations return a new file descriptor on success.
.TP
This operation is valid only for hierarchical namespaces
(i.e., PID and user namespaces).
For user namespaces,
-.BR NS_GET_PARENT
+.B NS_GET_PARENT
is synonymous with
.BR NS_GET_USERNS .
.PP
The new file descriptor returned by these operations is opened with the
-.BR O_RDONLY
+.B O_RDONLY
and
-.BR O_CLOEXEC
+.B O_CLOEXEC
(close-on-exec; see
.BR fcntl (2))
flags.
.I st_ino
(inode number) fields together identify the owning/parent namespace.
This inode number can be matched with the inode number of another
-.IR /proc/[pid]/ns/{pid,user}
+.IR /proc/ pid /ns/ { pid , user }
file to determine whether that is the owning/parent namespace.
.PP
Either of these
.PP
.I fd
refers to a
-.IR /proc/[pid]/ns/*
+.IR /proc/ pid /ns/*
file.
.PP
The return value is one of the
-.BR CLONE_NEW*
+.B CLONE_NEW*
values that can be specified to
.BR clone (2)
or
.PP
.I fd
refers to a
-.IR /proc/[pid]/ns/user
+.IR /proc/ pid /ns/user
file.
.PP
The owner user ID is returned in the
.TP
.B TIOCSBRK
Argument:
-.BI "void"
+.B void
.IP
Turn break on, that is, start sending zero bits.
.TP
.B TIOCCBRK
Argument:
-.BI "void"
+.B void
.IP
Turn break off, that is, stop sending zero bits.
.SS Software flow control
.BR TCION .
.SS Buffer count and flushing
.TP
-.BI FIONREAD
+.B FIONREAD
Argument:
.BI "int\~*" argp
.IP
.TP
.B TIOCCONS
Argument:
-.BI "void"
+.B void
.IP
Redirect output that would have gone to
.I /dev/console
In Linux before version 2.6.10,
anybody can do this as long as the output was not redirected yet;
since version 2.6.10, only a process with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability may do this.
If output was redirected already, then
.B EBUSY
of a different session group, then the ioctl fails with
.BR EPERM ,
unless the caller has the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability and
.I arg
equals 1, in which case the terminal is stolen, and all processes that had
.TP
.B TIOCNOTTY
Argument:
-.BI "void"
+.B void
.IP
If the given terminal was the controlling terminal of the calling process,
give up this controlling terminal.
.TP
.B TIOCEXCL
Argument:
-.BI "void"
+.B void
.IP
Put the terminal into exclusive mode.
No further
(They fail with
.BR EBUSY ,
except for a process with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.)
.TP
.B TIOCGEXCL
.TP
.B TIOCNXCL
Argument:
-.BI "void"
+.B void
.IP
Disable exclusive mode.
.SS Line discipline
.BI "int\~*" argp
.IP
Set (if
-.IR *argp
+.I *argp
is nonzero) or remove (if
-.IR *argp
+.I *argp
is zero) the lock on the pseudoterminal slave device.
(See also
.BR unlockpt (3).)
.BR UFFDIO_API ,
.BR UFFDIO_REGISTER ,
and
-.BR UFFDIO_UNREGISTER
+.B UFFDIO_UNREGISTER
operations are used to
.I configure
userfaultfd behavior.
These operations allow the caller to choose what features will be enabled and
what kinds of events will be delivered to the application.
The remaining operations are
-.IR range
+.I range
operations.
These operations enable the calling application to resolve page-fault
events.
The
.I argp
argument is a pointer to a
-.IR uffdio_api
+.I uffdio_api
structure, defined as:
.PP
.in +4n
.TP
.B EINVAL
The userfaultfd has already been enabled by a previous
-.BR UFFDIO_API
+.B UFFDIO_API
operation.
.TP
.B EINVAL
.BR UFFDIO_REGISTER .)
.PP
The address range to unregister is specified in the
-.IR uffdio_range
+.I uffdio_range
structure pointed to by
.IR argp .
.PP
.in
.PP
The following value may be bitwise ORed in
-.IR mode
+.I mode
to change the behavior of the
.B UFFDIO_COPY
operation:
or
.I len
was not a multiple of the system page size, or the range specified by
-.IR src
+.I src
and
-.IR len
+.I len
or
-.IR dst
+.I dst
and
-.IR len
+.I len
was invalid.
.TP
.B EINVAL
An invalid bit was specified in the
-.IR mode
+.I mode
field.
.TP
.BR ENOENT " (since Linux 4.11)"
.in
.PP
The following value may be bitwise ORed in
-.IR mode
+.I mode
to change the behavior of the
.B UFFDIO_ZEROPAGE
operation:
.TP
.B EINVAL
An invalid bit was specified in the
-.IR mode
+.I mode
field.
.TP
.BR ESRCH " (since Linux 4.13)"
The
.B UFFDIO_WAKE
operation is used in conjunction with
-.BR UFFDIO_COPY
+.B UFFDIO_COPY
and
-.BR UFFDIO_ZEROPAGE
+.B UFFDIO_ZEROPAGE
operations that have the
-.BR UFFDIO_COPY_MODE_DONTWAKE
+.B UFFDIO_COPY_MODE_DONTWAKE
or
-.BR UFFDIO_ZEROPAGE_MODE_DONTWAKE
+.B UFFDIO_ZEROPAGE_MODE_DONTWAKE
bit set in the
.I mode
field.
The userfault monitor can perform several
-.BR UFFDIO_COPY
+.B UFFDIO_COPY
and
-.BR UFFDIO_ZEROPAGE
+.B UFFDIO_ZEROPAGE
operations in a batch and then explicitly wake up the faulting thread using
.BR UFFDIO_WAKE .
.PP
(For all operations except
.BR UFFDIO_API .)
The userfaultfd object has not yet been enabled (via the
-.BR UFFDIO_API
+.B UFFDIO_API
operation).
.SH CONFORMING TO
These
In order to detect available userfault features and
enable some subset of those features
the userfaultfd file descriptor must be closed after the first
-.BR UFFDIO_API
+.B UFFDIO_API
operation that queries features availability and reopened before
the second
-.BR UFFDIO_API
+.B UFFDIO_API
operation that actually enables the desired features.
.SH EXAMPLES
See
.BR mmap (2),
.BR userfaultfd (2)
.PP
-.IR Documentation/admin\-guide/mm/userfaultfd.rst
+.I Documentation/admin\-guide/mm/userfaultfd.rst
in the Linux kernel source tree
argument specifies which resource is to be compared in the two processes.
It has one of the following values:
.TP
-.BR KCMP_FILE
+.B KCMP_FILE
Check whether a file descriptor
.I idx1
in the process
or passing file descriptors via a domain socket (see
.BR unix (7)).
.TP
-.BR KCMP_FILES
+.B KCMP_FILES
Check whether the processes share the same set of open file descriptors.
The arguments
.I idx1
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_FILES
+.B CLONE_FILES
flag in
.BR clone (2).
.TP
-.BR KCMP_FS
+.B KCMP_FS
Check whether the processes share the same filesystem information
(i.e., file mode creation mask, working directory, and filesystem root).
The arguments
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_FS
+.B CLONE_FS
flag in
.BR clone (2).
.TP
-.BR KCMP_IO
+.B KCMP_IO
Check whether the processes share I/O context.
The arguments
.I idx1
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_IO
+.B CLONE_IO
flag in
.BR clone (2).
.TP
-.BR KCMP_SIGHAND
+.B KCMP_SIGHAND
Check whether the processes share the same table of signal dispositions.
The arguments
.I idx1
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_SIGHAND
+.B CLONE_SIGHAND
flag in
.BR clone (2).
.TP
-.BR KCMP_SYSVSEM
+.B KCMP_SYSVSEM
Check whether the processes share the same
list of System\ V semaphore undo operations.
The arguments
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_SYSVSEM
+.B CLONE_SYSVSEM
flag in
.BR clone (2).
.TP
-.BR KCMP_VM
+.B KCMP_VM
Check whether the processes share the same address space.
The arguments
.I idx1
.I idx2
are ignored.
See the discussion of the
-.BR CLONE_VM
+.B CLONE_VM
flag in
.BR clone (2).
.TP
is not protected against false positives which may occur if
the processes are currently running.
One should stop the processes by sending
-.BR SIGSTOP
+.B SIGSTOP
(see
.BR signal (7))
prior to inspection with this system call to obtain meaningful results.
is copied from the calling process into
the kernel either in regular
memory or in reserved memory (if
-.BR KEXEC_ON_CRASH
+.B KEXEC_ON_CRASH
is set).
The kernel first performs various sanity checks on the
information passed in
then the excess bytes in the kernel buffer are zeroed out.
.PP
In case of a normal kexec (i.e., the
-.BR KEXEC_ON_CRASH
+.B KEXEC_ON_CRASH
flag is not set), the segment data is loaded in any available memory
and is moved to the final destination at kexec reboot time (e.g., when the
.BR kexec (8)
option).
.PP
In case of kexec on panic (i.e., the
-.BR KEXEC_ON_CRASH
+.B KEXEC_ON_CRASH
flag is set), the segment data is
loaded to reserved memory at the time of the call, and, after a crash,
the kexec mechanism simply passes control to that kernel.
to be loaded from file referred to by the file descriptor
.IR initrd_fd .
The
-.IR cmdline
+.I cmdline
argument is a pointer to a buffer containing the command line
for the new kernel.
The
-.IR cmdline_len
+.I cmdline_len
argument specifies size of the buffer.
The last byte in the buffer must be a null byte (\(aq\e0\(aq).
.PP
The
-.IR flags
+.I flags
argument is a bit mask which modifies the behavior of the call.
The following values can be specified in
.IR flags :
.TP
-.BR KEXEC_FILE_UNLOAD
+.B KEXEC_FILE_UNLOAD
Unload the currently loaded kernel.
.TP
-.BR KEXEC_FILE_ON_CRASH
+.B KEXEC_FILE_ON_CRASH
Load the new kernel in the memory region reserved for the crash kernel
(as for
.BR KEXEC_ON_CRASH ).
This kernel is booted if the currently running kernel crashes.
.TP
-.BR KEXEC_FILE_NO_INITRAMFS
+.B KEXEC_FILE_NO_INITRAMFS
Loading initrd/initramfs is optional.
Specify this flag if no initramfs is being loaded.
If this flag is set, the value passed in
-.IR initrd_fd
+.I initrd_fd
is ignored.
.PP
The
field.
.TP
.B EINVAL
-.IR nr_segments
+.I nr_segments
exceeds
-.BR KEXEC_SEGMENT_MAX
+.B KEXEC_SEGMENT_MAX
(16).
.TP
.B EINVAL
.TP
.B EPERM
The caller does not have the
-.BR CAP_SYS_BOOT
+.B CAP_SYS_BOOT
capability.
.SH VERSIONS
The
.BR kexec (8)
.PP
The kernel source files
-.IR Documentation/kdump/kdump.txt
+.I Documentation/kdump/kdump.txt
and
-.IR Documentation/admin\-guide/kernel\-parameters.txt
+.I Documentation/admin\-guide/kernel\-parameters.txt
permission on a keyring in order for it to be found.
.IP
The arguments
-.IR arg4
+.I arg4
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
.BR EKEYREVOKED .
.IP
The caller must have
-.IR write
+.I write
or
-.IR setattr
+.I setattr
permission on the key.
.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM
.\" error for KEYCTL_REVOKE. Does this need to be documented?
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
The key must grant
.I setattr
permission to the caller
-.IR regardless
+.I regardless
of the caller's capabilities.
.\" FIXME Above, is it really intended that a privileged process can't
.\" override the lack of the 'setattr' permission?
.IP
The permissions in
-.IR arg3
+.I arg3
specify masks of available operations
for each of the following user categories:
.RS
see
.BR keyrings (7).
.TP
-.IR user
+.I user
This is the permission granted to a process
whose filesystem UID matches the UID of the key.
.TP
-.IR group
+.I group
This is the permission granted to a process
whose filesystem GID or any of its supplementary GIDs
matches the GID of the key.
.TP
-.IR other
+.I other
This is the permission granted to other processes
that do not match the
-.IR user
+.I user
and
-.IR group
+.I group
categories.
.RE
.IP
.IR user ,
.IR group ,
and
-.IR other
+.I other
categories are exclusive: if a process matches the
-.IR user
+.I user
category, it will not receive permissions granted in the
-.IR group
+.I group
category; if a process matches the
.I user
or
-.IR group
+.I group
category, then it will not receive permissions granted in the
-.IR other
+.I other
category.
.IP
The
.IR user ,
.IR group ,
or
-.IR other
+.I other
category.
.IP
Each permission mask is eight bits in size,
The available permissions are:
.RS
.TP
-.IR view
+.I view
This permission allows reading attributes of a key.
.IP
This permission is required for the
-.BR KEYCTL_DESCRIBE
+.B KEYCTL_DESCRIBE
operation.
.IP
The permission bits for each category are
and
.BR KEY_OTH_VIEW .
.TP
-.IR read
+.I read
This permission allows reading a key's payload.
.IP
This permission is required for the
-.BR KEYCTL_READ
+.B KEYCTL_READ
operation.
.IP
The permission bits for each category are
and
.BR KEY_OTH_READ .
.TP
-.IR write
+.I write
This permission allows update or instantiation of a key's payload.
For a keyring, it allows keys to be linked and unlinked from the keyring,
.IP
.BR KEYCTL_CLEAR ,
.BR KEYCTL_LINK ,
and
-.BR KEYCTL_UNLINK
+.B KEYCTL_UNLINK
operations.
.IP
The permission bits for each category are
and
.BR KEY_OTH_WRITE .
.TP
-.IR search
+.I search
This permission allows keyrings to be searched and keys to be found.
Searches can recurse only into nested keyrings that have
.I search
.BR KEYCTL_JOIN_SESSION_KEYRING ,
.BR KEYCTL_SEARCH ,
and
-.BR KEYCTL_INVALIDATE
+.B KEYCTL_INVALIDATE
operations.
.IP
The permission bits for each category are
and
.BR KEY_OTH_SEARCH .
.TP
-.IR link
+.I link
This permission allows a key or keyring to be linked to.
.IP
This permission is required for the
-.BR KEYCTL_LINK
+.B KEYCTL_LINK
and
-.BR KEYCTL_SESSION_TO_PARENT
+.B KEYCTL_SESSION_TO_PARENT
operations.
.IP
The permission bits for each category are
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CHOWN ,
and
-.BR KEYCTL_SETPERM
+.B KEYCTL_SETPERM
operations.
.IP
The permission bits for each category are
.BR KEY_OTH_ALL .
.IP
The
-.IR arg4 " and " arg5
+.I arg4
+and
+.I arg5
arguments are ignored.
.IP
This operation is exposed by
The descriptive string is returned in the buffer pointed to by
.I arg3
(cast to
-.IR "char\ *" );
+.IR char\~* );
.I arg4
(cast to
.IR size_t )
.in
.IP
In the above,
-.IR type
+.I type
and
-.IR description
+.I description
are strings,
-.IR uid
+.I uid
and
-.IR gid
+.I gid
are decimal strings, and
.I perm
is a hexadecimal permissions mask.
The descriptive string is written with the following format:
.IP
- %s;%d;%d;%08x;%s
+.in +4n
+.EX
+%s;%d;%d;%08x;%s
+.EE
+.in
.IP
-.BR "Note: the intention is that the descriptive string should"
-.BR "be extensible in future kernel versions".
+.B Note: the intention is that the descriptive string should
+.B be extensible in future kernel versions.
In particular, the
-.IR description
+.I description
field will not contain semicolons;
.\" FIXME But, the kernel does not enforce the requirement
.\" that the key description contains no semicolons!
in the descriptive string in the future.
.IP
Writing to the buffer is attempted only when
-.IR arg3
+.I arg3
is non-NULL and the specified buffer size
is large enough to accept the descriptive string
(including the terminating null byte).
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
Create a link from a keyring to a key.
.IP
The key to be linked is specified in
-.IR arg2
+.I arg2
(cast to
.IR key_serial_t );
the keyring is specified in
-.IR arg3
+.I arg3
(cast to
.IR key_serial_t ).
.IP
permission on the keyring.
.IP
The arguments
-.IR arg4
+.I arg4
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
then that key will be scheduled for destruction.
.IP
The arguments
-.IR arg4
+.I arg4
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
.IP
The tree to be searched is specified by passing
the ID of the head keyring in
-.IR arg2
+.I arg2
(cast to
.IR key_serial_t ).
The search is performed breadth-first and recursively.
arguments specify the key to be searched for:
.I arg3
(cast as
-.IR "char\ *" )
+.IR char\~* )
contains the key type
(a null-terminated character string up to 32 bytes in size,
including the terminating null byte), and
.I arg4
(cast as
-.IR "char\ *" )
+.IR char\~* )
contains the description of the key
(a null-terminated character string up to 4096 bytes in size,
including the terminating null byte).
.I key_serial_t
entries representing the IDs of all the keys that are linked to it.
The
-.IR "user"
+.I user
key type will return its data as is.
If a key type does not implement this function,
the operation fails with the error
.IP
This operation is equivalent to the call:
.IP
- keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
+.in +4n
+.EX
+keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
+.EE
+.in
.IP
The
.I arg5
to specify the new default keyring:
.RS
.TP
-.BR KEY_REQKEY_DEFL_NO_CHANGE
+.B KEY_REQKEY_DEFL_NO_CHANGE
Don't change the default keyring.
This can be used to discover the current default keyring
(without changing it).
.TP
-.BR KEY_REQKEY_DEFL_DEFAULT
+.B KEY_REQKEY_DEFL_DEFAULT
This selects the default behaviour,
which is to use the thread-specific keyring if there is one,
otherwise the process-specific keyring if there is one,
otherwise the UID-specific session keyring,
otherwise the user-specific keyring.
.TP
-.BR KEY_REQKEY_DEFL_THREAD_KEYRING
+.B KEY_REQKEY_DEFL_THREAD_KEYRING
Use the thread-specific keyring
.RB ( thread\-keyring (7))
as the new default keyring.
.TP
-.BR KEY_REQKEY_DEFL_PROCESS_KEYRING
+.B KEY_REQKEY_DEFL_PROCESS_KEYRING
Use the process-specific keyring
.RB ( process\-keyring (7))
as the new default keyring.
.TP
-.BR KEY_REQKEY_DEFL_SESSION_KEYRING
+.B KEY_REQKEY_DEFL_SESSION_KEYRING
Use the session-specific keyring
.RB ( session\-keyring (7))
as the new default keyring.
.TP
-.BR KEY_REQKEY_DEFL_USER_KEYRING
+.B KEY_REQKEY_DEFL_USER_KEYRING
Use the UID-specific keyring
.RB ( user\-keyring (7))
as the new default keyring.
.TP
-.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING
+.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING
Use the UID-specific session keyring
.RB ( user\-session\-keyring (7))
as the new default keyring.
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
The setting controlled by this operation is inherited by the child of
or negatively instantiated keys.
.IP
The arguments
-.IR arg4
+.I arg4
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
in its keyrings the authorization key that is
associated with the specified key.
(In other words, the
-.BR KEYCTL_ASSUME_AUTHORITY
+.B KEYCTL_ASSUME_AUTHORITY
operation is available only from a
.BR request\-key (8)-style
program; see
and the value 0 is returned.
.IP
The
-.BR KEYCTL_ASSUME_AUTHORITY
+.B KEYCTL_ASSUME_AUTHORITY
mechanism allows a program such as
.BR request\-key (8)
to assume the necessary authority to instantiate a new uninstantiated key
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
If
.I arg3
is specified as NULL or the buffer size specified in
-.IR arg4
+.I arg4
is too small, the full size of the security label string
(including the terminating null byte)
is returned as the function result,
to the LSM in force.
For example, with SELinux, it may look like:
.IP
- unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
+.in +4n
+.EX
+unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
+.EE
+.in
.IP
If no LSM is currently in force,
then an empty string is placed in the buffer.
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
Mark a key as negatively instantiated and set an expiration timer
on the key.
This operation provides a superset of the functionality of the earlier
-.BR KEYCTL_NEGATE
+.B KEYCTL_NEGATE
operation.
.IP
The ID of the key that is to be negatively instantiated is specified in
This operation is the same as
.BR KEYCTL_INSTANTIATE ,
but the payload data is specified as an array of
-.IR iovec
+.I iovec
structures:
.IP
.in +4n
.in
.IP
The pointer to the payload vector is specified in
-.IR arg3
+.I arg3
(cast as
-.IR "const struct iovec\ *" ).
+.IR "const struct iovec\~*" ).
The number of items in the vector is specified in
-.IR arg4
+.I arg4
(cast as
.IR "unsigned int" ).
.IP
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
.IR key_serial_t ).
.IP
The caller must have the
-.BR CAP_SETUID
+.B CAP_SETUID
capability in its user namespace in order to fetch the persistent keyring
for a user ID that does not match either the real or effective user ID
of the caller.
Persistent keyrings were added to Linux in kernel version 3.13.
.IP
The arguments
-.IR arg4
+.I arg4
and
-.IR arg5
+.I arg5
are ignored.
.IP
This operation is exposed by
.I arg2
argument is a pointer to a set of parameters containing
serial numbers for three
-.IR """user"""
+.I """user"""
keys used in the Diffie-Hellman calculation,
packaged in a structure of the following form:
.IP
The payloads of these keys are used to calculate the Diffie-Hellman
result as:
.IP
- base \(ha private mod prime
+.in +4n
+.EX
+base \(ha private mod prime
+.EE
+.in
.IP
If the base is the shared generator, the result is the local public key.
If the base is the remote public key, the result is the shared secret.
The
.I arg3
argument (cast to
-.IR "char\ *" )
+.IR char\~* )
points to a buffer where the result of the calculation is placed.
The size of that buffer is specified in
.I arg4
.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
Apply a key-linking restriction to the keyring with the ID provided in
-.IR arg2
+.I arg2
(cast to
.IR key_serial_t ).
The caller must have
-.IR setattr
+.I setattr
permission on the key.
If
.I arg3
.B EDEADLK
.I operation
was
-.BR KEYCTL_LINK
+.B KEYCTL_LINK
and the requested link would result in a cycle.
.TP
.B EDEADLK
.I operation
was
-.BR KEYCTL_RESTRICT_KEYRING
+.B KEYCTL_RESTRICT_KEYRING
and the requested keyring restriction would result in a cycle.
.TP
.B EDQUOT
.B EEXIST
.I operation
was
-.BR KEYCTL_RESTRICT_KEYRING
+.B KEYCTL_RESTRICT_KEYRING
and keyring provided in
.I arg2
argument already has a restriction set.
.B EINVAL
.I operation
was
-.BR KEYCTL_SEARCH
+.B KEYCTL_SEARCH
and the size of the description in
-.IR arg4
+.I arg4
(including the terminating null byte) exceeded 4096 bytes.
.TP
.B EINVAL
.B ELOOP
.I operation
was
-.BR KEYCTL_LINK
+.B KEYCTL_LINK
and the requested link would cause the maximum nesting depth
for keyrings to be exceeded.
.TP
(which is 64 currently).
.TP
.BR ENFILE " (Linux kernels before 3.13)"
-.IR operation
+.I operation
was
-.BR KEYCTL_LINK
+.B KEYCTL_LINK
and the keyring is full.
(Before Linux 3.13,
.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
.B EPERM
.I operation
was
-.BR KEYCTL_SESSION_TO_PARENT
+.B KEYCTL_SESSION_TO_PARENT
and either:
all of the UIDs (GIDs) of the parent process do not match
the effective UID (GID) of the calling process;
This system call is a nonstandard Linux extension.
.SH NOTES
A wrapper is provided in the
-.IR libkeyutils
+.I libkeyutils
library.
(The accompanying package provides the
.I <keyutils.h>
.RI ( 0256e6a6 )
shown in the log output above;
we can also see the newly created key with the name
-.IR mykey
+.I mykey
and ID
.IR 20d035bf .
.PP
.BR request\-key (8)
.PP
The kernel source files under
-.IR Documentation/security/keys/
+.I Documentation/security/keys/
(or, before Linux 4.13, in the file
.IR Documentation/security/keys.txt ).
.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.PP
-.BI "int syscall(SYS_landlock_create_ruleset,
+.B int syscall(SYS_landlock_create_ruleset,
.BI " const struct landlock_ruleset_attr *" attr ,
.BI " size_t " size " , uint32_t " flags );
.fi
If
.I oldpath
is an empty string, create a link to the file referenced by
-.IR olddirfd
+.I olddirfd
(which may have been obtained using the
.BR open (2)
.B O_PATH
can refer to any type of file except a directory.
This will generally not work if the file has a link count of zero (files
created with
-.BR O_TMPFILE
+.B O_TMPFILE
and without
-.BR O_EXCL
+.B O_EXCL
are an exception).
The caller must have the
-.BR CAP_DAC_READ_SEARCH
+.B CAP_DAC_READ_SEARCH
capability in order to use this flag.
This flag is Linux-specific; define
.B _GNU_SOURCE
.BR EPERM " (since Linux 3.6)"
The caller does not have permission to create a hard link to this file
(see the description of
-.IR /proc/sys/fs/protected_hardlinks
+.I /proc/sys/fs/protected_hardlinks
in
.BR proc (5)).
.TP
.I newdirfd
.TP
.B EPERM
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
was specified in
.IR flags ,
.I oldpath
is an empty string, and
-.IR olddirfd
+.I olddirfd
refers to a directory.
.SH VERSIONS
.BR linkat ()
.I newpath
are relative pathnames,
glibc constructs pathnames based on the symbolic links in
-.IR /proc/self/fd
+.I /proc/self/fd
that correspond to the
.I olddirfd
and
-.IR newdirfd
+.I newdirfd
arguments.
.SH BUGS
On NFS filesystems, the return code may be wrong in case the NFS server
to the underlying storage may not be reported as a hole.)
In the simplest implementation,
a filesystem can support the operations by making
-.BR SEEK_HOLE
+.B SEEK_HOLE
always return the offset of the end of the file,
and making
-.BR SEEK_DATA
+.B SEEK_DATA
always return
-.IR offset
+.I offset
(i.e., even if the location referred to by
.I offset
is a hole,
.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
.PP
The
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
feature test macro must be defined in order to obtain the definitions of
-.BR SEEK_DATA
+.B SEEK_DATA
and
-.BR SEEK_HOLE
+.B SEEK_HOLE
from
.IR <unistd.h> .
.PP
The
-.BR SEEK_HOLE
+.B SEEK_HOLE
and
-.BR SEEK_DATA
+.B SEEK_DATA
operations are supported for the following filesystems:
.IP * 3
Btrfs (since Linux 3.1)
.SH CONFORMING TO
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
.PP
-.BR SEEK_DATA
+.B SEEK_DATA
and
-.BR SEEK_HOLE
+.B SEEK_HOLE
are nonstandard extensions also present in Solaris,
FreeBSD, and DragonFly BSD;
they are proposed for inclusion in the next POSIX revision (Issue 8).
.BR madvise ()
is not specified in POSIX.)
Subsequently, a number of Linux-specific
-.IR advice
+.I advice
values have been added.
.\"
.\" ======================================================================
or zero-fill-on-demand pages for anonymous private mappings.
.IP
Note that, when applied to shared mappings,
-.BR MADV_DONTNEED
+.B MADV_DONTNEED
might not lead to immediate freeing of the pages in the range.
The kernel is free to delay freeing the pages until an appropriate moment.
The resident set size (RSS) of the calling process will be immediately
.IP
.B MADV_DONTNEED
cannot be applied to locked pages, Huge TLB pages, or
-.BR VM_PFNMAP
+.B VM_PFNMAP
pages.
(Pages marked with the kernel-internal
.B VM_PFNMAP
.IP
The specified address range must be mapped shared and writable.
This flag cannot be applied to locked pages, Huge TLB pages, or
-.BR VM_PFNMAP
+.B VM_PFNMAP
pages.
.IP
In the initial implementation, only
.\" commit 3f31d07571eeea18a7d34db9af21d2285b807a17
any filesystem which supports the
.BR fallocate (2)
-.BR FALLOC_FL_PUNCH_HOLE
+.B FALLOC_FL_PUNCH_HOLE
mode also supports
.BR MADV_REMOVE .
Hugetlbfs fails with the error
-.BR EINVAL
+.B EINVAL
and other filesystems fail with the error
.BR EOPNOTSUPP .
.TP
Poison the pages in the range specified by
.I addr
and
-.IR length
+.I length
and handle subsequent references to those pages
like a hardware memory corruption.
This operation is available only for privileged
for more details.
.IP
The
-.BR MADV_MERGEABLE
+.B MADV_MERGEABLE
and
-.BR MADV_UNMERGEABLE
+.B MADV_UNMERGEABLE
operations are available only if the kernel was configured with
.BR CONFIG_KSM .
.TP
.BR MADV_UNMERGEABLE " (since Linux 2.6.32)"
Undo the effect of an earlier
-.BR MADV_MERGEABLE
+.B MADV_MERGEABLE
operation on the specified address range;
KSM unmerges whatever pages it had merged in the address range specified by
-.IR addr
+.I addr
and
.IR length .
.TP
Most common kernels configurations provide
.BR MADV_HUGEPAGE -style
behavior by default, and thus
-.BR MADV_HUGEPAGE
+.B MADV_HUGEPAGE
is normally not necessary.
It is mostly intended for embedded systems, where
.BR MADV_HUGEPAGE -style
On such systems,
this flag can be used in order to selectively enable THP.
Whenever
-.BR MADV_HUGEPAGE
+.B MADV_HUGEPAGE
is used, it should always be in regions of memory with
an access pattern that the developer knows in advance won't risk
to increase the memory footprint of the application when transparent
hugepages are enabled.
.IP
The
-.BR MADV_HUGEPAGE
+.B MADV_HUGEPAGE
and
-.BR MADV_NOHUGEPAGE
+.B MADV_NOHUGEPAGE
operations are available only if the kernel was configured with
.BR CONFIG_TRANSPARENT_HUGEPAGE .
.TP
.BR MADV_NOHUGEPAGE " (since Linux 2.6.38)"
Ensures that memory in the address range specified by
-.IR addr
+.I addr
and
-.IR length
+.I length
will not be backed by transparent hugepages.
.TP
.BR MADV_DONTDUMP " (since Linux 3.4)"
This is useful in applications that have large areas of memory
that are known not to be useful in a core dump.
The effect of
-.BR MADV_DONTDUMP
+.B MADV_DONTDUMP
takes precedence over the bit mask that is set via the
.I /proc/[pid]/coredump_filter
file (see
.TP
.BR MADV_FREE " (since Linux 4.5)"
The application no longer requires the pages in the range specified by
-.IR addr
+.I addr
and
.IR len .
The kernel can thus free these pages,
is
.B MADV_DONTNEED
or
-.BR MADV_REMOVE
+.B MADV_REMOVE
and the specified address range includes locked, Huge TLB pages, or
.B VM_PFNMAP
pages.
.B EINVAL
.I advice
is
-.BR MADV_MERGEABLE
+.B MADV_MERGEABLE
or
.BR MADV_UNMERGEABLE ,
but the kernel was not configured with
.B EINVAL
.I advice
is
-.BR MADV_FREE
+.B MADV_FREE
or
-.BR MADV_WIPEONFORK
+.B MADV_WIPEONFORK
but the specified address range includes file, Huge TLB,
.BR MAP_SHARED ,
or
-.BR VM_PFNMAP
+.B VM_PFNMAP
ranges.
.TP
.B EINVAL
.\" function first appeared in 4.4BSD.
.SH SEE ALSO
.BR getrlimit (2),
-.BR memfd_secret(2),
+.BR memfd_secret (2),
.BR mincore (2),
.BR mmap (2),
.BR mprotect (2),
.BR MPOL_INTERLEAVE ,
.BR MPOL_PREFERRED ,
or
-.BR MPOL_LOCAL
+.B MPOL_LOCAL
(which are described in detail below).
All policy modes except
.B MPOL_DEFAULT
.I maxnode
points outside your accessible address space.
Or, there was an unmapped hole in the specified memory range specified by
-.IR addr
+.I addr
and
.IR len .
.TP
.IP
Given that registration is about the intent to receive the barriers, it
is valid to invoke
-.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
+.B MEMBARRIER_CMD_GLOBAL_EXPEDITED
from a process that has not employed
.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
.IP
.TP
.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED " (since Linux 4.16)"
Register the process's intent to receive
-.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
+.B MEMBARRIER_CMD_GLOBAL_EXPEDITED
memory barriers.
.TP
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)"
.TP
.BR MEMBARRIER_CMD_SHARED " (since Linux 4.3)"
This is an alias for
-.BR MEMBARRIER_CMD_GLOBAL
+.B MEMBARRIER_CMD_GLOBAL
that exists for header backward compatibility.
.PP
The
is invalid, or
.I flags
is nonzero, or the
-.BR MEMBARRIER_CMD_GLOBAL
+.B MEMBARRIER_CMD_GLOBAL
command is disabled because the
.I nohz_full
CPU parameter has been set, or the
-.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+.B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
and
-.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
commands are not implemented by the architecture.
.TP
.B ENOSYS
memory allocations such as those allocated using
.BR mmap (2)
with the
-.BR MAP_ANONYMOUS
+.B MAP_ANONYMOUS
flag.
.PP
The initial size of the file is set to 0.
as the target of the corresponding symbolic link in the directory
.IR /proc/self/fd/ .
The displayed name is always prefixed with
-.IR memfd:
+.I memfd:
and serves only for debugging purposes.
Names do not affect the behavior of the file descriptor,
and as such multiple files can have the same name without any side effects.
.PP
The following values may be bitwise ORed in
-.IR flags
+.I flags
to change the behavior of
.BR memfd_create ():
.TP
-.BR MFD_CLOEXEC
+.B MFD_CLOEXEC
Set the close-on-exec
.RB ( FD_CLOEXEC )
flag on the new file descriptor.
.BR open (2)
for reasons why this may be useful.
.TP
-.BR MFD_ALLOW_SEALING
+.B MFD_ALLOW_SEALING
Allow sealing operations on this file.
See the discussion of the
.B F_ADD_SEALS
and
-.BR F_GET_SEALS
+.B F_GET_SEALS
operations in
.BR fcntl (2),
and also NOTES, below.
.TP
.B EFAULT
The address in
-.IR name
+.I name
points to invalid memory.
.TP
.B EINVAL
.BR memfd_create ()
system call also has uses without file sealing
(which is why file-sealing is disabled, unless explicitly requested with the
-.BR MFD_ALLOW_SEALING
+.B MFD_ALLOW_SEALING
flag).
In particular, it can be used as an alternative to creating files in
-.IR tmp
+.I tmp
or as an alternative to using the
.BR open (2)
.B O_TMPFILE
(typically dealt with by copying data from
the shared memory region before checking and using it).
The latter possibility leaves the local process vulnerable to
-.BR SIGBUS
+.B SIGBUS
signals when an attempt is made to access a now-nonexistent
location in the shared memory region.
(Dealing with this possibility necessitates the use of a handler for the
-.BR SIGBUS
+.B SIGBUS
signal.)
.PP
Dealing with untrusted peers imposes extra complexity on
then it will be necessary to first unmap the shared writable mapping
created in the previous step.
Otherwise, behavior similar to
-.BR F_SEAL_WRITE
+.B F_SEAL_WRITE
can be achieved by using
.BR F_SEAL_FUTURE_WRITE ,
which will prevent future writes via
what kinds of restrictions have been placed on file modifications.
If desired, the second process can apply further seals
to impose additional restrictions (so long as the
-.BR F_SEAL_SEAL
+.B F_SEAL_SEAL
seal has not yet been applied).
.SH EXAMPLES
Below are shown two example programs that demonstrate the use of
file created by
.BR memfd_create ()
by opening the
-.IR /proc/[pid]/fd
+.IR /proc/ pid /fd
file that corresponds to the file descriptor opened by
.BR memfd_create ().
Using that pathname, we inspect the content of the
-.IR /proc/[pid]/fd
+.IR /proc/ pid /fd
symbolic link, and use our
.I t_get_seals
program to view the seals that have been placed on the file:
.IP \(bu
Harden against exploited kernel flaws.
In order to access memory areas backed by
-.BR memfd_secret(),
+.BR memfd_secret (),
a kernel-side attack would need to
either walk the page tables and create new ones,
or spawn a new privileged user-space process to perform
"secretmem.enable=y" kernel parameter.
.PP
To prevent potiential data leaks of memory regions backed by
-.BR memfd_secret()
+.BR memfd_secret ()
from a hybernation image,
hybernation is prevented when there are active
.BR memfd_secret ()
.BR migratepages (8),
.BR numastat (8)
.PP
-.IR Documentation/vm/page_migration.rst
+.I Documentation/vm/page_migration.rst
in the Linux kernel source tree
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SH SEE ALSO
.BR mkdir (1),
The result of the addition
.IR addr + len
was less than
-.IR addr
+.I addr
(e.g., the addition may have resulted in an overflow).
.TP
.B EINVAL
when checking against the limit.
Such double accounting could incorrectly calculate a "total locked memory"
value for the process that exceeded the
-.BR RLIMIT_MEMLOCK
+.B RLIMIT_MEMLOCK
limit, with the result that
.BR mlock ()
and
.BR MAP_SHARED_VALIDATE ,
the kernel verifies all passed flags are known and fails the
mapping with the error
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
for unknown flags.
This mapping type is also required to be able to use some mapping flags
(e.g.,
will fail.
.IP
Software that aspires to be portable should use the
-.BR MAP_FIXED
+.B MAP_FIXED
flag with care,
keeping in mind that the exact layout of a process's memory mappings
is allowed to change significantly between kernel versions,
C library versions, and operating system releases.
-.IR "Carefully read the discussion of this flag in NOTES!"
+.I Carefully read the discussion of this flag in NOTES!
.TP
.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)"
.\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843
one thread will succeed; all others will report failure.
.IP
Note that older kernels which do not recognize the
-.BR MAP_FIXED_NOREPLACE
+.B MAP_FIXED_NOREPLACE
flag will typically (upon detecting a collision with a preexisting mapping)
fall back to a
.RB \(lqnon- MAP_FIXED \(rq
.BR mlock (2)
when major faults are not acceptable after the initialization of the mapping.
The
-.BR MAP_LOCKED
+.B MAP_LOCKED
flag is ignored in older kernels.
.\" If set, the mapped pages will not be swapped out.
.TP
Since Linux 2.6.23,
.\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7
this flag causes
-.BR MAP_POPULATE
+.B MAP_POPULATE
to do nothing.
One day, the combination of
-.BR MAP_POPULATE
+.B MAP_POPULATE
and
-.BR MAP_NONBLOCK
+.B MAP_NONBLOCK
may be reimplemented.
.TP
.B MAP_NORESERVE
call doesn't fail if the mapping cannot be populated (for example, due
to limitations on the number of mapped huge pages when using
.BR MAP_HUGETLB ).
-.BR MAP_POPULATE
+.B MAP_POPULATE
is supported for private mappings only since Linux 2.6.23.
.TP
.BR MAP_STACK " (since Linux 2.6.27)"
.\" "pthread_create() slow for many threads; also time to revisit 64b
.\" context switch optimization?"
A further reason to employ this flag is portability:
-.BR MAP_STACK
+.B MAP_STACK
exists (and has an effect) on some other systems (e.g., some of the BSDs).
.TP
.BR MAP_SYNC " (since Linux 4.15)"
was not set).
.TP
.B EEXIST
-.BR MAP_FIXED_NOREPLACE
+.B MAP_FIXED_NOREPLACE
was specified in
.IR flags ,
and the range covered by
-.IR addr
+.I addr
and
-.IR length
+.I length
clashes with an existing mapping.
.TP
.B EINVAL
.I flags
constants are defined only if suitable feature test macros are defined
(possibly by default):
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
with glibc 2.19 or later;
or
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
or
-.BR _SVID_SOURCE
+.B _SVID_SOURCE
in glibc 2.19 and earlier.
(Employing
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
also suffices,
and requiring that macro specifically would have been more logical,
since these flags are all Linux-specific.)
The relevant flags are:
.BR MAP_32BIT ,
-.BR MAP_ANONYMOUS
+.B MAP_ANONYMOUS
(and the synonym
.BR MAP_ANON ),
.BR MAP_DENYWRITE ,
.\"
.SS Using MAP_FIXED safely
The only safe use for
-.BR MAP_FIXED
+.B MAP_FIXED
is where the address range specified by
-.IR addr
+.I addr
and
.I length
was previously reserved using another mapping;
otherwise, the use of
-.BR MAP_FIXED
+.B MAP_FIXED
is hazardous because it forcibly removes preexisting mappings,
making it easy for a multithreaded process to corrupt its own address space.
.PP
.UE .
.PP
Since Linux 4.17, a multithreaded program can use the
-.BR MAP_FIXED_NOREPLACE
+.B MAP_FIXED_NOREPLACE
flag to avoid the hazard described above
when attempting to create a mapping at a fixed address
that has not been reserved by a preexisting mapping.
.nf
.BR "#include <sys/mman.h>" " /* Definition of " MAP_* " and " PROT_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.BR "#include <unistd.h>
+.B #include <unistd.h>
.PP
.BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length ,
.BI " unsigned long " prot ", unsigned long " flags ,
.BR modify_ldt ()
cannot be used to create a long mode (i.e., 64-bit) code segment.
The undocumented field "lm" in
-.IR user_desc
+.I user_desc
is not useful, and, despite its name,
does not result in a long mode segment.
.SH BUGS
On 64-bit kernels before Linux 3.19,
.\" commit e30ab185c490e9a9381385529e0fd32f0a399495
setting the "lm" bit in
-.IR user_desc
+.I user_desc
prevents the descriptor from being considered empty.
Keep in mind that the
"lm" bit does not exist in the 32-bit headers, but these buggy kernels
with the tests being conducted in the order listed here:
.IP * 3
Remount an existing mount:
-.IR mountflags
+.I mountflags
includes
.BR MS_REMOUNT .
.IP *
Create a bind mount:
-.IR mountflags
+.I mountflags
includes
.BR MS_BIND .
.IP *
Change the propagation type of an existing mount:
-.IR mountflags
+.I mountflags
includes one of
.BR MS_SHARED ,
.BR MS_PRIVATE ,
.BR MS_UNBINDABLE .
.IP *
Move an existing mount to a new location:
-.IR mountflags
+.I mountflags
includes
.BR MS_MOVE .
.IP *
Create a new mount:
-.IR mountflags
+.I mountflags
includes none of the above flags.
.PP
Each of these operations is detailed later in this page.
Further flags may be specified in
-.IR mountflags
+.I mountflags
to modify the behavior of
.BR mount (),
as described below.
.B MS_STRICTATIME
mount option is also enabled.
(The advantage of combining
-.BR MS_STRICTATIME
+.B MS_STRICTATIME
and
-.BR MS_LAZYTIME
+.B MS_LAZYTIME
is that
.BR stat (2)
will return the correctly updated atime, but the atime updates
This flag provides a subset of the functionality provided by
.BR MS_NOATIME ;
that is,
-.BR MS_NOATIME
+.B MS_NOATIME
implies
.BR MS_NODIRATIME .
.TP
.TP
.BR MS_REC " (since Linux 2.4.11)"
Used in conjunction with
-.BR MS_BIND
+.B MS_BIND
to create a recursive bind mount,
and in conjunction with the propagation type flags to recursively change
the propagation type of all of the mounts in a subtree.
that need to know when a file has been read since it was last modified.
Since Linux 2.6.30, the kernel defaults to the behavior provided
by this flag (unless
-.BR MS_NOATIME
+.B MS_NOATIME
was specified), and the
.B MS_STRICTATIME
flag is required to obtain traditional semantics.
.RI ( printk ())
warning messages in the kernel log.
This flag supersedes the misnamed and obsolete
-.BR MS_VERBOSE
+.B MS_VERBOSE
flag (available since Linux 2.4.12), which has the same meaning.
.TP
.BR MS_STRICTATIME " (since Linux 2.6.30)"
filesystem are accessed.
(This was the default behavior before Linux 2.6.30.)
Specifying this flag overrides the effect of setting the
-.BR MS_NOATIME
+.B MS_NOATIME
and
-.BR MS_RELATIME
+.B MS_RELATIME
flags.
.TP
.B MS_SYNCHRONOUS
.BR MS_NOSUID ,
.BR MS_RELATIME ,
.BR MS_RDONLY ,
-.BR MS_STRICTATIME
+.B MS_STRICTATIME
(whose effect is to clear the
-.BR MS_NOATIME
+.B MS_NOATIME
and
-.BR MS_RELATIME
+.B MS_RELATIME
flags),
and
.BR MS_SYNCHRONOUS .
.\" which excludes MS_DIRSYNC and MS_SILENT, although SB_DIRSYNC
.\" and SB_SILENT are split out as per-superblock flags in do_mount()
.\" (Linux 4.17 source code)
-.BR MS_DIRSYNC
+.B MS_DIRSYNC
and
-.BR MS_SILENT
+.B MS_SILENT
flags during a remount are silently ignored.
Note that changes to per-superblock flags are visible via
all mounts of the associated filesystem
.BR MS_NODIRATIME ,
.BR MS_RELATIME ,
or
-.BR MS_STRICTATIME
+.B MS_STRICTATIME
is specified in
.IR mountflags ,
then the remount operation preserves the existing values of these flags
This is particularly useful for setting or clearing the "read-only"
flag on a mount without changing the underlying filesystem.
Specifying
-.IR mountflags
+.I mountflags
as:
.PP
.in +4n
If
.I mountflags
includes
-.BR MS_BIND
+.B MS_BIND
(available since Linux 2.4),
.\" since 2.4.0-test9
then perform a bind mount.
jails.
.PP
The
-.IR filesystemtype
+.I filesystemtype
and
-.IR data
+.I data
arguments are ignored.
.PP
The remaining bits (other than
if there are any submounts under the directory tree,
they are not bind mounted.
If the
-.BR MS_REC
+.B MS_REC
flag is also specified, then a recursive bind mount operation is performed:
all submounts under the
.I source
.\"
.SS Changing the propagation type of an existing mount
If
-.IR mountflags
+.I mountflags
includes one of
.BR MS_SHARED ,
.BR MS_PRIVATE ,
.BR MS_SLAVE ,
or
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
(all available since Linux 2.6.15),
then the propagation type of an existing mount is changed.
If more than one of these flags is specified, an error results.
.PP
The only other flags that can be specified while changing
the propagation type are
-.BR MS_REC
+.B MS_REC
(described below) and
-.BR MS_SILENT
+.B MS_SILENT
(which is ignored).
.PP
The
.IR source ,
.IR filesystemtype ,
and
-.IR data
+.I data
arguments are ignored.
.PP
The meanings of the propagation type flags are as follows:
.TP
-.BR MS_SHARED
+.B MS_SHARED
Make this mount shared.
Mount and unmount events immediately under this mount will propagate
to the other mounts that are members of this mount's peer group.
Conversely, mount and unmount events that take place under
peer mounts will propagate to this mount.
.TP
-.BR MS_PRIVATE
+.B MS_PRIVATE
Make this mount private.
Mount and unmount events do not propagate into or out of this mount.
.TP
-.BR MS_SLAVE
+.B MS_SLAVE
If this is a shared mount that is a member of a peer group
that contains other members, convert it to a slave mount.
If this is a shared mount that is a member of a peer group
while at the same time sharing mount and unmount events
with a peer group of which it is a member.
.TP
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
Make this mount unbindable.
This is like a private mount,
and in addition this mount can't be bind mounted.
When a recursive bind mount
.RB ( mount ()
with the
-.BR MS_BIND
+.B MS_BIND
and
-.BR MS_REC
+.B MS_REC
flags) is performed on a directory subtree,
any unbindable mounts within the subtree are automatically pruned
(i.e., not replicated)
flag is also specified in
.IR mountflags ,
then the propagation type of all mounts under
-.IR target
+.I target
is also changed.
.PP
For further details regarding mount propagation types
If
.I mountflags
contains the flag
-.BR MS_MOVE
+.B MS_MOVE
(available since Linux 2.4.18),
then move a subtree:
.I source
The move is atomic: at no point is the subtree unmounted.
.PP
The remaining bits in the
-.IR mountflags
+.I mountflags
argument are ignored, as are the
-.IR filesystemtype
+.I filesystemtype
and
-.IR data
+.I data
arguments.
.\"
.SS Creating a new mount
.BR MS_PRIVATE ,
.BR MS_SLAVE ,
or
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
is specified in
.IR mountflags ,
then
.BR mount ()
performs its default action: creating a new mount.
-.IR source
+.I source
specifies the source for the new mount, and
-.IR target
+.I target
specifies the directory at which to create the mount point.
.PP
The
and
.I data
arguments are employed, and further bits may be specified in
-.IR mountflags
+.I mountflags
to modify the behavior of the call.
.\"
.SH RETURN VALUE
and can't be remounted as read-write (until the errors are fixed).
.IP
Some filesystems instead return the error
-.BR EROFS
+.B EROFS
on an attempt to mount a read-only filesystem.
.TP
.B EACCES
.BR MS_PRIVATE ,
.BR MS_SLAVE ,
or
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
and also includes a flag other than
-.BR MS_REC
+.B MS_REC
or
.BR MS_SILENT .
.TP
-.BR EINVAL
+.B EINVAL
An attempt was made to bind mount an unbindable mount.
.TP
-.BR EINVAL
+.B EINVAL
In an unprivileged mount namespace
(i.e., a mount namespace owned by a user namespace
that was created by an unprivileged user),
.BR MS_RDONLY ,
.BR MS_NOSUID ,
or
-.BR MS_NOEXEC
+.B MS_NOEXEC
flag, or one of the "atime" flags
.RB ( MS_NOATIME ,
.BR MS_NODIRATIME ,
.BR MS_SLAVE ,
.BR MS_STRICTATIME ,
and
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
were added to glibc headers in version 2.12.
.\"
.SH CONFORMING TO
occupy the low order 16 bits of
.IR mountflags .)
Specifying
-.BR MS_MGC_VAL
+.B MS_MGC_VAL
was required in kernel versions prior to 2.4,
but since Linux 2.4 is no longer required and is ignored if specified.
.PP
A process can obtain a private mount namespace if:
it was created using the
.BR clone (2)
-.BR CLONE_NEWNS
+.B CLONE_NEWNS
flag,
in which case its new namespace is initialized to be a
.I copy
or it calls
.BR unshare (2)
with the
-.BR CLONE_NEWNS
+.B CLONE_NEWNS
flag,
which causes the caller's mount namespace to obtain a private copy
of the namespace that it was previously sharing with other processes,
The kernel will verify that
.B MOUNT_ATTR__ATIME
isn't partially set in
-.IR attr_clr
+.I attr_clr
(i.e., either all bits in the
.B MOUNT_ATTR__ATIME
bit field are either set or clear), and that
.BR mprotect (),
.BR pkey_mprotect ()
changes the protection on the pages specified by
-.IR addr
+.I addr
and
.IR len .
The
\fIaddr\fP is not a valid pointer,
or not a multiple of the system page size.
.TP
-.BR EINVAL
+.B EINVAL
.RB ( pkey_mprotect ())
\fIpkey\fP has not been allocated with
.BR pkey_alloc (2)
.TP
-.BR EINVAL
+.B EINVAL
Both
-.BR PROT_GROWSUP
+.B PROT_GROWSUP
and
-.BR PROT_GROWSDOWN
+.B PROT_GROWSDOWN
were specified in
.IR prot .
.TP
-.BR EINVAL
+.B EINVAL
Invalid flags specified in
.IR prot .
.TP
-.BR EINVAL
+.B EINVAL
(PowerPC architecture)
.B PROT_SAO
was specified in
are invalid for the address space of the process,
or specify one or more pages that are not mapped.
(Before kernel 2.4.19, the error
-.BR EFAULT
+.B EFAULT
was incorrectly produced for these cases.)
.TP
.B ENOMEM
exceeding the allowed maximum.
.\" I.e., the number of VMAs would exceed the 64 kB maximum
(For example, making the protection of a range
-.BR PROT_READ
+.B PROT_READ
in the middle of a region currently protected as
-.BR PROT_READ|PROT_WRITE
+.B PROT_READ|PROT_WRITE
would result in three mappings:
two read/write mappings at each end and a read-only mapping in the middle.)
.SH VERSIONS
On x86, when
.BR mprotect ()
is used with
-.IR prot
+.I prot
set to
.B PROT_EXEC
a pkey may be allocated and set on the memory implicitly
On systems that do not support protection keys in hardware,
.BR pkey_mprotect ()
may still be used, but
-.IR pkey
+.I pkey
must be set to \-1.
When called this way, the operation of
.BR pkey_mprotect ()
.B MREMAP_DONTUNMAP
flag can be used only with private anonymous mappings
(see the description of
-.BR MAP_PRIVATE
+.B MAP_PRIVATE
and
-.BR MAP_ANONYMOUS
+.B MAP_ANONYMOUS
in
.BR mmap (2)).
.IP
After completion,
any access to the range specified by
-.IR old_address
+.I old_address
and
.I old_size
will result in a page fault.
Otherwise, the kernel allocates a zero-filled page to handle the fault.
.IP
The
-.BR MREMAP_DONTUNMAP
+.B MREMAP_DONTUNMAP
flag may be used to atomically move a mapping while leaving the source
mapped.
See NOTES for some possible applications of
.IP *
.B MREMAP_DONTUNMAP
was specified, but one or more pages in the range specified by
-.IR old_address
+.I old_address
and
-.IR old_size
+.I old_size
were not private anonymous;
.IP *
.B MREMAP_DONTUNMAP
was specified and
-.IR old_size
+.I old_size
was not equal to
.IR new_size ;
.IP *
shareable mapping (but see BUGS);
.IP *
\fIold_size\fP was zero and the
-.BR MREMAP_MAYMOVE
+.B MREMAP_MAYMOVE
flag was not specified.
.RE
.TP
.\"
.SS MREMAP_DONTUNMAP use cases
Possible applications for
-.BR MREMAP_DONTUNMAP
+.B MREMAP_DONTUNMAP
include:
.IP * 3
Non-cooperative
.BR userfaultfd (2):
an application can yank out a virtual address range using
-.BR MREMAP_DONTUNMAP
+.B MREMAP_DONTUNMAP
and then employ a
.BR userfaultfd (2)
handler to handle the page faults that subsequently occur
as other threads in the process touch pages in the yanked range.
.IP *
Garbage collection:
-.BR MREMAP_DONTUNMAP
+.B MREMAP_DONTUNMAP
can be used in conjunction with
.BR userfaultfd (2)
to implement garbage collection algorithms (e.g., in a Java virtual machine).
Such an implementation can be cheaper (and simpler)
than conventional garbage collection techniques that involve
marking pages with protection
-.BR PROT_NONE
+.B PROT_NONE
in conjunction with the of a
-.BR SIGSEGV
+.B SIGSEGV
handler to catch accesses to those pages.
.SH BUGS
Before Linux 4.14,
.I msg_ctime
Time of creation of queue or time of last
.BR msgctl ()
-.BR IPC_SET
+.B IPC_SET
operation.
.TP
.I msg_cbytes
However,
.I msg_perm.mode
is not checked for read access for
-.IR msqid
+.I msqid
meaning that any user can employ this operation (just as any user may read
-.IR /proc/sysvipc/msg
+.I /proc/sysvipc/msg
to obtain the same information).
.SH RETURN VALUE
On success,
.B EEXIST
.B IPC_CREAT
and
-.BR IPC_EXCL
+.B IPC_EXCL
were specified in
.IR msgflg ,
but a message queue already exists for
Unless
.B MSG_COPY
is specified in
-.IR msgflg
+.I msgflg
(see below),
the
.I msgtyp
Because they alter the meaning of
.I msgtyp
in orthogonal ways,
-.BR MSG_COPY
+.B MSG_COPY
and
-.BR MSG_EXCEPT
+.B MSG_EXCEPT
may not both be specified in
.IR msgflg .
.IP
The
-.BR MSG_COPY
+.B MSG_COPY
flag was added for the implementation of
the kernel checkpoint-restore facility and
is available only if the kernel was built with the
.BR EINVAL " (since Linux 3.14)"
.I msgflg
specified both
-.BR MSG_COPY
+.B MSG_COPY
and
.BR MSG_EXCEPT .
.TP
if
.BR msgrcv ()
was called with the
-.BR MSG_COPY
+.B MSG_COPY
flag, but without
.BR IPC_NOWAIT ,
and the message queue contained less than
The
.I flags
argument should specify exactly one of
-.BR MS_ASYNC
+.B MS_ASYNC
and
.BR MS_SYNC ,
and may additionally include the
.\" glibc defines them to 1.
.SH NOTES
According to POSIX, either
-.BR MS_SYNC
+.B MS_SYNC
or
-.BR MS_ASYNC
+.B MS_ASYNC
must be specified in
.IR flags ,
and indeed failure to include one of these flags will cause
.BR MS_ASYNC .
(Since Linux 2.6.19,
.\" commit 204ec841fbea3e5138168edbc3a76d46747cc987
-.BR MS_ASYNC
+.B MS_ASYNC
is in fact a no-op, since the kernel properly tracks dirty
pages and flushes them to storage as necessary.)
Notwithstanding the Linux behavior,
portable, future-proof applications should ensure that they specify either
-.BR MS_SYNC
+.B MS_SYNC
or
-.BR MS_ASYNC
+.B MS_ASYNC
in
.IR flags .
.SH SEE ALSO
.BR nanosleep ()
suspends the execution of the calling thread
until either at least the time specified in
-.IR *req
+.I *req
has elapsed, or the delivery of a signal
that triggers the invocation of a handler in the calling thread or
that terminates the process.
receives signals at a very high rate,
then scheduling delays and rounding errors in the kernel's
calculation of the sleep interval and the returned
-.IR remain
+.I remain
value mean that the
-.IR remain
+.I remain
value may steadily
-.IR increase
+.I increase
on successive restarts of the
.BR nanosleep ()
call.
To avoid such problems, use
.BR clock_nanosleep (2)
with the
-.BR TIMER_ABSTIME
+.B TIMER_ABSTIME
flag to sleep to an absolute deadline.
.PP
In Linux 2.4, if
(i.e., set a higher priority).
However, since Linux 2.6.12, an unprivileged process can decrease
the nice value of a target process that has a suitable
-.BR RLIMIT_NICE
+.B RLIMIT_NICE
soft limit; see
.BR getrlimit (2)
for details.
(This kind of race is in principle possible for any system call
that creates a file descriptor whose close-on-exec flag should be set,
and various other Linux system calls provide an equivalent of the
-.BR O_CLOEXEC
+.B O_CLOEXEC
flag to deal with this problem.)
.\" This flag fixes only one form of the race condition;
.\" The race can also occur with, for example, file descriptors
matches the owner UID of the file.
.IP *
The calling process has the
-.BR CAP_FOWNER
+.B CAP_FOWNER
capability in its user namespace and
the owner UID of the file has a mapping in the namespace.
.RE
and has subsequently been standardized in POSIX.1-2008.
.IP
See also
-.BR O_PATH
+.B O_PATH
below.
.\" The headers from glibc 2.0.100 and later include a
.\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
.IP *
Getting and setting file descriptor flags
.RB ( fcntl (2)
-.BR F_GETFD
+.B F_GETFD
and
.BR F_SETFD ).
.IP *
Retrieving open file status flags using the
.BR fcntl (2)
-.BR F_GETFL
+.B F_GETFL
operation: the returned flags will include the bit
.BR O_PATH .
.IP *
Passing the file descriptor as the
-.IR dirfd
+.I dirfd
argument of
.BR openat ()
and the other "*at()" system calls.
This includes
.BR linkat (2)
with
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
(or via procfs using
.BR AT_SYMLINK_FOLLOW )
even if the file is not a directory.
.IP *
Passing the file descriptor to another process via a UNIX domain socket
(see
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
in
.BR unix (7)).
.RE
.BR O_CLOEXEC ,
.BR O_DIRECTORY ,
and
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
are ignored.
.IP
Opening a file or directory with the
If
.I pathname
is a symbolic link and the
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
flag is also specified,
then the call returns a file descriptor referring to the symbolic link.
This file descriptor can be used as the
containing directory, and the containing directory is both world- or
group-writable and sticky.
For details, see the descriptions of
-.IR /proc/sys/fs/protected_fifos
+.I /proc/sys/fs/protected_fifos
and
-.IR /proc/sys/fs/protected_regular
+.I /proc/sys/fs/protected_regular
in
.BR proc (5).
.TP
.TP
.B EINVAL
The filesystem does not support the
-.BR O_DIRECT
+.B O_DIRECT
flag.
See
-.BR NOTES
+.B NOTES
for more information.
.TP
.B EINVAL
was a symbolic link, and
.I flags
specified
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
but not
.BR O_PATH .
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached
(see the description of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
.B ENXIO
The file is a UNIX domain socket.
.TP
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
The filesystem containing
.I pathname
does not support
.BR O_NOATIME ,
.BR O_PATH ,
and
-.BR O_TMPFILE
+.B O_TMPFILE
flags are Linux-specific.
One must define
.B _GNU_SOURCE
.BR O_CLOEXEC ,
.BR O_DIRECTORY ,
and
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
flags are not specified in POSIX.1-2001,
but are specified in POSIX.1-2008.
Since glibc 2.12, one can obtain their definitions by defining either
.B _POSIX_C_SOURCE
with a value greater than or equal to 200809L or
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value greater than or equal to 700.
In glibc 2.11 and earlier, one obtains the definitions by defining
.BR _GNU_SOURCE .
.BR O_SYNC ,
.BR O_DSYNC ,
and
-.BR O_RSYNC
+.B O_RSYNC
for controlling the behavior.
Regardless of whether an implementation supports this option,
it must at least support the use of
-.BR O_SYNC
+.B O_SYNC
for regular files.
.PP
Linux implements
-.BR O_SYNC
+.B O_SYNC
and
.BR O_DSYNC ,
but not
.BR O_RSYNC .
Somewhat incorrectly, glibc defines
-.BR O_RSYNC
+.B O_RSYNC
to have the same value as
.BR O_SYNC .
.RB ( O_RSYNC
.I <asm/fcntl.h>
on HP PA-RISC, but it is not used.)
.PP
-.BR O_SYNC
+.B O_SYNC
provides synchronized I/O
.I file
integrity completion,
meaning write operations will flush data and all associated metadata
to the underlying hardware.
-.BR O_DSYNC
+.B O_DSYNC
provides synchronized I/O
.I data
integrity completion,
The last modification timestamp is not needed to ensure that
a read completes successfully, but the file length is.
Thus,
-.BR O_DSYNC
+.B O_DSYNC
would only guarantee to flush updates to the file length metadata
(whereas
-.BR O_SYNC
+.B O_SYNC
would also always flush the last modification timestamp metadata).
.PP
Before Linux 2.6.33, Linux implemented only the
-.BR O_SYNC
+.B O_SYNC
flag for
.BR open ().
However, when that flag was specified,
most filesystems actually provided the equivalent of synchronized I/O
.I data
integrity completion (i.e.,
-.BR O_SYNC
+.B O_SYNC
was actually implemented as the equivalent of
.BR O_DSYNC ).
.PP
Since Linux 2.6.33, proper
-.BR O_SYNC
+.B O_SYNC
support is provided.
However, to ensure backward binary compatibility,
-.BR O_DSYNC
+.B O_DSYNC
was defined with the same value as the historical
.BR O_SYNC ,
and
-.BR O_SYNC
+.B O_SYNC
was defined as a new (two-bit) flag value that includes the
-.BR O_DSYNC
+.B O_DSYNC
flag value.
This ensures that applications compiled against
new headers get at least
-.BR O_DSYNC
+.B O_DSYNC
semantics on pre-2.6.33 kernels.
.\"
.SS C library/kernel differences
return a file descriptor but, for example,
.BR read (2)
requests are denied
-with \fBEACCES\fP.
+with
+.BR EACCES .
This is because the client performs
.BR open ()
by checking the
or
.BR openat ()
to open a directory (with either the
-.BR O_RDONLY
+.B O_RDONLY
or the
-.BR O_PATH
+.B O_PATH
flag).
Alternatively, such a file descriptor can be obtained by applying
.BR dirfd (3)
When these APIs are given a
.I dirfd
argument of
-.BR AT_FDCWD
+.B AT_FDCWD
or the specified pathname is absolute,
then they handle their pathname argument in the same way as
the corresponding conventional APIs.
if the memory buffer is a private mapping
(i.e., any mapping created with the
.BR mmap (2)
-.BR MAP_PRIVATE
+.B MAP_PRIVATE
flag;
this includes memory allocated on the heap and statically allocated buffers).
Any such I/Os, whether submitted via an asynchronous I/O interface or from
and
.B O_DIRECTORY
are specified in
-.IR flags
+.I flags
and the file specified by
.I pathname
does not exist,
.BR name_to_handle_at ()
system call returns a file handle and a mount ID corresponding to
the file specified by the
-.IR dirfd
+.I dirfd
and
-.IR pathname
+.I pathname
arguments.
The file handle is returned via the argument
.IR handle ,
with a size large enough to hold the handle returned in
.IR f_handle .
Before the call, the
-.IR handle_bytes
+.I handle_bytes
field should be initialized to contain the allocated size for
.IR f_handle .
(The constant
It is not a
guaranteed upper limit as future filesystems may require more space.)
Upon successful return, the
-.IR handle_bytes
+.I handle_bytes
field is updated to contain the number of bytes actually written to
.IR f_handle .
.PP
The caller can discover the required size for the
.I file_handle
structure by making a call in which
-.IR handle\->handle_bytes
+.I handle\->handle_bytes
is zero;
in this case, the call fails with the error
-.BR EOVERFLOW
+.B EOVERFLOW
and
-.IR handle\->handle_bytes
+.I handle\->handle_bytes
is set to indicate the required size;
the caller can then use this information to allocate a structure
of the correct size (see EXAMPLES below).
Some care is needed here as
-.BR EOVERFLOW
+.B EOVERFLOW
can also indicate that no file handle is available for this particular
name in a filesystem which does normally support file-handle lookup.
This case can be detected when the
being increased.
.PP
Other than the use of the
-.IR handle_bytes
+.I handle_bytes
field, the caller should treat the
-.IR file_handle
+.I file_handle
structure as an opaque data type: the
-.IR handle_type
+.I handle_type
and
-.IR f_handle
+.I f_handle
fields are needed only by a subsequent call to
.BR open_by_handle_at ().
.PP
The
.I flags
argument is a bit mask constructed by ORing together zero or more of
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
and
.BR AT_SYMLINK_FOLLOW ,
described below.
is a nonempty string containing an absolute pathname,
then a handle is returned for the file referred to by that pathname.
In this case,
-.IR dirfd
+.I dirfd
is ignored.
.IP *
If
.I pathname
is a nonempty string containing a relative pathname and
-.IR dirfd
+.I dirfd
has the special value
.BR AT_FDCWD ,
then
If
.I pathname
is a nonempty string containing a relative pathname and
-.IR dirfd
+.I dirfd
is a file descriptor referring to a directory, then
.I pathname
is interpreted relative to the directory referred to by
specifies the value
.BR AT_EMPTY_PATH ,
then
-.IR dirfd
+.I dirfd
can be an open file descriptor referring to any type of file,
or
.BR AT_FDCWD ,
automount points, a
.BR name_to_handle_at ()
call on an automount point will return with error
-.BR EOVERFLOW
+.B EOVERFLOW
without having increased
.IR handle_bytes .
This can happen since Linux 4.13
.BR name_to_handle_at ().
.PP
The
-.IR mount_fd
+.I mount_fd
argument is a file descriptor for any object (file, directory, etc.)
in the mounted filesystem with respect to which
-.IR handle
+.I handle
should be interpreted.
The special value
.B AT_FDCWD
.IR pathname ,
.IR mount_id ,
or
-.IR handle
+.I handle
points outside your accessible address space.
.TP
.B EINVAL
includes an invalid bit value.
.TP
.B EINVAL
-.IR handle\->handle_bytes
+.I handle\->handle_bytes
is greater than
.BR MAX_HANDLE_SZ .
.TP
.B ENOENT
.I pathname
is an empty string, but
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
was not specified in
.IR flags .
.TP
and it is not the case that both
.I flags
includes
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
and
.I pathname
is an empty string.
can fail with the following errors:
.TP
.B EBADF
-.IR mount_fd
+.I mount_fd
is not an open file descriptor.
.TP
.B EBADF
nor a valid file descriptor.
.TP
.B EFAULT
-.IR handle
+.I handle
points outside your accessible address space.
.TP
.B EINVAL
.I handle\->handle_bytes
is greater than
-.BR MAX_HANDLE_SZ
+.B MAX_HANDLE_SZ
or is equal to zero.
.TP
.B ELOOP
.TP
.B EPERM
The caller does not have the
-.BR CAP_DAC_READ_SEARCH
+.B CAP_DAC_READ_SEARCH
capability.
.TP
.B ESTALE
If
.I pathname
refers to a symbolic link and
-.IR flags
+.I flags
does not specify
.BR AT_SYMLINK_FOLLOW ,
then
on the symbolic link by converting the handle to a file descriptor using
.BR open_by_handle_at ()
with the
-.BR O_PATH
+.B O_PATH
flag, and then passing the file descriptor as the
-.IR dirfd
+.I dirfd
argument in system calls such as
.BR readlinkat (2)
and
.BR fchownat (2).
.SS Obtaining a persistent filesystem ID
The mount IDs in
-.IR /proc/self/mountinfo
+.I /proc/self/mountinfo
can be reused as filesystems are unmounted and mounted.
Therefore, the mount ID returned by
.BR name_to_handle_at ()
using the UUID to look up the device name,
and then obtaining the corresponding mount point,
in order to produce the
-.IR mount_fd
+.I mount_fd
argument used by
.BR open_by_handle_at ().
.SH EXAMPLES
.BR open_by_handle_at ()
to open the file using that handle.
If an optional command-line argument is supplied, then the
-.IR mount_fd
+.I mount_fd
argument for
.BR open_by_handle_at ()
is obtained by opening the directory named in that argument.
Otherwise,
-.IR mount_fd
+.I mount_fd
is obtained by scanning
-.IR /proc/self/mountinfo
+.I /proc/self/mountinfo
to find a record whose mount ID matches the mount ID
read from standard input,
and the mount directory specified in that record is opened.
argument specifies how
.I pathname
should be opened, and acts as a superset of the
-.IR flags
+.I flags
and
-.IR mode
+.I mode
arguments to
.BR openat (2).
This argument is a pointer to a structure of the following form:
Similarly, an error is returned if
.BR openat2 ()
is called with a nonzero
-.IR how.mode
+.I how.mode
and
-.IR how.flags
+.I how.flags
does not contain
-.BR O_CREAT
+.B O_CREAT
or
.BR O_TMPFILE .
.TP
equates to
.IR dirfd ,
then an immediately following
-.IR ..\&
+.I ..\&
component likewise equates to
-.IR dirfd
+.I dirfd
(just as
.I /..\&
is traditionally equivalent to
Magic links are symbolic link-like objects that are most notably found in
.BR proc (5);
examples include
-.IR /proc/[pid]/exe
+.IR /proc/ pid /exe
and
-.IR /proc/[pid]/fd/* .
+.IR /proc/ pid /fd/* .
(See
.BR symlink (7)
for more details.)
currently has no controlling terminal (see
.BR credentials (7)),
then opening a magic link inside
-.IR /proc/[pid]/fd
+.IR /proc/ pid /fd
that happens to refer to a terminal
would cause the process to acquire a controlling terminal.
.IP \(bu
.IP
Because of such risks,
an application may prefer to disable magic link resolution using the
-.BR RESOLVE_NO_MAGICLINKS
+.B RESOLVE_NO_MAGICLINKS
flag.
.IP
If the trailing component (i.e., basename) of
and
.I how.flags
contains both
-.BR O_PATH
+.B O_PATH
and
.BR O_NOFOLLOW ,
then an
and
.I how.flags
contains both
-.BR O_PATH
+.B O_PATH
and
.BR O_NOFOLLOW ,
then an
file descriptor referencing the symbolic link will be returned.
.IP
Note that the effect of the
-.BR RESOLVE_NO_SYMLINKS
+.B RESOLVE_NO_SYMLINKS
flag,
which affects the treatment of symbolic links in all of the components of
.IR pathname ,
differs from the effect of the
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
file creation flag (in
.IR how.flags ),
which affects the handling of symbolic links only in the final component of
.IR pathname .
.IP
Applications that employ the
-.BR RESOLVE_NO_SYMLINKS
+.B RESOLVE_NO_SYMLINKS
flag are encouraged to make its use configurable
(unless it is used for a specific security purpose),
as symbolic links are very widely used by end-users.
.B EAGAIN
.I how.resolve
contains either
-.BR RESOLVE_IN_ROOT
+.B RESOLVE_IN_ROOT
or
.BR RESOLVE_BENEATH ,
and the kernel could not ensure that a ".." component didn't escape (due to a
call.
.TP
.B EAGAIN
-.BR RESOLVE_CACHED
+.B RESOLVE_CACHED
was set, and the open operation cannot be performed using only cached
information.
The caller should retry without
is nonzero, but
.I how.flags
does not contain
-.BR O_CREAT
+.B O_CREAT
or
.BR O_TMPFILE .
.TP
.B EXDEV
.I how.resolve
contains either
-.BR RESOLVE_IN_ROOT
+.B RESOLVE_IN_ROOT
or
.BR RESOLVE_BENEATH ,
and an escape from the root during path resolution was detected.
three cases to consider:
.IP \(bu 2
If
-.IR ksize
+.I ksize
equals
.IR usize ,
then there is no version mismatch and
can be used verbatim.
.IP \(bu
If
-.IR ksize
+.I ksize
is larger than
.IR usize ,
then there are some extension fields that the kernel supports
This provides backwards-compatibility.
.IP \(bu
If
-.IR ksize
+.I ksize
is smaller than
.IR usize ,
then there are some extension fields which the user-space application
.PP
A user-space application that wishes to determine which extensions
the running kernel supports can do so by conducting a binary search on
-.IR size
+.I size
with a structure which has every byte nonzero (to find the largest value
which doesn't produce an error of
.BR E2BIG ).
then
.BR execve (2).
.TP
-.BR PERF_FLAG_FD_NO_GROUP
+.B PERF_FLAG_FD_NO_GROUP
This flag tells the event to ignore the
.I group_fd
parameter except for the purpose of setting up output redirection
existing children).
.IP
Inherit does not work for some combinations of
-.IR read_format
+.I read_format
values, such as
.BR PERF_FORMAT_GROUP .
.TP
.BR epoll (7).
Alternatively, the overflow events can be captured via sa signal handler,
by enabling I/O signaling on the file descriptor; see the discussion of the
-.BR F_SETOWN
+.B F_SETOWN
and
-.BR F_SETSIG
+.B F_SETSIG
operations in
.BR fcntl (2).
.PP
A paused ring-buffer does not prevent generation of samples,
but simply discards them.
The discarded samples are considered lost, and cause a
-.BR PERF_RECORD_LOST
+.B PERF_RECORD_LOST
sample to be generated when possible.
An overflow signal may still be triggered by the discarded sample
even though the ring-buffer remains empty.
.BR prctl (2),
.BR read (2)
.PP
-.IR Documentation/admin\-guide/perf\-security.rst
+.I Documentation/admin\-guide/perf\-security.rst
in the kernel source tree
sets the caller's execution domain to the value specified by
.IR persona .
Specifying
-.IR persona
+.I persona
as 0xffffffff provides a way of retrieving
the current persona without changing it.
.PP
.TP
.BR READ_IMPLIES_EXEC " (since Linux 2.6.8)"
With this flag set,
-.BR PROT_READ
+.B PROT_READ
implies
-.BR PROT_EXEC
+.B PROT_EXEC
for
.BR mmap (2).
.TP
.TP
.BR PER_OSR5 " (since Linux 2.4)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR WHOLE_SECONDS ;
otherwise no effects.
.TP
.BR PER_SVR3 " (since Linux 1.2.0)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR SHORT_INODE ;
otherwise no effects.
.TP
.BR PER_SVR4 " (since Linux 1.2.0)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR MMAP_PAGE_ZERO ;
otherwise no effects.
.TP
.BR PER_UW7 " (since Linux 2.4)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR MMAP_PAGE_ZERO ;
otherwise no effects.
.TP
.BR PER_WYSEV386 " (since Linux 1.2.0)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR SHORT_INODE ;
otherwise no effects.
.TP
.BR PER_XENIX " (since Linux 1.2.0)"
Implies
-.BR STICKY_TIMEOUTS
+.B STICKY_TIMEOUTS
and
.BR SHORT_INODE ;
otherwise no effects.
.B EMFILE
The per-process limit on the number of open file descriptors has been reached
(see the description of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
The effect of
.BR pidfd_getfd ()
is similar to the use of
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
messages described in
.BR unix (7),
but differs in the following respects:
.IP \(bu 2
In order to pass a file descriptor using an
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
message,
the two processes must first establish a UNIX domain socket connection.
.IP \(bu
The use of
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
requires cooperation on the part of the process whose
file descriptor is being copied.
By contrast, no such cooperation is necessary when using
The ability to use
.BR pidfd_getfd ()
is restricted by a
-.BR PTRACE_MODE_ATTACH_REALCREDS
+.B PTRACE_MODE_ATTACH_REALCREDS
ptrace access mode check.
.SH SEE ALSO
.BR clone3 (2),
then an attempt to wait on the file descriptor using
.BR waitid (2)
will immediately return the error
-.BR EAGAIN
+.B EAGAIN
rather than blocking.
.SH RETURN VALUE
On success,
.B EMFILE
The per-process limit on the number of open file descriptors has been reached
(see the description of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
conditions hold true:
.IP \(bu 2
the disposition of
-.BR SIGCHLD
+.B SIGCHLD
has not been explicitly set to
-.BR SIG_IGN
+.B SIG_IGN
(see
.BR sigaction (2));
.IP \(bu
the
-.BR SA_NOCLDWAIT
+.B SA_NOCLDWAIT
flag was not specified while establishing a handler for
-.BR SIGCHLD
+.B SIGCHLD
or while setting the disposition of that signal to
-.BR SIG_DFL
+.B SIG_DFL
(see
.BR sigaction (2));
and
should instead be created using
.BR clone (2)
with the
-.BR CLONE_PIDFD
+.B CLONE_PIDFD
flag.
.\"
.SS Use cases for PID file descriptors
(or by
.BR clone (2)
with the
-.BR CLONE_PID
+.B CLONE_PID
flag) can be used for the following purposes:
.IP \(bu 2
The
It then uses
.BR poll (2)
to monitor the file descriptor for process exit, as indicated by an
-.BR EPOLLIN
+.B EPOLLIN
event.
.\"
.SS Program source
.B EPERM
.I pidfd
doesn't refer to the calling process, and
-.IR info.si_code
+.I info.si_code
is invalid (see
.BR rt_sigqueueinfo (2)).
.TP
Such a file descriptor can be obtained in any of the following ways:
.IP * 3
by opening a
-.IR /proc/[pid]
+.IR /proc/ pid
directory;
.IP *
using
or
.BR clone3 (2)
that specifies the
-.BR CLONE_PIDFD
+.B CLONE_PIDFD
flag.
.PP
The
creates a pipe, a unidirectional data channel that
can be used for interprocess communication.
The array
-.IR pipefd
+.I pipefd
is used to return two file descriptors referring to the ends of the pipe.
-.IR pipefd[0]
+.I pipefd[0]
refers to the read end of the pipe.
-.IR pipefd[1]
+.I pipefd[1]
refers to the write end of the pipe.
Data written to the write end of the pipe is buffered by the kernel
until it is read from the read end of the pipe.
.BR pipe (7).
.PP
If
-.IR flags
+.I flags
is 0, then
.BR pipe2 ()
is the same as
.BR pipe ().
The following values can be bitwise ORed in
-.IR flags
+.I flags
to obtain different behavior:
.TP
.B O_CLOEXEC
.RS
.IP * 3
Writes of greater than
-.BR PIPE_BUF
+.B PIPE_BUF
bytes (see
.BR pipe (7))
will be split into multiple packets.
The constant
-.BR PIPE_BUF
+.B PIPE_BUF
is defined in
.IR <limits.h> .
.IP *
then the requested number of bytes are read,
and the excess bytes in the packet are discarded.
Specifying a buffer size of
-.BR PIPE_BUF
+.B PIPE_BUF
will be sufficient to read the largest possible packets
(see the previous point).
.IP *
.TP
.B O_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file descriptions
referred to by the new file descriptors.
Using this flag saves extra calls to
.PP
The following restrictions apply:
.IP \- 3
-.IR new_root
+.I new_root
and
-.IR put_old
+.I put_old
must be directories.
.IP \-
.I new_root
bind mounting the path onto itself.
.IP \-
The propagation type of the parent mount of
-.IR new_root
+.I new_root
and the parent mount of the current root directory must not be
.BR MS_SHARED ;
similarly, if
During the subsequent
.BR umount ()
call, resolution of
-.IR """."""
+.I """."""
starts with
.I new_root
and then moves up the list of mounts stacked at
value for
.BR poll ()
is interpreted as an infinite timeout, a negative value expressed in
-.IR *tmo_p
+.I *tmo_p
results in an error from
.BR ppoll ().
.PP
.B EINVAL
.RB ( ppoll ())
The timeout value expressed in
-.IR *ip
+.I *ip
is invalid (negative).
.TP
.B ENOMEM
and
.BR ppoll ()
is not affected by the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag.
.PP
On some other UNIX systems,
Some implementations define the nonstandard constant
.B INFTIM
with the value \-1 for use as a
-.IR timeout
+.I timeout
for
.BR poll ().
This constant is not provided in glibc.
system call has a fifth argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the
-.IR sigmask
+.I sigmask
argument.
The glibc
.BR ppoll ()
The second return from
.BR poll ()
also indicated
-.BR POLLIN
+.B POLLIN
and
.BR POLLHUP ;
the program then consumed the last of the available input.
On the final return,
.BR poll ()
indicated only
-.BR POLLHUP
+.B POLLHUP
on the FIFO,
at which point the file descriptor was closed and the program terminated.
.\"
(but other open file handles to the same file are unaffected).
.PP
The contents of the kernel buffer cache can be cleared via the
-.IR /proc/sys/vm/drop_caches
+.I /proc/sys/vm/drop_caches
interface described in
.BR proc (5).
.PP
.I arg3
is in the ambient set and 0 if it is not.
.TP
-.BR PR_CAP_AMBIENT_CLEAR_ALL
+.B PR_CAP_AMBIENT_CLEAR_ALL
All capabilities will be removed from the ambient set.
This operation requires setting
.I arg3
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
-.BR EINVAL
+.B EINVAL
if
.I arg2
does not represent a valid capability; or
-.BR EINVAL
+.B EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.IP
in the orphaned process will now return the PID of the subreaper process,
and when the orphan terminates, it is the subreaper process that
will receive a
-.BR SIGCHLD
+.B SIGCHLD
signal and will be able to
.BR wait (2)
on the process to discover its termination status.
.BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
Return the "child subreaper" setting of the caller,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_DUMPABLE
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
.IP
Normally, the "dumpable" attribute is set to 1.
However, it is reset to the current value contained in the file
-.IR /proc/sys/fs/\:suid_dumpable
+.I /proc/sys/fs/\:suid_dumpable
(which by default has the value 0),
in the following circumstances:
.\" See kernel/cred.c::commit_creds() (Linux 3.18 sources)
.IP
If a process is not dumpable,
the ownership of files in the process's
-.IR /proc/[pid]
+.IR /proc/ pid
directory is affected as described in
.BR proc (5).
.\" prctl PR_GET_DUMPABLE
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_FP_MODE
.TP
.BR PR_SET_FP_MODE " (since Linux 4.0, only on MIPS)"
argument is a bit mask describing the floating-point mode used:
.RS
.TP
-.BR PR_FP_MODE_FR
+.B PR_FP_MODE_FR
When this bit is
.I unset
(so called
.I set
.RB ( FR=1 ).
Applications that use the O32 FPXX ABI can operate with either
-.BR FR=0
+.B FR=0
or
-.BR FR=1 .
+.B FR=1 .
.TP
-.BR PR_FP_MODE_FRE
+.B PR_FP_MODE_FRE
Enable emulation of 32-bit floating-point mode.
When this mode is enabled,
it emulates 32-bit floating-point operations
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.\" prctl PR_GET_FP_MODE
.TP
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
are ignored.
.\" prctl PR_SET_FPEMU
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_FPEXC
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_IO_FLUSHER
.TP
.BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
the default behavior will be used.
.IP
The calling process must have the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability.
.IP
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
must be zero.
.IP
The IO_FLUSHER state is inherited by a child process created via
0 indicates that the caller is not in the IO_FLUSHER state.
.IP
The calling process must have the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability.
.IP
.IR arg2 ,
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
must be zero.
.\" prctl PR_SET_KEEPCAPS
.TP
See
.BR sigaction (2)
for more information on the
-.BR SIGBUS
+.B SIGBUS
signal.
The policy is inherited by children.
The remaining unused
where a program might find it useful to change its own memory map.
.IP
The calling process must have the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability.
The value in
.I arg2
Before Linux 3.10,
.\" commit 52b3694157e3aa6df871e283115652ec6f2d31e0
this feature is available only if the kernel is built with the
-.BR CONFIG_CHECKPOINT_RESTORE
+.B CONFIG_CHECKPOINT_RESTORE
option enabled.
.RS
.TP
-.BR PR_SET_MM_START_CODE
+.B PR_SET_MM_START_CODE
Set the address above which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or shareable (see
.BR mmap (2)
for more information).
.TP
-.BR PR_SET_MM_END_CODE
+.B PR_SET_MM_END_CODE
Set the address below which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or shareable.
.TP
-.BR PR_SET_MM_START_DATA
+.B PR_SET_MM_START_DATA
Set the address above which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
The corresponding memory area must be readable and writable,
but not executable or shareable.
.TP
-.BR PR_SET_MM_START_STACK
+.B PR_SET_MM_START_STACK
Set the start address of the stack.
The corresponding memory area must be readable and writable.
.TP
-.BR PR_SET_MM_START_BRK
+.B PR_SET_MM_START_BRK
Set the address above which the program heap can be expanded with
.BR brk (2)
call.
the current program data segment.
In addition, the combined size of the resulting heap and
the size of the data segment can't exceed the
-.BR RLIMIT_DATA
+.B RLIMIT_DATA
resource limit (see
.BR setrlimit (2)).
.TP
-.BR PR_SET_MM_BRK
+.B PR_SET_MM_BRK
Set the current
.BR brk (2)
value.
The requirements for the address are the same as for the
-.BR PR_SET_MM_START_BRK
+.B PR_SET_MM_START_BRK
option.
.PP
The following options are available since Linux 3.5.
.\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7
.TP
-.BR PR_SET_MM_ARG_START
+.B PR_SET_MM_ARG_START
Set the address above which the program command line is placed.
.TP
-.BR PR_SET_MM_ARG_END
+.B PR_SET_MM_ARG_END
Set the address below which the program command line is placed.
.TP
-.BR PR_SET_MM_ENV_START
+.B PR_SET_MM_ENV_START
Set the address above which the program environment is placed.
.TP
-.BR PR_SET_MM_ENV_END
+.B PR_SET_MM_ENV_END
Set the address below which the program environment is placed.
.IP
The address passed with
.BR PR_SET_MM_ARG_END ,
.BR PR_SET_MM_ENV_START ,
and
-.BR PR_SET_MM_ENV_END
+.B PR_SET_MM_ENV_END
should belong to a process stack area.
Thus, the corresponding memory area must be readable, writable, and
(depending on the kernel configuration) have the
-.BR MAP_GROWSDOWN
+.B MAP_GROWSDOWN
attribute set (see
.BR mmap (2)).
.TP
-.BR PR_SET_MM_AUXV
+.B PR_SET_MM_AUXV
Set a new auxiliary vector.
The
.I arg3
.I arg4
is the size of the vector.
.TP
-.BR PR_SET_MM_EXE_FILE
+.B PR_SET_MM_EXE_FILE
.\" commit b32dfe377102ce668775f8b6b1461f7ad428f8b6
Supersede the
-.IR /proc/pid/exe
+.IR /proc/ pid /exe
symbolic link with a new one pointing to a new executable file
identified by the file descriptor provided in
.I arg3
executable memory areas, including those created by the kernel itself
(for example the kernel usually creates at least one executable
memory area for the ELF
-.IR \.text
+.I \.text
section).
.IP
In Linux 4.9 and earlier, the
.\" commit 3fb4afd9a504c2386b8435028d43283216bf588e
-.BR PR_SET_MM_EXE_FILE
+.B PR_SET_MM_EXE_FILE
operation can be performed only once in a process's lifetime;
attempting to perform the operation a second time results in the error
.BR EPERM .
The following options are available since Linux 3.18.
.\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e
.TP
-.BR PR_SET_MM_MAP
+.B PR_SET_MM_MAP
Provides one-shot access to all the addresses by passing in a
.I struct prctl_mm_map
(as defined in \fI<linux/prctl.h>\fP).
argument should provide the size of the struct.
.IP
This feature is available only if the kernel is built with the
-.BR CONFIG_CHECKPOINT_RESTORE
+.B CONFIG_CHECKPOINT_RESTORE
option enabled.
.TP
-.BR PR_SET_MM_MAP_SIZE
+.B PR_SET_MM_MAP_SIZE
Returns the size of the
.I struct prctl_mm_map
the kernel expects.
argument should be a pointer to an unsigned int.
.IP
This feature is available only if the kernel is built with the
-.BR CONFIG_CHECKPOINT_RESTORE
+.B CONFIG_CHECKPOINT_RESTORE
option enabled.
.RE
.\" prctl PR_MPX_ENABLE_MANAGEMENT
.IR arg3 ,
.IR arg4 ,
and
-.IR arg5
+.I arg5
.\" commit e9d1b4f3c60997fe197bf0243cb4a41a44387a88
arguments must be zero.
.IP
.IP
These calls fail if the CPU or kernel does not support MPX.
Kernel support for MPX is enabled via the
-.BR CONFIG_X86_INTEL_MPX
+.B CONFIG_X86_INTEL_MPX
configuration option.
You can check whether the CPU supports MPX by looking for the
.I mpx
During
.BR execve (2),
MPX management is reset to a state as if
-.BR PR_MPX_DISABLE_MANAGEMENT
+.B PR_MPX_DISABLE_MANAGEMENT
had been called.
.IP
For further information on Intel MPX, see the kernel source file
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the name of the calling thread,
using the value in the location pointed to by
-.IR "(char\ *) arg2" .
+.IR "(char\~*) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
including the terminating null byte.
and retrieved using
.BR pthread_getname_np (3).
The attribute is likewise accessible via
-.IR /proc/self/task/[tid]/comm
+.IR /proc/self/task/ tid /comm
(see
.BR proc (5)),
where
-.I [tid]
+.I tid
is the thread ID of the calling thread, as returned by
.BR gettid (2).
.\" prctl PR_GET_NAME
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the name of the calling thread,
in the buffer pointed to by
-.IR "(char\ *) arg2" .
+.IR "(char\~*) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated.
.\" prctl PR_SET_NO_NEW_PRIVS
attribute can be viewed via the
.I NoNewPrivs
field in the
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
file.
.IP
For more information, see the kernel source file
-.IR Documentation/userspace\-api/no_new_privs.rst
+.I Documentation/userspace\-api/no_new_privs.rst
.\" commit 40fde647ccb0ae8c11d256d271e24d385eed595b
(or
-.IR Documentation/prctl/no_new_privs.txt
+.I Documentation/prctl/no_new_privs.txt
before Linux 4.13).
See also
.BR seccomp (2).
this is the recommended way to completely wipe the existing keys
when establishing a clean execution context.
Note that there is no need to use
-.BR PR_PAC_RESET_KEYS
+.B PR_PAC_RESET_KEYS
in preparation for calling
.BR execve (2),
since
above) to which the caller is subsequently reparented.
If the parent thread and all ancestor subreapers have already terminated
by the time of the
-.BR PR_SET_PDEATHSIG
+.B PR_SET_PDEATHSIG
operation, then no parent-death signal is sent to the caller.
.IP
The parent-death signal is process-directed (see
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_PTRACER
.TP
.BR PR_SET_PTRACER " (since Linux 3.4)"
calling process.
.IP
For further information, see the kernel source file
-.IR Documentation/admin\-guide/LSM/Yama.rst
+.I Documentation/admin\-guide/LSM/Yama.rst
.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22
(or
-.IR Documentation/security/Yama.txt
+.I Documentation/security/Yama.txt
before Linux 4.13).
.\" prctl PR_SET_SECCOMP
.TP
signal to be sent to the process.
If the caller is in filter mode, and this system call is allowed by the
seccomp filters, it returns 2; otherwise, the process is killed with a
-.BR SIGKILL
+.B SIGKILL
signal.
.IP
This operation is available only
enabled.
.IP
Since Linux 3.8, the
-.IR Seccomp
+.I Seccomp
field of the
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
file provides a method of obtaining the same information,
without the risk that the process is killed; see
.BR proc (5).
the state of the speculation misfeature specified in
.IR arg2 .
Currently, the only permitted value for this argument is
-.BR PR_SPEC_STORE_BYPASS
+.B PR_SPEC_STORE_BYPASS
(otherwise the call fails with the error
.BR ENODEV ).
.IP
The return value uses bits 0-3 with the following meaning:
.RS
.TP
-.BR PR_SPEC_PRCTL
+.B PR_SPEC_PRCTL
Mitigation can be controlled per thread by
.BR PR_SET_SPECULATION_CTRL .
.TP
-.BR PR_SPEC_ENABLE
+.B PR_SPEC_ENABLE
The speculation feature is enabled, mitigation is disabled.
.TP
-.BR PR_SPEC_DISABLE
+.B PR_SPEC_DISABLE
The speculation feature is disabled, mitigation is enabled.
.TP
-.BR PR_SPEC_FORCE_DISABLE
+.B PR_SPEC_FORCE_DISABLE
Same as
.B PR_SPEC_DISABLE
but cannot be undone.
.BR ENODEV .
.IP
The
-.IR arg3
+.I arg3
argument is used to hand in the control value,
which is one of the following:
.RS
.TP
-.BR PR_SPEC_ENABLE
+.B PR_SPEC_ENABLE
The speculation feature is enabled, mitigation is disabled.
.TP
-.BR PR_SPEC_DISABLE
+.B PR_SPEC_DISABLE
The speculation feature is disabled, mitigation is enabled.
.TP
-.BR PR_SPEC_FORCE_DISABLE
+.B PR_SPEC_FORCE_DISABLE
Same as
.BR PR_SPEC_DISABLE ,
but cannot be undone.
.RE
.IP
Any unsupported value in
-.IR arg3
+.I arg3
will result in the call failing with the error
.BR ERANGE .
.IP
as specified by
.IR "(int) arg2" .
Arguments
-.IR arg3 ", " arg4 ", and " arg5
+.IR arg3 ,
+.IR arg4 ,
+and
+.I arg5
are ignored.
.IP
The bits of
will contain
.BR SIGSYS .
.IP *
-.IR si_call_addr
+.I si_call_addr
will show the address of the system call instruction.
.IP *
-.IR si_syscall
+.I si_syscall
and
-.IR si_arch
+.I si_arch
will indicate which system call was attempted.
.IP *
.I si_code
.IP
For more information,
see the kernel source file
-.IR Documentation/admin-guide/syscall-user-dispatch.rst
+.I Documentation/admin-guide/syscall-user-dispatch.rst
.\" prctl PR_SET_TAGGED_ADDR_CTRL
.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
.TP
.BR clone (2)
.B CLONE_CHILD_CLEARTID
flag, in the location pointed to by
-.IR "(int\ **)\ arg2" .
+.IR "(int\~**)\~arg2" .
This feature is available only if the kernel is built with the
-.BR CONFIG_CHECKPOINT_RESTORE
+.B CONFIG_CHECKPOINT_RESTORE
option enabled.
Note that since the
.BR prctl ()
is an unsigned long value, then maximum "current" value is ULONG_MAX and
the minimum "current" value is 1.
If the nanosecond value supplied in
-.IR arg2
+.I arg2
is greater than zero, then the "current" value is set to this value.
If
.I arg2
.BR PR_SET_TIMERSLACK .
The "default" value can't be changed.
The timer slack values of
-.IR init
+.I init
(PID 1), the ancestor of all processes,
are 50,000 nanoseconds (50 microseconds).
The timer slack value is inherited by a child created via
.IP
Since Linux 4.6, the "current" timer slack value of any process
can be examined and changed via the file
-.IR /proc/[pid]/timerslack_ns .
+.IR /proc/ pid /timerslack_ns .
See
.BR proc (5).
.\" prctl PR_GET_TIMERSLACK
Return the state of the flag determining whether the timestamp counter
can be read,
in the location pointed to by
-.IR "(int\ *) arg2" .
+.IR "(int\~*) arg2" .
.\" prctl PR_SET_UNALIGN
.TP
.B PR_SET_UNALIGN
of 4 and no corresponding named constant,
which instructs kernel to not fix up
unaligned accesses (it is analogous to providing the
-.BR UAC_NOFIX
+.B UAC_NOFIX
flag in
-.BR SSI_NVPAIRS
+.B SSI_NVPAIRS
operation of the
.BR setsysinfo ()
system call on Tru64).
.B PR_SET_UNALIGN
for information on versions and architectures.)
Return unaligned access control bits, in the location pointed to by
-.IR "(unsigned int\ *) arg2" .
+.IR "(unsigned int\~*) arg2" .
.SH RETURN VALUE
On success,
.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
.BR PR_GET_TIMING ,
.BR PR_GET_TIMERSLACK ,
and (if it returns)
-.BR PR_GET_SECCOMP
+.B PR_GET_SECCOMP
return the nonnegative values described above.
All other
.I option
.B EACCES
.I option
is
-.BR PR_SET_SECCOMP
+.B PR_SET_SECCOMP
and
.I arg2
is
.BR SECCOMP_MODE_FILTER ,
but the process does not have the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability or has not set the
-.IR no_new_privs
+.I no_new_privs
attribute (see the discussion of
-.BR PR_SET_NO_NEW_PRIVS
+.B PR_SET_NO_NEW_PRIVS
above).
.TP
.B EACCES
is
.BR PR_SET_MM_EXE_FILE ,
and this the second attempt to change the
-.I /proc/pid/exe
+.IR /proc/ pid /exe
symbolic link, which is prohibited.
.TP
.B EFAULT
.B EINVAL
.I option
is
-.BR PR_MCE_KILL
+.B PR_MCE_KILL
or
-.BR PR_MCE_KILL_GET
+.B PR_MCE_KILL_GET
or
.BR PR_SET_MM ,
and unused
.B EINVAL
.I option
is
-.BR PR_SET_SECCOMP
+.B PR_SET_SECCOMP
or
.BR PR_GET_SECCOMP ,
and the kernel was not configured with
.IP *
.I arg2
is
-.BR PR_SET_MM_START_BRK
+.B PR_SET_MM_START_BRK
or
.BR PR_SET_MM_BRK ,
and
.B EINVAL
.I option
is
-.BR PR_SET_PTRACER
+.B PR_SET_PTRACER
and
.I arg2
is not 0,
.B EINVAL
.I option
is
-.BR PR_SET_DUMPABLE
+.B PR_SET_DUMPABLE
and
.I arg2
is neither
.B EINVAL
.I option
is
-.BR PR_SET_TIMING
+.B PR_SET_TIMING
and
.I arg2
is not
.B EINVAL
.I option
is
-.BR PR_SET_NO_NEW_PRIVS
+.B PR_SET_NO_NEW_PRIVS
and
.I arg2
is not equal to 1
.IR arg3 ,
.IR arg4 ,
or
-.IR arg5
+.I arg5
is nonzero.
.TP
.B EINVAL
.I option
is
-.BR PR_GET_NO_NEW_PRIVS
+.B PR_GET_NO_NEW_PRIVS
and
.IR arg2 ,
.IR arg3 ,
.IR arg4 ,
or
-.IR arg5
+.I arg5
is nonzero.
.TP
.B EINVAL
.I option
is
-.BR PR_SET_THP_DISABLE
+.B PR_SET_THP_DISABLE
and
.IR arg3 ,
.IR arg4 ,
or
-.IR arg5
+.I arg5
is nonzero.
.TP
.B EINVAL
.I option
is
-.BR PR_GET_THP_DISABLE
+.B PR_GET_THP_DISABLE
and
.IR arg2 ,
.IR arg3 ,
.IR arg4 ,
or
-.IR arg5
+.I arg5
is nonzero.
.TP
.B EINVAL
.BR PR_CAP_AMBIENT_CLEAR_ALL ,
.IR arg3 )
is nonzero; or
-.IR arg2
+.I arg2
has an invalid value;
or
-.IR arg2
+.I arg2
is
.BR PR_CAP_AMBIENT_LOWER ,
.BR PR_CAP_AMBIENT_RAISE ,
or
-.BR PR_CAP_AMBIENT_IS_SET
+.B PR_CAP_AMBIENT_IS_SET
and
-.IR arg3
+.I arg3
does not specify a valid capability.
.TP
.B EINVAL
.I option
was
-.BR PR_GET_SPECULATION_CTRL
+.B PR_GET_SPECULATION_CTRL
or
-.BR PR_SET_SPECULATION_CTRL
+.B PR_SET_SPECULATION_CTRL
and unused arguments to
.BR prctl ()
are not 0.
.B EINVAL
.I option
is
-.BR PR_SET_TAGGED_ADDR_CTRL
+.B PR_SET_TAGGED_ADDR_CTRL
and the arguments are invalid or unsupported.
See the description of
.B PR_SET_TAGGED_ADDR_CTRL
.B EINVAL
.I option
is
-.BR PR_GET_TAGGED_ADDR_CTRL
+.B PR_GET_TAGGED_ADDR_CTRL
and the arguments are invalid or unsupported.
See the description of
.B PR_GET_TAGGED_ADDR_CTRL
.B ENODEV
.I option
was
-.BR PR_SET_SPECULATION_CTRL
+.B PR_SET_SPECULATION_CTRL
the kernel or CPU does not support the requested speculation misfeature.
.TP
.B ENXIO
.I option
was
-.BR PR_MPX_ENABLE_MANAGEMENT
+.B PR_MPX_ENABLE_MANAGEMENT
or
-.BR PR_MPX_DISABLE_MANAGEMENT
+.B PR_MPX_DISABLE_MANAGEMENT
and the kernel or the CPU does not support MPX management.
Check that the kernel and processor have MPX support.
.TP
.B ENXIO
.I option
was
-.BR PR_SET_SPECULATION_CTRL
+.B PR_SET_SPECULATION_CTRL
implies that the control of the selected speculation misfeature is not possible.
See
-.BR PR_GET_SPECULATION_CTRL
+.B PR_GET_SPECULATION_CTRL
for the bit fields to determine which option is available.
.TP
.B EOPNOTSUPP
.B EPERM
.I option
is
-.BR PR_SET_SPECULATION_CTRL
+.B PR_SET_SPECULATION_CTRL
wherein the speculation was disabled with
.B PR_SPEC_FORCE_DISABLE
and caller tried to enable it again.
capability.
.TP
.B EPERM
-.IR option
+.I option
is
-.BR PR_CAP_AMBIENT
+.B PR_CAP_AMBIENT
and
-.IR arg2
+.I arg2
is
.BR PR_CAP_AMBIENT_RAISE ,
but either the capability specified in
-.IR arg3
+.I arg3
is not present in the process's permitted and inheritable capability sets,
or the
.B PR_CAP_AMBIENT_LOWER
.B ERANGE
.I option
was
-.BR PR_SET_SPECULATION_CTRL
+.B PR_SET_SPECULATION_CTRL
and
-.IR arg3
+.I arg3
is not
.BR PR_SPEC_ENABLE ,
.BR PR_SPEC_DISABLE ,
.BR syscall (2).
.SH BUGS
POSIX requires that opening a file with the
-.BR O_APPEND
+.B O_APPEND
flag should have no effect on the location at which
.BR pwrite ()
writes data.
points to an array of
.I iovec
structures, defined in
-.IR <sys/uio.h>
+.I <sys/uio.h>
as:
.PP
.in +4n
.SH DESCRIPTION
These system calls transfer data between the address space
of the calling process ("the local process") and the process identified by
-.IR pid
+.I pid
("the remote process").
The data moves directly between the address spaces of the two processes,
without passing through kernel space.
.BR process_vm_readv ()
system call transfers data from the remote process to the local process.
The data to be transferred is identified by
-.IR remote_iov
+.I remote_iov
and
.IR riovcnt :
-.IR remote_iov
+.I remote_iov
is a pointer to an array describing address ranges in the process
.IR pid ,
and
-.IR riovcnt
+.I riovcnt
specifies the number of elements in
.IR remote_iov .
The data is transferred to the locations specified by
-.IR local_iov
+.I local_iov
and
.IR liovcnt :
-.IR local_iov
+.I local_iov
is a pointer to an array describing address ranges in the calling process,
and
-.IR liovcnt
+.I liovcnt
specifies the number of elements in
.IR local_iov .
.PP
.IR local_iov ,
.IR riovcnt ,
and
-.IR remote_iov
+.I remote_iov
have the same meaning as for
.BR process_vm_readv ().
.PP
arguments point to an array of
.I iovec
structures, defined in
-.IR <sys/uio.h>
+.I <sys/uio.h>
as:
.PP
.in +4n
and
.I riovcnt
arguments must be less than or equal to
-.BR IOV_MAX
+.B IOV_MAX
(defined in
.I <limits.h>
or accessible via the call
.\" as is done for readv()/writev()
.PP
The count arguments and
-.IR local_iov
+.I local_iov
are checked before doing any transfers.
If the counts are too big, or
.I local_iov
Ptrace commands are always sent to
a specific tracee using a call of the form
.PP
- ptrace(PTRACE_foo, pid, ...)
+.in +4n
+.EX
+ptrace(PTRACE_foo, pid, ...)
+.EE
+.in
.PP
where
.I pid
.RI ( pid ,
.IR addr ,
and
-.IR data
+.I data
are ignored.)
.IP
The
.I addr
in the tracee's memory.
As for
-.BR PTRACE_PEEKTEXT
+.B PTRACE_PEEKTEXT
and
.BR PTRACE_PEEKDATA ,
these two requests are currently equivalent.
.I siginfo
structures,
the
-.IR si_code
+.I si_code
field includes information
.RB ( __SI_CHLD ,
.BR __SI_FAULT ,
The
.I addr
argument contains the size of the buffer pointed to by
-.IR data
+.I data
(i.e.,
.IR sizeof(sigset_t) ).
.TP
The
.I addr
argument contains the size of the buffer pointed to by
-.IR data
+.I data
(i.e.,
.IR sizeof(sigset_t) ).
.TP
.IR data .
.RI ( addr
is ignored.)
-.IR data
+.I data
is interpreted as a bit mask of options,
which are specified by the following flags:
.RS
.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
Stop the tracee when a
.BR seccomp (2)
-.BR SECCOMP_RET_TRACE
+.B SECCOMP_RET_TRACE
rule is triggered.
A
.BR waitpid (2)
.fi
.IP
While this triggers a
-.BR PTRACE_EVENT
+.B PTRACE_EVENT
stop, it is similar to a syscall-enter-stop.
For details, see the note on
.B PTRACE_EVENT_SECCOMP
below.
The seccomp event message data (from the
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
portion of the seccomp filter rule) can be retrieved with
.BR PTRACE_GETEVENTMSG .
.TP
let the tracee install the filters,
and then clear this flag when the filters should be resumed.
Setting this option requires that the tracer have the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability,
not have any seccomp protections installed, and not have
-.BR PTRACE_O_SUSPEND_SECCOMP
+.B PTRACE_O_SUSPEND_SECCOMP
set on itself.
.RE
.TP
this is the
.BR seccomp (2)
filter's
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
associated with the triggered rule.
.RI ( addr
is ignored.)
.IP
.I This operation is deprecated; do not use it!
Instead, send a
-.BR SIGKILL
+.B SIGKILL
directly using
.BR kill (2)
or
are ignored.)
.IP
Permission to perform a
-.BR PTRACE_ATTACH
+.B PTRACE_ATTACH
is governed by a ptrace access mode
.B PTRACE_MODE_ATTACH_REALCREDS
check; see below.
contains a bit mask of ptrace options to activate immediately.
.IP
Permission to perform a
-.BR PTRACE_SEIZE
+.B PTRACE_SEIZE
is governed by a ptrace access mode
.B PTRACE_MODE_ATTACH_REALCREDS
check; see below.
.IP
.I data
is either a pointer to a
-.IR "struct sock_filter"
+.I struct sock_filter
array that is large enough to store the BPF program,
or NULL if the program is not to be stored.
.IP
If
.I data
was NULL, then this return value can be used to correctly size the
-.IR "struct sock_filter"
+.I struct sock_filter
array passed in a subsequent call.
.IP
This operation fails with the error
It reads the TLS entry in the GDT whose index is given in
.IR addr ,
placing a copy of the entry into the
-.IR "struct user_desc"
+.I struct user_desc
pointed to by
.IR data .
(By contrast with
the
.I entry_number
of the
-.IR "struct user_desc"
+.I struct user_desc
is ignored.)
.TP
.BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
It sets the TLS entry in the GDT whose index is given in
.IR addr ,
assigning it the data supplied in the
-.IR "struct user_desc"
+.I struct user_desc
pointed to by
.IR data .
(By contrast with
the
.I entry_number
of the
-.IR "struct user_desc"
+.I struct user_desc
is ignored; in other words,
this ptrace operation can't be used to allocate a free TLS entry.)
.TP
fields are defined for all kinds of ptrace system call stops.
The rest of the structure is a union; one should read only those fields
that are meaningful for the kind of system call stop specified by the
-.IR op
+.I op
field.
.IP
The
.I op
field has one of the following values (defined in
-.IR <linux/ptrace.h>)
+.IR <linux/ptrace.h> )
indicating what type of stop occurred and
which part of the union is filled:
.RS
.TP
-.BR PTRACE_SYSCALL_INFO_ENTRY
+.B PTRACE_SYSCALL_INFO_ENTRY
The
.I entry
component of the union contains information relating to a
system call entry stop.
.TP
-.BR PTRACE_SYSCALL_INFO_EXIT
+.B PTRACE_SYSCALL_INFO_EXIT
The
.I exit
component of the union contains information relating to a
system call exit stop.
.TP
-.BR PTRACE_SYSCALL_INFO_SECCOMP
+.B PTRACE_SYSCALL_INFO_SECCOMP
The
.I seccomp
component of the union contains information relating to a
.B PTRACE_EVENT_SECCOMP
stop.
.TP
-.BR PTRACE_SYSCALL_INFO_NONE
+.B PTRACE_SYSCALL_INFO_NONE
No component of the union contains relevant information.
.RE
.\"
is nevertheless considered to be running, even if the tracee is blocked
for a long time.
The state of the tracee after
-.BR PTRACE_LISTEN
+.B PTRACE_LISTEN
is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
won't work on it, and it will deliver
.BR waitpid (2)
(or one of the other "wait" system calls).
Most of this manual page assumes that the tracer waits with:
.PP
- pid = waitpid(pid_or_minus_1, &status, __WALL);
+.in +4n
+.EX
+pid = waitpid(pid_or_minus_1, &status, __WALL);
+.EE
+.in
.PP
Ptrace-stopped tracees are reported as returns with
.I pid
After signal-delivery-stop is observed by the tracer,
the tracer should restart the tracee with the call
.PP
- ptrace(PTRACE_restart, pid, 0, sig)
+.in +4n
+.EX
+ptrace(PTRACE_restart, pid, 0, sig)
+.EE
+.in
.PP
where
.B PTRACE_restart
One typical scenario is that the tracer observes group-stop,
mistakes it for signal-delivery-stop, restarts the tracee with
.PP
- ptrace(PTRACE_restart, pid, 0, stopsig)
+.in +4n
+.EX
+ptrace(PTRACE_restart, pid, 0, stopsig)
+.EE
+.in
.PP
with the intention of injecting
.IR stopsig ,
This side effect happens before signal-delivery-stop.
The tracer can't suppress this side effect (it can
only suppress signal injection, which only causes the
-.BR SIGCONT
+.B SIGCONT
handler to not be executed in the tracee, if such a handler is installed).
In fact, waking up from group-stop may be followed by
signal-delivery-stop for signal(s)
The same result is returned by some other classes of ptrace-stops,
therefore the recommended practice is to perform the call
.PP
- ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
+.in +4n
+.EX
+ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
+.EE
+.in
.PP
The call can be avoided if the signal is not
.BR SIGSTOP ,
and
.I WSTOPSIG(status)
returns
-.BR SIGTRAP
+.B SIGTRAP
(or for
.BR PTRACE_EVENT_STOP ,
returns the stopping signal if tracee is in a group-stop).
.I status>>8
will be
.PP
- ((PTRACE_EVENT_foo<<8) | SIGTRAP).
+.in +4n
+.EX
+((PTRACE_EVENT_foo<<8) | SIGTRAP).
+.EE
+.in
.PP
The following events exist:
.TP
For all four stops described above,
the stop occurs in the parent (i.e., the tracee),
not in the newly created thread.
-.BR PTRACE_GETEVENTMSG
+.B PTRACE_GETEVENTMSG
can be used to retrieve the new thread's ID.
.TP
.B PTRACE_EVENT_EXEC
Stop before return from
.BR execve (2).
Since Linux 3.0,
-.BR PTRACE_GETEVENTMSG
+.B PTRACE_GETEVENTMSG
returns the former thread ID.
.TP
.B PTRACE_EVENT_EXIT
Stop triggered by a
.BR seccomp (2)
rule on tracee syscall entry when
-.BR PTRACE_O_TRACESECCOMP
+.B PTRACE_O_TRACESECCOMP
has been set by the tracer.
The seccomp event message data (from the
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
portion of the seccomp filter rule) can be retrieved with
.BR PTRACE_GETEVENTMSG .
The semantics of this stop are described in
.IR "(event<<8)\ |\ SIGTRAP" .
.SS Syscall-stops
If the tracee was restarted by
-.BR PTRACE_SYSCALL
+.B PTRACE_SYSCALL
or
.BR PTRACE_SYSEMU ,
the tracee enters
.BR PTRACE_SYSEMU ),
no syscall-exit-stop occurs.
Note that all mentions
-.BR PTRACE_SYSEMU
+.B PTRACE_SYSEMU
apply equally to
.BR PTRACE_SYSEMU_SINGLESTEP .
.PP
Syscall-stops can be distinguished from signal-delivery-stop with
.B SIGTRAP
by querying
-.BR PTRACE_GETSIGINFO
+.B PTRACE_GETSIGINFO
for the following cases:
.TP
.IR si_code " <= 0"
.\"
.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
The behavior of
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
stops and their interaction with other kinds
of ptrace stops has changed between kernel versions.
This documents the behavior
The behavior in later kernel versions is documented in the next section.
.PP
A
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
stop occurs whenever a
-.BR SECCOMP_RET_TRACE
+.B SECCOMP_RET_TRACE
rule is triggered.
This is independent of which methods was used to restart the system call.
Notably, seccomp still runs even if the tracee was restarted using
-.BR PTRACE_SYSEMU
+.B PTRACE_SYSEMU
and this system call is unconditionally skipped.
.PP
Restarts from this stop will behave as if the stop had occurred right
before the system call in question.
In particular, both
-.BR PTRACE_SYSCALL
+.B PTRACE_SYSCALL
and
-.BR PTRACE_SYSEMU
+.B PTRACE_SYSEMU
will normally cause a subsequent syscall-entry-stop.
However, if after the
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
the system call number is negative,
both the syscall-entry-stop and the system call itself will be skipped.
This means that if the system call number is negative after a
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
and the tracee is restarted using
.BR PTRACE_SYSCALL ,
the next observed stop will be a syscall-exit-stop,
Starting with Linux 4.8,
.\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
the
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
stop was reordered to occur between syscall-entry-stop and
syscall-exit-stop.
Note that seccomp no longer runs (and no
.B PTRACE_EVENT_SECCOMP
stop functions comparably
to a syscall-entry-stop (i.e., continuations using
-.BR PTRACE_SYSCALL
+.B PTRACE_SYSCALL
will cause syscall-exit-stops,
the system call number may be changed and any other modified registers
are visible to the to-be-executed system call as well).
but need not have been a preceding syscall-entry-stop.
.PP
After a
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
stop, seccomp will be rerun, with a
-.BR SECCOMP_RET_TRACE
+.B SECCOMP_RET_TRACE
rule now functioning the same as a
.BR SECCOMP_RET_ALLOW .
Specifically, this means that if registers are not modified during the
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
stop, the system call will then be allowed.
.\"
.SS PTRACE_SINGLESTEP stops
.PP
The call
.PP
- ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
+.in +4n
+.EX
+ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
+.EE
+.in
.PP
affects one tracee.
The tracee's current flags are replaced.
.BR PTRACE_O_TRACEFORK ,
.BR PTRACE_O_TRACEVFORK ,
or
-.BR PTRACE_O_TRACECLONE
+.B PTRACE_O_TRACECLONE
options.
.PP
Another group of commands makes the ptrace-stopped tracee run.
They have the form:
.PP
- ptrace(cmd, pid, 0, sig);
+.in +4n
+.EX
+ptrace(cmd, pid, 0, sig);
+.EE
+.in
.PP
where
.I cmd
.SS Attaching and detaching
A thread can be attached to the tracer using the call
.PP
- ptrace(PTRACE_ATTACH, pid, 0, 0);
+.in +4n
+.EX
+ptrace(PTRACE_ATTACH, pid, 0, 0);
+.EE
+.in
.PP
or
.PP
- ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
+.in +4n
+.EX
+ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
+.EE
+.in
.PP
.B PTRACE_ATTACH
sends
.PP
The request
.PP
- ptrace(PTRACE_TRACEME, 0, 0, 0);
+.in +4n
+.EX
+ptrace(PTRACE_TRACEME, 0, 0, 0);
+.EE
+.in
.PP
turns the calling thread into a tracee.
The thread continues to run (doesn't enter ptrace-stop).
.B PTRACE_TRACEME
with
.PP
- raise(SIGSTOP);
+.in +4n
+.EX
+raise(SIGSTOP);
+.EE
+.in
.PP
and allow the parent (which is our tracer now) to observe our
signal-delivery-stop.
.BR PTRACE_O_TRACEFORK ,
.BR PTRACE_O_TRACEVFORK ,
or
-.BR PTRACE_O_TRACECLONE
+.B PTRACE_O_TRACECLONE
options are in effect, then children created by, respectively,
.BR vfork (2)
or
.PP
Detaching of the tracee is performed by:
.PP
- ptrace(PTRACE_DETACH, pid, 0, sig);
+.in +4n
+.EX
+ptrace(PTRACE_DETACH, pid, 0, sig);
+.EE
+.in
.PP
.B PTRACE_DETACH
is a restarting operation;
All other threads stop in
.B PTRACE_EVENT_EXIT
stop, if the
-.BR PTRACE_O_TRACEEXIT
+.B PTRACE_O_TRACEEXIT
option was turned on.
Then all other threads except the thread group leader report
death as if they exited via
Then a
.B PTRACE_EVENT_EXEC
stop happens, if the
-.BR PTRACE_O_TRACEEXEC
+.B PTRACE_O_TRACEEXEC
option was turned on.
.IP *
If the thread group leader has reported its
.B PTRACE_O_TRACEEXEC
option is the recommended tool for dealing with this situation.
First, it enables
-.BR PTRACE_EVENT_EXEC
+.B PTRACE_EVENT_EXEC
stop,
which occurs before
.BR execve (2)
and retain only one data structure\(emone which
describes the single still running tracee, with
.PP
- thread ID == thread group ID == process ID.
+.in +4n
+.EX
+thread ID == thread group ID == process ID.
+.EE
+.in
.PP
Example: two threads call
.BR execve (2)
.\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
two access mode levels are distinguished:
.TP
-.BR PTRACE_MODE_READ
+.B PTRACE_MODE_READ
For "read" operations or other operations that are less dangerous,
such as:
.BR get_robust_list (2);
.BR kcmp (2);
reading
-.IR /proc/[pid]/auxv ,
-.IR /proc/[pid]/environ ,
+.IR /proc/ pid /auxv ,
+.IR /proc/ pid /environ ,
or
-.IR /proc/[pid]/stat ;
+.IR /proc/ pid /stat ;
or
.BR readlink (2)
of a
-.IR /proc/[pid]/ns/*
+.IR /proc/ pid /ns/*
file.
.TP
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
For "write" operations, or other operations that are more dangerous,
such as: ptrace attaching
.RB ( PTRACE_ATTACH )
Don't audit this access mode check.
This modifier is employed for ptrace access mode checks
(such as checks when reading
-.IR /proc/[pid]/stat )
+.IR /proc/ pid /stat )
that merely cause the output to be filtered or sanitized,
rather than causing an error to be returned to the caller.
In these cases, accessing the file is not a security violation and
such an audit record for the particular access check.
.PP
Note that all of the
-.BR PTRACE_MODE_*
+.B PTRACE_MODE_*
constants described in this subsection are kernel-internal,
and not visible to user space.
The constant names are mentioned here in order to label the various kinds of
the calling process is allowed to perform the corresponding action
on the target process.
(In the case of opening
-.IR /proc/[pid]
+.IR /proc/ pid
files, the "calling process" is the one opening the file,
and the process with the corresponding PID is the "target process".)
The algorithm is as follows:
so use the caller's real UID and GID for the checks in the next step.
(Most APIs that check the caller's UID and GID use the effective IDs.
For historical reasons, the
-.BR PTRACE_MODE_REALCREDS
+.B PTRACE_MODE_REALCREDS
check uses the real IDs instead.)
.IP 3.
Deny access if
.IP \(bu 2
The real, effective, and saved-set user IDs of the target
match the caller's user ID,
-.IR and
+.I and
the real, effective, and saved-set group IDs of the target
match the caller's group ID.
.IP \(bu
Deny access if the target process "dumpable" attribute has a value other than 1
.RB ( SUID_DUMP_USER ;
see the discussion of
-.BR PR_SET_DUMPABLE
+.B PR_SET_DUMPABLE
in
.BR prctl (2)),
and the caller does not have the
-.BR CAP_SYS_PTRACE
+.B CAP_SYS_PTRACE
capability in the user namespace of the target process.
.IP 5.
The kernel LSM
More precisely, the Yama LSM limits two types of operations:
.IP * 3
Any operation that performs a ptrace access mode
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
check\(emfor example,
.BR ptrace ()
.BR PTRACE_ATTACH .
A process that has the
.B CAP_SYS_PTRACE
capability can update the
-.IR /proc/sys/kernel/yama/ptrace_scope
+.I /proc/sys/kernel/yama/ptrace_scope
file with one of the following values:
.TP
0 ("classic ptrace permissions")
No additional restrictions on operations that perform
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
checks (beyond those imposed by the commoncap and other LSMs).
.IP
The use of
-.BR PTRACE_TRACEME
+.B PTRACE_TRACEME
is unchanged.
.TP
1 ("restricted ptrace") [default value]
When performing an operation that requires a
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
check, the calling process must either have the
.B CAP_SYS_PTRACE
capability in the user namespace of the target process or
.BR prctl (2)
.B PR_SET_PTRACER
operation to declare an additional PID that is allowed to perform
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
operations on the target.
See the kernel source file
-.IR Documentation/admin\-guide/LSM/Yama.rst
+.I Documentation/admin\-guide/LSM/Yama.rst
.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22
(or
-.IR Documentation/security/Yama.txt
+.I Documentation/security/Yama.txt
before Linux 4.13)
for further details.
.IP
The use of
-.BR PTRACE_TRACEME
+.B PTRACE_TRACEME
is unchanged.
.TP
2 ("admin-only attach")
Only processes with the
.B CAP_SYS_PTRACE
capability in the user namespace of the target process may perform
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
operations or trace children that employ
.BR PTRACE_TRACEME .
.TP
3 ("no attach")
No process may perform
-.BR PTRACE_MODE_ATTACH
+.B PTRACE_MODE_ATTACH
operations or trace children that employ
.BR PTRACE_TRACEME .
.IP
.BR PTRACE_PEEKTEXT ,
.BR PTRACE_PEEKDATA ,
and
-.BR PTRACE_PEEKUSER
+.B PTRACE_PEEKUSER
requests have a different API: they store the result
at the address specified by the
.I data
.BR epoll_wait (2)
again.
(Programs which do not expect such "stray"
-.BR EINTR
+.B EINTR
errors may behave in an unintended way upon an
.BR strace (1)
attach.)
group ID specified in
.IR id .
To initialize the
-.IR cmd
+.I cmd
argument, use the
-.IR "QCMD(subcmd, type)"
+.I QCMD(subcmd, type)
macro.
The
.I type
Currently, there are three supported quota formats:
.RS
.TP 13
-.BR QFMT_VFS_OLD
+.B QFMT_VFS_OLD
The original quota format.
.TP
-.BR QFMT_VFS_V0
+.B QFMT_VFS_V0
The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs
and quota limits up to 2^42 bytes and 2^32 inodes.
.TP
-.BR QFMT_VFS_V1
+.B QFMT_VFS_V1
A quota format that can handle 32-bit UIDs and GIDs
and quota limits of 2^63 - 1 bytes and 2^63 - 1 inodes.
.RE
.IP
The
-.IR addr
+.I addr
argument points to the pathname of a file containing the quotas for
the filesystem.
The quota file must exist; it is normally created with the
argument is a pointer to a
.I dqblk
structure defined in
-.IR <sys/quota.h>
+.I <sys/quota.h>
as follows:
.IP
.in +4n
This operation is the same as
.BR Q_GETQUOTA ,
but it returns quota information for the next ID greater than or equal to
-.IR id
+.I id
that has a quota set.
.IP
The
.I dqinfo
structure.
This structure is defined in
-.IR <sys/quota.h>
+.I <sys/quota.h>
as follows:
.IP
.in +4n
structure pointed by
.IR addr )
quota information for the next ID greater than or equal to
-.IR id
+.I id
that has a quota set.
Note that since
.I fs_disk_quota
or
.BR Q_XGETNEXTQUOTA ,
but there is no ID greater than or equal to
-.IR id
+.I id
that has an active quota.
.SH NOTES
Instead of
See
.BR open (2)
for further details on the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag.
.TP
.BR EAGAIN " or " EWOULDBLOCK
.I pathname
can be an empty string,
in which case the call operates on the symbolic link referred to by
-.IR dirfd
+.I dirfd
(which should have been obtained using
.BR open (2)
with the
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SH EXAMPLES
The following program allocates the buffer needed by
dynamically from the information provided by
.BR lstat (2),
falling back to a buffer of size
-.BR PATH_MAX
+.B PATH_MAX
in cases where
.BR lstat (2)
reports a size of zero.
Allows block-based filesystems to use polling of the device,
which provides lower latency, but may use additional resources.
(Currently, this feature is usable only on a file descriptor opened using the
-.BR O_DIRECT
+.B O_DIRECT
flag.)
.TP
.BR RWF_SYNC " (since Linux 4.7)"
the backing storage or wait for a lock.
If some data was successfully read, it will return the number of bytes read.
If no bytes were read, it will return \-1 and set
-.IR errno
+.I errno
to
-.BR EAGAIN
+.B EAGAIN
(but see
.BR BUGS ).
Currently, this flag is meaningful only for
the glibc wrapper functions always just directly invoke the system calls.
.SH BUGS
Linux 5.9 and 5.10 have a bug where
-.BR preadv2()
+.BR preadv2 ()
with the
-.BR RWF_NOWAIT
+.B RWF_NOWAIT
flag may return 0 even when not at end of file.
.\" See
.\" <https://lore.kernel.org/linux-fsdevel/fea8b16d-5a69-40f9-b123-e84dcd6e8f2e@www.fastmail.com/T/#u>
.BR sync (2),
data will be lost.
.TP
-.BR LINUX_REBOOT_CMD_KEXEC
+.B LINUX_REBOOT_CMD_KEXEC
.RB ( RB_KEXEC ,
0x45584543, since Linux 2.6.13).
Execute a kernel that has been loaded earlier with
.BR sync (2),
data will be lost.
.TP
-.BR LINUX_REBOOT_CMD_SW_SUSPEND
+.B LINUX_REBOOT_CMD_SW_SUSPEND
.RB ( RB_SW_SUSPEND ,
0xd000fce1; since Linux 2.5.18).
The system is suspended (hibernated) to disk.
(but see NOTES).
Also, the following call
.PP
- recv(sockfd, buf, len, flags);
+.in +4n
+.EX
+recv(sockfd, buf, len, flags);
+.EE
+.in
.PP
is equivalent to
.PP
- recvfrom(sockfd, buf, len, flags, NULL, NULL);
+.in +4n
+.EX
+recvfrom(sockfd, buf, len, flags, NULL, NULL);
+.EE
+.in
.PP
All three calls return the length of the message on successful
completion.
.BR connect (2)).
It is equivalent to the call:
.PP
- recvfrom(fd, buf, len, flags, NULL, 0);
+.in +4n
+.EX
+recvfrom(fd, buf, len, flags, NULL, 0);
+.EE
+.in
.\"
.SS recvmsg()
The
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.BI "#include <sys/socket.h>"
+.B #include <sys/socket.h>
.PP
.BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \
", unsigned int " vlen ","
On return from
.BR recvmmsg (),
successive elements of
-.IR msgvec
+.I msgvec
are updated to contain information about each received message:
.I msg_len
contains the size of the received message;
.TP
.B RENAME_EXCHANGE
Atomically exchange
-.IR oldpath
+.I oldpath
and
.IR newpath .
Both pathnames must exist
.TP
.B RENAME_NOREPLACE
Don't overwrite
-.IR newpath
+.I newpath
of the rename.
Return an error if
-.IR newpath
+.I newpath
already exists.
.IP
.B RENAME_NOREPLACE
.IP
.B RENAME_WHITEOUT
requires the same privileges as creating a device node (i.e., the
-.BR CAP_MKNOD
+.B CAP_MKNOD
capability).
.IP
.B RENAME_WHITEOUT
contains
.B RENAME_EXCHANGE
and
-.IR newpath
+.I newpath
does not exist.
.TP
.B EPERM
.I newpath
are relative pathnames,
glibc constructs pathnames based on the symbolic links in
-.IR /proc/self/fd
+.I /proc/self/fd
that correspond to the
.I olddirfd
and
-.IR newdirfd
+.I newdirfd
arguments.
.SH BUGS
On NFS filesystems, you can not assume that if the operation
it tries the following keyrings,
beginning with the keyring set via the
.BR keyctl (2)
-.BR KEYCTL_SET_REQKEY_KEYRING
+.B KEYCTL_SET_REQKEY_KEYRING
operation and continuing in the order shown below
until it finds the first keyring that exists:
.IP \(bu 3
.PP
If the
.BR keyctl (2)
-.BR KEYCTL_SET_REQKEY_KEYRING
+.B KEYCTL_SET_REQKEY_KEYRING
operation specifies
-.BR KEY_REQKEY_DEFL_DEFAULT
+.B KEY_REQKEY_DEFL_DEFAULT
(or no
-.BR KEYCTL_SET_REQKEY_KEYRING
+.B KEYCTL_SET_REQKEY_KEYRING
operation is performed),
then the kernel looks for a keyring
starting from the beginning of the list.
.\"
.SS Requesting user-space instantiation of a key
If the kernel cannot find a key matching
-.IR type
+.I type
and
.IR description ,
and
.I callout
is not NULL, then the kernel attempts to invoke a user-space
program to instantiate a key with the given
-.IR type
+.I type
and
.IR description .
In this case, the following steps are performed:
.IR view ,
.IR read ,
and
-.IR search
+.I search
permissions to the key possessor as well as
-.IR view
+.I view
permission for the key user.
.IP *
The description (name) of the key is the hexadecimal
.IP
.IR Note :
each of the command-line arguments that is a key ID is encoded in
-.IR decimal
+.I decimal
(unlike the key IDs shown in
.IR /proc/keys ,
which are shown as hexadecimal values).
.IP * 3
Assumes the authority to instantiate the key U using the
.BR keyctl (2)
-.BR KEYCTL_ASSUME_AUTHORITY
+.B KEYCTL_ASSUME_AUTHORITY
operation (typically via the
.BR keyctl_assume_authority (3)
function).
Obtains the callout data from the payload of the authorization key V
(using the
.BR keyctl (2)
-.BR KEYCTL_READ
+.B KEYCTL_READ
operation (or, more commonly, the
.BR keyctl_read (3)
function) with a key ID value of
.\" * A key added to that ring is then owned by the requester
Instantiation is performed using the
.BR keyctl (2)
-.BR KEYCTL_INSTANTIATE
+.B KEYCTL_INSTANTIATE
operation (or, more commonly, the
.BR keyctl_instantiate (3)
function).
.RE
.PP
If these steps are unsuccessful, then an
-.BR ENOKEY
+.B ENOKEY
error will be returned to the caller of
.BR request_key ()
and a temporary, negatively instantiated key will be installed
.IR type ,
.IR description ,
or
-.IR callout_info
+.I callout_info
points outside the process's accessible address space.
.TP
.B EINTR
.IR type ,
.IR description ,
and
-.IR callout_info
+.I callout_info
arguments for the system call are taken from the values
supplied in the command-line arguments.
The call specifies the session keyring as the target keyring.
specifiers.
.PP
Then we run the program and check the contents of
-.IR /proc/keys
+.I /proc/keys
to verify that the requested key has been instantiated:
.PP
.in +4n
.BR request\-key (8)
.PP
The kernel source files
-.IR Documentation/security/keys/core.rst
+.I Documentation/security/keys/core.rst
and
-.IR Documentation/keys/request\-key.rst
+.I Documentation/keys/request\-key.rst
(or, before Linux 4.13, in the files
.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
-.IR Documentation/security/keys.txt
+.I Documentation/security/keys.txt
and
.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
.IR Documentation/security/keys\-request\-key.txt ).
.BR restart_syscall ()
system call is used to restart certain system calls
after a process that was stopped by a signal (e.g.,
-.BR SIGSTOP
+.B SIGSTOP
or
.BR SIGTSTP )
is later resumed after receiving a
-.BR SIGCONT
+.B SIGCONT
signal.
This system call is designed only for internal use by the kernel.
.PP
and
.BR futex (2),
when employed with the
-.BR FUTEX_WAIT
+.B FUTEX_WAIT
(since Linux 2.6.22)
and
-.BR FUTEX_WAIT_BITSET
+.B FUTEX_WAIT_BITSET
(since Linux 2.6.31)
operations.
.\" These system calls correspond to the special internal errno value
.IR sig ,
.IR tgid ,
or
-.IR tid
+.I tid
was invalid.
.TP
.B EPERM
is 0.
.PP
On error, \-1 is returned, and
-.IR errno
+.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EFAULT
.I command
was
-.BR GS_SET_BC_CB
+.B GS_SET_BC_CB
and the copying of the guarded storage control block structure pointed by the
.I gs_cb
argument has failed.
The
.BR s390_pci_mmio_write ()
system call writes
-.IR length
+.I length
bytes of data from the user-space buffer
-.IR user_buffer
+.I user_buffer
to the PCI MMIO memory location specified by
.IR mmio_addr .
The
.I length
bytes of
data from the PCI MMIO memory location specified by
-.IR mmio_addr
+.I mmio_addr
to the user-space buffer
.IR user_buffer .
.PP
or data-transfer operations that are used to access the PCI MMIO
memory areas mapped to user space on the Linux System z platform.
The address specified by
-.IR mmio_addr
+.I mmio_addr
must belong to a PCI MMIO memory page mapping in the caller's address space,
and the data being written or read must not cross a page boundary.
The
-.IR length
+.I length
value cannot be greater than the system page size.
.SH RETURN VALUE
On success,
.BR s390_pci_mmio_read ()
return 0.
On failure, \-1 is returned and
-.IR errno
+.I errno
is set to indicate the error.
.SH ERRORS
.TP
is invalid.
.TP
.B EFAULT
-.IR user_buffer
+.I user_buffer
does not point to a valid location in the caller's address space.
.TP
.B EINVAL
calling thread.
.PP
The
-.IR command
+.I command
argument controls whether run-time instrumentation is started
.RB ( S390_RUNTIME_INSTR_START ,
1) or stopped
2) for the calling thread.
.PP
The
-.IR signum
+.I signum
argument specifies the number of a real-time signal.
This argument was used to specify a signal number that should be delivered
to the thread if the run-time instrumentation buffer was full or if
The caller can then read and modify the control block and start the run-time
instrumentation.
On error, \-1 is returned and
-.IR errno
+.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EINVAL
The value specified in
-.IR command
+.I command
is not a valid command.
.TP
.B EINVAL
The value specified in
-.IR signum
+.I signum
is not a real-time signal number.
From Linux 4.4 onwards, the
-.IR signum
+.I signum
argument has no effect,
so that an invalid signal number will not result in an error.
.TP
.PP
Starting with Linux 4.4,
support for signalling was removed, as was the check whether
-.IR signum
+.I signum
is a valid real-time signal.
For backwards compatibility with older kernels, it is recommended to pass
a valid real-time signal number in
A return value of 0 indicates that CPU capacity information is stored in
.IR *resp_buffer .
A return value of 3 indicates "unsupported function code" and the content of
-.IR *resp_buffer
+.I *resp_buffer
is unchanged.
The return values 1 and 2 are reserved.
.PP
On error, \-1 is returned, and
-.IR errno
+.I errno
is set to indicate the error.
.SH ERRORS
.TP
Linux 3.9 added
.\" commit ce0dbbbb30aee6a835511d5be446462388ba9eee
a new mechanism for adjusting (and viewing) the
-.BR SCHED_RR
+.B SCHED_RR
quantum: the
.I /proc/sys/kernel/sched_rr_timeslice_ms
file exposes the quantum as a millisecond value, whose default is 100.
using
.BR sysconf (3)
to obtain the values of the
-.BR _SC_NPROCESSORS_CONF
+.B _SC_NPROCESSORS_CONF
and
-.BR _SC_NPROCESSORS_ONLN
+.B _SC_NPROCESSORS_ONLN
parameters; and inspecting the list of CPU directories under
.IR /sys/devices/system/cpu/ .
.PP
If the kernel CPU affinity mask is larger than 1024,
then calls of the form:
.PP
- sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
+.in +4n
+.EX
+sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
+.EE
+.in
.PP
fail with the error
.BR EINVAL ,
(i.e., non-real-time) scheduling policies as values that may be specified in
.IR policy :
.TP 14
-.BR SCHED_OTHER
+.B SCHED_OTHER
the standard round-robin time-sharing policy;
.\" In the 2.6 kernel sources, SCHED_OTHER is actually called
.\" SCHED_NORMAL.
.TP
-.BR SCHED_BATCH
+.B SCHED_BATCH
for "batch" style execution of processes; and
.TP
-.BR SCHED_IDLE
+.B SCHED_IDLE
for running
.I very
low priority background jobs.
For the rules governing when a process may use these policies, see
.BR sched (7).
The real-time policies that may be specified in
-.IR policy
+.I policy
are:
.TP 14
-.BR SCHED_FIFO
+.B SCHED_FIFO
a first-in, first-out policy; and
.TP
-.BR SCHED_RR
+.B SCHED_RR
a round-robin policy.
.PP
Linux also provides the following policy:
.in
.PP
The fields of the
-.IR sched_attr
+.I sched_attr
structure are as follows:
.TP
.B size
if they are not,
.BR sched_setattr ()
fails with the error
-.BR E2BIG
+.B E2BIG
and updates
.I size
to contain the size of the kernel structure.
.TP
.I sched_policy
This field specifies the scheduling policy, as one of the
-.BR SCHED_*
+.B SCHED_*
values listed above.
.TP
.I sched_flags
that are ORed together to control scheduling behavior:
.RS
.TP
-.BR SCHED_FLAG_RESET_ON_FORK
+.B SCHED_FLAG_RESET_ON_FORK
Children created by
.BR fork (2)
do not inherit privileged scheduling policies.
.BR SCHED_FLAG_RECLAIM " (since Linux 4.13)"
.\" 2d4283e9d583a3ee8cfb1cbb9c1270614df4c29d
This flag allows a
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
thread to reclaim bandwidth unused by other real-time threads.
.\" Bandwidth reclaim is done via the GRUB algorithm; see
.\" Documentation/scheduler/sched-deadline.txt
.BR SCHED_FLAG_DL_OVERRUN " (since Linux 4.16)"
.\" commit 34be39305a77b8b1ec9f279163c7cdb6cc719b91
This flag allows an application to get informed about run-time overruns in
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
threads.
Such overruns may be caused by (for example) coarse execution time accounting
or incorrect parameter assignment.
signal which is generated on each overrun.
.IP
This
-.BR SIGXCPU
+.B SIGXCPU
signal is
.I process-directed
(see
.TP
.I sched_nice
This field specifies the nice value to be set when specifying
-.IR sched_policy
+.I sched_policy
as
-.BR SCHED_OTHER
+.B SCHED_OTHER
or
.BR SCHED_BATCH .
The nice value is a number in the range \-20 (high priority)
.TP
.I sched_priority
This field specifies the static priority to be set when specifying
-.IR sched_policy
+.I sched_policy
as
-.BR SCHED_FIFO
+.B SCHED_FIFO
or
.BR SCHED_RR .
The allowed range of priorities for these policies can be determined using
The value is expressed in nanoseconds.
This field, and the next two fields,
are used only for
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
scheduling; for further details, see
.BR sched (7).
.TP
is invalid; or
.I attr.sched_policy
is
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
and the deadline scheduling parameters in
.I attr
are invalid.
3.15,
.BR sched_setattr ()
failed with the error
-.BR EFAULT
+.B EFAULT
instead of
-.BR E2BIG
+.B E2BIG
for the case described in ERRORS.
.PP
In Linux versions up to 5.3,
.BR sched_getattr ()
failed with the error
-.BR EFBIG
+.B EFBIG
if the in-kernel
-.IR sched_attr
+.I sched_attr
structure was larger than the
-.IR size
+.I size
passed by user space.
.\" In Linux versions up to up 3.15,
.\" FIXME . patch from Peter Zijlstra pending
(i.e., non-real-time) scheduling policies as values that may be specified in
.IR policy :
.TP 14
-.BR SCHED_OTHER
+.B SCHED_OTHER
the standard round-robin time-sharing policy;
.\" In the 2.6 kernel sources, SCHED_OTHER is actually called
.\" SCHED_NORMAL.
.TP
-.BR SCHED_BATCH
+.B SCHED_BATCH
for "batch" style execution of processes; and
.TP
-.BR SCHED_IDLE
+.B SCHED_IDLE
for running
.I very
low priority background jobs.
.PP
For each of the above policies,
-.IR param\->sched_priority
+.I param\->sched_priority
must be 0.
.PP
Various "real-time" policies are also supported,
For the rules governing when a process may use these policies, see
.BR sched (7).
The real-time policies that may be specified in
-.IR policy
+.I policy
are:
.TP 14
-.BR SCHED_FIFO
+.B SCHED_FIFO
a first-in, first-out policy; and
.TP
-.BR SCHED_RR
+.B SCHED_RR
a round-robin policy.
.PP
For each of the above policies,
-.IR param\->sched_priority
+.I param\->sched_priority
specifies a scheduling priority for the thread.
This is a number in the range returned by calling
.BR sched_get_priority_min (2)
.PP
.BR sched_yield ()
is intended for use with real-time scheduling policies (i.e.,
-.BR SCHED_FIFO
+.B SCHED_FIFO
or
.BR SCHED_RR ).
Use of
.BR sched_yield ()
with nondeterministic scheduling policies such as
-.BR SCHED_OTHER
+.B SCHED_OTHER
is unspecified and very likely means your application design is broken.
.SH SEE ALSO
.BR sched (7)
calling process.
.PP
Currently, Linux supports the following
-.IR operation
+.I operation
values:
.TP
-.BR SECCOMP_SET_MODE_STRICT
+.B SECCOMP_SET_MODE_STRICT
The only system calls that the calling thread is permitted to make are
.BR read (2),
.BR write (2),
.BR sigreturn (2).
Other system calls result in the termination of the calling thread,
or termination of the entire process with the
-.BR SIGKILL
+.B SIGKILL
signal when there is only one thread.
Strict secure computing mode is useful for number-crunching
applications that may need to execute untrusted byte code, perhaps
it can use
.BR sigreturn (2)
to block all signals apart from
-.BR SIGKILL
+.B SIGKILL
and
.BR SIGSTOP .
This means that
.BR alarm (2)
(for example) is not sufficient for restricting the process's execution time.
Instead, to reliably terminate the process,
-.BR SIGKILL
+.B SIGKILL
must be used.
This can be done by using
.BR timer_create (2)
with
-.BR SIGEV_SIGNAL
+.B SIGEV_SIGNAL
and
-.IR sigev_signo
+.I sigev_signo
set to
.BR SIGKILL ,
or by using
.BR RLIMIT_CPU .
.IP
This operation is available only if the kernel is configured with
-.BR CONFIG_SECCOMP
+.B CONFIG_SECCOMP
enabled.
.IP
The value of
-.IR flags
+.I flags
must be 0, and
-.IR args
+.I args
must be NULL.
.IP
This operation is functionally identical to the call:
.EE
.in
.TP
-.BR SECCOMP_SET_MODE_FILTER
+.B SECCOMP_SET_MODE_FILTER
The system calls allowed are defined by a pointer to a Berkeley Packet
Filter (BPF) passed via
.IR args .
This argument is a pointer to a
-.IR "struct\ sock_fprog" ;
+.IR "struct\~sock_fprog" ;
it can be designed to filter arbitrary system calls and system call
arguments.
If the filter is invalid,
.BR seccomp ()
fails, returning
-.BR EINVAL
+.B EINVAL
in
.IR errno .
.IP
.BR execve (2).
.IP
In order to use the
-.BR SECCOMP_SET_MODE_FILTER
+.B SECCOMP_SET_MODE_FILTER
operation, either the calling thread must have the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability in its user namespace, or the thread must already have the
.I no_new_privs
bit set.
.in
.IP
Otherwise, the
-.BR SECCOMP_SET_MODE_FILTER
+.B SECCOMP_SET_MODE_FILTER
operation fails and returns
-.BR EACCES
+.B EACCES
in
.IR errno .
This requirement ensures that an unprivileged process cannot apply
the attack surface during execution of a thread.
.IP
The
-.BR SECCOMP_SET_MODE_FILTER
+.B SECCOMP_SET_MODE_FILTER
operation is available only if the kernel is configured with
-.BR CONFIG_SECCOMP_FILTER
+.B CONFIG_SECCOMP_FILTER
enabled.
.IP
When
-.IR flags
+.I flags
is 0, this operation is functionally identical to the call:
.IP
.in +4n
.in
.IP
The recognized
-.IR flags
+.I flags
are:
.RS
.TP
.BR SECCOMP_FILTER_FLAG_LOG " (since Linux 4.14)"
.\" commit e66a39977985b1e69e17c4042cb290768eca9b02
All filter return actions except
-.BR SECCOMP_RET_ALLOW
+.B SECCOMP_RET_ALLOW
should be logged.
An administrator may override this filter flag by preventing specific
actions from being logged via the
-.IR /proc/sys/kernel/seccomp/actions_logged
+.I /proc/sys/kernel/seccomp/actions_logged
file.
.TP
.BR SECCOMP_FILTER_FLAG_NEW_LISTENER " (since Linux 5.0)"
return a new user-space notification file descriptor.
(The close-on-exec flag is set for the file descriptor.)
When the filter returns
-.BR SECCOMP_RET_USER_NOTIF
+.B SECCOMP_RET_USER_NOTIF
a notification will be sent to this file descriptor.
.IP
At most one seccomp filter using the
-.BR SECCOMP_FILTER_FLAG_NEW_LISTENER
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
flag can be installed for a thread.
.IP
See
.\" commit 00a02d0c502a06d15e07b857f8ff921e3e402675
Disable Speculative Store Bypass mitigation.
.TP
-.BR SECCOMP_FILTER_FLAG_TSYNC
+.B SECCOMP_FILTER_FLAG_TSYNC
When adding a new filter, synchronize all other threads of the calling
process to the same seccomp filter tree.
A "filter tree" is the ordered list of filters attached to a thread.
the call will not attach the new seccomp filter,
and will fail, returning the first thread ID found that cannot synchronize.
Synchronization will fail if another thread in the same process is in
-.BR SECCOMP_MODE_STRICT
+.B SECCOMP_MODE_STRICT
or if it has attached new seccomp filters to itself,
diverging from the calling thread's filter tree.
.RE
.BR SECCOMP_RET_KILL_PROCESS .
.IP
The value of
-.IR flags
+.I flags
must be 0, and
-.IR args
+.I args
must be a pointer to an unsigned 32-bit filter return action.
.TP
.BR SECCOMP_GET_NOTIF_SIZES " (since Linux 5.0)"
much memory to allocate for sending and receiving notifications.
.IP
The value of
-.IR flags
+.I flags
must be 0, and
-.IR args
+.I args
must be a pointer to a
.IR "struct seccomp_notif_sizes" ,
which has the following form:
.SS Filters
When adding filters via
.BR SECCOMP_SET_MODE_FILTER ,
-.IR args
+.I args
points to a filter program:
.PP
.in +4n
.PP
When executing the instructions, the BPF program operates on the
system call information made available (i.e., use the
-.BR BPF_ABS
+.B BPF_ABS
addressing mode) as a (read-only)
.\" Quoting Kees Cook:
.\" If BPF even allows changing the data, it's not copied back to
.BR execve (2)
to execute binaries that employ the different conventions),
it is usually necessary to verify the value of the
-.IR arch
+.I arch
field.
.PP
It is strongly recommended to use an allow-list approach whenever
representation of a value without altering its meaning, leading to
a deny-list bypass.
See also
-.IR Caveats
+.I Caveats
below.
.PP
The
-.IR arch
+.I arch
field is not unique for all calling conventions.
The x86-64 ABI and the x32 ABI both use
-.BR AUDIT_ARCH_X86_64
+.B AUDIT_ARCH_X86_64
as
.IR arch ,
and they run on the same processors.
Instead, the mask
-.BR __X32_SYSCALL_BIT
+.B __X32_SYSCALL_BIT
is used on the system call number to tell the two ABIs apart.
.\" As noted by Dave Drysdale in a note at the end of
.\" https://lwn.net/Articles/604515/
.\" so that the syscall table indexing still works.
.PP
This means that a policy must either deny all syscalls with
-.BR __X32_SYSCALL_BIT
+.B __X32_SYSCALL_BIT
or it must recognize syscalls with and without
-.BR __X32_SYSCALL_BIT
+.B __X32_SYSCALL_BIT
set.
A list of system calls to be denied based on
-.IR nr
+.I nr
that does not also contain
-.IR nr
+.I nr
values with
-.BR __X32_SYSCALL_BIT
+.B __X32_SYSCALL_BIT
set can be bypassed by a malicious program that sets
.BR __X32_SYSCALL_BIT .
.PP
Additionally, kernels prior to Linux 5.4 incorrectly permitted
-.IR nr
+.I nr
in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed
with
.BR __X32_SYSCALL_BIT .
For example,
-.IR nr
+.I nr
== 521 and
-.IR nr
+.I nr
== (101 |
.BR __X32_SYSCALL_BIT )
would result in invocations of
field provides the address of the machine-language instruction that
performed the system call.
This might be useful in conjunction with the use of
-.I /proc/[pid]/maps
+.IR /proc/ pid /maps
to perform checks based on which region (mapping) of the program
made the system call.
(Probably, it is wise to lock down the
with a core dump.
The system call is not executed.
By contrast with
-.BR SECCOMP_RET_KILL_THREAD
+.B SECCOMP_RET_KILL_THREAD
below, all threads in the thread group are terminated.
(For a discussion of thread groups, see the description of the
-.BR CLONE_THREAD
+.B CLONE_THREAD
flag in
.BR clone (2).)
.IP
or similar), the returned
.I wstatus
will indicate that its child was terminated as though by a
-.BR SIGSYS
+.B SIGSYS
signal.
.TP
.BR SECCOMP_RET_KILL_THREAD " (or " SECCOMP_RET_KILL )
.B SIGSYS
signal.
See
-.BR SECCOMP_RET_KILL_PROCESS
+.B SECCOMP_RET_KILL_PROCESS
above.
.IP
.\" See these commits:
a single-threaded process will dump core if terminated in this way.
.IP
With the addition of
-.BR SECCOMP_RET_KILL_PROCESS
+.B SECCOMP_RET_KILL_PROCESS
in Linux 4.14,
-.BR SECCOMP_RET_KILL_THREAD
+.B SECCOMP_RET_KILL_THREAD
was added as a synonym for
.BR SECCOMP_RET_KILL ,
in order to more clearly distinguish the two actions.
.IP
.BR Note :
the use of
-.BR SECCOMP_RET_KILL_THREAD
+.B SECCOMP_RET_KILL_THREAD
to kill a single thread in a multithreaded process is likely to leave the
process in a permanently inconsistent and possibly corrupt state.
.TP
-.BR SECCOMP_RET_TRAP
+.B SECCOMP_RET_TRAP
This value results in the kernel sending a thread-directed
-.BR SIGSYS
+.B SIGSYS
signal to the triggering thread.
(The system call is not executed.)
Various fields will be set in the
will contain
.BR SIGSYS .
.IP *
-.IR si_call_addr
+.I si_call_addr
will show the address of the system call instruction.
.IP *
-.IR si_syscall
+.I si_syscall
and
-.IR si_arch
+.I si_arch
will indicate which system call was attempted.
.IP *
.I si_code
.IP *
.I si_errno
will contain the
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
portion of the filter return value.
.RE
.IP
The return value register will contain an architecture\-dependent value;
if resuming execution, set it to something appropriate for the system call.
(The architecture dependency is because replacing it with
-.BR ENOSYS
+.B ENOSYS
could overwrite some useful information.)
.TP
-.BR SECCOMP_RET_ERRNO
+.B SECCOMP_RET_ERRNO
This value results in the
.B SECCOMP_RET_DATA
portion of the filter's return value being passed to user space as the
-.IR errno
+.I errno
value without executing the system call.
.TP
.BR SECCOMP_RET_USER_NOTIF " (since Linux 5.0)"
process to allow that process to decide what to do with the system call.
If there is no attached supervisor (either
because the filter was not installed with the
-.BR SECCOMP_FILTER_FLAG_NEW_LISTENER
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
flag or because the file descriptor was closed), the filter returns
-.BR ENOSYS
+.B ENOSYS
(similar to what happens when a filter returns
-.BR SECCOMP_RET_TRACE
+.B SECCOMP_RET_TRACE
and there is no tracer).
See
.BR seccomp_unotify (2)
if another filter returns an action value with a precedence greater than
.BR SECCOMP_RET_USER_NOTIF .
.TP
-.BR SECCOMP_RET_TRACE
+.B SECCOMP_RET_TRACE
When returned, this value will cause the kernel to attempt to notify a
.BR ptrace (2)-based
tracer prior to executing the system call.
.BR ENOSYS .
.IP
A tracer will be notified if it requests
-.BR PTRACE_O_TRACESECCOMP
+.B PTRACE_O_TRACESECCOMP
using
.IR ptrace(PTRACE_SETOPTIONS) .
The tracer will be notified of a
-.BR PTRACE_EVENT_SECCOMP
+.B PTRACE_EVENT_SECCOMP
and the
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
portion of the filter's return value will be available to the tracer via
.BR PTRACE_GETEVENTMSG .
.IP
the filter return action is logged.
An administrator may override the logging of this action via
the
-.IR /proc/sys/kernel/seccomp/actions_logged
+.I /proc/sys/kernel/seccomp/actions_logged
file.
.TP
-.BR SECCOMP_RET_ALLOW
+.B SECCOMP_RET_ALLOW
This value results in the system call being executed.
.PP
If an action value other than one of the above is specified,
then the filter action is treated as either
-.BR SECCOMP_RET_KILL_PROCESS
+.B SECCOMP_RET_KILL_PROCESS
(since Linux 4.14)
.\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945
or
-.BR SECCOMP_RET_KILL_THREAD
+.B SECCOMP_RET_KILL_THREAD
(in Linux 4.13 and earlier).
.\"
.SS /proc interfaces
The files in the directory
-.IR /proc/sys/kernel/seccomp
+.I /proc/sys/kernel/seccomp
provide additional seccomp information and configuration:
.TP
.IR actions_avail " (since Linux 4.14)"
are allowed to be logged.
Writes to the file do not need to be in ordered form but reads from
the file will be ordered in the same way as the
-.IR actions_avail
+.I actions_avail
file.
.IP
It is important to note that the value of
-.IR actions_logged
+.I actions_logged
does not prevent certain filter return actions from being logged when
the audit subsystem is configured to audit a task.
If the action is not found in the
-.IR actions_logged
+.I actions_logged
file, the final decision on whether to audit the action for that task is
ultimately left up to the audit subsystem to decide for all filter return
actions other than
.BR SECCOMP_RET_ALLOW .
.IP
The "allow" string is not accepted in the
-.IR actions_logged
+.I actions_logged
file as it is not possible to log
-.BR SECCOMP_RET_ALLOW
+.B SECCOMP_RET_ALLOW
actions.
Attempting to write "allow" to the file will fail with the error
.BR EINVAL .
the action is not logged.
.IP *
Otherwise, if the action is either
-.BR SECCOMP_RET_KILL_PROCESS
+.B SECCOMP_RET_KILL_PROCESS
or
.BR SECCOMP_RET_KILL_THREAD ,
and that action appears in the
-.IR actions_logged
+.I actions_logged
file, the action is logged.
.IP *
Otherwise, if the filter has requested logging (the
-.BR SECCOMP_FILTER_FLAG_LOG
+.B SECCOMP_FILTER_FLAG_LOG
flag)
and the action appears in the
-.IR actions_logged
+.I actions_logged
file, the action is logged.
.IP *
Otherwise, if kernel auditing is enabled and the process is being audited
.BR seccomp ()
returns 0.
On error, if
-.BR SECCOMP_FILTER_FLAG_TSYNC
+.B SECCOMP_FILTER_FLAG_TSYNC
was used,
the return value is the ID of the thread
that caused the synchronization failure.
and
.BR gettid (2).)
On other errors, \-1 is returned, and
-.IR errno
+.I errno
is set to indicate the error.
.SH ERRORS
.BR seccomp ()
can fail for the following reasons:
.TP
-.BR EACCES
+.B EACCES
The caller did not have the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability in its user namespace, or had not set
-.IR no_new_privs
+.I no_new_privs
before using
.BR SECCOMP_SET_MODE_FILTER .
.TP
-.BR EBUSY
+.B EBUSY
While installing a new filter, the
-.BR SECCOMP_FILTER_FLAG_NEW_LISTENER
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
flag was specified,
but a previous filter had already been installed with that flag.
.TP
-.BR EFAULT
-.IR args
+.B EFAULT
+.I args
was not a valid address.
.TP
-.BR EINVAL
-.IR operation
+.B EINVAL
+.I operation
is unknown or is not supported by this kernel version or configuration.
.TP
.B EINVAL
The specified
-.IR flags
+.I flags
are invalid for the given
.IR operation .
.TP
-.BR EINVAL
+.B EINVAL
.I operation
included
.BR BPF_ABS ,
but the specified offset was not aligned to a 32-bit boundary or exceeded
-.IR "sizeof(struct\ seccomp_data)" .
+.IR "sizeof(struct\~seccomp_data)" .
.TP
-.BR EINVAL
+.B EINVAL
.\" See kernel/seccomp.c::seccomp_may_assign_mode() in 3.18 sources
A secure computing mode has already been set, and
.I operation
differs from the existing setting.
.TP
-.BR EINVAL
+.B EINVAL
.I operation
specified
.BR SECCOMP_SET_MODE_FILTER ,
.B BPF_MAXINSNS
(4096) instructions.
.TP
-.BR ENOMEM
+.B ENOMEM
Out of memory.
.TP
-.BR ENOMEM
+.B ENOMEM
.\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in 3.18 sources
The total length of all filter programs attached
to the calling thread would exceed
each already existing filter program incurs an
overhead penalty of 4 instructions.
.TP
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
.I operation
specified
.BR SECCOMP_GET_ACTION_AVAIL ,
but the kernel does not support the filter return action specified by
.IR args .
.TP
-.BR ESRCH
+.B ESRCH
Another thread caused a failure during thread sync, but its ID could not
be determined.
.SH VERSIONS
library, which provides a front-end for generating seccomp filters.
.PP
The
-.IR Seccomp
+.I Seccomp
field of the
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
file provides a method of viewing the seccomp mode of a process; see
.BR proc (5).
.PP
.BR seccomp ()
provides a superset of the functionality provided by the
.BR prctl (2)
-.BR PR_SET_SECCOMP
+.B PR_SET_SECCOMP
operation (which does not support
.IR flags ).
.PP
.B BPF_LEN
addressing mode modifier yields an immediate mode operand
whose value is the size of the
-.IR seccomp_data
+.I seccomp_data
buffer.
.SH EXAMPLES
The program below accepts four or more arguments.
.BR seccomp_rule_add (3).
.PP
The kernel source files
-.IR Documentation/networking/filter.txt
+.I Documentation/networking/filter.txt
and
-.IR Documentation/userspace\-api/seccomp_filter.rst
+.I Documentation/userspace\-api/seccomp_filter.rst
.\" commit c061f33f35be0ccc80f4b8e0aea5dfd2ed7e01a3
(or
-.IR Documentation/prctl/seccomp_filter.txt
+.I Documentation/prctl/seccomp_filter.txt
before Linux 4.13).
.PP
McCanne, S.\& and Jacobson, V.\& (1992)
As well as the use of the
.B SECCOMP_FILTER_FLAG_NEW_LISTENER
flag, the
-.BR SECCOMP_RET_USER_NOTIF
+.B SECCOMP_RET_USER_NOTIF
action value, and the
.B SECCOMP_GET_NOTIF_SIZES
operation described in
One way in which this could be done is by passing the file descriptor
over a UNIX domain socket connection between the target and the supervisor
(using the
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
ancillary message type described in
.BR unix (7)).
Another way to do this is through the use of
values of pointer arguments for the target's system call.
(This is something that can't be done from within a seccomp filter.)
One way in which the supervisor can do this is to open the corresponding
-.I /proc/[tid]/mem
+.IR /proc/ tid /mem
file (see
.BR proc (5))
and read bytes from the location that corresponds to one of
(The supervisor must be careful to avoid
a race condition that can occur when doing this;
see the description of the
-.BR SECCOMP_IOCTL_NOTIF_ID_VALID
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
.BR ioctl (2)
operation below.)
In addition,
is the listening file descriptor returned by a call to
.BR seccomp (2)
with the
-.BR SECCOMP_FILTER_FLAG_NEW_LISTENER
+.B SECCOMP_FILTER_FLAG_NEW_LISTENER
flag.
.\"
.SS SECCOMP_IOCTL_NOTIF_RECV
.IP \(bu
When returning a notification response to the kernel,
the supervisor must include the cookie value in the
-.IR seccomp_notif_resp
+.I seccomp_notif_resp
structure that is specified as the argument of the
-.BR SECCOMP_IOCTL_NOTIF_SEND
+.B SECCOMP_IOCTL_NOTIF_SEND
operation.
.RE
.TP
The supervisor
.BR open (2)s
the
-.IR /proc/[tid]/mem
+.IR /proc/ tid /mem
file for the TID obtained in step 1, with the intention of (say)
inspecting the memory location(s) that containing the argument(s) of
the system call that triggered the notification in step 1.
allows the supervisor to install a file descriptor
into the target's file descriptor table.
Much like the use of
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
messages described in
.BR unix (7),
this operation is semantically equivalent to duplicating
into the target's file descriptor table.
.PP
The
-.BR SECCOMP_IOCTL_NOTIF_ADDFD
+.B SECCOMP_IOCTL_NOTIF_ADDFD
operation permits the supervisor to emulate a target system call (such as
.BR socket (2)
or
the received file descriptor is subject to the same
Linux Security Module (LSM) checks as are applied to a file descriptor
that is received in an
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
ancillary message.
If the file descriptor refers to a socket,
it inherits the cgroup version 1 network controller settings
Currently, only one flag is supported:
.RS
.TP
-.BR SECCOMP_ADDFD_FLAG_SETFD
+.B SECCOMP_ADDFD_FLAG_SETFD
When allocating the file descriptor in the target,
use the file descriptor number specified in the
.I newfd
.I newfd
This field determines which file descriptor number is allocated in the target.
If the
-.BR SECCOMP_ADDFD_FLAG_SETFD
+.B SECCOMP_ADDFD_FLAG_SETFD
flag is set,
then this field specifies which file descriptor number should be allocated.
If this file descriptor number is already open in the target,
will not be closed in the target process.
.IP
If the
-.BR SECCOMP_ADDFD_FLAG_SETFD
+.B SECCOMP_ADDFD_FLAG_SETFD
flag it not set, then this field must be 0,
and the kernel allocates the lowest unused file descriptor number
in the target.
this value can be used as the return value
.RI ( resp.val )
that is supplied in the response that is subsequently sent with the
-.BR SECCOMP_IOCTL_NOTIF_SEND
+.B SECCOMP_IOCTL_NOTIF_SEND
operation.
.PP
On error, \-1 is returned and
.TP
.B EBADF
Allocating the file descriptor in the target would cause the target's
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
limit to be exceeded (see
.BR getrlimit (2)).
.TP
the processes inside the container)
to mount block devices or create device nodes for the container.
The mount use case provides an example of where the
-.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE
+.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
.BR ioctl (2)
operation is useful.
Upon receiving a notification for the
.\"
.SS Caveats regarding the use of /proc/[tid]/mem
The discussion above noted the need to use the
-.BR SECCOMP_IOCTL_NOTIF_ID_VALID
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
.BR ioctl (2)
when opening the
-.IR /proc/[tid]/mem
+.IR /proc/ tid /mem
file of the target
to avoid the possibility of accessing the memory of the wrong process
in the event that the target terminates and its ID
which triggers a user-space notification and causes the target to block.
.IP \(bu
The supervisor receives the notification, opens
-.IR /proc/[tid]/mem ,
+.IR /proc/ tid /mem ,
and (successfully) performs the
-.BR SECCOMP_IOCTL_NOTIF_ID_VALID
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
check.
.IP \(bu
The target receives a signal, which causes the
To prevent such scenarios,
every read from the target's memory must be separated from use of
the bytes so obtained by a
-.BR SECCOMP_IOCTL_NOTIF_ID_VALID
+.B SECCOMP_IOCTL_NOTIF_ID_VALID
check.
In the above example, the check would be placed between the two final steps.
An example of such a check is shown in EXAMPLES.
.B SECCOMP_IOCTL_NOTIF_SEND
.BR ioctl (2))
operation will fail with the
-.BR ENOENT
+.B ENOENT
error.
.PP
In this scenario, the kernel will restart the target's system call.
that would
.B never
normally be restarted by the
-.BR SA_RESTART
+.B SA_RESTART
flag.
.\" FIXME
.\" About the above, Kees Cook commented:
making sure no file descriptors are inadvertently leaked into the target.
.SH BUGS
If a
-.BR SECCOMP_IOCTL_NOTIF_RECV
+.B SECCOMP_IOCTL_NOTIF_RECV
.BR ioctl (2)
operation
.\" or a poll/epoll/select
.BR mkdir (2).
When such a notification occurs,
the supervisor examines the memory of the target process (using
-.IR /proc/[pid]/mem )
+.IR /proc/ pid /mem )
to discover the pathname argument that was supplied to the
.BR mkdir (2)
call, and performs one of the following actions:
so that the target process's
.BR mkdir (2)
call appears to fail with the error
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
("Operation not supported").
Additionally, if the specified pathname is exactly "/bye",
then the supervisor terminates.
the supervisor attempts to create that directory, but the
.BR mkdir (2)
call fails because the directory
-.BR /tmp/nosuchdir
+.B /tmp/nosuchdir
does not exist.
Consequently, the supervisor spoofs an error return that passes the error
that it received back to the target process's
.BR "WARNING" :
.BR select ()
can monitor only file descriptors numbers that are less than
-.BR FD_SETSIZE
+.B FD_SETSIZE
(1024)\(eman unreasonably low limit for many modern applications\(emand
this limitation will not change.
All modern applications should instead use
.B EINVAL
.I nfds
is negative or exceeds the
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
resource limit (see
.BR getrlimit (2)).
.TP
and
.BR pselect ()
is not affected by the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag.
.PP
On some other UNIX systems,
determining the length of the sets to be checked from the value of
.IR nfds .
However, in the glibc implementation, the
-.IR fd_set
+.I fd_set
type is fixed in size.
See also BUGS.
.PP
on the range of file descriptors that can be specified
in a file descriptor set.
The Linux kernel imposes no fixed limit, but the glibc implementation makes
-.IR fd_set
+.I fd_set
a fixed-size type, with
-.BR FD_SETSIZE
+.B FD_SETSIZE
defined as 1024, and the
.BR FD_* ()
macros operating according to that limit.
.BR IPCSET ,
.BR SETVAL ,
or
-.BR SETALL
+.B SETALL
operation.
.TP
.I sem_nsems
However,
.I sem_perm.mode
is not checked for read access for
-.IR semid
+.I semid
meaning that any user can employ this operation (just as any user may read
-.IR /proc/sysvipc/sem
+.I /proc/sysvipc/sem
to obtain the same information).
.TP
.B GETALL
Linux also updates
.I sempid
for
-.BR SETVAL
+.B SETVAL
operations and semaphore adjustments.
However, somewhat inconsistently, up to and including Linux 4.5,
the kernel did not update
.I sempid
for
-.BR SETALL
+.B SETALL
operations.
This was rectified
.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
.B EEXIST
.B IPC_CREAT
and
-.BR IPC_EXCL
+.B IPC_EXCL
were specified in
.IR semflg ,
but a semaphore set already exists for
argument for
.BR semget ().
Command-line options can be used to specify the
-.BR IPC_CREAT
+.B IPC_CREAT
.RI ( \-c )
and
-.BR IPC_EXCL
+.B IPC_EXCL
.RI ( \-x )
flags for the call to
.BR semget ().
is interrupted by a signal, causing the call to fail with the error
.BR EINTR ,
the contents of
-.IR timeout
+.I timeout
are left unchanged.
.SH RETURN VALUE
On success,
because of the risk of that
.BR semop ()
fails due to kernel memory fragmentation when allocating memory to copy the
-.IR sops
+.I sops
array.
.TP
.B SEMVMX
.BR write (2).
Also, the following call
.PP
- send(sockfd, buf, len, flags);
+.in +4n
+.EX
+send(sockfd, buf, len, flags);
+.EE
+.in
.PP
is equivalent to
.PP
- sendto(sockfd, buf, len, flags, NULL, 0);
+.in +4n
+.EX
+sendto(sockfd, buf, len, flags, NULL, 0);
+.EE
+.in
.PP
The argument
.I sockfd
If
.I offset
is NULL, then data will be read from
-.IR in_fd
+.I in_fd
starting at the file offset,
and the file offset will be updated by the call.
.PP
is the number of bytes to copy between the file descriptors.
.PP
The
-.IR in_fd
+.I in_fd
argument must correspond to a file which supports
.BR mmap (2)-like
operations
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.BI "#include <sys/socket.h>"
+.B #include <sys/socket.h>
.PP
.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \
", unsigned int " vlen ","
The
.I msg_len
field is used to return the number of bytes sent from the message in
-.IR msg_hdr
+.I msg_hdr
(i.e., the same as the return value from a single
.BR sendmsg (2)
call).
the
.I msg_len
fields of successive elements of
-.IR msgvec
+.I msgvec
are updated to contain the number of bytes transmitted from the corresponding
.IR msg_hdr .
The return value of the call indicates the number of elements of
.BR MPOL_INTERLEAVE ,
.BR MPOL_PREFERRED ,
or
-.BR MPOL_LOCAL
+.B MPOL_LOCAL
(which are described in detail below).
All modes except
.B MPOL_DEFAULT
.I clear_child_tid
and the kernel performs the following operation:
.PP
- futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
+.in +4n
+.EX
+futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
+.EE
+.in
.PP
The effect of this operation is to wake a single thread that
is performing a futex wait on the memory location.
In the case of
.BR seteuid ():
the calling process is not privileged (does not have the
-.BR CAP_SETUID
+.B CAP_SETUID
capability in its user namespace) and
.I euid
does not match the current real user ID, current effective user ID,
In the case of
.BR setegid ():
the calling process is not privileged (does not have the
-.BR CAP_SETGID
+.B CAP_SETGID
capability in its user namespace) and
.I egid
does not match the current real group ID, current effective group ID,
whether the call succeeded or failed.
Instead, the caller must resort to looking at the return value
from a further call such as
-.IR setfsgid(\-1)
+.I setfsgid(\-1)
(which will always fail), in order to determine if a preceding call to
.BR setfsgid ()
changed the filesystem group ID.
whether the call succeeded or failed.
Instead, the caller must resort to looking at the return value
from a further call such as
-.IR setfsuid(\-1)
+.I setfsuid(\-1)
(which will always fail), in order to determine if a preceding call to
.BR setfsuid ()
changed the filesystem user ID.
argument is one of the following:
.IP \(bu 2
a file descriptor referring to one of the magic links in a
-.I /proc/[pid]/ns/
+.IR /proc/ pid /ns/
directory (or a bind mount to such a link);
.IP \(bu
a PID file descriptor (see
If
.I fd
refers to a
-.I /proc/[pid]/ns/
+.IR /proc/ pid /ns/
link, then
.BR setns ()
reassociates the calling thread with the namespace associated with that link,
.I one
of the following values:
.TP
-.BR 0
+.B 0
Allow any type of namespace to be joined.
.TP
.BR CLONE_NEWCGROUP " (since Linux 4.6)"
Specifying a nonzero value for
.I nstype
is useful if the caller does not know what type of namespace is referred to by
-.IR fd
+.I fd
and wants to ensure that the namespace is of a particular type.
(The caller might not know the type of the namespace referred to by
-.IR fd
+.I fd
if the file descriptor was opened by another process and, for example,
passed to the caller via a UNIX domain socket.)
.\"
.IR fd .
.PP
The
-.IR nstype
+.I nstype
argument is a bit mask specified by ORing together
.I "one or more"
of the
-.BR CLONE_NEW*
+.B CLONE_NEW*
namespace constants listed above.
The caller is moved into each of the target thread's namespaces
that is specified in
Changing the mount namespace requires that the caller possess both
.B CAP_SYS_CHROOT
and
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capabilities in its own user namespace and
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
in the user namespace that owns the target mount namespace.
.IP
A process can't join a new mount namespace if it is sharing
system call is Linux-specific.
.SH NOTES
For further information on the
-.IR /proc/[pid]/ns/
+.IR /proc/ pid /ns/
magic links, see
.BR namespaces (7).
.PP
.SH EXAMPLES
The program below takes two or more arguments.
The first argument specifies the pathname of a namespace file in an existing
-.I /proc/[pid]/ns/
+.IR /proc/ pid /ns/
directory.
The remaining arguments specify a command and its arguments.
The program opens the namespace file, joins that namespace using
(compiled as a binary named
.IR ns_exec )
in conjunction with the
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
example program in the
.BR clone (2)
man page (complied as a binary named
.IR pgid ,
is a wrapper function that calls
.PP
- setpgid(pid, pgid)
+.in +4n
+.EX
+setpgid(pid, pgid)
+.EE
+.in
.PP
.\" The true BSD setpgrp() system call differs in allowing the PGID
.\" to be set to arbitrary values, rather than being restricted to
.I pid
argument, is a wrapper function that calls
.PP
- getpgid(pid)
+.in +4n
+.EX
+getpgid(pid)
+.EE
+.in
.PP
Since glibc 2.19, the BSD-specific
.BR getpgrp ()
.B CLOCAL
flag for that terminal is not set,
and a terminal hangup occurs, then the session leader is sent a
-.BR SIGHUP
+.B SIGHUP
signal.
.PP
If a process that is a session leader terminates, then a
sets the effective user ID of the calling process.
If the calling process is privileged
(more precisely: if the process has the
-.BR CAP_SETUID
+.B CAP_SETUID
capability in its user namespace),
the real UID and saved set-user-ID are also set.
.PP
.PP
By default
(i.e.,
-.IR flags
+.I flags
is zero),
the extended attribute will be created if it does not exist,
or the value will be replaced if the attribute already exists.
.I shm_ctime
Time of creation of segment or time of the last
.BR shmctl ()
-.BR IPC_SET
+.B IPC_SET
operation.
.TP
.I shm_cpid
is not checked for read access for
.IR shmid ,
meaning that any user can employ this operation (just as any user may read
-.IR /proc/sysvipc/shm
+.I /proc/sysvipc/shm
to obtain the same information).
.PP
The caller can prevent or allow swapping of a shared
capability in the user namespace that governs its IPC namespace.
.TP
.B EEXIST
-.BR IPC_CREAT
+.B IPC_CREAT
and
-.BR IPC_EXCL
+.B IPC_EXCL
were specified in
.IR shmflg ,
but a shared memory segment already exists for
.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
the default value for this limit is:
.IP
- ULONG_MAX - 2^24
+.in +4n
+.EX
+ULONG_MAX - 2^24
+.EE
+.in
.IP
The effect of this value
(which is suitable for both 32-bit and 64-bit systems)
From Linux 2.4 up to Linux 3.15,
the default value for this limit was:
.IP
- SHMMAX / PAGE_SIZE * (SHMMNI / 16)
+.in +4n
+.EX
+SHMMAX / PAGE_SIZE * (SHMMNI / 16)
+.EE
+.in
.IP
If
.B SHMMAX
.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31
the default value for this limit is:
.IP
- ULONG_MAX - 2^24
+.in +4n
+.EX
+ULONG_MAX - 2^24
+.EE
+.in
.IP
The effect of this value
(which is suitable for both 32-bit and 64-bit systems)
is to impose no limitation on allocations.
See the description of
-.BR SHMALL
+.B SHMALL
for a discussion of why this default value (rather than
.BR ULONG_MAX )
is used.
Allow the contents of the segment to be executed.
The caller must have execute permission on the segment.
.TP
-.BR SHM_RDONLY
+.B SHM_RDONLY
Attach the segment for read-only access.
The process must have read permission for the segment.
If this flag is not specified,
.TP
.B EINVAL
An invalid value was specified in
-.IR how
+.I how
(but see BUGS).
.TP
.B ENOTCONN
If an alternate stack is not available, the default stack will be used.
This flag is meaningful only when establishing a signal handler.
.TP
-.BR SA_RESETHAND
+.B SA_RESETHAND
Restore the signal action to the default upon entry to the signal handler.
This flag is meaningful only when establishing a signal handler.
.IP
.BR signal (7)
for a discussion of system call restarting.
.TP
-.BR SA_RESTORER
+.B SA_RESTORER
.IR "Not intended for application use" .
This flag is used by C libraries to indicate that the
-.IR sa_restorer
+.I sa_restorer
field contains the address of a "signal trampoline".
See
.BR sigreturn (2)
flag is specified in
.IR act.sa_flags ,
the signal handler address is passed via the
-.IR act.sa_sigaction
+.I act.sa_sigaction
field.
This handler takes three arguments, as follows:
.PP
on the user-space stack by the kernel; for details, see
.BR sigreturn (2).
Further information about the
-.IR ucontext_t
+.I ucontext_t
structure can be found in
.BR getcontext (3)
and
.BR SIGSEGV ,
.BR SIGBUS ,
and
-.BR SIGTRAP
+.B SIGTRAP
fill in
.I si_addr
with the address of the fault.
contains
.IR log2(sysconf(_SC_PAGESIZE)) .
When
-.BR SIGTRAP
+.B SIGTRAP
is delivered in response to a
.BR ptrace (2)
event (PTRACE_EVENT_foo),
are Linux-specific extensions.
.IP
The
-.BR SEGV_BNDERR
+.B SEGV_BNDERR
suberror of
.B SIGSEGV
populates
-.IR si_lower
+.I si_lower
and
.IR si_upper .
.IP
The
-.BR SEGV_PKUERR
+.B SEGV_PKUERR
suberror of
.B SIGSEGV
populates
.BR SIGIO / SIGPOLL
(the two names are synonyms on Linux)
fills in
-.IR si_band " and " si_fd .
+.I si_band
+and
+.IR si_fd .
The
.I si_band
event is a bit mask containing the same values as are filled in the
.I si_fd
field indicates the file descriptor for which the I/O event occurred;
for further details, see the description of
-.BR F_SETSIG
+.B F_SETSIG
in
.BR fcntl (2).
.IP *
event,
.I si_code
will contain
-.BR SIGTRAP
+.B SIGTRAP
and have the ptrace event in the high byte:
.PP
.in +4n
The following value can be placed in
.I si_code
for a
-.BR SIGSYS
+.B SIGSYS
signal:
.RS 4
.TP
field and sets the
.B SA_RESTORER
flag in the
-.IR act.sa_flags
+.I act.sa_flags
field.
See
.BR sigreturn (2).
.BR sigaction ().
However, with the addition of real-time signals in Linux 2.2,
the fixed-size, 32-bit
-.IR sigset_t
+.I sigset_t
type supported by that system call was no longer fit for purpose.
Consequently, a new system call,
.BR rt_sigaction (),
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type.
The new system call takes a fourth argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the signal sets in
-.IR act.sa_mask
+.I act.sa_mask
and
.IR oldact.sa_mask .
This argument is currently required to have the value
-.IR sizeof(sigset_t)
+.I sizeof(sigset_t)
(or the error
.B EINVAL
results).
On kernels where this flag is not supported,
.BR sigaltstack ()
fails with the error
-.BR EINVAL
+.B EINVAL
when this flag is supplied.
.RE
.TP
To disable an existing stack, specify \fIss.ss_flags\fP
as \fBSS_DISABLE\fP.
In this case, the kernel ignores any other flags in
-.IR ss.ss_flags
+.I ss.ss_flags
and the remaining fields
in \fIss\fP.
.PP
The same is also true for a child process created using
.BR clone (2),
unless the clone flags include
-.BR CLONE_VM
+.B CLONE_VM
and do not include
.BR CLONE_VFORK ,
in which case any alternate signal stack that was established in the parent
to allow
.I ss.ss_flags==SS_ONSTACK
with the same meaning as
-.IR "ss.ss_flags==0"
+.I ss.ss_flags==0
(i.e., the inclusion of
.B SS_ONSTACK
in
.BR sigaction (2))
to install an alternate signal stack that is employed by a handler
for the
-.BR SIGSEGV
+.B SIGSEGV
signal:
.PP
.in +4n
.B _BSD_SOURCE
(glibc 2.19 and earlier)
or
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(glibc 2.19 and later)
is defined.
Without use of such a type, the declaration of
The only portable use of
.BR signal ()
is to set a signal's disposition to
-.BR SIG_DFL
+.B SIG_DFL
or
.BR SIG_IGN .
The semantics when using
feature test macro is defined:
.B _BSD_SOURCE
on glibc 2.19 and earlier or
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
in glibc 2.19 and later.
(By default, these macros are defined; see
.BR feature_test_macros (7)
is used to replace the signal set associated with that file descriptor.
.PP
Starting with Linux 2.6.27, the following values may be bitwise ORed in
-.IR flags
+.I flags
to change the behavior of
.BR signalfd ():
.TP 14
.B SFD_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
.PP
The signal mask employed by a signalfd file descriptor can be viewed
via the entry for the corresponding file descriptor in the process's
-.IR /proc/[pid]/fdinfo
+.IR /proc/ pid /fdinfo
directory.
See
.BR proc (5)
.SS Limitations
The signalfd mechanism can't be used to receive signals that
are synchronously generated, such as the
-.BR SIGSEGV
+.B SIGSEGV
signal that results from accessing an invalid memory address
or the
-.BR SIGFPE
+.B SIGFPE
signal that results from an arithmetic error.
Such signals can be caught only via signal handler.
.PP
.BR sigpending ().
However, with the addition of real-time signals in Linux 2.2,
the fixed-size, 32-bit
-.IR sigset_t
+.I sigset_t
argument supported by that system call was no longer fit for purpose.
Consequently, a new system call,
.BR rt_sigpending (),
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type.
The new system call takes a second argument,
.IR "size_t sigsetsize" ,
.\"
.SS C library/kernel differences
The kernel's definition of
-.IR sigset_t
+.I sigset_t
differs in size from that used
by the C library.
In this manual page, the former is referred to as
.BR sigprocmask ().
However, with the addition of real-time signals in Linux 2.2,
the fixed-size, 32-bit
-.IR sigset_t
+.I sigset_t
(referred to as
-.IR old_kernel_sigset_t
+.I old_kernel_sigset_t
in this manual page)
type supported by that system call was no longer fit for purpose.
Consequently, a new system call,
.BR rt_sigprocmask (),
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type
(referred to as
-.IR kernel_sigset_t
+.I kernel_sigset_t
in this manual page).
The new system call takes a fourth argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the signal sets in
-.IR set
+.I set
and
.IR oldset .
This argument is currently required to have a fixed architecture specific value
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.BI "int sigreturn(...);"
+.B int sigreturn(...);
.fi
.SH DESCRIPTION
If the Linux kernel determines that an unblocked
.I sigaction
structure,
and sets the
-.BR SA_RESTORER
+.B SA_RESTORER
flag in the
-.IR sa_flags
+.I sa_flags
field.
.PP
The saved process context information is placed in a
as the third argument of a handler established via
.BR sigaction (2)
with the
-.BR SA_SIGINFO
+.B SA_SIGINFO
flag.
.PP
On some other UNIX systems,
a new system call,
.BR rt_sigreturn ()
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type.
The GNU C library
hides these details from us, transparently employing
.BR sigsuspend ().
However, with the addition of real-time signals in Linux 2.2,
the fixed-size, 32-bit
-.IR sigset_t
+.I sigset_t
type supported by that system call was no longer fit for purpose.
Consequently, a new system call,
.BR rt_sigsuspend (),
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type.
The new system call takes a second argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the signal set in
.IR mask .
This argument is currently required to have the value
-.IR sizeof(sigset_t)
+.I sizeof(sigset_t)
(or the error
.B EINVAL
results).
.BR sigtimedwait (),
can't be used to receive signals that
are synchronously generated, such as the
-.BR SIGSEGV
+.B SIGSEGV
signal that results from accessing an invalid memory address
or the
-.BR SIGFPE
+.B SIGFPE
signal that results from an arithmetic error.
Such signals can be caught only via signal handler.
.PP
Consequently, a new system call,
.BR rt_sigtimedwait (),
was added to support an enlarged
-.IR sigset_t
+.I sigset_t
type.
The new system call takes a fourth argument,
.IR "size_t sigsetsize" ,
which specifies the size in bytes of the signal set in
.IR set .
This argument is currently required to have the value
-.IR sizeof(sigset_t)
+.I sizeof(sigset_t)
(or the error
.B EINVAL
results).
l1 lw40 l.
Name:Purpose:Man page
T{
-.BR AF_UNIX
+.B AF_UNIX
T}:T{
Local communication
T}:T{
.TP 16
.B SOCK_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
Since Linux 2.6.27,
.BR socketpair ()
supports the
-.BR SOCK_NONBLOCK
+.B SOCK_NONBLOCK
and
-.BR SOCK_CLOEXEC
+.B SOCK_CLOEXEC
flags in the
.I type
argument, as described in
.B EAGAIN
.B SPLICE_F_NONBLOCK
was specified in
-.IR flags
+.I flags
or one of the file descriptors had been marked as nonblocking
.RB ( O_NONBLOCK ) ,
and the operation would block.
.IP
Because the context cannot be removed from the SPU, some functionality
is disabled for
-.BR SPU_CREATE_NOSCHED
+.B SPU_CREATE_NOSCHED
contexts.
Only a subset of the files will be
available in this context directory in
.BR spufs .
Additionally,
-.BR SPU_CREATE_NOSCHED
+.B SPU_CREATE_NOSCHED
contexts cannot dump a core file when crashing.
.IP
Creating
-.BR SPU_CREATE_NOSCHED
+.B SPU_CREATE_NOSCHED
contexts requires the
.B CAP_SYS_NICE
capability.
.I spu_status
register value is a bit mask of status codes and
optionally a 14-bit code returned from the
-.BR stop-and-signal
+.B stop-and-signal
instruction on the SPU.
The bit masks for the status codes
are:
.TP
.B 0x02
SPU was stopped by a
-.BR stop-and-signal
+.B stop-and-signal
instruction.
.TP
.B 0x04
SPU was stopped by a
-.BR halt
+.B halt
instruction.
.TP
.B 0x08
.TP
.B 0x3fff0000
The bits masked with this value contain the code returned from a
-.BR stop-and-signal
+.B stop-and-signal
instruction.
These bits are valid only if the 0x02 bit is set.
.PP
structure may contain state information from different moments
during the execution of the system call.
For example, if
-.IR st_mode
+.I st_mode
or
-.IR st_uid
+.I st_uid
is changed by another process by calling
.BR chmod (2)
or
If
.I pathname
is an empty string, operate on the file referred to by
-.IR dirfd
+.I dirfd
(which may have been obtained using the
.BR open (2)
.B O_PATH
on a symbolic link need return valid information only in the
.I st_size
field and the file type of the
-.IR st_mode
+.I st_mode
field of the
-.IR stat
+.I stat
structure.
POSIX.1-2008 tightens the specification, requiring
.BR lstat ()
.I stat
structure dealt with by the different versions are, respectively:
.TP
-.IR __old_kernel_stat
+.I __old_kernel_stat
The original structure, with rather narrow fields, and no padding.
.TP
-.IR stat
+.I stat
Larger
.I st_ino
field and padding added to various parts of the structure to
allow for future expansion.
.TP
-.IR stat64
+.I stat64
Even larger
.I st_ino
field,
and some are hardcoded in kernel sources.
.PP
The
-.IR f_flags
+.I f_flags
field is a bit mask indicating mount options for the filesystem.
It contains zero or more of the following bits:
.\" XXX Keep this list in sync with statvfs(3)
.IR pathname ,
.IR dirfd ,
and
-.IR flags
+.I flags
to identify the target file in one of the following ways:
.TP
An absolute pathname
If
.I pathname
is a string that begins with a character other than a slash and
-.IR dirfd
+.I dirfd
is
.BR AT_FDCWD ,
then
.TP
By file descriptor
If
-.IR pathname
+.I pathname
is an empty string and the
.B AT_EMPTY_PATH
flag is specified in
-.IR flags
+.I flags
(see below),
then the target file is the one referred to by the file descriptor
.IR dirfd .
.I flags
is constructed by ORing together zero or more of the following constants:
.TP
-.BR AT_EMPTY_PATH
+.B AT_EMPTY_PATH
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
If
.I pathname
is an empty string, operate on the file referred to by
-.IR dirfd
+.I dirfd
(which may have been obtained using the
.BR open (2)
.B O_PATH
.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
to obtain its definition.
.TP
-.BR AT_NO_AUTOMOUNT
+.B AT_NO_AUTOMOUNT
Don't automount the terminal ("basename") component of
.I pathname
if it is a directory that is an automount point.
structure may contain state information from different moments
during the execution of the system call.
For example, if
-.IR stx_mode
+.I stx_mode
or
-.IR stx_uid
+.I stx_uid
is changed by another process by calling
.BR chmod (2)
or
.TP
.I stx_attributes_mask
A mask indicating which bits in
-.IR stx_attributes
+.I stx_attributes
are supported by the VFS and the filesystem.
.TP
.I stx_atime
.BR mprotect (2),
.BR syscall (2)
.PP
-.IR Documentation/admin\-guide/mm/hugetlbpage.rst
+.I Documentation/admin\-guide/mm/hugetlbpage.rst
in the Linux kernel source tree
.RB ( symlinkat ())
.I linkpath
is a relative pathname and
-.IR newdirfd
+.I newdirfd
refers to a directory that has been deleted.
.TP
.B ENOMEM
.I linkpath
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR newdirfd
+.I newdirfd
argument.
.SH SEE ALSO
.BR ln (1),
.SH ERRORS
.TP
.B EFAULT
-.IR info
+.I info
is not a valid address.
.SH VERSIONS
.BR sysinfo ()
intended to be portable.
.SH NOTES
All of the information provided by this system call is also available via
-.IR /proc/meminfo
+.I /proc/meminfo
and
.IR /proc/loadavg .
.SH SEE ALSO
.IR len ,
which must be an integer between 1 and 8 (inclusive).
The kernel silently enforces a minimum value of
-.IR minimum_console_loglevel
+.I minimum_console_loglevel
for
.IR len .
See the
-.IR "log level"
+.I log level
section for details.
The
.I bufp
command types 3 and 10 are allowed to unprivileged processes;
since Linux 2.6.37,
these commands are allowed to unprivileged processes only if
-.IR /proc/sys/kernel/dmesg_restrict
+.I /proc/sys/kernel/dmesg_restrict
has the value 0.
Before Linux 2.6.37, "privileged" means that the caller has the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
Since Linux 2.6.37,
"privileged" means that the caller has either the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability (now deprecated for this purpose) or the (new)
-.BR CAP_SYSLOG
+.B CAP_SYSLOG
capability.
.\"
.\"
and to 15 in case
of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
The value of
-.IR console_loglevel
+.I console_loglevel
can be set (to a value in the range 1\(en8) by a
.BR syslog ()
call with a
.TP
.I default_message_loglevel
This value will be used as the log level for
-.IR printk()
+.I printk()
messages that do not have an explicit level.
Up to and including Linux 2.6.38,
the hard-coded default value for this field was 4
.TE
.sp 1
The kernel
-.IR printk()
+.I printk()
routine will print a message on the
console only if it has a log level less than the value of
.IR console_loglevel .
This
.BR syslog ()
system call is not available, because the kernel was compiled with the
-.BR CONFIG_PRINTK
+.B CONFIG_PRINTK
kernel-configuration option disabled.
.TP
.B EPERM
(more precisely: without the
.B CAP_SYS_ADMIN
or
-.BR CAP_SYSLOG
+.B CAP_SYSLOG
capability).
.TP
.B ERESTARTSYS
.B EAGAIN
.B SPLICE_F_NONBLOCK
was specified in
-.IR flags
+.I flags
or one of the file descriptors had been marked as nonblocking
.RB ( O_NONBLOCK ) ,
and the operation would block.
.BR CLOCK_MONOTONIC ,
this is a monotonically increasing clock.
However, whereas the
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
clock does not measure the time while a system is suspended, the
-.BR CLOCK_BOOTTIME
+.B CLOCK_BOOTTIME
clock does include the time during which the system is suspended.
This is useful for applications that need to be suspend-aware.
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
is not suitable for such applications, since that clock is affected
by discontinuous changes to the system clock.
.TP
.I sevp.sigev_notify
field can have the following values:
.TP
-.BR SIGEV_NONE
+.B SIGEV_NONE
Don't asynchronously notify when the timer expires.
Progress of the timer can be monitored using
.BR timer_gettime (2).
.TP
-.BR SIGEV_SIGNAL
+.B SIGEV_SIGNAL
Upon timer expiration, generate the signal
.I sigev_signo
for the process.
.BR timer_getoverrun (2)
for more details.
.TP
-.BR SIGEV_THREAD
+.B SIGEV_THREAD
Upon timer expiration, invoke
.I sigev_notify_function
as if it were the start function of a new thread.
.IR sigev_notify_thread_id ,
which must be a thread in the same process as the caller.
The
-.IR sigev_notify_thread_id
+.I sigev_notify_thread_id
field specifies a kernel thread ID, that is, the value returned by
.BR clone (2)
or
.IR sigev_notify ,
.IR sigev_signo ,
or
-.IR sigev_notify_thread_id
+.I sigev_notify_thread_id
is invalid.
.TP
.B ENOMEM
.B EPERM
.I clockid
was
-.BR CLOCK_REALTIME_ALARM
+.B CLOCK_REALTIME_ALARM
or
-.BR CLOCK_BOOTTIME_ALARM
+.B CLOCK_BOOTTIME_ALARM
but the caller did not have the
-.BR CAP_WAKE_ALARM
+.B CAP_WAKE_ALARM
capability.
.SH VERSIONS
This system call is available since Linux 2.6.
for each timer created using
.BR timer_create ().
Consequently, the number of timers is limited by the
-.BR RLIMIT_SIGPENDING
+.B RLIMIT_SIGPENDING
resource limit (see
.BR setrlimit (2)).
.PP
Disarm and delete a timer.
.PP
Since Linux 3.10, the
-.IR /proc/[pid]/timers
+.IR /proc/ pid /timers
file can be used to list the POSIX timers for the process with PID
.IR pid .
See
.\" baa73d9e478ff32d62f3f9422822b59dd9a95a21
support for POSIX timers is a configurable option that is enabled by default.
Kernel support can be disabled via the
-.BR CONFIG_POSIX_TIMERS
+.B CONFIG_POSIX_TIMERS
option.
.\"
.SS C library/kernel differences
In particular:
.IP * 3
Much of the functionality for
-.BR SIGEV_THREAD
+.B SIGEV_THREAD
is implemented within glibc, rather than the kernel.
(This is necessarily so,
since the thread involved in handling the notification is one
internally the NPTL implementation uses a
.I sigev_notify
value of
-.BR SIGEV_THREAD_ID
+.B SIGEV_THREAD_ID
along with a real-time signal that is reserved by the implementation (see
.BR nptl (7)).
.IP *
The time remaining until the next timer expiration is returned in
.IR curr_value\->it_value ;
this is always a relative value, regardless of whether the
-.BR TIMER_ABSTIME
+.B TIMER_ABSTIME
flag was used when arming the timer.
If the value returned in
-.IR curr_value\->it_value
+.I curr_value\->it_value
is zero, then the timer is currently disarmed.
The timer interval is returned in
.IR curr_value\->it_interval .
If the value returned in
-.IR curr_value\->it_interval
+.I curr_value\->it_interval
is zero, then this is a "one-shot" timer.
.SH RETURN VALUE
On success,
.BR CLOCK_MONOTONIC ,
this is a monotonically increasing clock.
However, whereas the
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
clock does not measure the time while a system is suspended, the
-.BR CLOCK_BOOTTIME
+.B CLOCK_BOOTTIME
clock does include the time during which the system is suspended.
This is useful for applications that need to be suspend-aware.
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
is not suitable for such applications, since that clock is affected
by discontinuous changes to the system clock.
.TP
.BR clock_gettime (2).
.PP
Starting with Linux 2.6.27, the following values may be bitwise ORed in
-.IR flags
+.I flags
to change the behavior of
.BR timerfd_create ():
.TP 14
.B TFD_NONBLOCK
Set the
-.BR O_NONBLOCK
+.B O_NONBLOCK
file status flag on the open file description (see
.BR open (2))
referred to by the new file descriptor.
clock reaches the value specified in
.IR new_value.it_value .
.TP
-.BR TFD_TIMER_CANCEL_ON_SET
+.B TFD_TIMER_CANCEL_ON_SET
If this flag is specified along with
.B TFD_TIMER_ABSTIME
and the clock for this timer is
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
or
.BR CLOCK_REALTIME_ALARM ,
then mark this timer as cancelable if the real-time clock
returns, in
.IR curr_value ,
an
-.IR itimerspec
+.I itimerspec
structure that contains the current setting of the timer
referred to by the file descriptor
.IR fd .
If both fields of this structure are zero,
then the timer is currently disarmed.
This field always contains a relative value, regardless of whether the
-.BR TFD_TIMER_ABSTIME
+.B TFD_TIMER_ABSTIME
flag was specified when setting the timer.
.PP
The
if the size of the supplied buffer is less than 8 bytes.
.IP
If the associated clock is either
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
or
.BR CLOCK_REALTIME_ALARM ,
the timer is absolute
.RB ( TFD_TIMER_ABSTIME ),
and the flag
-.BR TFD_TIMER_CANCEL_ON_SET
+.B TFD_TIMER_CANCEL_ON_SET
was specified when calling
.BR timerfd_settime (),
then
.BR read (2)
fails with the error
-.BR ECANCELED
+.B ECANCELED
if the real-time clock undergoes a discontinuous change.
(This allows the reading application to discover
such discontinuous changes to the clock.)
.IP
If the associated clock is either
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
or
.BR CLOCK_REALTIME_ALARM ,
the timer is absolute
.RB ( TFD_TIMER_ABSTIME ),
and the flag
-.BR TFD_TIMER_CANCEL_ON_SET
+.B TFD_TIMER_CANCEL_ON_SET
was
.I not
specified when calling
The only purpose of this command is to restore the expirations
for the purpose of checkpoint/restore.
This operation is available only if the kernel was configured with the
-.BR CONFIG_CHECKPOINT_RESTORE
+.B CONFIG_CHECKPOINT_RESTORE
option.
.RE
.TP
.B EPERM
.I clockid
was
-.BR CLOCK_REALTIME_ALARM
+.B CLOCK_REALTIME_ALARM
or
-.BR CLOCK_BOOTTIME_ALARM
+.B CLOCK_BOOTTIME_ALARM
but the caller did not have the
-.BR CAP_WAKE_ALARM
+.B CAP_WAKE_ALARM
capability.
.PP
.BR timerfd_settime ()
These system calls are Linux-specific.
.SH NOTES
Suppose the following scenario for
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
or
-.BR CLOCK_REALTIME_ALARM
+.B CLOCK_REALTIME_ALARM
timer that was created with
.BR timerfd_create ():
.IP (a) 4
The timer has been started
.RB ( timerfd_settime ())
with the
-.BR TFD_TIMER_ABSTIME
+.B TFD_TIMER_ABSTIME
and
-.BR TFD_TIMER_CANCEL_ON_SET
+.B TFD_TIMER_CANCEL_ON_SET
flags;
.IP (b)
A discontinuous change (e.g.,
.BR settimeofday (2))
is subsequently made to the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock; and
.IP (c)
the caller once more calls
.SH BUGS
A header file bug in glibc 2.12 meant that the minimum value of
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
required to expose the declaration of
.BR ftruncate ()
was 200809L instead of 200112L.
argument are turned off.
For example, the following default ACL is equivalent to a umask of 022:
.PP
- u::rwx,g::r-x,o::r-x
+.in +4n
+.EX
+u::rwx,g::r-x,o::r-x
+.EE
+.in
.PP
Combining the effect of this default ACL with a
.I mode
Since Linux 4.7, the umask of any process can be viewed via the
.I Umask
field of
-.IR /proc/[pid]/status .
+.IR /proc/ pid /status .
Inspecting this field in
-.IR /proc/self/status
+.I /proc/self/status
allows a process to retrieve its umask without at the same time changing it.
.PP
The umask setting also affects the permissions assigned to POSIX IPC objects
some processes still have active references to the filesystem,
the unmount will still fail.
As at Linux 4.12,
-.BR MNT_FORCE
+.B MNT_FORCE
is supported only on the following filesystems:
9p (since Linux 2.6.16),
ceph (since Linux 2.6.34),
.B EPERM
The caller does not have the required privileges.
.SH VERSIONS
-.BR MNT_DETACH
+.B MNT_DETACH
and
-.BR MNT_EXPIRE
+.B MNT_EXPIRE
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092
are available in glibc since version 2.11.
.SH CONFORMING TO
On such systems,
recursively bind mounting the root directory of the filesystem
onto a subdirectory and then later unmounting that subdirectory with
-.BR MNT_DETACH
+.B MNT_DETACH
will cause every mount in the mount namespace to be lazily unmounted.
.PP
To ensure
call with a
.I mount_flags
argument that includes both
-.BR MS_REC
+.B MS_REC
and
-.BR MS_PRIVATE
+.B MS_PRIVATE
prior to
.BR umount ()
being called.
(See also
.BR path_resolution (7).)
.TP
-.BR EBUSY
+.B EBUSY
The file
.I pathname
cannot be unlinked because it is being used by the system
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
-.IR /proc/self/fd
+.I /proc/self/fd
that corresponds to the
-.IR dirfd
+.I dirfd
argument.
.SH BUGS
Infelicities in the protocol underlying NFS can cause the unexpected
flag.
Unshare the cgroup namespace.
Use of
-.BR CLONE_NEWCGROUP
+.B CLONE_NEWCGROUP
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.BR CLONE_NEWIPC " (since Linux 2.6.19)"
so that the calling process has a private copy of the
IPC namespace which is not shared with any other process.
Specifying this flag automatically implies
-.BR CLONE_SYSVSEM
+.B CLONE_SYSVSEM
as well.
Use of
-.BR CLONE_NEWIPC
+.B CLONE_NEWIPC
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.BR CLONE_NEWNET " (since Linux 2.6.24)"
new network namespace which is not shared
with any previously existing process.
Use of
-.BR CLONE_NEWNET
+.B CLONE_NEWNET
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.B CLONE_NEWNS
.B CLONE_FS
as well.
Use of
-.BR CLONE_NEWNS
+.B CLONE_NEWNS
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
For further information, see
.BR mount_namespaces (7).
the process ID 1 and will assume the role of
.BR init (1)
in the new namespace.
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
automatically implies
-.BR CLONE_THREAD
+.B CLONE_THREAD
as well.
Use of
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
For further information, see
.BR pid_namespaces (7).
.I not
moved into the new namespace.
Use of
-.BR CLONE_NEWTIME
+.B CLONE_NEWTIME
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
For further information, see
.BR time_namespaces (7).
.B CLONE_NEWUSER
flag, the caller obtains a full set of capabilities in the new namespace.
.IP
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
requires that the calling process is not threaded; specifying
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
automatically implies
.BR CLONE_THREAD .
Since Linux 3.9,
.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
.\" https://lwn.net/Articles/543273/
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
also automatically implies
.BR CLONE_FS .
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
requires that the user ID and group ID
of the calling process are mapped to user IDs and group IDs in the
user namespace of the calling process at the time of the call.
so that the calling process has a private copy of the
UTS namespace which is not shared with any other process.
Use of
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.BR CLONE_SYSVSEM " (since Linux 2.6.26)"
.BR CLONE_THREAD ,
.BR CLONE_SIGHAND ,
and
-.BR CLONE_VM
+.B CLONE_VM
can be specified in
.I flags
if the caller is single threaded (i.e., it is not sharing
its address space with another process or thread).
In this case, these flags have no effect.
(Note also that specifying
-.BR CLONE_THREAD
+.B CLONE_THREAD
automatically implies
.BR CLONE_VM ,
and specifying
-.BR CLONE_VM
+.B CLONE_VM
automatically implies
.BR CLONE_SIGHAND .)
.\" As at 3.9, the following forced implications also apply,
.BR CLONE_THREAD ,
.BR CLONE_SIGHAND ,
or
-.BR CLONE_VM
+.B CLONE_VM
was specified in
.IR flags ,
and the caller is multithreaded.
.TP
.B EINVAL
-.BR CLONE_NEWIPC
+.B CLONE_NEWIPC
was specified in
.IR flags ,
but the kernel was not configured with the
.B CONFIG_SYSVIPC
and
-.BR CONFIG_IPC_NS
+.B CONFIG_IPC_NS
options.
.TP
.B EINVAL
-.BR CLONE_NEWNET
+.B CLONE_NEWNET
was specified in
.IR flags ,
but the kernel was not configured with the
option.
.TP
.B EINVAL
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
was specified in
.IR flags ,
but the kernel was not configured with the
option.
.TP
.B EINVAL
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
was specified in
.IR flags ,
but the kernel was not configured with the
option.
.TP
.B EINVAL
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
was specified in
.IR flags ,
but the kernel was not configured with the
option.
.TP
.B EINVAL
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
was specified in
.IR flags ,
but the process has previously called
.BR unshare ()
with the
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
flag.
.TP
.B ENOMEM
.I flags
specified the creation of a new user namespace,
but doing so would have caused the limit defined by the corresponding file in
-.IR /proc/sys/user
+.I /proc/sys/user
to be exceeded.
For further details, see
.BR namespaces (7).
The calling process did not have the required privileges for this operation.
.TP
.B EPERM
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
was specified in
.IR flags ,
but either the effective user ID or the effective group ID of the caller
.IR flags ,
and the limit on the number of nested user namespaces would be exceeded.
See the discussion of the
-.BR ENOSPC
+.B ENOSPC
error above.
.SH VERSIONS
The
.BR fcntl (2).
.PP
The following values may be bitwise ORed in
-.IR flags
+.I flags
to change the behavior of
.BR userfaultfd ():
.TP
-.BR O_CLOEXEC
+.B O_CLOEXEC
Enable the close-on-exec flag for the new userfaultfd file descriptor.
See the description of the
.B O_CLOEXEC
flag in
.BR open (2).
.TP
-.BR O_NONBLOCK
+.B O_NONBLOCK
Enables non-blocking operation for the userfaultfd object.
See the description of the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag in
.BR open (2).
.PP
This operation must be performed before any of the other
.BR ioctl (2)
operations described below (or those operations fail with the
-.BR EINVAL
+.B EINVAL
error).
.PP
After a successful
write-protect notifications will always have the
.B UFFD_PAGEFAULT_FLAG_WRITE
bit set along with the
-.BR UFFD_PAGEFAULT_FLAG_WP
+.B UFFD_PAGEFAULT_FLAG_WP
bit.
.PP
To resolve a write-protection page fault, the user should initiate another
(or
.BR clone (2)
without the
-.BR CLONE_VM
+.B CLONE_VM
flag).
The event details are available in the
.I fork
Generated when the faulting process invokes
.BR madvise (2)
with
-.BR MADV_DONTNEED
+.B MADV_DONTNEED
or
-.BR MADV_REMOVE
+.B MADV_REMOVE
advice.
The event details are available in the
.I remove
.TP
.B EINVAL
The userfaultfd object has not yet been enabled using the
-.BR UFFDIO_API
+.B UFFDIO_API
.BR ioctl (2)
operation
.PP
flag is not enabled, then
.BR poll (2)
(always) indicates the file as having a
-.BR POLLERR
+.B POLLERR
condition, and
.BR select (2)
indicates the file descriptor as both readable and writable.
An unsupported value was specified in
.IR flags .
.TP
-.BR EMFILE
+.B EMFILE
The per-process limit on the number of open file descriptors has been
reached
.TP
.SH NOTES
The userfaultfd mechanism can be used as an alternative to
traditional user-space paging techniques based on the use of the
-.BR SIGSEGV
+.B SIGSEGV
signal and
.BR mmap (2).
It can also be used to implement lazy restore
.BR madvise (2),
.BR mmap (2)
.PP
-.IR Documentation/admin\-guide/mm/userfaultfd.rst
+.I Documentation/admin\-guide/mm/userfaultfd.rst
in the Linux kernel source tree
.I pathname
is relative, then by default it is interpreted relative to the
directory referred to by the open file descriptor,
-.IR dirfd
+.I dirfd
(rather than relative to the current working directory of
the calling process, as is done by
.BR utimes (2)
is relative but
.I dirfd
is neither
-.BR AT_FDCWD
+.B AT_FDCWD
nor a valid file descriptor.
.TP
.B EFAULT
the caller's effective user ID does not match the owner of file,
and the caller is not privileged
(Linux: does not have the
-.BR CAP_FOWNER
+.B CAP_FOWNER
capability); or,
.IP *
.\" Linux 2.6.22 was broken here:
then the Linux implementation of
.BR utimensat ()
succeeds even if the file referred to by
-.IR dirfd
+.I dirfd
and
.I pathname
does not exist.
disallows passing NULL as the value for
.IR pathname :
the wrapper function returns the error
-.BR EINVAL
+.B EINVAL
in this case.
.SH BUGS
Several bugs afflict
the case where both
.I tv_nsec
fields are set to
-.BR UTIME_NOW
+.B UTIME_NOW
isn't always treated the same as specifying
.I times
as NULL,
On systems where memory is constrained,
.BR vfork ()
avoids the need to temporarily commit memory (see the description of
-.IR /proc/sys/vm/overcommit_memory
+.I /proc/sys/vm/overcommit_memory
in
.BR proc (5))
in order to execute a new program.
.I flags
specified as:
.PP
- CLONE_VM | CLONE_VFORK | SIGCHLD
+.in +4n
+.EX
+ CLONE_VM | CLONE_VFORK | SIGCHLD
+.EE
+.in
.SS History
The
.BR vfork ()
.BR vm86 ()
was introduced.
The definition of
-.IR "struct vm86_struct"
+.I struct vm86_struct
was changed
in 1.1.8 and 1.1.9.
.PP
See
.BR open (2)
for further details on the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag.
.TP
.BR EAGAIN " or " EWOULDBLOCK
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH INFINITY 3 2020-12-21 "" "Linux Programmer's Manual"
+.TH INFINITY 3 2020-12-21 GNU "Linux Programmer's Manual"
.SH NAME
INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL \- floating-point constants
.SH LIBRARY
Manual"
.SH NAME
__ppc_get_timebase, __ppc_get_timebase_freq \- get the current value
- of the Time Base Register on Power architecture and its frequency.
+of the Time Base Register on Power architecture and its frequency.
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.nf
.B #include <sys/platform/ppc.h>
.PP
-.BI "uint64_t __ppc_get_timebase(void);"
-.BI "uint64_t __ppc_get_timebase_freq(void);"
+.B uint64_t __ppc_get_timebase(void);
+.B uint64_t __ppc_get_timebase_freq(void);
.fi
.SH DESCRIPTION
.BR __ppc_get_timebase ()
.IP * 3
.BR __ppc_set_ppr_med ()
sets the Program Priority Register value to
-.IR medium
+.I medium
(default).
.IP *
.BR __ppc_set_ppr_very_low ()
.IR "medium low" .
.PP
The privileged state
-.IR "medium high"
+.I medium high
may also be set during certain time intervals by problem-state (unprivileged)
programs, with the following function:
.IP * 3
.SH SEE ALSO
.BR __ppc_yield (3)
.PP
-.IR "Power ISA, Book\ II - Section\ 3.1 (Program Priority Registers)"
+.I Power ISA, Book\~II - Section\ 3.1 (Program Priority Registers)
.\"
.\" Corrected, aeb, 2002-05-30
.\"
-.TH A64L 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH A64L 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
a64l, l64a \- convert between long and base-64
.SH LIBRARY
.\" Modified 2002-07-25 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ACOS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ACOS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
acos, acosf, acosl \- arc cosine function
.SH LIBRARY
.IR x .
.SH RETURN VALUE
On success, these functions return the arc cosine of
-.IR x
+.I x
in radians; the return value is in the range [0,\ pi].
.PP
If
.\" Modified 2002-07-25 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ACOSH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ACOSH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
acosh, acoshf, acoshl \- inverse hyperbolic cosine function
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_CANCEL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_CANCEL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_cancel \- cancel an outstanding asynchronous I/O request
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_ERROR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_ERROR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_error \- get error status of asynchronous I/O operation
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_FSYNC 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_FSYNC 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_fsync \- asynchronous file synchronization
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_READ 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_READ 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_read \- asynchronous read
.SH LIBRARY
.BR read (2).
The arguments of the call
.PP
- read(fd, buf, count)
+.in +4n
+.EX
+read(fd, buf, count)
+.EE
+.in
.PP
correspond (in order) to the fields
.IR aio_fildes ,
.IR aio_buf ,
and
-.IR aio_nbytes
+.I aio_nbytes
of the structure pointed to by
.IR aiocbp .
(See
The return status of a completed I/O operation can be obtained by
.BR aio_return (3).
Asynchronous notification of I/O completion can be obtained by setting
-.IR aiocbp\->aio_sigevent
+.I aiocbp\->aio_sigevent
appropriately; see
.BR sigevent (7)
for details.
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_RETURN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_RETURN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_return \- get return status of asynchronous I/O operation
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_SUSPEND 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_SUSPEND 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_suspend \- wait for asynchronous I/O operation or timeout
.SH LIBRARY
that specifies a zero time interval.
.PP
If one or more of the asynchronous I/O operations specified in
-.IR aiocb_list
+.I aiocb_list
has already completed at the time of the call to
.BR aio_suspend (),
then the call returns immediately.
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH AIO_WRITE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH AIO_WRITE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
aio_write \- asynchronous write
.SH LIBRARY
.BR write (2).
The arguments of the call
.PP
- write(fd, buf, count)
+.in +4n
+.EX
+write(fd, buf, count)
+.EE
+.in
.PP
correspond (in order) to the fields
.IR aio_fildes ,
.IR aio_buf ,
and
-.IR aio_nbytes
+.I aio_nbytes
of the structure pointed to by
.IR aiocbp .
(See
The return status of a completed I/O operation can be obtained
.BR aio_return (3).
Asynchronous notification of I/O completion can be obtained by setting
-.IR aiocbp\->aio_sigevent
+.I aiocbp\->aio_sigevent
appropriately; see
.BR sigevent (7)
for details.
.\" based on the description in glibc source and infopages
.\"
.\" Corrections and additions, aeb
-.TH ARGZ_ADD 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ARGZ_ADD 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
argz_add, argz_add_sep, argz_append, argz_count, argz_create,
argz_create_sep, argz_delete, argz_extract, argz_insert,
after
.RI ( *argz ,\ *argz_len )
and updates
-.IR *argz
+.I *argz
and
.IR *argz_len .
(Thus,
.IR sep .
.SH RETURN VALUE
All argz functions that do memory allocation have a return type of
-.IR error_t
+.I error_t
(an integer type),
and return 0 for success, and
.B ENOMEM
.\" Modified 2002-07-25 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ASIN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ASIN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
asin, asinf, asinl \- arc sine function
.SH LIBRARY
.IR x .
.SH RETURN VALUE
On success, these functions return the principal value of the arc sine of
-.IR x
+.I x
in radians; the return value is in the range [\-pi/2,\ pi/2].
.PP
If
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ATAN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ATAN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
atan, atanf, atanl \- arc tangent function
.SH LIBRARY
.IR x .
.SH RETURN VALUE
On success, these functions return the principal value of the arc tangent of
-.IR x
+.I x
in radians; the return value is in the range [\-pi/2,\ pi/2].
.PP
If
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ATAN2 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ATAN2 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
atan2, atan2f, atan2l \- arc tangent function of two variables
.SH LIBRARY
the quadrant of the result.
.SH RETURN VALUE
On success, these functions return the principal value of the arc tangent of
-.IR y/x
+.I y/x
in radians; the return value is in the range [\-pi,\ pi].
.PP
If
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH ATANH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ATANH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
atanh, atanhf, atanhl \- inverse hyperbolic tangent function
.SH LIBRARY
Pole error: \fIx\fP is +1 or \-1
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
when a pole error occurs,
.I errno
is set to
-.BR EDOM
+.B EDOM
instead of the POSIX-mandated
.BR ERANGE .
Since version 2.10, glibc does the right thing.
.\" 2007-05-31, mtk: Rewrite and substantial additional text.
.\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors
.\"
-.TH BINDRESVPORT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH BINDRESVPORT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
bindresvport \- bind a socket to a privileged IP port
.SH LIBRARY
.BR bind (2).
In addition, the following errors may occur:
.TP
-.BR EACCES
+.B EACCES
The calling process was not privileged
(on Linux: the calling process did not have the
.B CAP_NET_BIND_SERVICE
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH BSD_SIGNAL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH BSD_SIGNAL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
bsd_signal \- signal handling with BSD semantics
.SH LIBRARY
.\" 386BSD man pages
.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe
.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu)
-.TH BSEARCH 3 2021-08-27 "" "Linux Programmer's Manual"
+.TH BSEARCH 3 2021-08-27 GNU "Linux Programmer's Manual"
.SH NAME
bsearch \- binary search of a sorted array
.SH LIBRARY
.\" Modified 1993-04-12, David Metcalfe
.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
.\" Modified 2002-01-20, Walter Harms
-.TH BSTRING 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH BSTRING 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem,
memmove, memset \- byte string operations
.\"
.\" @(#)btree.3 8.4 (Berkeley) 8/18/94
.\"
-.TH BTREE 3 2020-12-21 "" "Linux Programmer's Manual"
+.TH BTREE 3 2020-12-21 GNU "Linux Programmer's Manual"
.\".UC 7
.SH NAME
btree \- btree database access method
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CABS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CABS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cabs, cabsf, cabsl \- absolute value of a complex number
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CACOS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CACOS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cacos, cacosf, cacosl \- complex arc cosine
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CACOSH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CACOSH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine
.SH LIBRARY
.I canonicalize_file_name(path)
is equivalent to the call:
.PP
- realpath(path, NULL);
+.in +4n
+.EX
+realpath(path, NULL);
+.EE
+.in
.SH RETURN VALUE
On success,
.BR canonicalize_file_name ()
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CARG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CARG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
carg, cargf, cargl \- calculate the complex argument
.SH LIBRARY
A complex number can be described by two real coordinates.
One may use rectangular coordinates and gets
.PP
-.nf
- z = x + I * y
-.fi
+.in +4n
+.EX
+z = x + I * y
+.EE
+.in
.PP
where
-.IR "x\ =\ creal(z)"
+.I x\~=\~creal(z)
and
-.IR "y\ =\ cimag(z)" .
+.IR y\~=\~cimag(z) .
.PP
Or one may use polar coordinates and gets
.PP
-.nf
- z = r * cexp(I * a)
-.fi
+.in +4n
+.EX
+z = r * cexp(I * a)
+.EE
+.in
.PP
where
-.IR "r\ =\ cabs(z)"
+.I r\~=\~cabs(z)
is the "radius", the "modulus", the absolute value of
.IR z ,
and
-.IR "a\ =\ carg(z)"
+.I a\~=\~carg(z)
is the "phase angle", the argument of
.IR z .
.PP
One has:
.PP
-.nf
- tan(carg(z)) = cimag(z) / creal(z)
-.fi
+.in +4n
+.EX
+tan(carg(z)) = cimag(z) / creal(z)
+.EE
+.in
.SH RETURN VALUE
The return value is in the range of [\-pi,pi].
.SH VERSIONS
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CASIN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CASIN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
casin, casinf, casinl \- complex arc sine
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CASINH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CASINH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
casinh, casinhf, casinhl \- complex arc sine hyperbolic
.SH LIBRARY
.SH DESCRIPTION
These functions calculate the complex arc hyperbolic sine of
.IR z .
-If \fIy\ =\ casinh(z)\fP, then \fIz\ =\ csinh(y)\fP.
+If \fIy\~=\~casinh(z)\fP, then \fIz\~=\~csinh(y)\fP.
The imaginary part of
.I y
is chosen in the interval [\-pi/2,pi/2].
.PP
One has:
.PP
-.nf
- casinh(z) = clog(z + csqrt(z * z + 1))
-.fi
+.in +4n
+.EX
+casinh(z) = clog(z + csqrt(z * z + 1))
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CATAN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CATAN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
catan, catanf, catanl \- complex arc tangents
.SH LIBRARY
.SH DESCRIPTION
These functions calculate the complex arc tangent of
.IR z .
-If \fIy\ =\ catan(z)\fP, then \fIz\ =\ ctan(y)\fP.
+If \fIy\~=\~catan(z)\fP, then \fIz\~=\~ctan(y)\fP.
The real part of y is chosen in the interval [\-pi/2,pi/2].
.PP
One has:
.PP
-.nf
- catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i)
-.fi
+.in +4n
+.EX
+catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CATANH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CATANH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
catanh, catanhf, catanhl \- complex arc tangents hyperbolic
.SH LIBRARY
.SH DESCRIPTION
These functions calculate the complex arc hyperbolic tangent of
.IR z .
-If \fIy\ =\ catanh(z)\fP, then \fIz\ =\ ctanh(y)\fP.
+If \fIy\~=\~catanh(z)\fP, then \fIz\~=\~ctanh(y)\fP.
The imaginary part of
.I y
is chosen in the interval [\-pi/2,pi/2].
.PP
One has:
.PP
-.nf
- catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z))
-.fi
+.in +4n
+.EX
+catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z))
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Updated, aeb, 980809
-.TH CATGETS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CATGETS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
catgets \- get message from a message catalog
.SH LIBRARY
.I nl_catd
on success.
On failure, it returns
-.IR "(nl_catd)\ \-1"
+.I (nl_catd)\~\-1
and sets
.I errno
to indicate the error.
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CCOS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CCOS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ccos, ccosf, ccosl \- complex cosine function
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex ccos(double complex " z ");"
-.BI "float complex ccosf(float complex " z ");"
-.BI "long double complex ccosl(long double complex " z ");"
+.BI "double complex ccos(double complex " z );
+.BI "float complex ccosf(float complex " z );
+.BI "long double complex ccosl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex cosine of
.PP
The complex cosine function is defined as:
.PP
-.nf
- ccos(z) = (exp(i * z) + exp(\-i * z)) / 2
-.fi
+.in +4n
+.EX
+ccos(z) = (exp(i * z) + exp(\-i * z)) / 2
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CCOSH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CCOSH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ccosh, ccoshf, ccoshl \- complex hyperbolic cosine
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex ccosh(double complex " z ");"
-.BI "float complex ccoshf(float complex " z ");"
-.BI "long double complex ccoshl(long double complex " z ");"
+.BI "double complex ccosh(double complex " z );
+.BI "float complex ccoshf(float complex " z );
+.BI "long double complex ccoshl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex hyperbolic cosine of
.PP
The complex hyperbolic cosine function is defined as:
.PP
-.nf
- ccosh(z) = (exp(z)+exp(\-z))/2
-.fi
+.in +4n
+.EX
+ccosh(z) = (exp(z)+exp(\-z))/2
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH CONFORMING TO
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH CEIL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CEIL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ceil, ceilf, ceill \- ceiling function: smallest integral value not
less than argument
.IR x .
.PP
For example,
-.IR ceil(0.5)
+.I ceil(0.5)
is 1.0, and
-.IR ceil(\-0.5)
+.I ceil(\-0.5)
is 0.0.
.SH RETURN VALUE
These functions return the ceiling of
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CEXP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CEXP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cexp, cexpf, cexpl \- complex exponential function
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex cexp(double complex " z ");"
-.BI "float complex cexpf(float complex " z ");"
-.BI "long double complex cexpl(long double complex " z ");"
+.BI "double complex cexp(double complex " z );
+.BI "float complex cexpf(float complex " z );
+.BI "long double complex cexpl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate e (2.71828..., the base of natural logarithms)
.PP
One has:
.PP
-.nf
- cexp(I * z) = ccos(z) + I * csin(z)
-.fi
+.in +4n
+.EX
+cexp(I * z) = ccos(z) + I * csin(z)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CEXP2 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CEXP2 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex cexp2(double complex " z ");"
-.BI "float complex cexp2f(float complex " z ");"
-.BI "long double complex cexp2l(long double complex " z ");"
+.BI "double complex cexp2(double complex " z );
+.BI "float complex cexp2f(float complex " z );
+.BI "long double complex cexp2l(long double complex " z );
.fi
.SH DESCRIPTION
The function returns 2 raised to the power of
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH CFREE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CFREE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cfree \- free allocated memory
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CIMAG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CIMAG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cimag, cimagf, cimagl \- get imaginary part of a complex number
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double cimag(double complex " z ");"
-.BI "float cimagf(float complex " z ");"
-.BI "long double cimagl(long double complex " z ");"
+.BI "double cimag(double complex " z );
+.BI "float cimagf(float complex " z );
+.BI "long double cimagl(long double complex " z );
.fi
.SH DESCRIPTION
These functions return the imaginary part of the complex number
.PP
One has:
.PP
-.nf
- z = creal(z) + I * cimag(z)
-.fi
+.in +4n
+.EX
+z = creal(z) + I * cimag(z)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
since glibc 2.18, it is implemented on top of
.BR clock_gettime (2)
(using the
-.BR CLOCK_PROCESS_CPUTIME_ID
+.B CLOCK_PROCESS_CPUTIME_ID
clock).
.SH SEE ALSO
.BR clock_gettime (2),
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CLOG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CLOG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
clog, clogf, clogl \- natural logarithm of a complex number
.SH LIBRARY
.PP
One has:
.PP
-.nf
- clog(z) = log(cabs(z)) + I * carg(z)
-.fi
+.in +4n
+.EX
+clog(z) = log(cabs(z)) + I * carg(z)
+.EE
+.in
.PP
Note that
.I z
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CLOG10 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CLOG10 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
clog10, clog10f, clog10l \- base-10 logarithm of a complex number
.SH LIBRARY
.I clog10(z)
is equivalent to:
.PP
- clog(z)/log(10)
+.in +4n
+.EX
+clog(z)/log(10)
+.EE
+.in
.PP
or equally:
.PP
- log10(cabs(c)) + I * carg(c) / log(10)
+.in +4n
+.EX
+log10(cabs(c)) + I * carg(c) / log(10)
+.EE
+.in
.PP
The other functions perform the same task for
.I float
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CLOG2 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CLOG2 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
clog2, clog2f, clog2l \- base-2 logarithm of a complex number
.SH LIBRARY
.\" 386BSD man pages
.\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
-.TH CLOSEDIR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CLOSEDIR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
closedir \- close a directory
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CONJ 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CONJ 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
conj, conjf, conjl \- calculate the complex conjugate
.SH LIBRARY
.PP
One has:
.PP
-.nf
- cabs(z) = csqrt(z * conj(z))
-.fi
+.in +4n
+.EX
+cabs(z) = csqrt(z * conj(z))
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
-.TH COS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH COS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cos, cosf, cosl \- cosine function
.SH LIBRARY
Domain error: \fIx\fP is an infinity
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH COSH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH COSH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cosh, coshf, coshl \- hyperbolic cosine function
.SH LIBRARY
.IR x ,
which is defined mathematically as:
.PP
-.nf
- cosh(x) = (exp(x) + exp(\-x)) / 2
-.fi
+.in +4n
+.EX
+cosh(x) = (exp(x) + exp(\-x)) / 2
+.EE
+.in
.SH RETURN VALUE
On success, these functions return the hyperbolic cosine of
.IR x .
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CPOW 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CPOW 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cpow, cpowf, cpowl \- complex power function
.SH LIBRARY
These functions calculate
.I x
raised to the power
-.IR z
+.I z
(with a branch cut for
.I x
along the negative real axis.)
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CPROJ 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CPROJ 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
cproj, cprojf, cprojl \- project into Riemann Sphere
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CREAL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CREAL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
creal, crealf, creall \- get real part of a complex number
.SH LIBRARY
.\" added _XOPEN_SOURCE, aeb, 970705
.\" added GNU MD5 stuff, aeb, 011223
.\"
-.TH CRYPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CRYPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
crypt, crypt_r \- password and data encryption
.SH LIBRARY
Glibc 2.27 and earlier:
_XOPEN_SOURCE
.fi
-.BR
.PP
.BR crypt_r ():
.nf
functions are part of the POSIX.1-2008 XSI Options Group for Encryption
and are optional.
If the interfaces are not available, then the symbolic constant
-.BR _XOPEN_CRYPT
+.B _XOPEN_CRYPT
is either not defined,
or it is defined to \-1 and availability can be checked at run time with
.BR sysconf (3).
.IR libxcrypt .
When recompiling applications in such distributions,
the programmer must detect if
-.BR _XOPEN_CRYPT
+.B _XOPEN_CRYPT
is not available and include
.I <crypt.h>
for the function prototypes;
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CSIN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CSIN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
csin, csinf, csinl \- complex sine function
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex csin(double complex " z ");"
+.BI "double complex csin(double complex " z );
.BI "float complex csinf(float complex " z );
-.BI "long double complex csinl(long double complex " z ");"
+.BI "long double complex csinl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex sine of
.PP
The complex sine function is defined as:
.PP
-.nf
- csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i)
-.fi
+.in +4n
+.EX
+csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CSINH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CSINH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
csinh, csinhf, csinhl \- complex hyperbolic sine
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex csinh(double complex " z ");"
-.BI "float complex csinhf(float complex " z ");"
-.BI "long double complex csinhl(long double complex " z ");"
+.BI "double complex csinh(double complex " z );
+.BI "float complex csinhf(float complex " z );
+.BI "long double complex csinhl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex hyperbolic sine of
.PP
The complex hyperbolic sine function is defined as:
.PP
-.nf
- csinh(z) = (exp(z)\-exp(\-z))/2
-.fi
+.in +4n
+.EX
+csinh(z) = (exp(z)\-exp(\-z))/2
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CSQRT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CSQRT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
csqrt, csqrtf, csqrtl \- complex square root
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex csqrt(double complex " z ");"
-.BI "float complex csqrtf(float complex " z ");"
-.BI "long double complex csqrtl(long double complex " z ");"
+.BI "double complex csqrt(double complex " z );
+.BI "float complex csqrtf(float complex " z );
+.BI "long double complex csqrtl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex square root of
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CTAN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CTAN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ctan, ctanf, ctanl \- complex tangent function
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex ctan(double complex " z ");"
+.BI "double complex ctan(double complex " z );
.BI "float complex ctanf(float complex " z );
-.BI "long double complex ctanl(long double complex " z ");"
+.BI "long double complex ctanl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex tangent of
.PP
The complex tangent function is defined as:
.PP
-.nf
- ctan(z) = csin(z) / ccos(z)
-.fi
+.in +4n
+.EX
+ctan(z) = csin(z) / ccos(z)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH CTANH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CTANH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ctanh, ctanhf, ctanhl \- complex hyperbolic tangent
.SH LIBRARY
.nf
.B #include <complex.h>
.PP
-.BI "double complex ctanh(double complex " z ");"
+.BI "double complex ctanh(double complex " z );
.BI "float complex ctanhf(float complex " z );
-.BI "long double complex ctanhl(long double complex " z ");"
+.BI "long double complex ctanhl(long double complex " z );
.fi
.SH DESCRIPTION
These functions calculate the complex hyperbolic tangent of
The complex hyperbolic tangent function is defined
mathematically as:
.PP
-.nf
- ctanh(z) = csinh(z) / ccosh(z)
-.fi
+.in +4n
+.EX
+ctanh(z) = csinh(z) / ccosh(z)
+.EE
+.in
.SH VERSIONS
These functions first appeared in glibc in version 2.1.
.SH ATTRIBUTES
.\" Modified 2001-12-13, joey, aeb
.\" Modified 2004-11-16, mtk
.\"
-.TH CTIME 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH CTIME 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
localtime_r \- transform date and time to broken-down time or ASCII
The
.BR mktime ()
function modifies the fields of the
-.IR tm
+.I tm
structure as follows:
.I tm_wday
and
.\"
.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94
.\"
-.TH DBOPEN 3 2017-09-15 "" "Linux Programmer's Manual"
+.TH DBOPEN 3 2017-09-15 GNU "Linux Programmer's Manual"
.UC 7
.SH NAME
dbopen \- database access methods
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH DES_CRYPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH DES_CRYPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast
DES encryption
.IR mode ,
is formed by ORing together some things.
For the encryption direction OR in either
-.BR DES_ENCRYPT
+.B DES_ENCRYPT
or
.BR DES_DECRYPT .
For software versus hardware
encryption, OR in either
-.BR DES_HW
+.B DES_HW
or
.BR DES_SW .
If
-.BR DES_HW
+.B DES_HW
is specified, and there is no hardware, then the encryption is performed
in software and the routine returns
.BR DESERR_NOHWDEVICE .
vector upon return.
.SH RETURN VALUE
.TP
-.BR DESERR_NONE
+.B DESERR_NONE
No error.
.TP
-.BR DESERR_NOHWDEVICE
+.B DESERR_NOHWDEVICE
Encryption succeeded, but done in software instead of the requested hardware.
.TP
-.BR DESERR_HWERROR
+.B DESERR_HWERROR
An error occurred in the hardware or driver.
.TP
-.BR DESERR_BADPARAM
+.B DESERR_BADPARAM
Bad argument to routine.
.PP
Given a result status
.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
.\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb
.\"
-.TH DIV 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH DIV 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of
an integer division
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <link.h>
.PP
-.BI "int dl_iterate_phdr("
+.B int dl_iterate_phdr(
.BI " int (*" callback ")(struct dl_phdr_info *" info ,
-.BI " size_t " size ", void *" data "),"
-.BI " void *" data ");"
+.BI " size_t " size ", void *" data ),
+.BI " void *" data );
.fi
.SH DESCRIPTION
The
Possible values for
.I p_type
include the following (see
-.IR <elf.h>
+.I <elf.h>
for further details):
.PP
.in +4n
.IR dlpi_name ,
.IR dlpi_phdr ,
and
-.IR dlpi_phnum
+.I dlpi_phnum
in addition to other implementation-specific fields.
.SH NOTES
Future versions of the C library may add further fields to the
-.IR dl_phdr_info
+.I dl_phdr_info
structure; in that event, the
.I size
argument provides a mechanism for the callback function to discover
whether it is running on a system with added fields.
.PP
The first object visited by
-.IR callback
+.I callback
is the main program.
For the main program, the
.I dlpi_name
The function
.BR dladdr ()
determines whether the address specified in
-.IR addr
+.I addr
is located in one of the shared objects loaded by the calling application.
If it is, then
.BR dladdr ()
.B RTLD_DL_LINKMAP
Obtain a pointer to the link map for the matched file.
The
-.IR extra_info
+.I extra_info
argument points to a pointer to a
.I link_map
structure (i.e.,
-.IR "struct link_map\ **" ),
+.IR "struct link_map\~**" ),
defined in
.I <link.h>
as:
.B RTLD_DL_SYMENT
Obtain a pointer to the ELF symbol table entry of the matching symbol.
The
-.IR extra_info
+.I extra_info
argument is a pointer to a symbol pointer:
.IR "const ElfW(Sym) **" .
The
yields the data type name
.IR Elf64_Sym ,
which is defined in
-.IR <elf.h>
+.I <elf.h>
as:
.IP
.in +4n
.I st_info
field encodes the symbol's type and binding.
The type can be extracted using the macro
-.BR ELF64_ST_TYPE(st_info)
+.B ELF64_ST_TYPE(st_info)
(or
-.BR ELF32_ST_TYPE()
+.B ELF32_ST_TYPE()
on 32-bit platforms), which yields one of the following values:
.in +4n
.TS
The symbol binding can be extracted from the
.I st_info
field using the macro
-.BR ELF64_ST_BIND(st_info)
+.B ELF64_ST_BIND(st_info)
(or
-.BR ELF32_ST_BIND()
+.B ELF32_ST_BIND()
on 32-bit platforms), which yields one of the following values:
.in +4n
.TS
The
.I st_other
field contains the symbol's visibility, which can be extracted using the macro
-.BR ELF64_ST_VISIBILITY(st_info)
+.B ELF64_ST_VISIBILITY(st_info)
(or
-.BR ELF32_ST_VISIBILITY()
+.B ELF32_ST_VISIBILITY()
on 32-bit platforms), which yields one of the following values:
.in +4n
.TS
.BR dlinfo ()
function obtains information about the dynamically loaded object
referred to by
-.IR handle
+.I handle
(typically obtained by an earlier call to
.BR dlopen (3)
or
.IR request .
.PP
The following values are supported for
-.IR request
+.I request
(with the corresponding type for
-.IR info
+.I info
shown in parentheses):
.TP
.BR RTLD_DI_LMID " (\fILmid_t *\fP)"
structure corresponding to
.IR handle .
The
-.IR info
+.I info
argument points to a pointer to a
.I link_map
structure, defined in
.TP
.BR RTLD_DI_ORIGIN " (\fIchar *\fP)"
Copy the pathname of the origin of the shared object corresponding to
-.IR handle
+.I handle
to the location pointed to by
.IR info .
.TP
that contains the search paths.
Because the number of search paths may vary,
the size of the structure pointed to by
-.IR info
+.I info
can vary.
The
.B RTLD_DI_SERINFOSIZE
fields of the
.I Dl_serinfo
structure pointed to by
-.IR info
+.I info
with values suitable for allocating a buffer for use in a subsequent
.B RTLD_DI_SERINFO
request.
that were previously opened with
.BR dlopen ()
using the
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
flag;
and definitions in the shared object itself
(and any dependencies that were loaded for that object).
may force symbol resolution for a shared object earlier loaded with
.BR RTLD_LAZY .
Similarly, an object that was previously opened with
-.BR RTLD_LOCAL
+.B RTLD_LOCAL
can be promoted to
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
in a subsequent
.BR dlopen ().
.PP
after first calling any destructors defined for the object.
(Symbols in this object might be required in another object
because this object was opened with the
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
flag and one of its symbols satisfied a relocation in another object.)
.PP
All shared objects that were automatically loaded when
.BR RTLD_NOLOAD ,
.BR RTLD_NODELETE ,
and
-.BR RTLD_DEEPBIND
+.B RTLD_DEEPBIND
flags are GNU extensions;
the first two of these flags are also present on Solaris.
.SH NOTES
The
.BR dlmopen ()
function also can be used to provide better isolation than the
-.BR RTLD_LOCAL
+.B RTLD_LOCAL
flag.
In particular, shared objects loaded with
-.BR RTLD_LOCAL
+.B RTLD_LOCAL
may be promoted to
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
if they are dependencies of another shared object loaded with
.BR RTLD_GLOBAL .
Thus,
-.BR RTLD_LOCAL
+.B RTLD_LOCAL
is insufficient to isolate a loaded shared object except in the (uncommon)
case where one has explicit control over all shared object dependencies.
.PP
and priorities can be associated with each function
to determine the order in which they are executed.
See the
-.BR gcc
+.B gcc
info pages (under "Function attributes")
.\" info gcc "C Extensions" "Function attributes"
for further information.
Use of
.B _init
and
-.BR _fini
+.B _fini
is now deprecated in favor of the aforementioned
constructors and destructors,
which among other advantages,
These functions are part of the dlopen API, derived from SunOS.
.SH BUGS
As at glibc 2.24, specifying the
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
flag when calling
.BR dlmopen ()
.\" dlerror(): "invalid mode"
generates an error.
Furthermore, specifying
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
when calling
.BR dlopen ()
results in a program crash
The search will include global symbols in the executable
and its dependencies,
as well as symbols in shared objects that were dynamically loaded with the
-.BR RTLD_GLOBAL
+.B RTLD_GLOBAL
flag.
.TP
-.BR RTLD_NEXT
+.B RTLD_NEXT
Find the next occurrence of the desired symbol in the search order
after the current object.
This allows one to provide a wrapper
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu)
-.TH DRAND48 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH DRAND48 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48,
lcong48 \- generate uniformly distributed pseudo-random numbers
Unless
.BR lcong48 ()
is called,
-.IR a
+.I a
and
.I c
are given by:
.BR duplocale ()
to the value returned by the following call:
.IP
- loc = uselocale((locale_t) 0);
+.in +4n
+.EX
+loc = uselocale((locale_t) 0);
+.EE
+.in
.IP
This technique is necessary, because the above
.BR uselocale (3)
Calling
.BR duplocale ()
can be used to ensure that the
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
value is converted into a usable locale object.
See EXAMPLES, below.
.PP
.\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl)
.\"
-.TH ECVT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ECVT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ecvt, fcvt \- convert a floating-point number to a string
.SH LIBRARY
.\"
.\" Modified 2003-04-04, aeb
.\"
-.TH ENCRYPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ENCRYPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages
.SH LIBRARY
.BI "void setkey(const char *" key );
.PP
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.B "#include <crypt.h>"
+.B #include <crypt.h>
.PP
.BI "void setkey_r(const char *" key ", struct crypt_data *" data );
.BI "void encrypt_r(char *" block ", int " edflag \
.PP
At the start of program execution,
the program break will be somewhere near
-.IR &end
+.I &end
(perhaps at the start of the following page).
However, the break will change as memory is allocated via
.BR brk (2)
.\" based on the description in glibc source and infopages
.\"
.\" Corrections and additions, aeb
-.TH ENVZ_ADD 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ENVZ_ADD 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
envz_add, envz_entry, envz_get, envz_merge,
envz_remove, envz_strip \- environment string support
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.B "#include <envz.h>"
+.B #include <envz.h>
.PP
.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " name \
removes all entries with value NULL.
.SH RETURN VALUE
All envz functions that do memory allocation have a return type of
-.IR error_t
+.I error_t
(an integer type),
and return 0 for success, and
.B ENOMEM
These functions return the error function of
.IR x ,
defined as
-.TP
- erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt
+.PP
+.in +4n
+.EX
+erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt
+.EE
+.in
.SH RETURN VALUE
On success, these functions return the value of the error function of
.IR x ,
.BR erfcl ()
functions are provided to avoid the loss accuracy that
would occur for the calculation 1-erf(x) for large values of
-.IR x
+.I x
(for which the value of erf(x) approaches 1).
.SH SEE ALSO
.BR cerf (3),
.\" 2006-02-09 Kurt Wall, mtk
.\" Added non-POSIX errors
.\"
-.TH ERRNO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ERRNO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
errno \- number of last error
.SH LIBRARY
.B EMFILE
Too many open files (POSIX.1-2001).
Commonly caused by exceeding the
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
resource limit described in
.BR getrlimit (2).
Can also be caused by exceeding the limit specified in
.B ENFILE
Too many open files in system (POSIX.1-2001).
On Linux, this is probably a result of encountering the
-.IR /proc/sys/fs/file\-max
+.I /proc/sys/fs/file\-max
limit (see
.BR proc (5)).
.TP
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH EUIDACCESS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH EUIDACCESS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
euidaccess, eaccess \- check effective user's permissions for a file
.SH LIBRARY
If you need to check the permissions on a symbolic link, use
.BR faccessat (2)
with the flags
-.BR AT_EACCESS
+.B AT_EACCESS
and
.BR AT_SYMLINK_NOFOLLOW .
.SH SEE ALSO
environment variable.
If this variable isn't defined, the path list defaults to
a list that includes the directories returned by
-.IR confstr(_CS_PATH)
+.I confstr(_CS_PATH)
(which typically returns the value "/bin:/usr/bin")
and possibly also the current working directory;
see NOTES for further details.
It generally includes
.I /bin
and
-.IR /usr/bin
+.I /usr/bin
(in that order) and may also include the current working directory.
On some other systems, the current working is included after
.I /bin
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH EXP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH EXP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
exp, expf, expl \- base-e exponential function
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH EXP2 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH EXP2 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
exp2, exp2f, exp2l \- base-2 exponential function
.SH LIBRARY
.\" Modified 2002-07-27 Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH EXPM1 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH EXPM1 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
expm1, expm1f, expm1l \- exponential minus 1
.SH LIBRARY
Range error, overflow
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
An overflow floating-point exception
.RB ( FE_OVERFLOW )
.\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu)
.\" Added fabsl, fabsf, aeb, 2001-06-07
.\"
-.TH FABS 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FABS 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fabs, fabsf, fabsl \- absolute value of floating-point number
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH FDIM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FDIM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fdim, fdimf, fdiml \- positive difference
.SH LIBRARY
.BR FE_UPWARD ,
.BR FE_DOWNWARD ,
and
-.BR FE_TOWARDZERO
+.B FE_TOWARDZERO
is defined when the implementation supports getting and setting
the corresponding rounding direction.
.PP
Other values represent machine-dependent, nonstandard rounding modes.
.PP
The value of
-.BR FLT_ROUNDS
+.B FLT_ROUNDS
should reflect the current rounding mode as set by
.BR fesetround ()
(but see BUGS).
.\"
.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu
.\"
-.TH FERROR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FERROR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
clearerr, feof, ferror \- check and reset stream status
.SH LIBRARY
system call, then
.BR fexecve ()
is implemented using that system call, with the benefit that
-.IR /proc
+.I /proc
does not need to be mounted.
.PP
The idea behind
.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu
.\" Added remark on EBADF for fileno, aeb, 2001-03-22
.\"
-.TH FILENO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FILENO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fileno \- obtain file descriptor of a stdio stream
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH FINITE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FINITE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \-
BSD floating-point classification functions
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH FLOCKFILE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FLOCKFILE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
flockfile, ftrylockfile, funlockfile \- lock FILE for stdio
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH FLOOR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FLOOR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
floor, floorf, floorl \- largest integral value not greater than argument
.SH LIBRARY
.IR x .
.PP
For example,
-.IR floor(0.5)
+.I floor(0.5)
is 0.0, and
-.IR floor(\-0.5)
+.I floor(\-0.5)
is \-1.0.
.SH RETURN VALUE
These functions return the floor of
.\" Modified 2004-11-15, Added further text on FLT_ROUNDS
.\" as suggested by AEB and Fabian Kreutz
.\"
-.TH FMA 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FMA 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fma, fmaf, fmal \- floating-point multiply and add
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH FMAX 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FMAX 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fmax, fmaxf, fmaxl \- determine maximum of two floating-point numbers
.SH LIBRARY
Disabling buffering with the following call
may be useful to detect errors at the time of an output operation:
.PP
- setbuf(stream, NULL);
+.in +4n
+.EX
+setbuf(stream, NULL);
+.EE
+.in
.SH RETURN VALUE
Upon successful completion,
.BR fmemopen ()
and is not widely available on other systems.
.PP
POSIX.1-2008 specifies that \(aqb\(aq in
-.IR mode
+.I mode
shall be ignored.
However, Technical Corrigendum 1
.\" http://austingroupbugs.net/view.php?id=396
Thus, for example, "wb+" has the desired effect, but "w+b" does not.
This is inconsistent with the treatment of
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836
-.IR mode
+.I mode
by
.BR fopen (3).
.PP
the
.I offset
was
-.IR subtracted
+.I subtracted
from the end-of-stream position, instead of being added.
This bug is fixed in glibc 2.22.
.PP
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH FMIN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FMIN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fmin, fminf, fminl \- determine minimum of two floating-point numbers
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH FMOD 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FMOD 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fmod, fmodf, fmodl \- floating-point remainder function
.SH LIBRARY
by
.IR y .
The return value is
-.IR x
+.I x
\-
.I n
*
Domain error: \fIx\fP is an infinity
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
.\" The function is quite complex and deserves an example
.\"
.\" Polished, aeb, 2003-11-01
-.TH FMTMSG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FMTMSG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fmtmsg \- print formatted error messages
.SH LIBRARY
and functions to convert to the coded character set are loaded.
.SH BUGS
When parsing for individual flag characters in
-.IR mode
+.I mode
(i.e., the characters preceding the "ccs" specification),
the glibc implementation of
.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685
(e.g., where to store data) used by the aforementioned hook functions.
The standard I/O package knows nothing about the contents of this cookie
(thus it is typed as
-.IR "void\ *"
+.I void\~*
when passed to
.BR fopencookie ()),
but automatically supplies the cookie
This function implements read operations for the stream.
When called, it receives three arguments:
.IP
- ssize_t read(void *cookie, char *buf, size_t size);
+.in +4n
+.EX
+ssize_t read(void *cookie, char *buf, size_t size);
+.EE
+.in
.IP
The
.I buf
This function implements write operations for the stream.
When called, it receives three arguments:
.IP
- ssize_t write(void *cookie, const char *buf, size_t size);
+.in +4n
+.EX
+ssize_t write(void *cookie, const char *buf, size_t size);
+.EE
+.in
.IP
The
.I buf
This function implements seek operations on the stream.
When called, it receives three arguments:
.IP
- int seek(void *cookie, off64_t *offset, int whence);
+.in +4n
+.EX
+int seek(void *cookie, off64_t *offset, int whence);
+.EE
+.in
.IP
The
.I *offset
for the stream.
When called, it receives one argument:
.IP
- int close(void *cookie);
+.in +4n
+.EX
+int close(void *cookie);
+.EE
+.in
.IP
The
.I cookie
The maximum length of a filename in the directory
.I path
or
-.IR fd
+.I fd
that the process is allowed to create.
The corresponding macro is
.BR _POSIX_NAME_MAX .
.\" This was done with the help of the glibc manual.
.\"
.\" 2004-10-31, aeb, corrected
-.TH FPCLASSIFY 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FPCLASSIFY 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fpclassify, isfinite, isnormal, isnan, isinf \- floating-point
classification macros
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH FPURGE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FPURGE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fpurge, __fpurge \- purge a stream
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH FREXP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FREXP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
frexp, frexpf, frexpl \- convert floating-point number to fractional
and integral components
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH FSEEKO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH FSEEKO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
fseeko, ftello \- seek to or report file position
.SH LIBRARY
.IR long .
.PP
On some architectures, both
-.IR off_t
+.I off_t
and
.I long
are 32-bit types, but defining
-.BR _FILE_OFFSET_BITS
+.B _FILE_OFFSET_BITS
with the value 64 (before including
.I any
header files)
These fields are defined as follows:
.\" .Bl -tag -width "fts_namelen"
.TP
-.IR fts_info
+.I fts_info
One of the following values describing the returned
.I FTSENT
structure and
.\" .Bl -tag -width FTS_DEFAULT
.RS
.TP
-.BR FTS_D
+.B FTS_D
A directory being visited in preorder.
.TP
-.BR FTS_DC
+.B FTS_DC
A directory that causes a cycle in the tree.
(The
.I fts_cycle
.I FTSENT
structure will be filled in as well.)
.TP
-.BR FTS_DEFAULT
+.B FTS_DEFAULT
Any
.I FTSENT
structure that represents a file type not explicitly described
.I fts_info
values.
.TP
-.BR FTS_DNR
+.B FTS_DNR
A directory which cannot be read.
This is an error return, and the
.I fts_errno
field will be set to indicate what caused the error.
.TP
-.BR FTS_DOT
+.B FTS_DOT
A file named
"."
or
(see
.BR FTS_SEEDOT ).
.TP
-.BR FTS_DP
+.B FTS_DP
A directory being visited in postorder.
The contents of the
.I FTSENT
field set to
.BR FTS_D .
.TP
-.BR FTS_ERR
+.B FTS_ERR
This is an error return, and the
.I fts_errno
field will be set to indicate what caused the error.
.TP
-.BR FTS_F
+.B FTS_F
A regular file.
.TP
-.BR FTS_NS
+.B FTS_NS
A file for which no
.BR stat (2)
information was available.
.I fts_errno
field will be set to indicate what caused the error.
.TP
-.BR FTS_NSOK
+.B FTS_NSOK
A file for which no
.BR stat (2)
information was requested.
.I fts_statp
field are undefined.
.TP
-.BR FTS_SL
+.B FTS_SL
A symbolic link.
.TP
-.BR FTS_SLNONE
+.B FTS_SLNONE
A symbolic link with a nonexistent target.
The contents of the
.I fts_statp
.\" .El
.RE
.TP
-.IR fts_accpath
+.I fts_accpath
A path for accessing the file from the current directory.
.TP
-.IR fts_path
+.I fts_path
The path for the file relative to the root of the traversal.
This path contains the path specified to
.BR fts_open ()
as a prefix.
.TP
-.IR fts_pathlen
+.I fts_pathlen
The sum of the lengths of the strings referenced by
-.IR fts_path
+.I fts_path
and
.IR fts_name .
.TP
-.IR fts_name
+.I fts_name
The name of the file.
.TP
-.IR fts_namelen
+.I fts_namelen
The length of the string referenced by
.IR fts_name .
.TP
-.IR fts_level
+.I fts_level
The depth of the traversal, numbered from \-1 to N, where this file
was found.
The
structure for the root
itself is numbered 0.
.TP
-.IR fts_errno
+.I fts_errno
If
.BR fts_children ()
or
the
.I fts_errno
field contains the error number (i.e., the
-.IR errno
+.I errno
value)
specifying the cause of the error.
Otherwise, the contents of the
.I fts_errno
field are undefined.
.TP
-.IR fts_number
+.I fts_number
This field is provided for the use of the application program and is
not modified by the
fts functions.
It is initialized to 0.
.TP
-.IR fts_pointer
+.I fts_pointer
This field is provided for the use of the application program and is
not modified by the
fts functions.
It is initialized to
NULL.
.TP
-.IR fts_parent
+.I fts_parent
A pointer to the
.I FTSENT
structure referencing the file in the hierarchy
.I fts_pointer
fields are guaranteed to be initialized.
.TP
-.IR fts_link
+.I fts_link
Upon return from the
.BR fts_children ()
function, the
.I fts_link
field are undefined.
.TP
-.IR fts_cycle
+.I fts_cycle
If a directory causes a cycle in the hierarchy (see
.BR FTS_DC ),
either because
.I fts_cycle
field are undefined.
.TP
-.IR fts_statp
+.I fts_statp
A pointer to
.BR stat (2)
information for the file.
.PP
There are
a number of options, at least one of which (either
-.BR FTS_LOGICAL
+.B FTS_LOGICAL
or
.BR FTS_PHYSICAL )
must be specified.
the following values:
.\" .Bl -tag -width "FTS_PHYSICAL"
.TP
-.BR FTS_COMFOLLOW
+.B FTS_COMFOLLOW
This option causes any symbolic link specified as a root path to be
followed immediately whether or not
-.BR FTS_LOGICAL
+.B FTS_LOGICAL
is also specified.
.TP
-.BR FTS_LOGICAL
+.B FTS_LOGICAL
This option causes the
fts routines to return
.I FTSENT
structures
are returned to the application are those referencing nonexistent files.
Either
-.BR FTS_LOGICAL
+.B FTS_LOGICAL
or
-.BR FTS_PHYSICAL
+.B FTS_PHYSICAL
.I must
be provided to the
.BR fts_open ()
function.
.TP
-.BR FTS_NOCHDIR
+.B FTS_NOCHDIR
As a performance optimization, the
fts functions change directories as they walk the file hierarchy.
This has the side-effect that an application cannot rely on being
in any particular directory during the traversal.
The
-.BR FTS_NOCHDIR
+.B FTS_NOCHDIR
option turns off this optimization, and the
fts functions will not change the current directory.
Note that applications should not themselves change their current directory
and try to access files unless
-.BR FTS_NOCHDIR
+.B FTS_NOCHDIR
is specified and absolute
pathnames were provided as arguments to
.BR fts_open ().
.TP
-.BR FTS_NOSTAT
+.B FTS_NOSTAT
By default, returned
.I FTSENT
structures reference file characteristic information (the
fts functions to set the
.I fts_info
field to
-.BR FTS_NSOK
+.B FTS_NSOK
and leave the contents of the
.I statp
field undefined.
.TP
-.BR FTS_PHYSICAL
+.B FTS_PHYSICAL
This option causes the
fts routines to return
.I FTSENT
structures for all symbolic links in the
hierarchy are returned to the application.
Either
-.BR FTS_LOGICAL
+.B FTS_LOGICAL
or
-.BR FTS_PHYSICAL
+.B FTS_PHYSICAL
.I must
be provided to the
.BR fts_open ()
function.
.TP
-.BR FTS_SEEDOT
+.B FTS_SEEDOT
By default, unless they are specified as path arguments to
.BR fts_open (),
any files named
.I FTSENT
structures for them.
.TP
-.BR FTS_XDEV
+.B FTS_XDEV
This option prevents
fts from descending into directories that have a different device number
than the file from which the descent began.
If the
.I fts_info
field is set to
-.BR FTS_NS
+.B FTS_NS
or
.BR FTS_NSOK ,
the
argument is either zero or the following value:
.\" .Bl -tag -width FTS_NAMEONLY
.TP
-.BR FTS_NAMEONLY
+.B FTS_NAMEONLY
Only the names of the files are needed.
The contents of all the fields in the returned linked list of structures
are undefined with the exception of the
argument is either 0 (meaning "do nothing") or one of the following values:
.\" .Bl -tag -width FTS_PHYSICAL
.TP
-.BR FTS_AGAIN
+.B FTS_AGAIN
Revisit the file; any file type may be revisited.
The next call to
.BR fts_read ()
directory to be revisited (in both preorder and postorder) as well as all
of its descendants.
.TP
-.BR FTS_FOLLOW
+.B FTS_FOLLOW
The referenced file must be a symbolic link.
If the referenced file is the one most recently returned by
.BR fts_read (),
by the return of all of its descendants, followed by a postorder return,
is done.
.TP
-.BR FTS_SKIP
+.B FTS_SKIP
No descendants of this file are visited.
The file may be one of those most recently returned by either
.BR fts_children ()
current working directory at the time of the call to
.BR nftw (),
if
-.IR dirpath
+.I dirpath
was expressed as a relative pathname,
or as an absolute pathname, if
.I dirpath
.IP * 3
.BR ftw ()
has no
-.IR flags
+.I flags
argument.
It behaves the same as when
.BR nftw ()
.BR nftw ().
.SH BUGS
According to POSIX.1-2008, when the
-.IR typeflag
+.I typeflag
argument passed to
.IR fn ()
contains
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu)
-.TH GCVT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GCVT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
gcvt \- convert a floating-point number to a string
.SH LIBRARY
.nf
.B #include <sys/sysinfo.h>
.PP
-.BI "int get_nprocs(void);"
-.BI "int get_nprocs_conf(void);"
+.B int get_nprocs(void);
+.B int get_nprocs_conf(void);
.fi
.SH DESCRIPTION
The function
.I ai_family
This field specifies the desired address family for the returned addresses.
Valid values for this field include
-.BR AF_INET
+.B AF_INET
and
.BR AF_INET6 .
The value
.TP
.I ai_socktype
This field specifies the preferred socket type, for example
-.BR SOCK_STREAM
+.B SOCK_STREAM
or
.BR SOCK_DGRAM .
Specifying 0 in this field indicates that socket addresses of any type
The returned socket address will contain the "wildcard address"
.RB ( INADDR_ANY
for IPv4 addresses,
-.BR IN6ADDR_ANY_INIT
+.B IN6ADDR_ANY_INIT
for IPv6 address).
The wildcard address is used by applications (typically servers)
that intend to accept connections on any of the host's network addresses.
then the network address will be set to the loopback interface address
.RB ( INADDR_LOOPBACK
for IPv4 addresses,
-.BR IN6ADDR_LOOPBACK_INIT
+.B IN6ADDR_LOOPBACK_INIT
for IPv6 address);
this is used by applications that intend to communicate
with peers running on the same host.
.I addrinfo
structure, including: the network host is multihomed, accessible
over multiple protocols (e.g., both
-.BR AF_INET
+.B AF_INET
and
.BR AF_INET6 );
or the same service is available from multiple socket types (one
.BR getaddrinfo ()
is defined in RFC\ 3484; the order can be tweaked for a particular
system by editing
-.IR /etc/gai.conf
+.I /etc/gai.conf
(available since glibc 2.5).
.PP
If
was not NULL, and
.I hints.ai_socktype
was
-.BR SOCK_RAW
+.B SOCK_RAW
(a socket type that does not support the concept of services).
.TP
.B EAI_SOCKTYPE
and
.I hints.ai_protocol
are inconsistent (e.g.,
-.BR SOCK_DGRAM
+.B SOCK_DGRAM
and
.BR IPPROTO_TCP ,
respectively).
.I ai_flags
to be assumed as 0.
The GNU C library instead assumes a value of
-.BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
+.B (AI_V4MAPPED\~|\~AI_ADDRCONFIG)
for this case,
since this value is considered an improvement on the specification.
.SH EXAMPLES
.I sevp\->sigev_notify
field can have the following values:
.TP
-.BR SIGEV_NONE
+.B SIGEV_NONE
Don't provide any notification.
.TP
-.BR SIGEV_SIGNAL
+.B SIGEV_SIGNAL
When a look-up completes, generate the signal
.I sigev_signo
for the process.
.\" si_pid and si_uid are also set, to the values of the calling process,
.\" which doesn't provide useful information, so we'll skip mentioning it.
.TP
-.BR SIGEV_THREAD
+.B SIGEV_THREAD
When a look-up completes, invoke
.I sigev_notify_function
as if it were the start function of a new thread.
for details.
.PP
For
-.BR SIGEV_SIGNAL
+.B SIGEV_SIGNAL
and
.BR SIGEV_THREAD ,
it may be useful to point
-.IR sevp\->sigev_value.sival_ptr
+.I sevp\->sigev_value.sival_ptr
to
.IR list .
.PP
.I type
values are present on all architectures.
.TP
-.BR AT_BASE
+.B AT_BASE
The base address of the program interpreter (usually, the dynamic linker).
.TP
-.BR AT_BASE_PLATFORM
+.B AT_BASE_PLATFORM
A pointer to a string (PowerPC and MIPS only).
On PowerPC, this identifies the real platform; may differ from
.BR AT_PLATFORM "."
.\" commit e585b768da111f2c2d413de6214e83bbdfee8f22
this identifies the ISA level (since Linux 5.7).
.TP
-.BR AT_CLKTCK
+.B AT_CLKTCK
The frequency with which
.BR times (2)
counts.
This value can also be obtained via
.IR sysconf(_SC_CLK_TCK) .
.TP
-.BR AT_DCACHEBSIZE
+.B AT_DCACHEBSIZE
The data cache block size.
.TP
-.BR AT_EGID
+.B AT_EGID
The effective group ID of the thread.
.TP
-.BR AT_ENTRY
+.B AT_ENTRY
The entry address of the executable.
.TP
-.BR AT_EUID
+.B AT_EUID
The effective user ID of the thread.
.TP
-.BR AT_EXECFD
+.B AT_EXECFD
File descriptor of program.
.TP
-.BR AT_EXECFN
+.B AT_EXECFN
A pointer to a string containing the pathname used to execute the program.
.TP
-.BR AT_FLAGS
+.B AT_FLAGS
Flags (unused).
.TP
-.BR AT_FPUCW
+.B AT_FPUCW
Used FPU control word (SuperH architecture only).
This gives some information about the FPU initialization
performed by the kernel.
.TP
-.BR AT_GID
+.B AT_GID
The real group ID of the thread.
.TP
-.BR AT_HWCAP
+.B AT_HWCAP
An architecture and ABI dependent bit-mask whose settings
indicate detailed processor capabilities.
The contents of the bit mask are hardware dependent
(for example, see the kernel source file
-.IR arch/x86/include/asm/cpufeature.h
+.I arch/x86/include/asm/cpufeature.h
for details relating to the Intel x86 architecture; the value
returned is the first 32-bit word of the array described there).
A human-readable version of the same information is available via
.BR AT_HWCAP2 " (since glibc 2.18)"
Further machine-dependent hints about processor capabilities.
.TP
-.BR AT_ICACHEBSIZE
+.B AT_ICACHEBSIZE
The instruction cache block size.
.\" .TP
.\" .BR AT_IGNORE
.\" .BR AT_NOTELF
.TP
.\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147
-.BR AT_L1D_CACHEGEOMETRY
+.B AT_L1D_CACHEGEOMETRY
Geometry of the L1 data cache, encoded with the cache line size in bytes
in the bottom 16 bits and the cache associativity in the next 16 bits.
The associativity is such that if N is the 16-bit value,
the cache is N-way set associative.
.TP
-.BR AT_L1D_CACHESIZE
+.B AT_L1D_CACHESIZE
The L1 data cache size.
.TP
-.BR AT_L1I_CACHEGEOMETRY
+.B AT_L1I_CACHEGEOMETRY
Geometry of the L1 instruction cache, encoded as for
.BR AT_L1D_CACHEGEOMETRY .
.TP
-.BR AT_L1I_CACHESIZE
+.B AT_L1I_CACHESIZE
The L1 instruction cache size.
.TP
-.BR AT_L2_CACHEGEOMETRY
+.B AT_L2_CACHEGEOMETRY
Geometry of the L2 cache, encoded as for
.BR AT_L1D_CACHEGEOMETRY .
.TP
-.BR AT_L2_CACHESIZE
+.B AT_L2_CACHESIZE
The L2 cache size.
.TP
-.BR AT_L3_CACHEGEOMETRY
+.B AT_L3_CACHEGEOMETRY
Geometry of the L3 cache, encoded as for
.BR AT_L1D_CACHEGEOMETRY .
.TP
-.BR AT_L3_CACHESIZE
+.B AT_L3_CACHESIZE
The L3 cache size.
.TP
-.BR AT_PAGESZ
+.B AT_PAGESZ
The system page size (the same value returned by
.IR sysconf(_SC_PAGESIZE) ).
.TP
-.BR AT_PHDR
+.B AT_PHDR
The address of the program headers of the executable.
.TP
-.BR AT_PHENT
+.B AT_PHENT
The size of program header entry.
.TP
-.BR AT_PHNUM
+.B AT_PHNUM
The number of program headers.
.TP
-.BR AT_PLATFORM
+.B AT_PLATFORM
A pointer to a string that identifies the hardware platform
that the program is running on.
The dynamic linker uses this in the interpretation of
-.IR rpath
+.I rpath
values.
.TP
-.BR AT_RANDOM
+.B AT_RANDOM
The address of sixteen bytes containing a random value.
.TP
-.BR AT_SECURE
+.B AT_SECURE
Has a nonzero value if this executable should be treated securely.
Most commonly, a nonzero value indicates that the process is
executing a set-user-ID or set-group-ID binary
(See also
.BR secure_getenv (3).)
.TP
-.BR AT_SYSINFO
+.B AT_SYSINFO
The entry point to the system call function in the vDSO.
Not present/needed on all architectures (e.g., absent on x86-64).
.TP
-.BR AT_SYSINFO_EHDR
+.B AT_SYSINFO_EHDR
The address of a page containing the virtual Dynamic Shared Object (vDSO)
that the kernel creates in order to provide fast implementations of
certain system calls.
.TP
-.BR AT_UCACHEBSIZE
+.B AT_UCACHEBSIZE
The unified cache block size.
.TP
-.BR AT_UID
+.B AT_UID
The real user ID of the thread.
.SH RETURN VALUE
On success,
.BR ENOENT " (since glibc 2.19)"
.\" commit b9ab448f980e296eac21ac65f53783967cc6037b
No entry corresponding to
-.IR type
+.I type
could be found in the auxiliary vector.
.SH VERSIONS
The
.in
.PP
with
-.IR sigset_t
+.I sigset_t
and
.I stack_t
defined in
.BR makecontext (3),
or received as the third argument to a signal
handler (see the discussion of the
-.BR SA_SIGINFO
+.B SA_SIGINFO
flag in
.BR sigaction (2)).
.PP
system call, which the functions described in this page will use if possible.
The system call takes the same arguments as the library function
of the same name, but is limited to returning at most
-.BR PATH_MAX
+.B PATH_MAX
bytes.
(Before Linux 3.12,
.\" commit 3272c544da48f8915a0e34189182aed029bd0f2b
the limit on the size of the returned pathname was the system page size.
On many architectures,
-.BR PATH_MAX
+.B PATH_MAX
and the system page size are both 4096 bytes,
but a few architectures have a larger page size.)
If the length of the pathname of the current working directory
.\" Modified, 2001-12-26, aeb
.\" 2008-09-07, mtk, Various rewrites; added an example program.
.\"
-.TH GETDATE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETDATE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getdate, getdate_r \- convert a date-plus-time string to broken-down time
.SH LIBRARY
returns a pointer to a
.IR "struct tm" .
Otherwise, it returns NULL and sets the global variable
-.IR getdate_err
+.I getdate_err
to one of the error numbers shown below.
Changes to
.I errno
on error it returns one of the error numbers shown below.
.SH ERRORS
The following errors are returned via
-.IR getdate_err
+.I getdate_err
(for
.BR getdate ())
or as the function result (for
These functions read from the file
.IR /etc/fstab .
The
-.IR "struct fstab"
+.I struct fstab
is defined by:
.PP
.in +4n
.BR getfstype ()).
HP-UX has functions of the same names,
that however use a
-.IR "struct checklist"
+.I struct checklist
instead of a
.IR "struct fstab" ,
and calls these functions obsolete, superseded by
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu)
-.TH GETGRENT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETGRENT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getgrent, setgrent, endgrent \- get group file entry
.SH LIBRARY
.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2003-11-15 by aeb
.\"
-.TH GETGRNAM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETGRNAM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry
.SH LIBRARY
.PP
The call
.PP
- sysconf(_SC_GETGR_R_SIZE_MAX)
+.in +4n
+.EX
+sysconf(_SC_GETGR_R_SIZE_MAX)
+.EE
+.in
.PP
returns either \-1, without changing
.IR errno ,
and
.BR getgrgid_r ()
return zero, and set
-.IR *result
+.I *result
to
.IR grp .
If no matching group record was found,
.BR getgrouplist ()
returns \-1.
In this case, the value returned in
-.IR *ngroups
+.I *ngroups
can be used to resize the buffer passed to a further call to
.BR getgrouplist ().
.SH VERSIONS
In glibc versions before 2.3.3,
the implementation of this function contains a buffer-overrun bug:
it returns the complete list of groups for
-.IR user
+.I user
in the array
.IR groups ,
even when the number of groups exceeds
.\" Modified 2002-08-05, Michael Kerrisk
.\" Modified 2004-10-31, Andries Brouwer
.\"
-.TH GETHOSTBYNAME 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETHOSTBYNAME 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
h_errno,
Valid address types are
.B AF_INET
and
-.BR AF_INET6
+.B AF_INET6
(defined in
.IR <sys/socket.h> ).
The host address argument is a pointer to a struct of a type depending
In glibc 2.4 and earlier, the
.I order
keyword was used to control the order of host lookups as defined in
-.IR /etc/host.conf
+.I /etc/host.conf
.RB ( host.conf (5)).
.PP
The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
.B HOST_NOT_FOUND
The specified host is unknown.
.TP
-.BR NO_DATA
+.B NO_DATA
The requested name is valid but does not have an IP address.
Another type of request to the name server for this domain
may return an answer.
The constant
-.BR NO_ADDRESS
+.B NO_ADDRESS
is a synonym for
.BR NO_DATA .
.TP
.BR gethostbyname (),
.BR gethostbyaddr (),
and
-.IR h_errno
+.I h_errno
are marked obsolescent in that standard.
POSIX.1-2008 removes the specifications of
.BR gethostbyname (),
field may contain a pointer to a
.IR "struct rtnl_link_stats" ,
defined in
-.IR <linux/if_link.h>
+.I <linux/if_link.h>
(in Linux 2.4 and earlier,
.IR "struct net_device_stats" ,
defined in
.\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 961109, 031115, aeb
.\"
-.TH GETMNTENT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETMNTENT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getmntent, setmntent, addmntent, endmntent, hasmntopt,
getmntent_r \- get filesystem descriptor file entry
The
.BR endmntent ()
function closes the
-.IR stream
+.I stream
associated with the filesystem description file.
.PP
The
function is similar to
.BR getmntent (),
but stores the
-.IR "struct mount"
+.I struct mount
in the provided
.I *mntbuf
and stores the strings pointed to by the entries in that struct
these definitions are exposed only if suitable
feature test macros are defined, namely:
.BR _GNU_SOURCE ,
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(since glibc 2.19),
or (in glibc versions up to and including 2.19)
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
or
.BR _SVID_SOURCE .
.PP
.BR getopt ()
can detect two kinds of errors:
(1) an option character that was not specified in
-.IR optstring
+.I optstring
and (2) a missing option argument
(i.e., an option at the end of the command line without an expected argument).
Such errors are handled and reported as follows:
and returns \(aq?\(aq as the function result.
.IP *
If the caller has set the global variable
-.IR opterr
+.I opterr
to zero, then
.BR getopt ()
does not print an error message.
The caller can determine that there was an error by testing whether
the function return value is \(aq?\(aq.
(By default,
-.IR opterr
+.I opterr
has a nonzero value.)
.IP *
If the first character
.PP
The call
.PP
- sysconf(_SC_GETPW_R_SIZE_MAX)
+.in +4n
+.EX
+sysconf(_SC_GETPW_R_SIZE_MAX)
+.EE
+.in
.PP
returns either \-1, without changing
.IR errno ,
and
.BR getpwuid_r ()
return zero, and set
-.IR *result
+.I *result
to
.IR pwd .
If no matching password record was found,
.\" %%%LICENSE_END
.\"
.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI
-.TH GETRPCENT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETRPCENT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getrpcent, getrpcbyname, getrpcbynumber, setrpcent, endrpcent \- get
RPC entry
.nf
.B #include <netdb.h>
.PP
-.BI "struct rpcent *getrpcent(void);"
+.B struct rpcent *getrpcent(void);
.PP
.BI "struct rpcent *getrpcbyname(const char *" name );
.BI "struct rpcent *getrpcbynumber(int " number );
.PP
.BI "void setrpcent(int " stayopen );
-.BI "void endrpcent(void);"
+.B void endrpcent(void);
.fi
.SH DESCRIPTION
The
.\" %%%LICENSE_END
.\"
.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI
-.TH GETRPCPORT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETRPCPORT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getrpcport \- get RPC port number
.SH LIBRARY
.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt
.\" <michael@cantor.informatik.rwth-aachen.de>
.\"
-.TH GETUTENT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GETUTENT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getutent, getutid, getutline, pututline, setutent, endutent,
utmpname \- access utmp file entries
instead of using the pattern itself as the name,
.BR glob ()
returns
-.BR GLOB_NOMATCH
+.B GLOB_NOMATCH
to indicate an error.
.TP
.B GLOB_ONLYDIR
.\"
.\" This replaces an earlier man page written by Walter Harms
.\" <walter.harms@informatik.uni-oldenburg.de>.
-.TH GSIGNAL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH GSIGNAL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
gsignal, ssignal \- software signal facility
.SH LIBRARY
.\"
.\" @(#)hash.3 8.6 (Berkeley) 8/18/94
.\"
-.TH HASH 3 2017-09-15 "" "Linux Programmer's Manual"
+.TH HASH 3 2017-09-15 GNU "Linux Programmer's Manual"
.UC 7
.SH NAME
hash \- hash database access method
This argument must either have the value
.BR ENTER ,
meaning insert a copy of
-.IR item
+.I item
(and return a pointer to the new hash table entry as the function result),
or the value
.BR FIND ,
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH HYPOT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH HYPOT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
hypot, hypotf, hypotl \- Euclidean distance function
.SH LIBRARY
is raised.
.IP
These functions do not set
-.IR errno
+.I errno
for this case.
.\" This is intentional; see
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6795
In case of error,
.BR iconv ()
returns
-.IR (size_t)\ \-1
+.I (size_t)\ \-1
and sets
.I errno
to indicate the error.
.IR tocode .
.PP
The values permitted for
-.IR fromcode
+.I fromcode
and
.I tocode
and the supported
returns a freshly allocated conversion
descriptor.
On failure, it returns
-.IR (iconv_t)\ \-1
+.I (iconv_t)\ \-1
and sets
.I errno
to indicate the error.
.TP
.B EINVAL
The conversion from
-.IR fromcode
+.I fromcode
to
.I tocode
is not supported by the
.\"
.\" Inspired by a page by Walter Harms created 2002-08-10
.\"
-.TH ILOGB 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ILOGB 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ilogb, ilogbf, ilogbl \- get integer exponent of a floating-point value
.SH LIBRARY
is raised, and
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
.TP
Domain error: \fIx\fP is an infinity
is raised, and
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
Addresses in any of these forms are collectively termed
.IR "IPV4 numbers-and-dots notation" .
The form that uses exactly four decimal numbers is referred to as
-.IR "IPv4 dotted-decimal notation"
+.I IPv4 dotted-decimal notation
(or sometimes:
.IR "IPv4 dotted-quad notation" ).
.PP
The
.BR inet_net_ntop ()
function converts the network number in the buffer pointed to by
-.IR netp
+.I netp
to presentation format;
.I *netp
is interpreted as a value in network byte order.
.TP
.B ENOENT
.RB ( inet_net_pton ())
-.IR pres
+.I pres
was not in correct presentation format.
.SH CONFORMING TO
The
as decimal numbers separated by dots.
Thus, any of the following forms are accepted:
.PP
- a.b.c.d
- a.b.c
- a.b
- a
+.in +4n
+.EX
+a.b.c.d
+a.b.c
+a.b
+a
+.EE
+.in
.PP
Each part is a number in the range 0 to 255 that
populates one byte of the resulting network number,
.B AF_INET
or
.BR AF_INET6 .
-.IR dst
+.I dst
is written in network byte order.
.PP
The following address families are currently supported:
.\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular
.\" lists, added example program
.\"
-.TH INSQUE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH INSQUE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
insque, remque \- insert/remove an item from a queue
.SH LIBRARY
function returns 1 if the file descriptor
.I fd
is of type
-.IR fdtype
+.I fdtype
and 0 if it is not.
On failure, \-1 is returned and
.I errno
.\" 2002-07-27 Walter Harms
.\" this was done with the help of the glibc manual
.\"
-.TH ISGREATER 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ISGREATER 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
isgreater, isgreaterequal, isless, islessequal, islessgreater,
isunordered \- floating-point relational tests without exception for NaN
.BR isgreater ()
determines \fI(x)\ >\ (y)\fP without an exception
if
-.IR x
+.I x
or
.I y
is NaN.
.BR isgreaterequal ()
determines \fI(x)\ >=\ (y)\fP without an exception
if
-.IR x
+.I x
or
.I y
is NaN.
.BR isless ()
determines \fI(x)\ <\ (y)\fP without an exception
if
-.IR x
+.I x
or
.I y
is NaN.
.BR islessequal ()
determines \fI(x)\ <=\ (y)\fP without an exception
if
-.IR x
+.I x
or
.I y
is NaN.
.BR islessgreater ()
determines \fI(x)\ < (y) || (x) >\ (y)\fP
without an exception if
-.IR x
+.I x
or
.I y
is NaN.
This macro is not equivalent to \fIx\ !=\ y\fP because that expression is
true if
-.IR x
+.I x
or
.I y
is NaN.
.PP
.BR isunordered ()
returns 1 if
-.IR x
+.I x
or
.I y
is NaN and 0 otherwise.
.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB
.\" 2008-07-24, mtk, moved yxx() material into separate y0.3 page
.\"
-.TH J0 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH J0 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl \-
Bessel functions of the first kind
.\"
.\" I had no way the check the functions out
.\" be careful
-.TH KEY_SETSECRET 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH KEY_SETSECRET 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
key_decryptsession, key_encryptsession, key_setsecret, key_gendes,
key_secretkey_is_set \- interfaces to rpc keyserver daemon
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.B "#include <rpc/rpc.h>"
+.B #include <rpc/rpc.h>
.PP
.BI "int key_decryptsession(char *" remotename ", des_block *" deskey );
.BI "int key_encryptsession(char *" remotename ", des_block *" deskey );
.BI "int key_gendes(des_block *" deskey );
.PP
.BI "int key_setsecret(char *" key );
-.B "int key_secretkey_is_set(void);"
+.B int key_secretkey_is_set(void);
.fi
.SH DESCRIPTION
The functions here are used within the RPC's secure authentication
.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2004-10-31 by aeb
.\"
-.TH LDEXP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LDEXP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2
.SH LIBRARY
.\"
.\" based on glibc infopages
.\"
-.TH LGAMMA 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LGAMMA 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \-
log gamma function
Pole error: \fIx\fP is a nonpositive integer
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH LIO_LISTIO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LIO_LISTIO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
lio_listio \- initiate a list of I/O requests
.SH LIBRARY
.nf
.B "#include <aio.h>"
.PP
-.BI "int lio_listio(int " mode ", struct aiocb *restrict const " aiocb_list [restrict],
+.BI "int lio_listio(int " mode \
+", struct aiocb *restrict const " aiocb_list [restrict],
.BI " int " nitems ", struct sigevent *restrict " sevp );
.fi
.SH DESCRIPTION
The I/O operations are queued for processing and the call returns immediately.
When all of the I/O operations complete, asynchronous notification occurs,
as specified by the
-.IR sevp
+.I sevp
argument; see
.BR sigevent (7)
for details.
If
-.IR sevp
+.I sevp
is NULL, no asynchronous notification occurs.
.PP
The
.I aio_lio_opcode
field specifies the I/O operation to be initiated, as follows:
.TP
-.BR LIO_READ
+.B LIO_READ
Initiate a read operation.
The operation is queued as for a call to
.BR aio_read (3)
specifying this control block.
.TP
-.BR LIO_WRITE
+.B LIO_WRITE
Initiate a write operation.
The operation is queued as for a call to
.BR aio_write (3)
specifying this control block.
.TP
-.BR LIO_NOP
+.B LIO_NOP
Ignore this control block.
.PP
The remaining fields in each control block have the same meanings as for
One or more of the I/O operations may fail,
but this does not prevent other operations completing.
The status of individual I/O operations in
-.IR aiocb_list
+.I aiocb_list
can be determined using
.BR aio_error (3).
When an operation has completed,
The number of I/O operations specified by
.I nitems
would cause the limit
-.BR AIO_MAX
+.B AIO_MAX
to be exceeded.
.TP
.B EINTR
.I mode
was
-.BR LIO_WAIT
+.B LIO_WAIT
and a signal
was caught before all I/O operations completed; see
.BR signal (7).
.TP
.B EIO
One of more of the operations specified by
-.IR aiocb_list
+.I aiocb_list
failed.
.\" e.g., ioa_reqprio or aio_lio_opcode was invalid
The application can check the status of each operation using
or
.BR EIO ,
then some of the operations in
-.IR aiocb_list
+.I aiocb_list
may have been initiated.
If
.BR lio_listio ()
named
.IR NAME .
The argument
-.IR HEADNAME
+.I HEADNAME
is the name of a user-defined structure
that must be declared using the macro
.BR LIST_HEAD ().
is
.B F_LOCK
or
-.BR F_TLOCK
+.B F_TLOCK
and
.I fd
is not a writable file descriptor.
and
.I mandatory\-locking.txt
in the Linux kernel source directory
-.IR Documentation/filesystems
+.I Documentation/filesystems
(on older kernels, these files are directly under the
.I Documentation
directory, and
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH LOG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LOG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
log, logf, logl \- natural logarithmic function
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH LOG10 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LOG10 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
log10, log10f, log10l \- base-10 logarithmic function
.SH LIBRARY
.\"
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
-.TH LOG1P 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LOG1P 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
log1p, log1pf, log1pl \- logarithm of 1 plus argument
.SH LIBRARY
Domain error: \fIx\fP is less than \-1
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
Pole error: \fIx\fP is \-1
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH LOG2 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LOG2 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
log2, log2f, log2l \- base-2 logarithmic function
.SH LIBRARY
.\"
.\" Inspired by a page by Walter Harms created 2002-08-10
.\"
-.TH LOGB 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LOGB 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
logb, logbf, logbl \- get exponent of a floating-point value
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH LRINT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LRINT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH LROUND 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH LROUND 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
lround, lroundf, lroundl, llround, llroundf, llroundl \- round to
nearest integer
perform a linear search for
.I key
in the array
-.IR base
+.I base
which has
.I *nmemb
elements of
The purpose of the specification was to provide transitional support
that allowed applications on 32-bit systems to access
files whose size exceeds that which can be represented with a 32-bit
-.IR off_t
+.I off_t
type.
As noted above, this symbol is exposed by header files if the
.B _LARGEFILE64_SOURCE
.\" glibc commit dbab6577c6684c62bd2521c1c29dc25c3cac966f
and since glibc 2.28,
.\" glibc commit e16deca62e16f645213dffd4ecd1153c37765f17
-.IR <sys/types.h>
+.I <sys/types.h>
no longer provides these definitions.
.SH SEE ALSO
.BR mknod (2),
this is not considered an error.
(See "Nonportable behavior" for portability issues.)
Otherwise, the returned pointer may be the same as
-.IR ptr
+.I ptr
if the allocation was not moved
(e.g., there was room to expand the allocation in-place), or different from
-.IR ptr
+.I ptr
if the allocation was moved to a new address.
If these functions fail,
the original block is left untouched; it is not freed or moved.
.B ENOMEM
Out of memory.
Possibly, the application hit the
-.BR RLIMIT_AS
+.B RLIMIT_AS
or
-.BR RLIMIT_DATA
+.B RLIMIT_DATA
limit described in
.BR getrlimit (2).
.SH VERSIONS
In case it turns out that the system is out of memory,
one or more processes will be killed by the OOM killer.
For more information, see the description of
-.IR /proc/sys/vm/overcommit_memory
+.I /proc/sys/vm/overcommit_memory
and
-.IR /proc/sys/vm/oom_adj
+.I /proc/sys/vm/oom_adj
in
.BR proc (5),
and the Linux kernel source file
there could be contention for these mutexes.
To scalably handle memory allocation in multithreaded applications,
glibc creates additional
-.IR "memory allocation arenas"
+.I memory allocation arenas
if mutex contention is detected.
Each arena is a large region of memory that is internally allocated
by the system
.nf
.B #include <malloc.h>
.PP
-.BI "void *malloc_get_state(void);"
+.B void *malloc_get_state(void);
.BI "int malloc_set_state(void *" state );
.fi
.SH DESCRIPTION
memory-allocation functions (see
.BR malloc (3)).
The
-.IR param
+.I param
argument specifies the parameter to be modified, and
.I value
specifies the new value for that parameter.
The following values can be specified for
.IR param :
.TP
-.BR M_ARENA_MAX
+.B M_ARENA_MAX
If this parameter has a nonzero value,
it defines a hard limit on the maximum number of arenas that can be created.
An arena represents a pool of memory that can be used by
This is similar in behavior to strategies taken by tcmalloc and jemalloc
(e.g., per-thread allocation pools).
.TP
-.BR M_ARENA_TEST
+.B M_ARENA_TEST
This parameter specifies a value, in number of arenas created,
at which point the system configuration will be examined
to determine a hard limit on the number of created arenas.
The default value for the
.B M_ARENA_TEST
parameter is 2 on systems where
-.IR sizeof(long)
+.I sizeof(long)
is 4; otherwise the default value is 8.
.IP
This parameter has been available since glibc 2.10 via
.B M_ARENA_MAX
has a nonzero value.
.TP
-.BR M_CHECK_ACTION
+.B M_CHECK_ACTION
Setting this parameter controls how glibc responds when various kinds
of programming errors are detected (e.g., freeing the same pointer twice).
The 3 least significant bits (2, 1, and 0) of the value assigned
the program also prints a stack trace in the manner of
.BR backtrace (3),
and prints the process's memory mapping in the style of
-.IR /proc/[pid]/maps
+.IR /proc/ pid /maps
(see
.BR proc (5)).
.TP
.RE
.IP
Since glibc 2.3.4, the default value for the
-.BR M_CHECK_ACTION
+.B M_CHECK_ACTION
parameter is 3.
In glibc version 2.3.3 and earlier, the default value is 1.
.IP
value can be useful because otherwise a crash may happen much later,
and the true cause of the problem is then very hard to track down.
.TP
-.BR M_MMAP_MAX
+.B M_MMAP_MAX
.\" The following text adapted from comments in the glibc source:
This parameter specifies the maximum number of allocation requests that
may be simultaneously serviced using
.BR mmap (2)
for servicing large allocation requests.
.TP
-.BR M_MMAP_THRESHOLD
+.B M_MMAP_THRESHOLD
For allocations greater than or equal to the limit specified (in bytes) by
-.BR M_MMAP_THRESHOLD
+.B M_MMAP_THRESHOLD
that can't be satisfied from the free list,
the memory-allocation functions employ
.BR mmap (2)
memory allocated via
.BR mmap (2).
Balancing these factors leads to a default setting of 128*1024 for the
-.BR M_MMAP_THRESHOLD
+.B M_MMAP_THRESHOLD
parameter.
.IP
The lower limit for this parameter is 0.
The upper limit is
.BR DEFAULT_MMAP_THRESHOLD_MAX :
512*1024 on 32-bit systems or
-.IR 4*1024*1024*sizeof(long)
+.I 4*1024*1024*sizeof(long)
on 64-bit systems.
.IP
-.IR Note:
+.IR Note :
Nowadays, glibc uses a dynamic mmap threshold by default.
The initial value of the threshold is 128*1024,
but when blocks larger than the current threshold and less than or equal to
-.BR DEFAULT_MMAP_THRESHOLD_MAX
+.B DEFAULT_MMAP_THRESHOLD_MAX
are freed,
the threshold is adjusted upward to the size of the freed block.
When dynamic mmap thresholding is in effect,
.BR M_TOP_PAD ,
.BR M_MMAP_THRESHOLD ,
or
-.BR M_MMAP_MAX
+.B M_MMAP_MAX
parameters is set.
.TP
.BR M_MXFAST " (since glibc 2.3)"
of the program can increase.
.IP
The default value for this parameter is
-.IR "64*sizeof(size_t)/4"
+.I 64*sizeof(size_t)/4
(i.e., 64 on 32-bit architectures).
The range for this parameter is 0 to
-.IR "80*sizeof(size_t)/4" .
+.IR 80*sizeof(size_t)/4 .
Setting
.B M_MXFAST
to 0 disables the use of fastbins.
.IP
The default value for this parameter is 0.
.TP
-.BR M_TOP_PAD
+.B M_TOP_PAD
This parameter defines the amount of padding to employ when calling
.BR sbrk (2)
to modify the program break.
.RS
.IP * 3
When the program break is increased, then
-.BR M_TOP_PAD
+.B M_TOP_PAD
bytes are added to the
.BR sbrk (2)
request.
the amount of padding is always rounded to a system page boundary.
.IP
Modifying
-.BR M_TOP_PAD
+.B M_TOP_PAD
is a trade-off between increasing the number of system calls
(when the parameter is set low)
and wasting unused memory at the top of the heap
The default value for this parameter is 128*1024.
.\" DEFAULT_TOP_PAD in glibc source
.TP
-.BR M_TRIM_THRESHOLD
+.B M_TRIM_THRESHOLD
When the amount of contiguous free memory at the top of the heap
grows sufficiently large,
.BR free (3)
(This can be useful in programs that continue to execute for
a long period after freeing a significant amount of memory.)
The
-.BR M_TRIM_THRESHOLD
+.B M_TRIM_THRESHOLD
parameter specifies the minimum size (in bytes) that
this block of memory must reach before
.BR sbrk (2)
.IP
The default value for this parameter is 128*1024.
Setting
-.BR M_TRIM_THRESHOLD
+.B M_TRIM_THRESHOLD
to \-1 disables trimming completely.
.IP
Modifying
-.BR M_TRIM_THRESHOLD
+.B M_TRIM_THRESHOLD
is a trade-off between increasing the number of system calls
(when the parameter is set low)
and wasting unused memory at the top of the heap
The environment variables are as follows
(note the trailing underscore at the end of the name of some variables):
.TP
-.BR MALLOC_ARENA_MAX
+.B MALLOC_ARENA_MAX
Controls the same parameter as
.BR mallopt ()
.BR M_ARENA_MAX .
.TP
-.BR MALLOC_ARENA_TEST
+.B MALLOC_ARENA_TEST
Controls the same parameter as
.BR mallopt ()
.BR M_ARENA_TEST .
.TP
-.BR MALLOC_CHECK_
+.B MALLOC_CHECK_
This environment variable controls the same parameter as
.BR mallopt ()
.BR M_CHECK_ACTION .
Any characters beyond the initial digit are ignored.
.IP
For security reasons, the effect of
-.BR MALLOC_CHECK_
+.B MALLOC_CHECK_
is disabled by default for set-user-ID and set-group-ID programs.
However, if the file
-.IR /etc/suid\-debug
+.I /etc/suid\-debug
exists (the content of the file is irrelevant), then
-.BR MALLOC_CHECK_
+.B MALLOC_CHECK_
also has an effect for set-user-ID and set-group-ID programs.
.TP
-.BR MALLOC_MMAP_MAX_
+.B MALLOC_MMAP_MAX_
Controls the same parameter as
.BR mallopt ()
.BR M_MMAP_MAX .
.TP
-.BR MALLOC_MMAP_THRESHOLD_
+.B MALLOC_MMAP_THRESHOLD_
Controls the same parameter as
.BR mallopt ()
.BR M_MMAP_THRESHOLD .
.TP
-.BR MALLOC_PERTURB_
+.B MALLOC_PERTURB_
Controls the same parameter as
.BR mallopt ()
.BR M_PERTURB .
.TP
-.BR MALLOC_TRIM_THRESHOLD_
+.B MALLOC_TRIM_THRESHOLD_
Controls the same parameter as
.BR mallopt ()
.BR M_TRIM_THRESHOLD .
.TP
-.BR MALLOC_TOP_PAD_
+.B MALLOC_TOP_PAD_
Controls the same parameter as
.BR mallopt ()
.BR M_TOP_PAD .
This function is not specified by POSIX or the C standards.
A similar function exists on many System V derivatives,
but the range of values for
-.IR param
+.I param
varies across systems.
The SVID defined options
.BR M_MXFAST ,
.BR M_CHECK_ACTION .
If the program is supplied with an (integer) command-line argument,
then that argument is used to set the
-.BR M_CHECK_ACTION
+.B M_CHECK_ACTION
parameter.
The program then allocates a block of memory,
and frees it twice (an error).
If the multibyte character is the null wide character, it returns 0.
.PP
If the
-.IR n
+.I n
bytes starting at
.I s
do not contain a complete multibyte
to the initial state and returns 0.
.PP
If the
-.IR n
+.I n
bytes starting at
.I s
do not contain a complete multibyte
sequence before the next complete character,
.BR mbrlen ()
returns
-.IR "(size_t)\ \-1"
+.I (size_t)\ \-1
and sets
.I errno
to
if an invalid multibyte sequence was
encountered.
It returns
-.IR "(size_t)\ \-2"
+.I (size_t)\ \-2
if it couldn't parse a complete multibyte
character, meaning that
.I n
.fi
.SH DESCRIPTION
The main case for this function is when
-.IR s
+.I s
is not NULL and
.I pwc
is
to the initial state and returns 0.
.PP
If the
-.IR n
+.I n
bytes starting at
.I s
do not contain a complete multibyte
sequence before the next complete character,
.BR mbrtowc ()
returns
-.IR "(size_t)\ \-1"
+.I (size_t)\ \-1
and sets
.I errno
to
are undefined.
.PP
A different case is when
-.IR s
+.I s
is not NULL but
.I pwc
is NULL.
.I s
is NULL.
In this case,
-.IR pwc
+.I pwc
and
.I n
are
.BR mbrtowc ()
function is used instead.
Otherwise,
-.IR *ps
+.I *ps
must be a valid
.I mbstate_t
object.
An
-.IR mbstate_t
+.I mbstate_t
object
.I a
can be initialized to the initial state
the number of bytes to be converted, starting at
.IR *src ,
is limited to at most
-.IR nms
+.I nms
bytes.
.PP
If
The glibc implementation adopts the former behavior.
.PP
If
-.IR dest
+.I dest
is NULL,
.I len
is ignored, and the conversion proceeds as
excluding the terminating null wide character, is returned.
.PP
If
-.IR dest
+.I dest
is NULL,
.I len
is ignored,
.IR dest .
.PP
If
-.IR dest
+.I dest
is NULL,
.I n
is ignored, and the conversion proceeds as
.fi
.SH DESCRIPTION
The main case for this function is when
-.IR s
+.I s
is not NULL and
.I pwc
is
otherwise it returns 0.
.PP
If the
-.IR n
+.I n
bytes starting at
.I s
do not contain a complete multibyte
if the multibyte string contains redundant shift sequences.
.PP
A different case is when
-.IR s
+.I s
is not NULL but
.I pwc
is NULL.
.I s
is NULL.
In this case,
-.IR pwc
+.I pwc
and
.I n
are
.BR malloc (3)
or a related function.
In cases where this is difficult to ensure, linking the program with
-.IR \-lmcheck
+.I \-lmcheck
inserts an implicit call to
.BR mcheck ()
(with a NULL argument)
If
.I abortfunc
is NULL, a default function prints an error message on
-.IR stderr
+.I stderr
and calls
.BR abort (3).
.PP
.BR memccpy ()
function returns a pointer to the next character
in
-.IR dest
+.I dest
after
.IR c ,
or NULL if
.\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com)
.\" 2008-07-09, mtk, add rawmemchr()
.\"
-.TH MEMCHR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH MEMCHR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
memchr, memrchr, rawmemchr \- scan memory for a character
.SH LIBRARY
lies somewhere in the memory area starting at the location pointed to by
.IR s ,
and so performs an optimized search for
-.IR c
+.I c
(i.e., no use of a count argument to limit the range of the search).
If an instance of
.I c
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu)
-.TH MEMCMP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH MEMCMP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
memcmp \- compare memory areas
.SH LIBRARY
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu)
-.TH MEMCPY 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH MEMCPY 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
memcpy \- copy memory area
.SH LIBRARY
.BR memmem ()
function finds the start of the first occurrence
of the substring
-.IR needle
+.I needle
of length
.I needlelen
in the memory
.BR O_RDWR ,
.BR O_CREAT ,
and
-.BR O_EXCL
+.B O_EXCL
in the
.I flags
argument given to
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH MODF 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH MODF 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
modf, modff, modfl \- extract signed integral and fractional values from
floating-point number
If
.I x
is a NaN, a NaN is returned, and
-.IR *iptr
+.I *iptr
is set to a NaN.
.PP
If
.I x
is positive infinity (negative infinity), +0 (\-0) is returned, and
-.IR *iptr
+.I *iptr
is set to positive infinity (negative infinity).
.SH ERRORS
No errors occur.
.\"
.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93
.\"
-.TH MPOOL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH MPOOL 3 2021-03-22 GNU "Linux Programmer's Manual"
.UC 7
.SH NAME
mpool \- shared memory buffer pool
The permissions settings are masked against the process umask.
.PP
The fields of the
-.IR "struct mq_attr"
+.I struct mq_attr
pointed to
.I attr
specify the maximum number of messages and
The per-process limit on the number of open file
and message queue descriptors has been reached
(see the description of
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
If the pathname is successfully opened, it is truncated to zero length.
.PP
If
-.BR MALLOC_TRACE
+.B MALLOC_TRACE
is not set,
or the pathname it specifies is invalid or not writable,
then no hook functions are installed, and
.BR mtrace ()
has no effect.
In set-user-ID and set-group-ID programs,
-.BR MALLOC_TRACE
+.B MALLOC_TRACE
is ignored, and
.BR mtrace ()
has no effect.
If
.I base
is the special locale object
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
(see
.BR duplocale (3)),
or is not
-.IR "(locale_t)\ 0"
+.I (locale_t)\ 0
and is not a valid locale object handle,
the behavior is undefined.
.PP
.BR newlocale ().
If a new locale object is being created,
data for all categories not specified in
-.IR category_mask
+.I category_mask
is taken from the default ("POSIX") locale.
.PP
The following preset values of
""
An implementation-defined native environment
corresponding to the values of the
-.BR LC_*
+.B LC_*
and
.B LANG
environment variables (see
If
.I locobj
is
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
or is not valid locale object handle, the results are undefined.
.PP
Once a locale object has been freed,
Set the
.B LC_NUMERIC
category to
-.IR fr_FR
+.I fr_FR
(French):
.PP
.in +4n
Set the
.B LC_NUMERIC
category to
-.IR fr_FR
+.I fr_FR
(French),
and the
.B LC_TIME
category to
-.IR it_IT
+.I it_IT
(Italian):
.PP
.in +4n
the returned value is NaN.
.PP
The value returned by
-.IR nextdown(x)
+.I nextdown(x)
is
.IR \-nextup(\-x) ,
and similarly for the other types.
.sp 1
.SH CONFORMING TO
These functions are described in
-.IR "IEEE Std 754-2008 - Standard for Floating-Point Arithmetic"
+.I IEEE Std 754-2008 - Standard for Floating-Point Arithmetic
and
.IR "ISO/IEC TS 18661".
.SH SEE ALSO
is undefined if
.I locale
is the special locale object
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
or is not a valid locale object handle.
.SH EXAMPLES
The following program sets the character type and the numeric locale
.IR time ,
.IR maxerror ,
and
-.IR esterror
+.I esterror
fields are filled in.
.PP
.BR ntp_gettimex ()
this buffer.
.PP
The locations pointed to by
-.IR ptr
+.I ptr
and
.I sizeloc
are used to report, respectively,
.\" (msmith@falcon.mercer.peachnet.edu) and various other changes.
.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de)
.\"
-.TH PERROR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH PERROR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
perror \- print a system error message
.SH LIBRARY
In glibc, this function is implemented using
.BR madvise (2).
However, since glibc 2.6,
-.BR POSIX_MADV_DONTNEED
+.B POSIX_MADV_DONTNEED
is treated as a no-op, because the corresponding
.BR madvise (2)
value,
.I size
is 0, then
the value placed in
-.IR "*memptr"
+.I *memptr
is either NULL
.\" glibc does this:
or a unique pointer value.
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH POSIX_OPENPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH POSIX_OPENPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
posix_openpt \- open a pseudoterminal device
.SH LIBRARY
.BR posix_spawnp (),
the executable file is specified as a simple filename;
the system searches for this file in the list of directories specified by
-.BR PATH
+.B PATH
(in the same way as for
.BR execvp (3)).
For the remainder of this page, the discussion is phrased in terms of
function commences by calling
.BR clone (2)
with
-.BR CLONE_VM
+.B CLONE_VM
and
-.BR CLONE_VFORK
+.B CLONE_VFORK
flags.
Older implementations use
.BR fork (2),
the requested file.
.SS pre-exec() step: housekeeping
In between the
-.BR fork()
+.B fork()
and the
-.BR exec()
+.B exec()
steps, a child process may need to perform a set of housekeeping actions.
The
.BR posix_spawn ()
functions support a small, well-defined set of system tasks that the child
process can accomplish before it executes the executable file.
These operations are controlled by the attributes object pointed to by
-.IR attrp
+.I attrp
and the file actions object pointed to by
.IR file_actions .
In the child, processing is done in the following sequence:
All process attributes in the child,
other than those affected by attributes specified in the
object pointed to by
-.IR attrp
+.I attrp
and the file actions in the object pointed to by
.IR file_actions ,
will be affected as though the child was created with
to be used during those actions.
.PP
The effects of the flags that may be specified in
-.IR spawn-flags
+.I spawn-flags
are as follows:
.TP
.B POSIX_SPAWN_SETSIGMASK
.\" (see
.\" .BR posix_spawnattr_setsigdefault (3))
of the object pointed to by
-.IR attrp
+.I attrp
to the default.
For the treatment of the dispositions of signals not specified in the
.I spawn-sigdefault
.\" (see
.\" .BR posix_spawnattr_setschedparam (3))
of the object pointed to by
-.IR attrp
+.I attrp
(but see BUGS).
.PP
If the
.B POSIX_SPAWN_USEVFORK
Since glibc 2.24, this flag has no effect.
On older implementations, setting this flag forces the
-.BR fork()
+.B fork()
step to use
.BR vfork (2)
instead of
.IR pid ,
and return 0.
If there is an error during the
-.BR fork()
+.B fork()
step,
then no child is created,
the contents of
-.IR *pid
+.I *pid
are unspecified,
and these functions return an error number as described below.
.PP
However, this functionality can be obtained by specifying the
.I path
argument as one of the files in the caller's
-.IR /proc/self/fd
+.I /proc/self/fd
directory.
.SH BUGS
POSIX.1 says that when
.BR posix_spawn ()
failed with an error if
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052
-.BR POSIX_SPAWN_SETSCHEDULER
+.B POSIX_SPAWN_SETSCHEDULER
was specified without also specifying
.BR POSIX_SPAWN_SETSCHEDPARAM .
.SH EXAMPLES
.BR SIGTERM )
fails, because that signal is blocked.
Therefore, to kill the child,
-.BR SIGKILL
+.B SIGKILL
is necessary
.RB ( SIGKILL
can't be blocked).
.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no>
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
-.TH POW 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH POW 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
pow, powf, powl \- power functions
.SH LIBRARY
Pole error: \fIx\fP is zero, and \fIy\fP is negative
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
when a pole error occurs,
.I errno
is set to
-.BR EDOM
+.B EDOM
instead of the POSIX-mandated
.BR ERANGE .
Since version 2.10,
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH POW10 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH POW10 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
pow10, pow10f, pow10l \- base-10 power functions
.SH LIBRARY
.TP
.B Z
A nonstandard synonym for
-.BR z
+.B z
that predates the appearance of
.BR z .
Do not use in new code.
and
.B L
as synonyms, so that one can, for example, write
-.BR llg
+.B llg
(as a synonym for the standards-compliant
.BR Lg )
and
-.BR Ld
+.B Ld
(as a synonym for the standards compliant
.BR lld ).
Such usage is nonportable.
.SH NOTES
Some programs imprudently rely on code such as the following
.PP
- sprintf(buf, "%s some further text", buf);
+.in +4n
+.EX
+sprintf(buf, "%s some further text", buf);
+.EE
+.in
.PP
to append text to
.IR buf .
.PP
Three kinds of handler can be registered:
.IP * 3
-.IR prepare
+.I prepare
specifies a handler that is executed in the parent process before
.BR fork (2)
processing starts.
The
.BR pthread_attr_init ()
function initializes the thread attributes object pointed to by
-.IR attr
+.I attr
with default attribute values.
After this call, individual attributes of the object can be set
using various related functions (listed under SEE ALSO),
function
returns the CPU affinity mask attribute of the thread attributes object
referred to by
-.IR attr
+.I attr
in the buffer pointed to by
.IR cpuset .
.PP
on error, they return a nonzero error number.
.SH ERRORS
.TP
-.BR EINVAL
+.B EINVAL
.RB ( pthread_attr_setaffinity_np ())
.I cpuset
specified a CPU that was outside the set supported by the kernel.
(The kernel configuration option
-.BR CONFIG_NR_CPUS
+.B CONFIG_NR_CPUS
defines the range of the set supported by the kernel data type
.\" cpumask_t
used to represent CPU sets.)
A CPU in the affinity mask of the thread attributes object referred to by
.I attr
lies outside the range specified by
-.IR cpusetsize
+.I cpusetsize
(i.e.,
.IR cpuset / cpusetsize
is too small).
.BR pthread_attr_setdetachstate ()
function sets the detach state attribute of the
thread attributes object referred to by
-.IR attr
+.I attr
to the value specified in
.IR detachstate .
The detach state attribute determines whether a thread created using
The
.BR pthread_attr_getdetachstate ()
returns the detach state attribute of the thread attributes object
-.IR attr
+.I attr
in the buffer pointed to by
.IR detachstate .
.SH RETURN VALUE
.BR pthread_attr_setinheritsched ()
function sets the inherit-scheduler attribute of the
thread attributes object referred to by
-.IR attr
+.I attr
to the value specified in
.IR inheritsched .
The inherit-scheduler attribute determines whether a thread created using
The
.BR pthread_attr_getinheritsched ()
returns the inherit-scheduler attribute of the thread attributes object
-.IR attr
+.I attr
in the buffer pointed to by
.IR inheritsched .
.SH RETURN VALUE
As at glibc 2.8, if a thread attributes object is initialized using
.BR pthread_attr_init (3),
then the scheduling policy of the attributes object is set to
-.BR SCHED_OTHER
+.B SCHED_OTHER
and the scheduling priority is set to 0.
However, if the inherit-scheduler attribute is then set to
.BR PTHREAD_EXPLICIT_SCHED ,
.BR pthread_attr_setschedparam ()
function sets the scheduling parameter attributes of the
thread attributes object referred to by
-.IR attr
+.I attr
to the values specified in the buffer pointed to by
.IR param .
These attributes determine the scheduling parameters of
The
.BR pthread_attr_getschedparam ()
returns the scheduling parameter attributes of the thread attributes object
-.IR attr
+.I attr
in the buffer pointed to by
.IR param .
.PP
.BR pthread_attr_setschedpolicy ()
function sets the scheduling policy attribute of the
thread attributes object referred to by
-.IR attr
+.I attr
to the value specified in
.IR policy .
This attribute determines the scheduling policy of
The
.BR pthread_attr_getschedpolicy ()
returns the scheduling policy attribute of the thread attributes object
-.IR attr
+.I attr
in the buffer pointed to by
.IR policy .
.PP
.B PTHREAD_SCOPE_PROCESS
The thread competes for resources with all other threads
in the same process that were also created with the
-.BR PTHREAD_SCOPE_PROCESS
+.B PTHREAD_SCOPE_PROCESS
contention scope.
-.BR PTHREAD_SCOPE_PROCESS
+.B PTHREAD_SCOPE_PROCESS
threads are scheduled relative to other threads in the process
according to their scheduling policy and priority.
POSIX.1 leaves it unspecified how these threads contend
.IR scope .
.TP
.B ENOTSUP
-.IR scope
+.I scope
specified the value
.BR PTHREAD_SCOPE_PROCESS ,
which is not supported on Linux.
.BR pthread_attr_getsigmask_np ()
function returns the signal mask attribute of the thread attributes object
referred to by
-.IR attr
+.I attr
in the buffer pointed to by
.IR sigmask .
If the signal mask attribute is currently unset,
thread attributes object referred to by
.I attr
to the values specified in
-.IR stackaddr
+.I stackaddr
and
.IR stacksize ,
respectively.
thread attributes object referred to by
.I attr
in the buffers pointed to by
-.IR stackaddr
+.I stackaddr
and
.IR stacksize ,
respectively.
.B EINVAL
.I stacksize
is less than
-.BR PTHREAD_STACK_MIN
+.B PTHREAD_STACK_MIN
(16384) bytes.
On some systems, this error may also occur if
-.IR stackaddr
+.I stackaddr
or
-.IR "stackaddr\ +\ stacksize"
+.I stackaddr\~+\~stacksize
is not suitably aligned.
.PP
POSIX.1 also documents an
-.BR EACCES
+.B EACCES
error if the stack area described by
.I stackaddr
and
.BR posix_memalign (3)
may be useful for allocation.
Probably,
-.IR stacksize
+.I stacksize
should also be a multiple of the system page size.
.PP
If
.TP
.B EINVAL
The stack size is less than
-.BR PTHREAD_STACK_MIN
+.B PTHREAD_STACK_MIN
(16384) bytes.
.PP
On some systems,
if the specified
.I stacksize
is not a multiple of
-.BR STACK_ALIGN
+.B STACK_ALIGN
(16 bytes on most architectures), it may be rounded
.IR downward ,
in violation of POSIX.1, which says that the allocated stack will
A thread's cancelation type, determined by
.BR pthread_setcanceltype (3),
may be either
-.IR asynchronous
+.I asynchronous
or
-.IR deferred
+.I deferred
(the default for new threads).
Asynchronous cancelability
means that the thread can be canceled at any time
.BR pthreads (7).
.PP
When a cancelation requested is acted on, the following steps occur for
-.IR thread
+.I thread
(in this order):
.IP 1. 3
Cancellation clean-up handlers are popped
.IR break ,
.IR continue ,
or
-.IR goto
+.I goto
to prematurely leave a block bracketed
.BR pthread_cleanup_push ()
and
function starts a new thread in the calling process.
The new thread starts execution by invoking
.IR start_routine ();
-.IR arg
+.I arg
is passed as the sole argument of
.IR start_routine ().
.PP
.BR pthread_create ()
returns 0;
on error, it returns an error number, and the contents of
-.IR *thread
+.I *thread
are undefined.
.SH ERRORS
.TP
.\" NOTE! The following should match the description in fork(2)
A system-imposed limit on the number of threads was encountered.
There are a number of limits that may trigger this error: the
-.BR RLIMIT_NPROC
+.B RLIMIT_NPROC
soft resource limit (set via
.BR setrlimit (2)),
which limits the number of processes and threads for a real user ID,
See
.BR pthread_self (3)
for further information on the thread ID returned in
-.IR *thread
+.I *thread
by
.BR pthread_create ().
Unless real-time scheduling policies are being employed,
.BR pthread_attr_setdetachstate (3)).
.PP
Under the NPTL threading implementation, if the
-.BR RLIMIT_STACK
+.B RLIMIT_STACK
soft resource limit
-.IR "at the time the program started"
+.I at the time the program started
has any value other than "unlimited",
then it determines the default stack size of new threads.
Using
argument used to create a thread,
in order to obtain a stack size other than the default.
If the
-.BR RLIMIT_STACK
+.B RLIMIT_STACK
resource limit is set to "unlimited",
a per-architecture value is used for the stack size.
Here is the value for a few architectures:
The
.BR pthread_detach ()
function marks the thread identified by
-.IR thread
+.I thread
as detached.
When a detached thread terminates,
its resources are automatically released back to the system without
.SH EXAMPLES
The following statement detaches the calling thread:
.PP
- pthread_detach(pthread_self());
+.in +4n
+.EX
+pthread_detach(pthread_self());
+.EE
+.in
.SH SEE ALSO
.BR pthread_attr_setdetachstate (3),
.BR pthread_cancel (3),
.BR exit (3).
.PP
The value pointed to by
-.IR retval
+.I retval
should not be located on the calling thread's stack,
since the contents of that stack are undefined after the thread terminates.
.SH BUGS
The attribute settings in the object must be valid.
.IP *
The
-.IR "stack address"
+.I stack address
attribute must not be set in the object.
.IP *
Setting the
-.IR "stack size"
+.I stack size
attribute to zero means leave the default stack size unchanged.
.PP
The
.B EINVAL
.RB ( pthread_setattr_default_np ())
One of the attribute settings in
-.IR attr
+.I attr
is invalid, or the stack address attribute is set in
.IR attr .
.TP
can fail because of errors from various underlying calls:
.BR fopen (3),
if
-.IR /proc/self/maps
+.I /proc/self/maps
can't be opened;
and
.BR getrlimit (2),
if the
-.BR RLIMIT_STACK
+.B RLIMIT_STACK
resource limit is not supported.
.SH VERSIONS
This function is available in glibc since version 2.2.3.
The
.BR pthread_join ()
function waits for the thread specified by
-.IR thread
+.I thread
to terminate.
If that thread has already terminated, then
.BR pthread_join ()
A mutex can be left in an inconsistent state if its owner terminates
while holding the mutex, in which case the next owner who acquires the
mutex will succeed and be notified by a return value of
-.BR EOWNERDEAD
+.B EOWNERDEAD
from a call to
.BR pthread_mutex_lock ().
.SH RETURN VALUE
.BR pthread_mutex_consistent ()
to POSIX,
glibc defined the following equivalent nonstandard function if
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
was defined:
.PP
.nf
.nf
.B #include <pthread.h>
.PP
-.BI "int pthread_mutexattr_getpshared("
+.B int pthread_mutexattr_getpshared(
.BI " const pthread_mutexattr_t *restrict " attr ,
.BI " int *restrict " pshared );
.BI "int pthread_mutexattr_setpshared(pthread_mutexattr_t *" attr ,
.BR pthread_mutexattr_getpshared ()
places the value of the process-shared attribute of
the mutex attributes object referred to by
-.IR attr
+.I attr
in the location pointed to by
.IR pshared .
.PP
.BR pthread_mutexattr_setpshared ()
sets the value of the process-shared attribute of
the mutex attributes object referred to by
-.IR attr
+.I attr
to the value specified in
.BR pshared .
.PP
.TP
.B ENOTSUP
.I pshared is
-.BR PTHREAD_PROCESS_SHARED
+.B PTHREAD_PROCESS_SHARED
but the implementation does not support process-shared mutexes.
.SH CONFORMING TO
POSIX.1-2001, POSIX.1-2008.
The following values are valid for
.IR robustness :
.TP
-.BR PTHREAD_MUTEX_STALLED
+.B PTHREAD_MUTEX_STALLED
This is the default value for a mutex attributes object.
If a mutex is initialized with the
-.BR PTHREAD_MUTEX_STALLED
+.B PTHREAD_MUTEX_STALLED
attribute and its owner dies without unlocking it,
the mutex remains locked afterwards and any future attempts to call
.BR pthread_mutex_lock (3)
.TP
.B PTHREAD_MUTEX_ROBUST
If a mutex is initialized with the
-.BR PTHREAD_MUTEX_ROBUST
+.B PTHREAD_MUTEX_ROBUST
attribute and its owner dies without unlocking it,
any future attempts to call
.BR pthread_mutex_lock (3)
.BR EOWNERDEAD .
.PP
Note that the
-.IR attr
+.I attr
argument of
.BR pthread_mutexattr_getrobust ()
and
.BR pthread_mutexattr_setrobust ()
to POSIX,
glibc defined the following equivalent nonstandard functions if
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
was defined:
.PP
.nf
.PP
.BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr ,
.BI " int " pref );
-.BI "int pthread_rwlockattr_getkind_np("
+.B int pthread_rwlockattr_getkind_np(
.BI " const pthread_rwlockattr_t *restrict " attr ,
.BI " int *restrict " pref );
.PP
.BR pthread_rwlockattr_getkind_np ()
function returns the value of the lock kind attribute of the
read-write lock attribute object referred to by
-.IR attr
+.I attr
in the pointer
.IR pref .
.SH RETURN VALUE
returns a nonzero error number.
.SH ERRORS
.TP
-.BR EINVAL
+.B EINVAL
.I pref
specifies an unsupported value.
.SH VERSIONS
.BR pthread_self ()
function returns the ID of the calling thread.
This is the same value that is returned in
-.IR *thread
+.I *thread
in the
.BR pthread_create (3)
call that created this thread.
may be imposed by the "cpuset" mechanism described in
.BR cpuset (7).
.TP
-.BR EINVAL
+.B EINVAL
.RB ( pthread_setaffinity_np ())
.I cpuset
specified a CPU that was outside the set supported by the kernel.
(The kernel configuration option
-.BR CONFIG_NR_CPUS
+.B CONFIG_NR_CPUS
defines the range of the set supported by the kernel data type
.\" cpumask_t
used to represent CPU sets.)
is negative.
.PP
POSIX.1 also documents an
-.BR EAGAIN
+.B EAGAIN
error ("the value specified by
.I new_level
would cause a system resource to be exceeded").
internally writes to the thread-specific
.I comm
file under the
-.IR /proc
+.I /proc
filesystem:
.IR /proc/self/task/[tid]/comm .
.BR pthread_getname_np ()
pthreads functions.
.PP
In the following run, the main thread sets its scheduling policy to
-.BR SCHED_FIFO
+.B SCHED_FIFO
with a priority of 10,
and initializes a thread attributes object with
a scheduling policy attribute of
-.BR SCHED_RR
+.B SCHED_RR
and a scheduling priority attribute of 20.
The program then sets (using
.BR pthread_attr_setinheritsched (3))
rather than the thread attributes object.
.PP
Note that if we had omitted the
-.IR "\-i\ i"
+.I \-i\~i
option, the output would have been the same, since
-.BR PTHREAD_INHERIT_SCHED
+.B PTHREAD_INHERIT_SCHED
is the default for the inherit scheduler attribute.
.SS Program source
\&
or possibly
.BR SCHED_RR ).
Use of spin locks with nondeterministic scheduling policies such as
-.BR SCHED_OTHER
+.B SCHED_OTHER
probably indicates a design mistake.
The problem is that if a thread operating under such a policy
is scheduled off the CPU while it holds a spin lock,
then the call blocks until a maximum time, specified in
.IR abstime ,
measured against the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock.
If the timeout expires before
.I thread
.BR pthread_timedjoin_np ()
can in addition fail with the following errors:
.TP
-.BR EINVAL
+.B EINVAL
.I abstime
value is invalid
.RI ( tv_sec
is less than 0 or
-.IR tv_nsec
+.I tv_nsec
is greater than 1e9).
.TP
-.BR ETIMEDOUT
+.B ETIMEDOUT
The call timed out before
.I thread
terminated.
.BR pthread_timedjoin_np ()
function measures time by internally calculating a relative sleep interval
that is then measured against the
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
clock instead of the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock.
Consequently, the timeout is unaffected by discontinuous changes to the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock.
.SH EXAMPLES
The following code waits to join for up to 5 seconds:
.PP
.BR pthread_yield ()
is intended for use with real-time scheduling policies (i.e.,
-.BR SCHED_FIFO
+.B SCHED_FIFO
or
.BR SCHED_RR ).
Use of
.BR pthread_yield ()
with nondeterministic scheduling policies such as
-.BR SCHED_OTHER
+.B SCHED_OTHER
is unspecified and very likely means your application design is broken.
.SH SEE ALSO
.BR sched_yield (2),
.\"
.\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS
.\"
-.TH PTSNAME 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH PTSNAME 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ptsname, ptsname_r \- get the name of the slave pseudoterminal
.SH LIBRARY
.ad
.sp 1
.SH CONFORMING TO
+.TP
.BR ptsname ():
- POSIX.1-2001, POSIX.1-2008.
+POSIX.1-2001, POSIX.1-2008.
.PP
.BR ptsname ()
is part of the UNIX 98 pseudoterminal support (see
function is the counterpart for
.BR fgetgrent (3).
The function writes the content of the provided
-.IR "struct group"
+.I struct group
into the
.IR stream .
The list of group members must be NULL-terminated or NULL-initialized.
.PP
The
-.IR "struct group"
+.I struct group
is defined as follows:
.PP
.in +4n
.BR WEOF .
If a wide character
conversion error occurs, it sets
-.IR errno
+.I errno
to
.B EILSEQ
and returns
.\" and Ben Bacarisse <software@bsb.me.uk>
.\" Document qsort_r()
.\"
-.TH QSORT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH QSORT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
qsort, qsort_r \- sort an array
.SH LIBRARY
.\" Modified 2003-11-15, aeb, added rand_r
.\" 2010-09-13, mtk, added example program
.\"
-.TH RAND 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH RAND 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
rand, rand_r, srand \- pseudo-random number generator
.SH LIBRARY
The
.BR rand ()
function returns a pseudo-random integer in the range 0 to
-.BR RAND_MAX
+.B RAND_MAX
inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]).
.PP
The
The
.I seedp
argument is a pointer to an
-.IR "unsigned int"
+.I unsigned int
that is used to store state between calls.
If
.BR rand_r ()
and
.BR rand_r ()
functions return a value between 0 and
-.BR RAND_MAX
+.B RAND_MAX
(inclusive).
The
.BR srand ()
.IR buf ,
rather than initializing the global state variable.
Before calling this function, the
-.IR buf.state
+.I buf.state
field must be initialized to NULL.
The
.BR initstate_r ()
argument inside the structure pointed to by
.IR buf .
Thus,
-.IR statebuf
+.I statebuf
should not be deallocated so long as
-.IR buf
+.I buf
is still in use.
(So,
.I statebuf
interface is confusing.
.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662
It appears that the
-.IR random_data
+.I random_data
type is intended to be opaque,
but the implementation requires the user to either initialize the
.I buf.state
.PP
If the connection succeeds,
a socket in the Internet domain of type
-.BR SOCK_STREAM
+.B SOCK_STREAM
is returned to the caller, and given to the remote
command as
-.IR stdin
+.I stdin
and
.IR stdout .
If
If
.I fd2p
is 0, then the
-.IR stderr
+.I stderr
(unit 2 of the remote
command) will be made the same as the
-.IR stdout
+.I stdout
and no
provision is made for sending arbitrary signals to the remote process,
although you may be able to get its attention by using out-of-band data.
Then, if the user is
.I not
the superuser, it checks the
-.IR /etc/hosts.equiv
+.I /etc/hosts.equiv
file.
If that lookup is not done, or is unsuccessful, the
-.IR .rhosts
+.I .rhosts
in the local user's home directory is checked to see if the request for
service is allowed.
.PP
other than the user or the superuser, is writable by anyone other
than the owner, or is hardlinked anywhere, the check automatically fails.
Zero is returned if the machine name is listed in the
-.IR hosts.equiv
+.I hosts.equiv
file, or the host and remote username are found in the
-.IR .rhosts
+.I .rhosts
file; otherwise
.BR iruserok ()
and
For these functions, the
.I af
argument can be specified as
-.BR AF_INET
+.B AF_INET
or
.BR AF_INET6 .
In addition,
.I errno
to indicate the error.
The error code
-.BR EAGAIN
+.B EAGAIN
is overloaded to mean: "All network ports in use".
.PP
For information on the return from
.\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk:
.\" Rework discussion of nonstandard structure fields.
.\"
-.TH READDIR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH READDIR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
readdir \- read a directory
.SH LIBRARY
The only fields in the
.I dirent
structure that are mandated by POSIX.1 are
-.IR d_name
+.I d_name
and
.IR d_ino .
The other fields are unstandardized, and not present on all systems;
When a suitable feature test macro is defined
.RB ( _DEFAULT_SOURCE
on glibc versions since 2.19, or
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
on glibc versions 2.19 and earlier),
glibc defines the following macro constants for the value returned in
.IR d_type :
The standard also notes that the use of
.I sizeof(d_name)
is incorrect; use
-.IR strlen(d_name)
+.I strlen(d_name)
instead.
(On some systems, this field is defined as
-.IR char\ d_name[1] !)
+.IR char\~d_name[1] !)
By implication, the use
-.IR "sizeof(struct dirent)"
+.I sizeof(struct dirent)
to capture the size of the record including the size of
-.IR d_name
+.I d_name
is also incorrect.
.PP
Note that while the call
.PP
- fpathconf(fd, _PC_NAME_MAX)
+.in +4n
+.EX
+fpathconf(fd, _PC_NAME_MAX)
+.EE
+.in
.PP
returns the value 255 for most filesystems,
on some filesystems (e.g., CIFS, Windows SMB servers),
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH READDIR_R 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH READDIR_R 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
readdir_r \- read a directory
.SH LIBRARY
and returns it in the caller-allocated buffer pointed to by
.IR entry .
For details of the
-.IR dirent
+.I dirent
structure, see
.BR readdir (3).
.PP
The reasons are as follows:
.IP * 3
On systems where
-.BR NAME_MAX
+.B NAME_MAX
is undefined, calling
.BR readdir_r ()
may be unsafe because the interface does not allow the caller to specify
On some other systems,
.BR readdir_r ()
may return a success status, but the returned
-.IR d_name
+.I d_name
field may not be null terminated or may be truncated.
.IP *
In the current POSIX.1 specification (POSIX.1-2008),
.\" Rewritten old page, 990824, aeb@cwi.nl
.\" 2004-12-14, mtk, added discussion of resolved_path == NULL
.\"
-.TH REALPATH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH REALPATH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
realpath \- return the canonicalized absolute pathname
.SH LIBRARY
.\" (In libc5 this would just cause a segfault.)
(In glibc versions before 2.3,
this error is also returned if
-.IR resolved_path
+.I resolved_path
is NULL.)
.TP
.B EIO
.\" but in \fI<stdlib.h>\fP everywhere else.
.SS GNU extensions
If the call fails with either
-.BR EACCES
+.B EACCES
or
-.BR ENOENT
+.B ENOENT
and
.I resolved_path
is not NULL, then the prefix of
.\"
.\" @(#)recno.3 8.5 (Berkeley) 8/18/94
.\"
-.TH RECNO 3 2017-09-15 "" "Linux Programmer's Manual"
+.TH RECNO 3 2017-09-15 GNU "Linux Programmer's Manual"
.UC 7
.SH NAME
recno \- record number database access method
.\" (walter.harms@informatik.uni-oldenburg.de)
.\" Modified 2003-11-18, 2004-10-05 aeb
.\"
-.TH REMAINDER 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH REMAINDER 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
drem, dremf, dreml, remainder, remainderf, remainderl \- \
floating-point remainder function
Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
is raised.
.IP
These functions do not set
-.IR errno
+.I errno
for this case.
.TP
Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779
the call
.PP
- remainder(nan(""), 0);
+.in +4n
+.EX
+remainder(nan(""), 0);
+.EE
+.in
.PP
returned a NaN, as expected, but wrongly caused a domain error.
Since glibc 2.15, a silent NaN (i.e., no domain error) is returned.
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783
.I errno
was not set to
-.BR EDOM
+.B EDOM
for the domain error that occurs when
.I x
is an infinity and
The value stored via the
.I quo
pointer has the sign of
-.IR "x\ /\ y"
+.I x\~/\~y
and agrees with the quotient in at least the low order 3 bits.
.PP
For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2.
.PP
The resolver routines use configuration and state information
contained in a
-.IR __res_state
+.I __res_state
structure (either passed as the
-.IR statep
+.I statep
argument, or in the global variable
.IR _res ,
in the case of the older nonreentrant functions).
The only field of this structure that is normally manipulated by the
user is the
-.IR options
+.I options
field.
This field can contain the bitwise "OR"
of the following options:
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
-.TH REWINDDIR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH REWINDDIR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
rewinddir \- reset directory stream
.SH LIBRARY
.BR rexec ()
function
looks up the host
-.IR *ahost
+.I *ahost
using
.BR gethostbyname (3),
returning \-1 if the host does not exist.
Otherwise,
-.IR *ahost
+.I *ahost
is set to the standard name of the host.
If a username and password are both specified, then these
are used to authenticate to the foreign host; otherwise
.PP
If the connection succeeds,
a socket in the Internet domain of type
-.BR SOCK_STREAM
+.B SOCK_STREAM
is returned to
the caller, and given to the remote command as
-.IR stdin
+.I stdin
and
.IR stdout .
If
If
.I fd2p
is 0, then the
-.IR stderr
+.I stderr
(unit 2 of the remote
command) will be made the same as the
-.IR stdout
+.I stdout
and no
provision is made for sending arbitrary signals to the remote process,
although you may be able to get its attention by using out-of-band data.
.BR AF_INET ,
.BR AF_INET6 ,
or
-.BR AF_UNSPEC
+.B AF_UNSPEC
(to allow the implementation to select the protocol).
.SH VERSIONS
The
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH RINT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH RINT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round
to nearest integer
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH ROUND 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH ROUND 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
round, roundf, roundl \- round to nearest integer, away from zero
.SH LIBRARY
.BR rint (3).
.PP
For example,
-.IR round(0.5)
+.I round(0.5)
is 1.0, and
-.IR round(\-0.5)
+.I round(\-0.5)
is \-1.0.
.SH RETURN VALUE
These functions return the rounded integer value.
.\"
.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
.\"
-.TH RPC 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH RPC 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
rpc \- library routines for remote procedure calls
.SH LIBRARY
.IR CLIENT ,
.IR SVCXPRT ,
and
-.IR XDR
+.I XDR
types.
.PP
.nf
.BR auth_destroy ().
.PP
.nf
-.BI "AUTH *authnone_create(void);"
+.B AUTH *authnone_create(void);
.fi
.IP
Create and return an RPC
It is easy to impersonate a user.
.PP
.nf
-.BI "AUTH *authunix_create_default(void);"
+.B AUTH *authunix_create_default(void);
.fi
.IP
Calls
.IR *addr .
This routine can return NULL.
The command
-.IR "rpcinfo\ \-p"
+.I rpcinfo\~\-p
uses this routine.
.PP
.nf
If they are zero, a reasonable default is chosen.
.PP
.nf
-.BI "SVCXPRT *svcraw_create(void);"
+.B SVCXPRT *svcraw_create(void);
.fi
.IP
This routine creates a toy RPC
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH SCALB 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SCALB 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
scalb, scalbf, scalbl \- multiply floating-point number
by integral power of radix (OBSOLETE)
.\" not in /usr/include but in a gcc lib
.SH RETURN VALUE
On success, these functions return
-.IR x
+.I x
*
.B FLT_RADIX
**
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH SCALBLN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SCALBLN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \-
multiply floating-point number by integral power of radix
.\" not in /usr/include but in a gcc lib
.SH RETURN VALUE
On success, these functions return
-.IR x
+.I x
*
.B FLT_RADIX
**
.BI " struct dirent ***restrict " namelist ,
.BI " int (*" filter ")(const struct dirent *),"
.BI " int (*" compar ")(const struct dirent **,"
-.BR " const struct dirent **));"
+.B " const struct dirent **));"
.PP
.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b );
.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b );
.BI " struct dirent ***restrict " namelist ,
.BI " int (*" filter ")(const struct dirent *),"
.BI " int (*" compar ")(const struct dirent **,"
-.BI " const struct dirent **));"
+.B " const struct dirent **));"
.fi
.PP
.RS -4
For decimal conversions, an optional quote character (\(aq).
This specifies that the input number may include thousands'
separators as defined by the
-.BR LC_NUMERIC
+.B LC_NUMERIC
category of the current locale.
(See
.BR setlocale (3).)
with a pointer to that buffer being returned in
.IR *buf :
.PP
- char *buf;
- scanf("%as", &buf);
+.in +4n
+.EX
+char *buf;
+scanf("%as", &buf);
+.EE
+.in
.PP
The use of the letter
.B a
Note that the
.B a
modifier is not available if the program is compiled with
-.I "gcc \-std=c99"
+.I gcc\~\-std=c99
or
-.IR "gcc \-D_ISOC99_SOURCE"
+.I gcc\~\-D_ISOC99_SOURCE
(unless
.B _GNU_SOURCE
is also specified), in which case the
.B m
modifier has the following further advantages over
the use of
-.BR a:
+.BR a :
.IP * 2
It may also be applied to
.B %c
It avoids ambiguity with respect to the
.B %a
floating-point conversion specifier (and is unaffected by
-.IR "gcc \-std=c99"
+.I gcc\~\-std=c99
etc.).
.SH BUGS
All functions are fully C89 conformant, but provide the
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu)
.\"
-.TH SEEKDIR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SEEKDIR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
seekdir \- set the position of the next readdir() call in the directory
stream.
The
.B O_CREAT
flag was not specified in
-.IR oflag
+.I oflag
and no semaphore with this
.I name
exists;
.I name
does exist in the environment, then
its value is changed to
-.IR value
+.I value
if
.I overwrite
is nonzero;
if
-.IR overwrite
+.I overwrite
is zero, then the value of
.I name
is not changed (and
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH SETJMP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SETJMP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto
.SH LIBRARY
(typically, the stack pointer, the instruction pointer,
possibly the values of other registers and the signal mask)
in the buffer
-.IR env
+.I env
for later use by
.BR longjmp ().
In this case,
The
.BR longjmp ()
function uses the information saved in
-.IR env
+.I env
to transfer control back to the point where
.BR setjmp ()
was called and to restore ("rewind") the stack to its state at the time of the
.BR setjmp ()
follows the System V behavior by default,
but the BSD behavior is provided if the
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
feature test macro is explicitly defined
.\" so that _FAVOR_BSD is triggered
and none of
.B _SVID_SOURCE
is defined.
Since glibc 2.19,
-.IR <setjmp.h>
+.I <setjmp.h>
exposes only the System V version of
.BR setjmp ().
Programs that need the BSD semantics should replace calls to
Nonlocal gotos provide no such cues: multiple
.BR setjmp ()
calls might employ the same
-.IR jmp_buf
+.I jmp_buf
variable so that the content of the variable may change
over the lifetime of the application.
Consequently, the programmer may be forced to perform detailed
(To make the programmer's life easier, each
.BR setjmp ()
call should employ a unique
-.IR jmp_buf
+.I jmp_buf
variable.)
.PP
Adding further difficulty, the
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH SETLOGMASK 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SETLOGMASK 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
setlogmask \- set log priority mask
.SH LIBRARY
is
.IR LOG_MASK(p) .
Some systems also provide a macro
-.IR LOG_UPTO(p)
+.I LOG_UPTO(p)
for the mask
of all priorities in the above list up to and including
.IR p .
a shared memory object should be identified by a name of the form
.IR /somename ;
that is, a null-terminated string of up to
-.BI NAME_MAX
+.B NAME_MAX
(i.e., 255) characters consisting of an initial slash,
.\" glibc allows the initial slash to be omitted, and makes
.\" multiple initial slashes equivalent to a single slash.
.\" 386BSD man pages
.\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl)
-.TH SIGINTERRUPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SIGINTERRUPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
siginterrupt \- allow signals to interrupt system calls
.SH LIBRARY
.IR "x < 0.0" ,
because IEEE 754 floating point allows zero to be signed.
The comparison
-.IR "\-0.0 < 0.0"
+.I \-0.0\~<\~0.0
is false, but
-.IR "signbit(\-0.0)"
+.I signbit(\-0.0)
will return a nonzero value.
.PP
NaNs and infinities have a sign bit.
.BR sigwait ()
function suspends execution of the calling thread until
one of the signals specified in the signal set
-.IR set
+.I set
becomes pending.
The function accepts the signal
(removes it from the pending list of signals),
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH SIN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SIN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
sin, sinf, sinl \- sine function
.SH LIBRARY
Domain error: \fIx\fP is an infinity
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
Domain error: \fIx\fP is an infinity
.I errno
is set to
-.BR EDOM
+.B EDOM
(but see BUGS).
An invalid floating-point exception
.RB ( FE_INVALID )
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH SINH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SINH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
sinh, sinhf, sinhl \- hyperbolic sine function
.SH LIBRARY
may be implemented using
.BR alarm (2)
and
-.BR SIGALRM
+.B SIGALRM
(POSIX.1 permits this);
mixing calls to
.BR alarm (2)
named
.IR NAME .
The argument
-.IR HEADNAME
+.I HEADNAME
is the name of a user-defined structure
that must be declared using the macro
.BR SLIST_HEAD ().
.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
-.TH SQRT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SQRT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
sqrt, sqrtf, sqrtl \- square root function
.SH LIBRARY
.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d
.BR statvfs ()
populated the bits of the
-.IR f_flag
+.I f_flag
field by scanning the mount options shown in
.IR /proc/mounts .
However, starting with Linux 2.6.36, the underlying
.BR statfs (2)
system call provides the necessary information via the
-.IR f_flags
+.I f_flags
field, and since glibc version 2.13, the
.BR statvfs ()
function will use information from that field rather than scanning
.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu
.\" Additions, 2001-10-14, aeb
.\"
-.TH STDARG 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STDARG 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists
.SH LIBRARY
The behavior is as if
.BR va_start ()
were applied to
-.IR dest
+.I dest
with the same
.I last
argument, followed by the same number of
.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu
.\" Modified, 2001-12-26, aeb
.\"
-.TH STDIO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STDIO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
stdio \- standard input/output library functions
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH STDIO_EXT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STDIO_EXT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
__fbufsize, __flbf, __fpending, __fpurge, __freadable,
__freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \-
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu)
-.TH STRCASECMP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRCASECMP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strcasecmp, strncasecmp \- compare two strings ignoring case
.SH LIBRARY
no more than
.I n
bytes of
-.IR s1
+.I s1
and
.IR s2 .
.SH RETURN VALUE
is always null-terminated.
.PP
If
-.IR src
+.I src
contains
.I n
or more bytes,
.SH NOTES
Some systems (the BSDs, Solaris, and others) provide the following function:
.PP
- size_t strlcat(char *dest, const char *src, size_t size);
+.in +4n
+.EX
+size_t strlcat(char *dest, const char *src, size_t size);
+.EE
+.in
.PP
This function appends the null-terminated string
.I src
to the string
.IR dest ,
copying at most
-.IR "size\-strlen(dest)\-1"
+.I size\-strlen(dest)\-1
from
.IR src ,
and adds a terminating null byte to the result,
.I unless
-.IR size
+.I size
is less than
.IR strlen(dest) .
This function fixes the buffer overrun problem of
is not present in glibc and is not standardized by POSIX,
.\" https://lwn.net/Articles/506530/
but is available on Linux via the
-.IR libbsd
+.I libbsd
library.
.\"
.SH EXAMPLES
.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2001-08-31, aeb
.\"
-.TH STRCMP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRCMP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strcmp, strncmp \- compare two strings
.SH LIBRARY
.BR strncmp ()
function is similar, except it compares
only the first (at most)
-.IR n
+.I n
bytes of
.I s1
and
The strings may not overlap, and the destination string
.I dest
must be large enough to receive the copy.
-.IR "Beware of buffer overruns!"
+.I Beware of buffer overruns!
(See BUGS.)
.PP
The
.SS strlcpy()
Some systems (the BSDs, Solaris, and others) provide the following function:
.PP
- size_t strlcpy(char *dest, const char *src, size_t size);
+.in +4n
+.EX
+size_t strlcpy(char *dest, const char *src, size_t size);
+.EE
+.in
.PP
.\" http://static.usenix.org/event/usenix99/full_papers/millert/millert_html/index.html
.\" "strlcpy and strlcat - consistent, safe, string copy and concatenation"
is not present in glibc and is not standardized by POSIX,
.\" https://lwn.net/Articles/506530/
but is available on Linux via the
-.IR libbsd
+.I libbsd
library.
.SH BUGS
If the destination string of a
.\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
.\" Addition of extra material on portability and standards.
.\"
-.TH STRERROR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRERROR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- return string describing error number
.SH LIBRARY
code passed in the argument
.IR errnum .
For example, given
-.BR EPERM
+.B EPERM
as an argument, this function returns a pointer to the string "EPERM".
.\"
.SS strerror_r()
is undefined if
.I locale
is the special locale object
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
or is not a valid locale object handle.
.SH RETURN VALUE
The
is undefined if
.I locale
is the special locale object
-.BR LC_GLOBAL_LOCALE
+.B LC_GLOBAL_LOCALE
(see
.BR duplocale (3))
or is not a valid locale object handle.
into a string of characters,
.IR str ,
with a configurable
-.IR format
+.I format
string.
At most
.I n
If
.I fp
is a NaN, +NaN, or \-NaN, and
-.BR f
+.B f
(or
.BR a ,
.BR e ,
and
.BR %W .
(Calculated from
-.IR tm_yday
+.I tm_yday
and
.IR tm_wday .)
.TP
The week number of the current year as a decimal number,
range 00 to 53, starting with the first Monday as the first day of week 01.
(Calculated from
-.IR tm_yday
+.I tm_yday
and
.IR tm_wday .)
.TP
.BR %G ,
.BR %g ,
and
-.BR %V
+.B %V
yield values calculated from the week-based year defined by the
ISO\ 8601 standard.
In this system, weeks start on a Monday, and are numbered from 01,
Nowadays,
.BR gcc (1)
provides the
-.IR \-Wno\-format\-y2k
+.I \-Wno\-format\-y2k
option to prevent the warning,
so that the above workaround is no longer required.
.SH EXAMPLES
-.BR "RFC\ 2822-compliant date format"
+.B RFC\~2822-compliant date format
(with an English locale for %a and %b)
.PP
.in +4n
.EE
.in
.PP
-.BR "RFC\ 822-compliant date format"
+.B RFC\~822-compliant date format
(with an English locale for %a and %b)
.PP
.in +4n
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu)
-.TH STRING 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRING 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
stpcpy, strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn,
strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk,
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu)
-.TH STRPBRK 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRPBRK 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strpbrk \- search a string for any of a set of bytes
.SH LIBRARY
The broken-down time structure
.I tm
is defined in
-.IR <time.h>
+.I <time.h>
as follows:
.PP
.in +4n
.TP
.B %Ow
The ordinal number of the day of the week (Sunday=0),
- using the locale's alternative numeric symbols.
+using the locale's alternative numeric symbols.
.TP
.B %OW
The week number of the year (Monday as the first day of the week)
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu)
-.TH STRSPN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRSPN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strspn, strcspn \- get length of a prefix substring
.SH LIBRARY
is "NAN" (disregarding case) optionally followed by a string,
.IR (n-char-sequence) ,
where
-.IR n-char-sequence
+.I n-char-sequence
specifies in an implementation-dependent
way the type of NAN (see NOTES).
.SH RETURN VALUE
has a nonzero value after the call.
.PP
In the glibc implementation, the
-.IR n-char-sequence
+.I n-char-sequence
that optionally follows "NAN"
is interpreted as an integer number
(with an optional '0' or '0x' prefix to select base 8 or 16)
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH STRTOIMAX 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH STRTOIMAX 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
strtoimax, strtoumax \- convert string to integer
.SH LIBRARY
The
.I saveptr
argument is a pointer to a
-.IR "char\ *"
+.I char\~*
variable that is used internally by
.BR strtok_r ()
in order to maintain context between successive calls that parse the
The resulting value was out of range.
.PP
The implementation may also set
-.IR errno
+.I errno
to
.B EINVAL
in case
The resulting value was out of range.
.PP
The implementation may also set
-.IR errno
+.I errno
to
.B EINVAL
in case
.\" 386BSD man pages
.\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2001-12-15, aeb
-.TH SWAB 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SWAB 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
swab \- swap adjacent bytes
.SH LIBRARY
A synonym for
.BR PAGESIZE / _SC_PAGESIZE .
(Both
-.BR PAGESIZE
+.B PAGESIZE
and
-.BR PAGE_SIZE
+.B PAGE_SIZE
are specified in POSIX.)
.TP
.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX
is used, or, if there was no preceding
.BR openlog ()
call, a default of
-.BR LOG_USER
+.B LOG_USER
is employed.
.PP
The remaining arguments are a
.\" Modified 14 May 2001, 23 Sep 2001 by aeb
.\" 2004-12-20, mtk
.\"
-.TH SYSTEM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SYSTEM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
system \- execute a shell command
.SH LIBRARY
because strange values for some environment variables
might be used to subvert system integrity.
For example,
-.BR PATH
+.B PATH
could be manipulated so that an arbitrary program
is executed with privilege.
Use the
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH SYSV_SIGNAL 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH SYSV_SIGNAL 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
sysv_signal \- signal handling with System V semantics
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH TAN 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TAN 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tan, tanf, tanl \- tangent function
.SH LIBRARY
.\" Modified 2002-07-27 by Walter Harms
.\" (walter.harms@informatik.uni-oldenburg.de)
.\"
-.TH TANH 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TANH 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tanh, tanhf, tanhl \- hyperbolic tangent function
.SH LIBRARY
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu)
-.TH TELLDIR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TELLDIR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
telldir \- return current location in directory stream
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH TEMPNAM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TEMPNAM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tempnam \- create a name for a temporary file
.SH LIBRARY
.SH NOTES
UNIX\ V7 and several later systems have a list of baud rates
where after the values
-.BR B0
+.B B0
through
.B B9600
one finds the two constants
do not work;
portable applications can instead use
.PP
- !timercmp(..., <)
- !timercmp(..., >)
- !timercmp(..., !=)
+.in +4n
+.EX
+!timercmp(..., <)
+!timercmp(..., >)
+!timercmp(..., !=)
+.EE
+.in
.SH RETURN VALUE
.BR timerisset ()
and
.\" 386BSD man pages
.\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 2001-11-17, aeb
-.TH TMPFILE 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TMPFILE 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tmpfile \- create a temporary file
.SH LIBRARY
.\"
.\" 2003-11-15, aeb, added tmpnam_r
.\"
-.TH TMPNAM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TMPNAM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tmpnam, tmpnam_r \- create a name for a temporary file
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH TRUNC 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TRUNC 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
trunc, truncf, truncl \- round to integer, toward zero
.SH LIBRARY
.nf
.B #include <search.h>
.PP
-.BI "typedef enum { preorder, postorder, endorder, leaf } VISIT;"
+.B typedef enum { preorder, postorder, endorder, leaf } VISIT;
.PP
.BI "void *tsearch(const void *" key ", void **" rootp ,
.BI " int (*" compar ")(const void *, const void *));"
.\" Modified 2001-11-13, aeb
.\" Modified 2004-12-01 mtk and Martin Schulze <joey@infodrom.org>
.\"
-.TH TZSET 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH TZSET 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
tzset, tzname, timezone, daylight \- initialize time conversion information
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH UALARM 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH UALARM 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
ualarm \- schedule signal after given number of microseconds
.SH LIBRARY
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH UNLOCKED_STDIO 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH UNLOCKED_STDIO 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
getc_unlocked, getchar_unlocked, putc_unlocked,
putchar_unlocked \- nonlocking stdio functions
.\" This page is in the public domain. - aeb
.\" %%%LICENSE_END
.\"
-.TH UNLOCKPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH UNLOCKPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
unlockpt \- unlock a pseudoterminal master/slave pair
.SH LIBRARY
.B #define _XOPEN_SOURCE
.B #include <stdlib.h>
.PP
-.BI "int unlockpt(int " fd ");"
+.BI "int unlockpt(int " fd );
.fi
.PP
.RS -4
.\" Modified 2001-04-01 by aeb
.\" Modified 2003-07-23 by aeb
.\"
-.TH USLEEP 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH USLEEP 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
usleep \- suspend execution for microsecond intervals
.SH LIBRARY
.PP
The programmer must ensure that there
is room for at least
-.IR wcslen(src)+1
+.I wcslen(src)+1
wide characters at
.IR dest .
.SH RETURN VALUE
written at
.IR dest .
If the length
-.IR wcslen(src)
+.I wcslen(src)
is smaller than
.IR n ,
the remaining wide characters in the array pointed to
.I dest
are filled with L\(aq\e0\(aq characters.
If the length
-.IR wcslen(src)
+.I wcslen(src)
is greater than or equal
to
.IR n ,
is ignored,
and the function effectively returns
.PP
- wcrtomb(buf, L\(aq\e0\(aq, ps)
+.in +4n
+.EX
+wcrtomb(buf, L\(aq\e0\(aq, ps)
+.EE
+.in
.PP
where
.I buf
.PP
The programmer must ensure that there is
room for at least
-.IR "wcslen(src)+1"
+.I wcslen(src)+1
wide characters at
.IR dest .
.SH RETURN VALUE
the wide-character string
.IR reject ,
or
-.IR wcslen(wcs)
+.I wcslen(wcs)
if there is none.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
returned.
.PP
If
-.IR dest
+.I dest
is NULL,
.I len
is ignored,
is returned.
.PP
If
-.IR dest
+.I dest
is NULL,
.I len
is ignored,
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH WCSTOIMAX 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH WCSTOIMAX 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
wcstoimax, wcstoumax \- convert wide-character string to integer
.SH LIBRARY
bytes are written to
.IR dest .
The sequence of characters placed in
-.IR dest
+.I dest
begins in the initial shift state.
The conversion can stop for three reasons:
.IP 1. 3
.IR dest .
.PP
If
-.IR dest
+.I dest
is NULL,
.I n
is ignored, and the conversion proceeds as
another wide character.
Its nature is implementation-dependent, but the special
value
-.IR "(wctrans_t)\ 0"
+.I (wctrans_t)\ 0
denotes an invalid mapping.
Nonzero
.I wctrans_t
.BR memchr (3)
function.
It searches the
-.IR n
+.I n
wide characters starting at
.I s
for
function returns a pointer to the first occurrence of
.I c
among the
-.IR n
+.I n
wide characters starting at
.IR s ,
or NULL if
.BR memcmp (3)
function.
It compares the
-.IR n
+.I n
wide-characters starting at
.I s1
and the
zero if the wide-character arrays of size
.I n
at
-.IR s1
+.I s1
and
.I s2
are equal.
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
-.TH WORDEXP 3 2021-08-27 "" "Linux Programmer's Manual"
+.TH WORDEXP 3 2021-08-27 GNU "Linux Programmer's Manual"
.SH NAME
wordexp, wordfree \- perform word expansion like a posix-shell
.SH LIBRARY
buffer overflow on Linux.)
.PP
The treatment of the conversion characters
-.BR c
+.B c
and
.B s
is different:
.\" 3. xencrypt() a hexstring
.\" to bad to be true :(
.\"
-.TH XCRYPT 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH XCRYPT 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
xencrypt, xdecrypt, passwd2des \- RFS password encryption
.SH LIBRARY
.\"
.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
.\"
-.TH XDR 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH XDR 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
xdr \- library routines for external data representation
.SH LIBRARY
This inserts additional bytes in the stream to provide
record boundary information.
Also, XDR streams created with different
-.BR xdr*_create
+.B xdr*_create
APIs are not compatible for the same reason.
.PP
.nf
This routine returns one if it succeeds, zero otherwise.
.PP
.nf
-.BI "bool_t xdr_void(void);"
+.B bool_t xdr_void(void);
.fi
.IP
This routine always returns one.
.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB
.\" 2008-07-24, mtk, created this page, based on material from j0.3.
.\"
-.TH Y0 3 2021-03-22 "" "Linux Programmer's Manual"
+.TH Y0 3 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \-
Bessel functions of the second kind
.\" as a range error.
.I errno
is set to
-.BR ERANGE
+.B ERANGE
and an
.B FE_DIVBYZERO
exception is raised
.\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32
.I errno
is set to
-.BR ERANGE
+.B ERANGE
(but see BUGS).
An overflow floating-point exception
.RB ( FE_OVERFLOW )
was set to
.BR EDOM ,
instead of
-.BR ERANGE
+.B ERANGE
and no
.B FE_DIVBYZERO
exception was raised.
For each message, first the struct sent by the kernel is given,
followed by a description of the semantics of the message.
.TP
-.BR FUSE_INIT
+.B FUSE_INIT
.IP
.in +4n
.EX
of the minor versions provided by the daemon and the kernel and
both parties should use the protocol corresponding to said minor version.
.TP
-.BR FUSE_GETATTR
+.B FUSE_GETATTR
.IP
.in +4n
.EX
and similar operations for the given filesystem object.
The object for which the attributes should be computed is indicated
either by
-.IR header\->nodeid
+.I header\->nodeid
or, if the
-.BR FUSE_GETATTR_FH
+.B FUSE_GETATTR_FH
flag is set, by the file handle
.IR fh .
The latter case of operation is analogous to
.EE
.in
.TP
-.BR FUSE_ACCESS
+.B FUSE_ACCESS
.IP
.in +4n
.EX
that indicate properties of this file handle to the kernel:
.RS 7
.TP 18
-.BR FOPEN_DIRECT_IO
+.B FOPEN_DIRECT_IO
Bypass page cache for this open file.
.TP
-.BR FOPEN_KEEP_CACHE
+.B FOPEN_KEEP_CACHE
Don't invalidate the data cache on open.
.TP
-.BR FOPEN_NONSEEKABLE
+.B FOPEN_NONSEEKABLE
The file is not seekable.
.RE
.TP
.IR offset .
The bytes should be returned directly following the usual reply header.
.TP
-.BR FUSE_INTERRUPT
+.B FUSE_INTERRUPT
.in +4n
.EX
struct fuse_interrupt_in {
After issuing said operation,
the kernel will wait uninterruptibly for completion of the indicated request.
.TP
-.BR FUSE_LOOKUP
+.B FUSE_LOOKUP
Directly following the header is a filename to be looked up in the directory
indicated by
.IR header\->nodeid .
is as for
.BR FUSE_GETATTR .
.TP
-.BR FUSE_FLUSH
+.B FUSE_FLUSH
.in +4n
.EX
struct fuse_flush_in {
.in
.IP
These are the converse of
-.BR FUSE_OPEN
+.B FUSE_OPEN
and
-.BR FUSE_OPENDIR
+.B FUSE_OPENDIR
respectively.
The daemon may now free any resources associated with the
file handle
but a reply still needs to be issued once the request has
been completely processed.
.TP
-.BR FUSE_STATFS
+.B FUSE_STATFS
This operation implements
.BR statfs (2)
for this filesystem.
.\" FIXME: Document the following.
.in +4n
.EX
-.BR FUSE_BATCH_FORGET
-.BR FUSE_BMAP
-.BR FUSE_CREATE
-.BR FUSE_DESTROY
-.BR FUSE_FALLOCATE
-.BR FUSE_FORGET
-.BR FUSE_FSYNC
-.BR FUSE_FSYNCDIR
-.BR FUSE_GETLK
-.BR FUSE_GETXATTR
-.BR FUSE_IOCTL
-.BR FUSE_LINK
-.BR FUSE_LISTXATTR
-.BR FUSE_LSEEK
-.BR FUSE_MKDIR
-.BR FUSE_MKNOD
-.BR FUSE_NOTIFY_REPLY
-.BR FUSE_POLL
-.BR FUSE_READDIRPLUS
-.BR FUSE_READLINK
-.BR FUSE_REMOVEXATTR
-.BR FUSE_RENAME
-.BR FUSE_RENAME2
-.BR FUSE_RMDIR
-.BR FUSE_SETATTR
-.BR FUSE_SETLK
-.BR FUSE_SETLKW
-.BR FUSE_SYMLINK
-.BR FUSE_UNLINK
-.BR FUSE_WRITE
+.B FUSE_BATCH_FORGET
+.B FUSE_BMAP
+.B FUSE_CREATE
+.B FUSE_DESTROY
+.B FUSE_FALLOCATE
+.B FUSE_FORGET
+.B FUSE_FSYNC
+.B FUSE_FSYNCDIR
+.B FUSE_GETLK
+.B FUSE_GETXATTR
+.B FUSE_IOCTL
+.B FUSE_LINK
+.B FUSE_LISTXATTR
+.B FUSE_LSEEK
+.B FUSE_MKDIR
+.B FUSE_MKNOD
+.B FUSE_NOTIFY_REPLY
+.B FUSE_POLL
+.B FUSE_READDIRPLUS
+.B FUSE_READLINK
+.B FUSE_REMOVEXATTR
+.B FUSE_RENAME
+.B FUSE_RENAME2
+.B FUSE_RMDIR
+.B FUSE_SETATTR
+.B FUSE_SETLK
+.B FUSE_SETLKW
+.B FUSE_SYMLINK
+.B FUSE_UNLINK
+.B FUSE_WRITE
.EE
.in
.SH SEE ALSO
.PP
Also, support for both "RAM disk" and "Initial RAM disk"
(e.g.,
-.BR CONFIG_BLK_DEV_RAM=y
+.B CONFIG_BLK_DEV_RAM=y
and
.BR CONFIG_BLK_DEV_INITRD=y )
must be compiled directly into the Linux kernel to use
then the kernel skips to the last step for the usual boot sequence.
.IP 5.
If the executable file
-.IR /linuxrc
+.I /linuxrc
is present in the initial root filesystem,
.I /linuxrc
is executed with UID 0.
the device
.I /dev/ram0
is moved from
-.IR /
+.I /
to
.IR /initrd .
Otherwise, if the directory
-.IR /initrd
+.I /initrd
does not exist, the device
.I /dev/ram0
is unmounted.
(When moved from
-.IR /
+.I /
to
.IR /initrd ,
.I /dev/ram0
.I /initrd
does not exist on the normal root filesystem
and any processes remain running from
-.IR /dev/ram0
+.I /dev/ram0
when
.I /linuxrc
exits, the behavior of the kernel is
.I Documentation/filesystems/nfsroot.txt
before Linux 2.6.33).
For more information on setting the root filesystem see also the
-.BR LILO
+.B LILO
and
-.BR LOADLIN
+.B LOADLIN
documentation.
.PP
It is also possible for the
For
.I /linuxrc
to change the normal root device,
-.IR /proc
+.I /proc
must be mounted.
After mounting
.IR /proc ,
For an NFS root filesystem, the root device is changed by having
.I /linuxrc
write the NFS setting into files
-.IR /proc/sys/kernel/nfs\-root\-name
+.I /proc/sys/kernel/nfs\-root\-name
and
.I /proc/sys/kernel/nfs\-root\-addrs
and then writing 0xff (e.g., the pseudo-NFS-device number) into file
.IR /dev/ram ,
.IR /dev/initrd ,
and the ext2 filesystem) and loads
-.IR /dev/initrd
+.I /dev/initrd
with a gzipped version of the initial filesystem.
.IP 2.
The executable
completed system yet.)
.IP 5.
The executable
-.IR /linuxrc
+.I /linuxrc
sets
.IR /proc/sys/kernel/real\-root\-dev ,
unmounts
The distribution could also use a
.B LILO
boot floppy and then bootstrap a bigger RAM disk via
-.IR /dev/initrd
+.I /dev/initrd
from the CD-ROM.
.\"
.\"
.I /dev/ram0
is used by any process or has any filesystem mounted on it.
If
-.IR /dev/ram0
+.I /dev/ram0
is
.B not
fully unmounted, then
Some hardware (typically TV-cards) decodes the IR signal internally
and provides decoded button presses as scancode values.
Drivers for this kind of hardware work in
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
mode.
Such hardware usually does not support sending IR signals.
Furthermore, such hardware can only decode a limited set of IR protocols,
.PP
Other hardware provides a stream of pulse/space durations.
Such drivers work in
-.BR LIRC_MODE_MODE2
+.B LIRC_MODE_MODE2
mode.
Sometimes, this kind of hardware also supports
sending IR data.
Such hardware can be used with (almost) any kind of remote.
This type of hardware can also be used in
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
mode, in which case the kernel IR decoders will decode the IR.
These decoders can be written in extended BPF (see
.BR bpf (2))
The time of the duration (microseconds) is encoded in the lower 24 bits.
The upper 8 bits indicate the type of package:
.TP 4
-.BR LIRC_MODE2_SPACE
+.B LIRC_MODE2_SPACE
Value reflects a space duration (microseconds).
.TP 4
-.BR LIRC_MODE2_PULSE
+.B LIRC_MODE2_PULSE
Value reflects a pulse duration (microseconds).
.TP 4
-.BR LIRC_MODE2_FREQUENCY
+.B LIRC_MODE2_FREQUENCY
Value reflects a frequency (Hz); see the
.B LIRC_SET_MEASURE_CARRIER_MODE
ioctl.
.TP 4
-.BR LIRC_MODE2_TIMEOUT
+.B LIRC_MODE2_TIMEOUT
Value reflects a space duration (microseconds).
The package reflects a timeout; see the
.B LIRC_SET_REC_TIMEOUT_REPORTS
definition of
.IR "struct file_operations" ,
leaving us with an
-.IR "unsigned int"
+.I unsigned int
for the ioctl command and an
-.IR "unsigned long"
+.I unsigned long
for the argument.
For the purposes of ioctl portability across 32-bit and 64-bit architectures,
these values are capped to their 32-bit sizes.
Otherwise, it returns the receive mode, which will be one of:
.RS
.TP
-.BR LIRC_MODE_MODE2
+.B LIRC_MODE_MODE2
The driver returns a sequence of pulse/space durations.
.TP
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
The driver returns struct
.I lirc_scancode
values, each of which represents
.TP
.BR LIRC_SET_REC_MODE " (\fIint\fP)"
Set the receive mode.
-.IR val
+.I val
is either
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
or
.BR LIRC_MODE_MODE2 .
If the
.TP
.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
Return the send mode.
-.BR LIRC_MODE_PULSE
+.B LIRC_MODE_PULSE
or
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
is supported.
If the
.B lirc
.TP
.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
Set the send mode.
-.IR val
+.I val
is either
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
or
.BR LIRC_MODE_PULSE .
If the
set (microseconds).
Some devices have a fixed timeout.
For such drivers,
-.BR LIRC_GET_MIN_TIMEOUT
+.B LIRC_GET_MIN_TIMEOUT
and
-.BR LIRC_GET_MAX_TIMEOUT
+.B LIRC_GET_MAX_TIMEOUT
will fail with the error
.BR ENOTTY .
.TP
.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
Set the integer value for IR inactivity timeout (microseconds).
To be accepted, the value must be within the limits defined by
-.BR LIRC_GET_MIN_TIMEOUT
+.B LIRC_GET_MIN_TIMEOUT
and
.BR LIRC_GET_MAX_TIMEOUT .
A value of 0 (if supported by the hardware) disables all hardware
.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
Sets the lower bound of the receive carrier frequency (Hz).
For this to take affect, first set the lower bound using the
-.BR LIRC_SET_REC_CARRIER_RANGE
+.B LIRC_SET_REC_CARRIER_RANGE
ioctl, and then the upper bound using the
-.BR LIRC_SET_REC_CARRIER
+.B LIRC_SET_REC_CARRIER
ioctl.
.TP
.BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)"
.RI ( val
is 0) the measure mode.
If enabled, from the next key press on, the driver will send
-.BR LIRC_MODE2_FREQUENCY
+.B LIRC_MODE2_FREQUENCY
packets.
By default, this should be turned off.
.TP
.\"
.SH FEATURES
the
-.BR LIRC_GET_FEATURES
+.B LIRC_GET_FEATURES
ioctl returns a bit mask describing features of the driver.
The following bits may be returned in the mask:
.TP
-.BR LIRC_CAN_REC_MODE2
+.B LIRC_CAN_REC_MODE2
The driver is capable of receiving using
.BR LIRC_MODE_MODE2 .
.TP
-.BR LIRC_CAN_REC_SCANCODE
+.B LIRC_CAN_REC_SCANCODE
The driver is capable of receiving using
.BR LIRC_MODE_SCANCODE .
.TP
-.BR LIRC_CAN_SET_SEND_CARRIER
+.B LIRC_CAN_SET_SEND_CARRIER
The driver supports changing the modulation frequency using
.BR LIRC_SET_SEND_CARRIER .
.TP
-.BR LIRC_CAN_SET_SEND_DUTY_CYCLE
+.B LIRC_CAN_SET_SEND_DUTY_CYCLE
The driver supports changing the duty cycle using
.BR LIRC_SET_SEND_DUTY_CYCLE .
.TP
-.BR LIRC_CAN_SET_TRANSMITTER_MASK
+.B LIRC_CAN_SET_TRANSMITTER_MASK
The driver supports changing the active transmitter(s) using
.BR LIRC_SET_TRANSMITTER_MASK .
.TP
-.BR LIRC_CAN_SET_REC_CARRIER
+.B LIRC_CAN_SET_REC_CARRIER
The driver supports setting the receive carrier frequency using
.BR LIRC_SET_REC_CARRIER .
Any
.B lirc
device since the drivers were merged in kernel release 2.6.36
must have
-.BR LIRC_CAN_SET_REC_CARRIER_RANGE
+.B LIRC_CAN_SET_REC_CARRIER_RANGE
set if
-.BR LIRC_CAN_SET_REC_CARRIER
+.B LIRC_CAN_SET_REC_CARRIER
feature is set.
.TP
-.BR LIRC_CAN_SET_REC_CARRIER_RANGE
+.B LIRC_CAN_SET_REC_CARRIER_RANGE
The driver supports
.BR LIRC_SET_REC_CARRIER_RANGE .
The lower bound of the carrier must first be set using the
-.BR LIRC_SET_REC_CARRIER_RANGE
+.B LIRC_SET_REC_CARRIER_RANGE
ioctl, before using the
-.BR LIRC_SET_REC_CARRIER
+.B LIRC_SET_REC_CARRIER
ioctl to set the upper bound.
.TP
-.BR LIRC_CAN_GET_REC_RESOLUTION
+.B LIRC_CAN_GET_REC_RESOLUTION
The driver supports
.BR LIRC_GET_REC_RESOLUTION .
.TP
-.BR LIRC_CAN_SET_REC_TIMEOUT
+.B LIRC_CAN_SET_REC_TIMEOUT
The driver supports
.BR LIRC_SET_REC_TIMEOUT .
.TP
-.BR LIRC_CAN_MEASURE_CARRIER
+.B LIRC_CAN_MEASURE_CARRIER
The driver supports measuring of the modulation frequency using
.BR LIRC_SET_MEASURE_CARRIER_MODE .
.TP
-.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
+.B LIRC_CAN_USE_WIDEBAND_RECEIVER
The driver supports learning mode using
.BR LIRC_SET_WIDEBAND_RECEIVER .
.TP
-.BR LIRC_CAN_SEND_PULSE
+.B LIRC_CAN_SEND_PULSE
The driver supports sending using
-.BR LIRC_MODE_PULSE
+.B LIRC_MODE_PULSE
or
-.BR LIRC_MODE_SCANCODE
+.B LIRC_MODE_SCANCODE
.\"
.SH BUGS
Using these devices requires the kernel source header file
field is a bit mask that can include zero or more of the following:
.RS
.TP
-.BR LO_FLAGS_READ_ONLY
+.B LO_FLAGS_READ_ONLY
The loopback device is read-only.
.TP
.BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)"
The only
.I lo_flags
that can be modified by
-.BR LOOP_SET_STATUS
+.B LOOP_SET_STATUS
are
-.BR LO_FLAGS_AUTOCLEAR
+.B LO_FLAGS_AUTOCLEAR
and
.BR LO_FLAGS_PARTSCAN .
.TP
.in
.IP
In addition to doing what
-.BR LOOP_SET_STATUS
+.B LOOP_SET_STATUS
can do,
-.BR LOOP_CONFIGURE
+.B LOOP_CONFIGURE
can also be used to do the following:
.RS
.IP * 2
.IR loop_config.block_size ;
.IP *
explicitly request direct I/O mode by setting
-.BR LO_FLAGS_DIRECT_IO
+.B LO_FLAGS_DIRECT_IO
in
.IR loop_config.info.lo_flags ;
and
.IP *
explicitly request read-only mode by setting
-.BR LO_FLAGS_READ_ONLY
+.B LO_FLAGS_READ_ONLY
in
.IR loop_config.info.lo_flags .
.RE
device, which permits an application to dynamically find a free device,
and to add and remove loop devices from the system.
To perform these operations, one first opens
-.IR /dev/loop\-control
+.I /dev/loop\-control
and then employs one of the following
.BR ioctl (2)
operations:
.BR EBUSY .
.SH FILES
.TP
-.IR /dev/loop*
+.I /dev/loop*
The loop block special device files.
.SH EXAMPLES
The program below uses the
.SH NAME
mem, kmem, port \- system memory, kernel memory and system ports
.SH DESCRIPTION
-.IR /dev/mem
+.I /dev/mem
is a character device file
that is an image of the main memory of the computer.
It may be used, for example, to examine (and even patch) the system.
.PP
Byte addresses in
-.IR /dev/mem
+.I /dev/mem
are interpreted as physical memory addresses.
References to nonexistent locations cause errors to be returned.
.PP
.in
.PP
The file
-.IR /dev/kmem
+.I /dev/kmem
is the same as
.IR /dev/mem ,
except that the kernel virtual memory
.EE
.in
.PP
-.IR /dev/port
+.I /dev/port
is similar to
.IR /dev/mem ,
but the I/O ports are accessed.
and one stop bit at the speed of 1200 bits/sec.
Data is sent to RxD in 3-byte packets.
The
-.IR dx
+.I dx
and
.I dy
movements are sent as
null, zero \- data sink
.SH DESCRIPTION
Data written to the
-.IR /dev/null
+.I /dev/null
and
-.IR /dev/zero
+.I /dev/zero
special files is discarded.
.PP
Reads from
-.IR /dev/null
+.I /dev/null
always return end of file (i.e.,
.BR read (2)
returns 0), whereas reads from
-.IR /dev/zero
+.I /dev/zero
always return bytes containing zero (\(aq\e0\(aq characters).
.PP
These devices are typically created by:
Since Linux 2.6.31,
.\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0
reads from
-.IR /dev/zero
+.I /dev/zero
are interruptible by signals.
(This change was made to help with bad latencies for large reads from
.IR /dev/zero .)
.I /dev/pts
directory.
Each file descriptor obtained by opening
-.IR /dev/ptmx
+.I /dev/ptmx
is an independent pseudoterminal master with its own associated slave,
whose path can
be found by passing the file descriptor to
but can incur an appreciable delay when requesting large amounts of data.
.PP
When read during early boot time,
-.IR /dev/urandom
+.I /dev/urandom
may return data prior to the entropy pool being initialized.
.\" This is a real problem; see
.\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24
is called for
.I /dev/random
with the
-.BR O_NONBLOCK
+.B O_NONBLOCK
flag, a subsequent
.BR read (2)
will not block if the requested number of bytes is not available.
a
.BR read (2)
from
-.IR /dev/urandom
+.I /dev/urandom
will return at most 32\ MB.
A
.BR read (2)
from
-.IR /dev/random
+.I /dev/random
will return at most 512 bytes
.\" SEC_XFER_SIZE in drivers/char/random.c
(340 bytes on Linux kernels before version 2.6.12).
\fI/dev/random\fP faster.
.SS Usage
The
-.IR /dev/random
+.I /dev/random
interface is considered a legacy interface, and
-.IR /dev/urandom
+.I /dev/urandom
is preferred and sufficient in all use cases, with the exception of
applications which require randomness during early boot time; for
these applications,
.in
.PP
In the above examples, we assume Linux 2.6.0 or later, where
-.IR /proc/sys/kernel/random/poolsize
+.I /proc/sys/kernel/random/poolsize
returns the size of the entropy pool in bits (see below).
.\"
.SS /proc interfaces
capability is required for all requests except
.BR RNDGETENTCNT .
.TP
-.BR RNDGETENTCNT
+.B RNDGETENTCNT
Retrieve the entropy count of the input pool, the contents will be the same
as the
.I entropy_avail
file under proc.
The result will be stored in the int pointed to by the argument.
.TP
-.BR RNDADDTOENTCNT
+.B RNDADDTOENTCNT
Increment or decrement the entropy count of the input pool
by the value pointed to by the argument.
.TP
-.BR RNDGETPOOL
+.B RNDGETPOOL
Removed in Linux 2.6.9.
.TP
-.BR RNDADDENTROPY
+.B RNDADDENTROPY
Add some additional entropy to the input pool,
incrementing the entropy count.
This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP,
.IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc."
RTC special character device files.
.TP
-.IR /proc/driver/rtc
+.I /proc/driver/rtc
status of the (first) RTC.
.SH NOTES
When the kernel's system time is synchronized with an external
Port A of the first adapter should be ON,
but on the Port A of the second adapter switched OFF, one must enter:
.PP
- insmod sk98lin.o AutoNeg_A=On,Off
+.in +4n
+.EX
+insmod sk98lin.o AutoNeg_A=On,Off
+.EE
+.in
.PP
After
.B sk98lin
address and a large frame MTU size,
the following two commands might be used:
.PP
- ifconfig eth0 10.1.1.1
- ifconfig eth0 mtu 9000
+.in +4n
+.EX
+ifconfig eth0 10.1.1.1
+ifconfig eth0 mtu 9000
+.EE
+.in
.PP
Those two commands might even be combined into one:
.PP
- ifconfig eth0 10.1.1.1 mtu 9000
+.in +4n
+.EX
+ifconfig eth0 10.1.1.1 mtu 9000
+.EE
+.in
.PP
Note that large frames can be used only if permitted by
your network infrastructure.
.BR ifconfig (8)
command again:
.PP
- ifconfig eth0 mtu 1500
+.in +4n
+.EX
+ifconfig eth0 mtu 1500
+.EE
+.in
.PP
The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to
support VLAN and Link Aggregation according to
.I SymOrRem
is the default.
The different modes have the following meaning:
-.IP
-.I Sym
-= Symmetric
- both link partners are allowed to send PAUSE frames
-.br
-.I SymOrRem
-= SymmetricOrRemote
- both or only remote partner are allowed to send PAUSE frames
-.br
-.I LocSend
-= LocalSend
- only local link partner is allowed to send PAUSE frames
-.br
-.I None
-= None
- no link partner is allowed to send PAUSE frames
+.RS
+.TP
+.IR Sym " = Symmetric"
+Both link partners are allowed to send PAUSE frames.
+.TP
+.IR SymOrRem " = SymmetricOrRemote"
+Both or only remote partner are allowed to send PAUSE frames.
+.TP
+.IR LocSend " = LocalSend"
+Only local link partner is allowed to send PAUSE frames.
+.TP
+.IR None " = None"
+No link partner is allowed to send PAUSE frames.
+.RE
.IP
Note that this parameter is ignored if AutoNeg_A is set to
.IR Off .
.I SymOrRem
is the default.
The different modes have the following meaning:
-.IP
-.I Sym
-= Symmetric
- both link partners are allowed to send PAUSE frames
-.br
-.I SymOrRem
-= SymmetricOrRemote
- both or only remote partner are allowed to send PAUSE frames
-.br
-.I LocSend
-= LocalSend
- only local link partner is allowed to send PAUSE frames
-.br
-.I None
-= None
- no link partner is allowed to send PAUSE frames
-.br
+.RS
+.TP
+.IR Sym " = Symmetric"
+Both link partners are allowed to send PAUSE frames.
+.TP
+.IR SymOrRem " = SymmetricOrRemote"
+Both or only remote partner are allowed to send PAUSE frames.
+.TP
+.IR LocSend " = LocalSend"
+Only local link partner is allowed to send PAUSE frames.
+.TP
+.IR None " = None"
+No link partner is allowed to send PAUSE frames.
+.RE
.IP
Note that this parameter is ignored if AutoNeg_B is set to
.IR Off .
.I DualNet
In this mode, ports A and B are used as separate devices.
If you have a dual port adapter, port A will be configured as
-.IR eth[x]
+.I eth[x]
and port B as
.IR eth[x+1] .
Both ports can be used independently with distinct IP addresses.
This attribute will cause the driver to perform a specific action in the
unlikely event that a controller lockup has been detected.
See
-.BR OPTIONS
+.B OPTIONS
above
for an explanation of the
.I lockup_action
values.
.TP
-.IR /sys/class/scsi_host/host*/driver_version
+.I /sys/class/scsi_host/host*/driver_version
The
.I driver_version
attribute is read-only.
.EE
.in
.TP
-.IR /sys/class/scsi_host/host*/firmware_version
+.I /sys/class/scsi_host/host*/firmware_version
The
.I firmware_version
attribute is read-only.
.EE
.in
.TP
-.IR /sys/class/scsi_host/host*/model
+.I /sys/class/scsi_host/host*/model
The
.I model
attribute is read-only.
.EE
.in
.TP
-.IR /sys/class/scsi_host/host*/serial_number
+.I /sys/class/scsi_host/host*/serial_number
The
.I serial_number
attribute is read-only.
.EE
.in
.TP
-.IR /sys/class/scsi_host/host*/vendor
+.I /sys/class/scsi_host/host*/vendor
The
.I vendor
attribute is read-only.
and the \(lqno-rewind\(rq device numbers,
.RI ( n " + 128)."
Devices opened using the principal device number will be sent a
-.BR REWIND
+.B REWIND
command when they are closed.
Devices opened using the \(lqno-rewind\(rq device number will not.
(Note that using an auto-rewind device for positioning the tape with,
The physical ordering of partitions depends on the drive.
This command is not allowed for a drive unless the partition support
is enabled for the drive (see
-.BR MT_ST_CAN_PARTITIONS
+.B MT_ST_CAN_PARTITIONS
below).
.TP
.B MTNOP
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
Viper, Wangtek, ...).
The block number should be one that was previously returned by
-.BR MTIOCPOS
+.B MTIOCPOS
if device-specific addresses are used.
.TP
.B MTSETBLK
.RS 12
.IP 0 4
The drive will not report
-.BR GOOD
+.B GOOD
status on write commands until the data
blocks are actually written to the medium.
.IP 1
The drive may report
-.BR GOOD
+.B GOOD
status on write commands as soon as all the
data has been transferred to the drive's internal buffer.
.IP 2
The drive may report
-.BR GOOD
+.B GOOD
status on write commands as soon as (a) all
the data has been transferred to the drive's internal buffer, and
(b) all buffered data from different initiators has been successfully
To control the write threshold the value in
.I mt_count
must include the constant
-.BR MT_ST_WRITE_THRESHOLD
+.B MT_ST_WRITE_THRESHOLD
bitwise ORed with a block count in the low 28 bits.
The block count refers to 1024-byte blocks, not the physical block
size on the tape.
.BR MT_ST_SETBOOLEANS ,
.BR MT_ST_CLEARBOOLEANS ,
or
-.BR MT_ST_DEFBOOLEANS
+.B MT_ST_DEFBOOLEANS
bitwise ORed with
whatever combination of the following options is desired.
Using
-.BR MT_ST_BOOLEANS
+.B MT_ST_BOOLEANS
the options can be set to the values
defined in the corresponding bits.
With
-.BR MT_ST_SETBOOLEANS
+.B MT_ST_SETBOOLEANS
the options can be selectively set and with
-.BR MT_ST_DEFBOOLEANS
+.B MT_ST_DEFBOOLEANS
selectively cleared.
-.IP ""
+.IP
The default options for a tape device are set with
.BR MT_ST_DEFBOOLEANS .
A nonactive tape device (e.g., device with
defined the first time.
An activated device inherits from the device
activated at start-up the options not set explicitly.
-.IP ""
+.IP
The Boolean options are:
.RS
.TP
The only field defined in
.I mt_erreg
is the recovered error count in the low 16 bits (as defined by
-.BR MT_ST_SOFTERR_SHIFT
+.B MT_ST_SOFTERR_SHIFT
and
.BR MT_ST_SOFTERR_MASK ).
Due to inconsistencies in the way drives report recovered errors, this
\fImt_fileno\fP
reports the current file number (zero-based).
This value is set to \-1 when the file number is unknown (e.g., after
-.BR MTBSS
+.B MTBSS
or
.BR MTSEEK ).
.TP
are character devices for virtual console
terminals, they have major number 7 and minor number 1 to 63, usually
mode 0644 and ownership root:tty.
-.IR /dev/vcsa[0\-63]
+.I /dev/vcsa[0\-63]
are the same, but
using
.IR "unsigned short" s
.IP * 3
The process does not have permission to write the core file.
(By default, the core file is called
-.IR core
+.I core
or
.IR core.pid ,
where
(Since Linux 3.7)
.\" commit 046d662f481830e652ac34cd112249adde16452a
The kernel was configured without the
-.BR CONFIG_COREDUMP
+.B CONFIG_COREDUMP
option.
.PP
In addition,
(without path prefix, and truncated to a maximum of 15 characters),
but may have been modified to be something different;
see the discussion of
-.I /proc/[pid]/comm
+.IR /proc/ pid /comm
and
-.I /proc/[pid]/task/[tid]/comm
+.IR /proc/ pid /task/ tid /comm
in
.BR proc (5).
.TP
does not confer any exceptional security bypasses.
Namely, LSMs (e.g., SELinux) are still active and may prevent the handler
from accessing details about the crashed process via
-.IR /proc/[pid] .
+.IR /proc/ pid.
.IP *
The program pathname is interpreted with respect to the initial mount namespace
as it is always executed there.
One can utilize specifiers such as
.I %P
to find the right
-.I /proc/[pid]
+.IR /proc/ pid
directory and probe/enter the crashing process's namespaces if needed.
.IP *
The process starts with its current working directory
the dumping process by employing the value provided by the
.I %P
specifier to change to the location of the dumping process via
-.IR /proc/[pid]/cwd .
+.IR /proc/ pid /cwd .
.IP *
Command-line arguments can be supplied to the
program (since Linux 2.6.24),
When collecting core dumps via a pipe to a user-space program,
it can be useful for the collecting program to gather data about
the crashing process from that process's
-.IR /proc/[pid]
+.IR /proc/ pid
directory.
In order to do this safely,
the kernel must wait for the program collecting the core dump to exit,
so as not to remove the crashing process's
-.IR /proc/[pid]
+.IR /proc/ pid
files prematurely.
This in turn creates the
possibility that a misbehaving collecting program can block
.\"
.SS Controlling which mappings are written to the core dump
Since kernel 2.6.23, the Linux-specific
-.IR /proc/[pid]/coredump_filter
+.IR /proc/ pid /coredump_filter
file can be used to control which memory segments are written to the
core dump file in the event that a core dump is performed for the
process with the corresponding process ID.
.BR systemd (1)
location into a specified file.
For example, to extract the core dump for PID 2955 shown above to a file named
-.IR core
+.I core
in the current directory, one could use:
.PP
.in +4n
Synonym:
.BR END .
.TP
-\fB*\fIextension\fR \fIcolor-sequence\fR
+.BI * "extension color-sequence"
Specifies the color used for any file that ends in \fIextension\fR.
.TP
-\fB .\fIextension\fR \fIcolor-sequence\fR
+.BI . "extension color-sequence"
Same as \fB*\fR.\fIextension\fR.
Specifies the color used for any file that
ends in .\fIextension\fR.
.\"
.\"
.TP
-.IR e_ident
+.I e_ident
This array of bytes specifies how to interpret the file,
independent of the processor or the file's remaining contents.
Within this array everything is named by macros, which start with
the prefix
-.BR EI_
+.B EI_
and may contain values which start with the prefix
.BR ELF .
The following macros are defined:
.RS
.TP
-.BR EI_MAG0
+.B EI_MAG0
The first byte of the magic number.
It must be filled with
.BR ELFMAG0 .
(0: 0x7f)
.TP
-.BR EI_MAG1
+.B EI_MAG1
The second byte of the magic number.
It must be filled with
.BR ELFMAG1 .
(1: \(aqE\(aq)
.TP
-.BR EI_MAG2
+.B EI_MAG2
The third byte of the magic number.
It must be filled with
.BR ELFMAG2 .
(2: \(aqL\(aq)
.TP
-.BR EI_MAG3
+.B EI_MAG3
The fourth byte of the magic number.
It must be filled with
.BR ELFMAG3 .
(3: \(aqF\(aq)
.TP
-.BR EI_CLASS
+.B EI_CLASS
The fifth byte identifies the architecture for this binary:
.RS
.TP 14
.PD 0
-.BR ELFCLASSNONE
+.B ELFCLASSNONE
This class is invalid.
.TP
-.BR ELFCLASS32
+.B ELFCLASS32
This defines the 32-bit architecture.
It supports machines with files
and virtual address spaces up to 4 Gigabytes.
.TP
-.BR ELFCLASS64
+.B ELFCLASS64
This defines the 64-bit architecture.
.PD
.RE
.TP
-.BR EI_DATA
+.B EI_DATA
The sixth byte specifies the data encoding of the processor-specific
data in the file.
Currently, these encodings are supported:
.RS 9
.TP 14
.PD 0
-.BR ELFDATANONE
+.B ELFDATANONE
Unknown data format.
.TP
-.BR ELFDATA2LSB
+.B ELFDATA2LSB
Two's complement, little-endian.
.TP
-.BR ELFDATA2MSB
+.B ELFDATA2MSB
Two's complement, big-endian.
.PD
.RE
.TP
-.BR EI_VERSION
+.B EI_VERSION
The seventh byte is the version number of the ELF specification:
.IP
.PD 0
.RS
.TP 14
-.BR EV_NONE
+.B EV_NONE
Invalid version.
.TP
-.BR EV_CURRENT
+.B EV_CURRENT
Current version.
.PD
.RE
.\".El
.TP
-.BR EI_OSABI
+.B EI_OSABI
The eighth byte identifies the operating system
and ABI to which the object is targeted.
Some fields in other ELF structures have flags
.RS
.TP 21
.PD 0
-.BR ELFOSABI_NONE
+.B ELFOSABI_NONE
Same as ELFOSABI_SYSV
.\" 0
.TP
-.BR ELFOSABI_SYSV
+.B ELFOSABI_SYSV
UNIX System V ABI
.\" 0
.\" synonym: ELFOSABI_NONE
.TP
-.BR ELFOSABI_HPUX
+.B ELFOSABI_HPUX
HP-UX ABI
.\" 1
.TP
-.BR ELFOSABI_NETBSD
+.B ELFOSABI_NETBSD
NetBSD ABI
.\" 2
.TP
-.BR ELFOSABI_LINUX
+.B ELFOSABI_LINUX
Linux ABI
.\" 3
.\" .TP
.\" 86Open Common IA32 ABI
.\" 5
.TP
-.BR ELFOSABI_SOLARIS
+.B ELFOSABI_SOLARIS
Solaris ABI
.\" 6
.\" .TP
.\" ELFOSABI_AIX
.\" 7
.TP
-.BR ELFOSABI_IRIX
+.B ELFOSABI_IRIX
IRIX ABI
.\" 8
.TP
-.BR ELFOSABI_FREEBSD
+.B ELFOSABI_FREEBSD
FreeBSD ABI
.\" 9
.TP
-.BR ELFOSABI_TRU64
+.B ELFOSABI_TRU64
TRU64 UNIX ABI
.\" 10
.\" ELFOSABI_MODESTO
.\" ELFOSABI_OPENBSD
.\" 12
.TP
-.BR ELFOSABI_ARM
+.B ELFOSABI_ARM
ARM architecture ABI
.\" 97
.TP
-.BR ELFOSABI_STANDALONE
+.B ELFOSABI_STANDALONE
Stand-alone (embedded) ABI
.\" 255
.PD
.RE
.TP
-.BR EI_ABIVERSION
+.B EI_ABIVERSION
The ninth byte identifies the version of the ABI
to which the object is targeted.
This field is used to distinguish among incompatible versions of an ABI.
field.
Applications conforming to this specification use the value 0.
.TP
-.BR EI_PAD
+.B EI_PAD
Start of padding.
These bytes are reserved and set to zero.
Programs
.\" .BR EI_BRAND
.\" Start of architecture identification.
.TP
-.BR EI_NIDENT
+.B EI_NIDENT
The size of the
.I e_ident
array.
.RE
.TP
-.IR e_type
+.I e_type
This member of the structure identifies the object file type:
.RS
.TP 16
.PD 0
-.BR ET_NONE
+.B ET_NONE
An unknown type.
.TP
-.BR ET_REL
+.B ET_REL
A relocatable file.
.TP
-.BR ET_EXEC
+.B ET_EXEC
An executable file.
.TP
-.BR ET_DYN
+.B ET_DYN
A shared object.
.TP
-.BR ET_CORE
+.B ET_CORE
A core file.
.PD
.RE
.TP
-.IR e_machine
+.I e_machine
This member specifies the required architecture for an individual file.
For example:
.RS
.TP 16
.PD 0
-.BR EM_NONE
+.B EM_NONE
An unknown machine
.\" 0
.TP
-.BR EM_M32
+.B EM_M32
AT&T WE 32100
.\" 1
.TP
-.BR EM_SPARC
+.B EM_SPARC
Sun Microsystems SPARC
.\" 2
.TP
-.BR EM_386
+.B EM_386
Intel 80386
.\" 3
.TP
-.BR EM_68K
+.B EM_68K
Motorola 68000
.\" 4
.TP
-.BR EM_88K
+.B EM_88K
Motorola 88000
.\" 5
.\" .TP
.\" Intel 80486
.\" 6
.TP
-.BR EM_860
+.B EM_860
Intel 80860
.\" 7
.TP
-.BR EM_MIPS
+.B EM_MIPS
MIPS RS3000 (big-endian only)
.\" 8
.\" EM_S370
.\" EM_MIPS_RS3_LE (MIPS R3000 little-endian)
.\" 10
.TP
-.BR EM_PARISC
+.B EM_PARISC
HP/PA
.\" 15
.TP
-.BR EM_SPARC32PLUS
+.B EM_SPARC32PLUS
SPARC with enhanced instruction set
.\" 18
.TP
-.BR EM_PPC
+.B EM_PPC
PowerPC
.\" 20
.TP
-.BR EM_PPC64
+.B EM_PPC64
PowerPC 64-bit
.\" 21
.TP
-.BR EM_S390
+.B EM_S390
IBM S/390
.\" 22
.TP
-.BR EM_ARM
+.B EM_ARM
Advanced RISC Machines
.\" 40
.TP
-.BR EM_SH
+.B EM_SH
Renesas SuperH
.\" 42
.TP
-.BR EM_SPARCV9
+.B EM_SPARCV9
SPARC v9 64-bit
.\" 43
.TP
-.BR EM_IA_64
+.B EM_IA_64
Intel Itanium
.\" 50
.TP
-.BR EM_X86_64
+.B EM_X86_64
AMD x86-64
.\" 62
.TP
-.BR EM_VAX
+.B EM_VAX
DEC Vax
.\" 75
.\" EM_CRIS
.PD
.RE
.TP
-.IR e_version
+.I e_version
This member identifies the file version:
.RS
.TP 16
.PD 0
-.BR EV_NONE
+.B EV_NONE
Invalid version
.TP
-.BR EV_CURRENT
+.B EV_CURRENT
Current version
.PD
.RE
.TP
-.IR e_entry
+.I e_entry
This member gives the virtual address to which the system first transfers
control, thus starting the process.
If the file has no associated entry
point, this member holds zero.
.TP
-.IR e_phoff
+.I e_phoff
This member holds the program header table's file offset in bytes.
If
the file has no program header table, this member holds zero.
.TP
-.IR e_shoff
+.I e_shoff
This member holds the section header table's file offset in bytes.
If the
file has no section header table, this member holds zero.
.TP
-.IR e_flags
+.I e_flags
This member holds processor-specific flags associated with the file.
Flag names take the form EF_`machine_flag'.
Currently, no flags have been defined.
.TP
-.IR e_ehsize
+.I e_ehsize
This member holds the ELF header's size in bytes.
.TP
-.IR e_phentsize
+.I e_phentsize
This member holds the size in bytes of one entry in the file's
program header table; all entries are the same size.
.TP
-.IR e_phnum
+.I e_phnum
This member holds the number of entries in the program header
table.
Thus the product of
-.IR e_phentsize
+.I e_phentsize
and
-.IR e_phnum
+.I e_phnum
gives the table's size
in bytes.
If a file has no program header,
-.IR e_phnum
+.I e_phnum
holds the value zero.
.IP
If the number of entries in the program header table is
larger than or equal to
.\" This is a Linux extension, added in Linux 2.6.34.
-.BR PN_XNUM
+.B PN_XNUM
(0xffff), this member holds
-.BR PN_XNUM
+.B PN_XNUM
(0xffff) and the real number of entries in the program header table is held
in the
-.IR sh_info
+.I sh_info
member of the initial entry in section header table.
Otherwise, the
-.IR sh_info
+.I sh_info
member of the initial entry contains the value zero.
.RS
.TP
-.BR PN_XNUM
+.B PN_XNUM
This is defined as 0xffff, the largest number
-.IR e_phnum
+.I e_phnum
can have, specifying where the actual number of program headers is assigned.
.PD
.RE
.TP
-.IR e_shentsize
+.I e_shentsize
This member holds a sections header's size in bytes.
A section header is one
entry in the section header table; all entries are the same size.
.TP
-.IR e_shnum
+.I e_shnum
This member holds the number of entries in the section header table.
Thus
the product of
-.IR e_shentsize
+.I e_shentsize
and
-.IR e_shnum
+.I e_shnum
gives the section header table's size in bytes.
If a file has no section
header table,
-.IR e_shnum
+.I e_shnum
holds the value of zero.
.IP
If the number of entries in the section header table is
larger than or equal to
-.BR SHN_LORESERVE
+.B SHN_LORESERVE
(0xff00),
-.IR e_shnum
+.I e_shnum
holds the value zero and the real number of entries in the section header
table is held in the
-.IR sh_size
+.I sh_size
member of the initial entry in section header table.
Otherwise, the
-.IR sh_size
+.I sh_size
member of the initial entry in the section header table holds
the value zero.
.TP
-.IR e_shstrndx
+.I e_shstrndx
This member holds the section header table index of the entry associated
with the section name string table.
If the file has no section name string
.IP
If the index of section name string table section is
larger than or equal to
-.BR SHN_LORESERVE
+.B SHN_LORESERVE
(0xff00), this member holds
-.BR SHN_XINDEX
+.B SHN_XINDEX
(0xffff) and the real index of the section name string table section
is held in the
-.IR sh_link
+.I sh_link
member of the initial entry in section header table.
Otherwise, the
-.IR sh_link
+.I sh_link
member of the initial entry in section header table contains the value zero.
.\"
.SS Program header (Phdr)
structures, each describing a segment or other information the system needs
to prepare the program for execution.
An object file
-.IR segment
+.I segment
contains one or more
.IR sections .
Program headers are meaningful only for executable and shared object files.
A file specifies its own program header size with the ELF header's
-.IR e_phentsize
+.I e_phentsize
and
-.IR e_phnum
+.I e_phnum
members.
The ELF program header is described by the type
.I Elf32_Phdr
.PP
The main difference between the 32-bit and the 64-bit program header lies
in the location of the
-.IR p_flags
+.I p_flags
member in the total struct.
.TP
-.IR p_type
+.I p_type
This member of the structure indicates what kind of segment this array
element describes or how to interpret the array element's information.
.RS 10
.TP
-.BR PT_NULL
+.B PT_NULL
The array element is unused and the other members' values are undefined.
This lets the program header have ignored entries.
.TP
-.BR PT_LOAD
+.B PT_LOAD
The array element specifies a loadable segment, described by
-.IR p_filesz
+.I p_filesz
and
.IR p_memsz .
The bytes from the file are mapped to the beginning of the memory
segment.
If the segment's memory size
-.IR p_memsz
+.I p_memsz
is larger than the file size
.IR p_filesz ,
the
The file size may not be larger than the memory size.
Loadable segment entries in the program header table appear in ascending
order, sorted on the
-.IR p_vaddr
+.I p_vaddr
member.
.TP
-.BR PT_DYNAMIC
+.B PT_DYNAMIC
The array element specifies dynamic linking information.
.TP
-.BR PT_INTERP
+.B PT_INTERP
The array element specifies the location and size of a null-terminated
pathname to invoke as an interpreter.
This segment type is meaningful
However it may not occur more than once in a file.
If it is present, it must precede any loadable segment entry.
.TP
-.BR PT_NOTE
+.B PT_NOTE
The array element specifies the location of notes (ElfN_Nhdr).
.TP
-.BR PT_SHLIB
+.B PT_SHLIB
This segment type is reserved but has unspecified semantics.
Programs that
contain an array element of this type do not conform to the ABI.
.TP
-.BR PT_PHDR
+.B PT_PHDR
The array element, if present,
specifies the location and size of the program header table itself,
both in the file and in the memory image of the program.
.TP
.BR PT_LOPROC ", " PT_HIPROC
Values in the inclusive range
-.RB [ PT_LOPROC ", " PT_HIPROC ]
+.RB [ PT_LOPROC ,
+.BR PT_HIPROC ]
are reserved for processor-specific semantics.
.TP
-.BR PT_GNU_STACK
+.B PT_GNU_STACK
GNU extension which is used by the Linux kernel to control the state of the
stack via the flags set in the
-.IR p_flags
+.I p_flags
member.
.RE
.TP
-.IR p_offset
+.I p_offset
This member holds the offset from the beginning of the file at which
the first byte of the segment resides.
.TP
-.IR p_vaddr
+.I p_vaddr
This member holds the virtual address at which the first byte of the
segment resides in memory.
.TP
-.IR p_paddr
+.I p_paddr
On systems for which physical addressing is relevant, this member is
reserved for the segment's physical address.
Under
this member is
not used and must be zero.
.TP
-.IR p_filesz
+.I p_filesz
This member holds the number of bytes in the file image of the segment.
It may be zero.
.TP
-.IR p_memsz
+.I p_memsz
This member holds the number of bytes in the memory image of the segment.
It may be zero.
.TP
-.IR p_flags
+.I p_flags
This member holds a bit mask of flags relevant to the segment:
.RS
.TP
.PD 0
-.BR PF_X
+.B PF_X
An executable segment.
.TP
-.BR PF_W
+.B PF_W
A writable segment.
.TP
-.BR PF_R
+.B PF_R
A readable segment.
.PD
.RE
.IP
A text segment commonly has the flags
-.BR PF_X
+.B PF_X
and
-.BR PF_R .
+.B PF_R .
A data segment commonly has
-.BR PF_W
+.B PF_W
and
.BR PF_R .
.TP
-.IR p_align
+.I p_align
This member holds the value to which the segments are aligned in memory
and in the file.
Loadable process segments must have congruent values for
-.IR p_vaddr
+.I p_vaddr
and
.IR p_offset ,
modulo the page size.
Values of zero and one mean no alignment is required.
Otherwise,
-.IR p_align
+.I p_align
should be a positive, integral power of two, and
-.IR p_vaddr
+.I p_vaddr
should equal
.IR p_offset ,
modulo
structures.
The
ELF header's
-.IR e_shoff
+.I e_shoff
member gives the byte offset from the beginning of the file to the section
header table.
-.IR e_shnum
+.I e_shnum
holds the number of entries the section header table contains.
-.IR e_shentsize
+.I e_shentsize
holds the size in bytes of each entry.
.PP
A section header table index is a subscript into this array.
An object file does not have sections for
these special indices:
.TP
-.BR SHN_UNDEF
+.B SHN_UNDEF
This value marks an undefined, missing, irrelevant,
or otherwise meaningless section reference.
.TP
-.BR SHN_LORESERVE
+.B SHN_LORESERVE
This value specifies the lower bound of the range of reserved indices.
.TP
.BR SHN_LOPROC ", " SHN_HIPROC
Values greater in the inclusive range
-.RB [ SHN_LOPROC ", " SHN_HIPROC ]
+.RB [ SHN_LOPROC ,
+.BR SHN_HIPROC ]
are reserved for processor-specific semantics.
.TP
-.BR SHN_ABS
+.B SHN_ABS
This value specifies the absolute value for the corresponding reference.
For
example, a symbol defined relative to section number
-.BR SHN_ABS
+.B SHN_ABS
has an absolute value and is not affected by relocation.
.TP
-.BR SHN_COMMON
+.B SHN_COMMON
Symbols defined relative to this section are common symbols,
such as FORTRAN COMMON or unallocated C external variables.
.TP
-.BR SHN_HIRESERVE
+.B SHN_HIRESERVE
This value specifies the upper bound of the range of reserved indices.
The
system reserves indices between
-.BR SHN_LORESERVE
+.B SHN_LORESERVE
and
.BR SHN_HIRESERVE ,
inclusive.
.PP
No real differences exist between the 32-bit and 64-bit section headers.
.TP
-.IR sh_name
+.I sh_name
This member specifies the name of the section.
Its value is an index
into the section header string table section, giving the location of
a null-terminated string.
.TP
-.IR sh_type
+.I sh_type
This member categorizes the section's contents and semantics.
.RS
.TP
-.BR SHT_NULL
+.B SHT_NULL
This value marks the section header as inactive.
It does not
have an associated section.
Other members of the section header
have undefined values.
.TP
-.BR SHT_PROGBITS
+.B SHT_PROGBITS
This section holds information defined by the program, whose
format and meaning are determined solely by the program.
.TP
-.BR SHT_SYMTAB
+.B SHT_SYMTAB
This section holds a symbol table.
Typically,
-.BR SHT_SYMTAB
+.B SHT_SYMTAB
provides symbols for link editing, though it may also be used
for dynamic linking.
As a complete symbol table, it may contain
many symbols unnecessary for dynamic linking.
An object file can
also contain a
-.BR SHT_DYNSYM
+.B SHT_DYNSYM
section.
.TP
-.BR SHT_STRTAB
+.B SHT_STRTAB
This section holds a string table.
An object file may have multiple
string table sections.
.TP
-.BR SHT_RELA
+.B SHT_RELA
This section holds relocation entries with explicit addends, such
as type
-.IR Elf32_Rela
+.I Elf32_Rela
for the 32-bit class of object files.
An object may have multiple
relocation sections.
.TP
-.BR SHT_HASH
+.B SHT_HASH
This section holds a symbol hash table.
An object participating in
dynamic linking must contain a symbol hash table.
An object file may
have only one hash table.
.TP
-.BR SHT_DYNAMIC
+.B SHT_DYNAMIC
This section holds information for dynamic linking.
An object file may
have only one dynamic section.
.TP
-.BR SHT_NOTE
+.B SHT_NOTE
This section holds notes (ElfN_Nhdr).
.TP
-.BR SHT_NOBITS
+.B SHT_NOBITS
A section of this type occupies no space in the file but otherwise
resembles
.BR SHT_PROGBITS .
Although this section contains no bytes, the
-.IR sh_offset
+.I sh_offset
member contains the conceptual file offset.
.TP
-.BR SHT_REL
+.B SHT_REL
This section holds relocation offsets without explicit addends, such
as type
-.IR Elf32_Rel
+.I Elf32_Rel
for the 32-bit class of object files.
An object file may have multiple
relocation sections.
.TP
-.BR SHT_SHLIB
+.B SHT_SHLIB
This section is reserved but has unspecified semantics.
.TP
-.BR SHT_DYNSYM
+.B SHT_DYNSYM
This section holds a minimal set of dynamic linking symbols.
An
object file can also contain a
-.BR SHT_SYMTAB
+.B SHT_SYMTAB
section.
.TP
.BR SHT_LOPROC ", " SHT_HIPROC
Values in the inclusive range
-.RB [ SHT_LOPROC ", " SHT_HIPROC ]
+.RB [ SHT_LOPROC ,
+.BR SHT_HIPROC ]
are reserved for processor-specific semantics.
.TP
-.BR SHT_LOUSER
+.B SHT_LOUSER
This value specifies the lower bound of the range of indices reserved for
application programs.
.TP
-.BR SHT_HIUSER
+.B SHT_HIUSER
This value specifies the upper bound of the range of indices reserved for
application programs.
Section types between
-.BR SHT_LOUSER
+.B SHT_LOUSER
and
-.BR SHT_HIUSER
+.B SHT_HIUSER
may be used by the application, without conflicting with current or future
system-defined section types.
.RE
.TP
-.IR sh_flags
+.I sh_flags
Sections support one-bit flags that describe miscellaneous attributes.
If a flag bit is set in
.IR sh_flags ,
Undefined attributes are set to zero.
.RS
.TP
-.BR SHF_WRITE
+.B SHF_WRITE
This section contains data that should be writable during process
execution.
.TP
-.BR SHF_ALLOC
+.B SHF_ALLOC
This section occupies memory during process execution.
Some control
sections do not reside in the memory image of an object file.
This
attribute is off for those sections.
.TP
-.BR SHF_EXECINSTR
+.B SHF_EXECINSTR
This section contains executable machine instructions.
.TP
-.BR SHF_MASKPROC
+.B SHF_MASKPROC
All bits included in this mask are reserved for processor-specific
semantics.
.RE
.TP
-.IR sh_addr
+.I sh_addr
If this section appears in the memory image of a process, this member
holds the address at which the section's first byte should reside.
Otherwise, the member contains zero.
.TP
-.IR sh_offset
+.I sh_offset
This member's value holds the byte offset from the beginning of the file
to the first byte in the section.
One section type,
.BR SHT_NOBITS ,
occupies no space in the file, and its
-.IR sh_offset
+.I sh_offset
member locates the conceptual placement in the file.
.TP
-.IR sh_size
+.I sh_size
This member holds the section's size in bytes.
Unless the section type
is
.BR SHT_NOBITS ,
the section occupies
-.IR sh_size
+.I sh_size
bytes in the file.
A section of type
-.BR SHT_NOBITS
+.B SHT_NOBITS
may have a nonzero size, but it occupies no space in the file.
.TP
-.IR sh_link
+.I sh_link
This member holds a section header table index link, whose interpretation
depends on the section type.
.TP
-.IR sh_info
+.I sh_info
This member holds extra information, whose interpretation depends on the
section type.
.TP
-.IR sh_addralign
+.I sh_addralign
Some sections have address alignment constraints.
If a section holds a
doubleword, the system must ensure doubleword alignment for the entire
section.
That is, the value of
-.IR sh_addr
+.I sh_addr
must be congruent to zero, modulo the value of
.IR sh_addralign .
Only zero and positive integral powers of two are allowed.
The value 0 or 1 means that the section has no alignment constraints.
.TP
-.IR sh_entsize
+.I sh_entsize
Some sections hold a table of fixed-sized entries, such as a symbol table.
For such a section, this member gives the size in bytes for each entry.
This member contains zero if the section does not hold a table of
.PP
Various sections hold program and control information:
.TP
-.IR .bss
+.I .bss
This section holds uninitialized data that contributes to the program's
memory image.
By definition, the system initializes the data with zeros
This section is of type
.BR SHT_NOBITS .
The attribute types are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_WRITE .
.TP
-.IR .comment
+.I .comment
This section holds version control information.
This section is of type
.BR SHT_PROGBITS .
No attribute types are used.
.TP
-.IR .ctors
+.I .ctors
This section holds initialized pointers to the C++ constructor functions.
This section is of type
.BR SHT_PROGBITS .
The attribute types are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_WRITE .
.TP
-.IR .data
+.I .data
This section holds initialized data that contribute to the program's
memory image.
This section is of type
.BR SHT_PROGBITS .
The attribute types are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_WRITE .
.TP
-.IR .data1
+.I .data1
This section holds initialized data that contribute to the program's
memory image.
This section is of type
.BR SHT_PROGBITS .
The attribute types are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_WRITE .
.TP
-.IR .debug
+.I .debug
This section holds information for symbolic debugging.
The contents
are unspecified.
.BR SHT_PROGBITS .
No attribute types are used.
.TP
-.IR .dtors
+.I .dtors
This section holds initialized pointers to the C++ destructor functions.
This section is of type
.BR SHT_PROGBITS .
The attribute types are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_WRITE .
.TP
-.IR .dynamic
+.I .dynamic
This section holds dynamic linking information.
The section's attributes
will include the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Whether the
-.BR SHF_WRITE
+.B SHF_WRITE
bit is set is processor-specific.
This section is of type
.BR SHT_DYNAMIC .
See the attributes above.
.TP
-.IR .dynstr
+.I .dynstr
This section holds strings needed for dynamic linking, most commonly
the strings that represent the names associated with symbol table entries.
This section is of type
The attribute type used is
.BR SHF_ALLOC .
.TP
-.IR .dynsym
+.I .dynsym
This section holds the dynamic linking symbol table.
This section is of type
.BR SHT_DYNSYM .
The attribute used is
.BR SHF_ALLOC .
.TP
-.IR .fini
+.I .fini
This section holds executable instructions that contribute to the process
termination code.
When a program exits normally the system arranges to
This section is of type
.BR SHT_PROGBITS .
The attributes used are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_EXECINSTR .
.TP
-.IR .gnu.version
+.I .gnu.version
This section holds the version symbol table, an array of
.I ElfN_Half
elements.
The attribute type used is
.BR SHF_ALLOC .
.TP
-.IR .gnu.version_d
+.I .gnu.version_d
This section holds the version symbol definitions, a table of
.I ElfN_Verdef
structures.
The attribute type used is
.BR SHF_ALLOC .
.TP
-.IR .gnu.version_r
+.I .gnu.version_r
This section holds the version symbol needed elements, a table of
.I ElfN_Verneed
structures.
The attribute type used is
.BR SHF_ALLOC .
.TP
-.IR .got
+.I .got
This section holds the global offset table.
This section is of type
.BR SHT_PROGBITS .
The attributes are processor-specific.
.TP
-.IR .hash
+.I .hash
This section holds a symbol hash table.
This section is of type
.BR SHT_HASH .
The attribute used is
.BR SHF_ALLOC .
.TP
-.IR .init
+.I .init
This section holds executable instructions that contribute to the process
initialization code.
When a program starts to run the system arranges to execute
This section is of type
.BR SHT_PROGBITS .
The attributes used are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_EXECINSTR .
.TP
-.IR .interp
+.I .interp
This section holds the pathname of a program interpreter.
If the file has
a loadable segment that includes the section, the section's attributes will
include the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Otherwise, that bit will be off.
This section is of type
.BR SHT_PROGBITS .
.TP
-.IR .line
+.I .line
This section holds line number information for symbolic debugging,
which describes the correspondence between the program source and
the machine code.
.BR SHT_PROGBITS .
No attribute types are used.
.TP
-.IR .note
+.I .note
This section holds various notes.
This section is of type
.BR SHT_NOTE .
No attribute types are used.
.TP
-.IR .note.ABI\-tag
+.I .note.ABI\-tag
This section is used to declare the expected run-time ABI of the ELF image.
It may include the operating system name and its run-time versions.
This section is of type
The only attribute used is
.BR SHF_ALLOC .
.TP
-.IR .note.gnu.build\-id
+.I .note.gnu.build\-id
This section is used to hold an ID that uniquely identifies
the contents of the ELF image.
Different files with the same build ID should contain the same executable
content.
See the
-.BR \-\-build\-id
+.B \-\-build\-id
option to the GNU linker (\fBld\fR (1)) for more details.
This section is of type
.BR SHT_NOTE .
The only attribute used is
.BR SHF_ALLOC .
.TP
-.IR .note.GNU\-stack
+.I .note.GNU\-stack
This section is used in Linux object files for declaring stack attributes.
This section is of type
.BR SHT_PROGBITS .
This indicates to the GNU linker that the object file requires an
executable stack.
.TP
-.IR .note.openbsd.ident
+.I .note.openbsd.ident
OpenBSD native executables usually contain this section
to identify themselves so the kernel can bypass any compatibility
ELF binary emulation tests when loading the file.
.TP
-.IR .plt
+.I .plt
This section holds the procedure linkage table.
This section is of type
.BR SHT_PROGBITS .
The attributes are processor-specific.
.TP
-.IR .relNAME
+.I .relNAME
This section holds relocation information as described below.
If the file
has a loadable segment that includes relocation, the section's attributes
will include the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Otherwise, the bit will be off.
By convention,
is supplied by the section to which the relocations apply.
Thus a relocation
section for
-.BR .text
+.B .text
normally would have the name
.BR .rel.text .
This section is of type
.BR SHT_REL .
.TP
-.IR .relaNAME
+.I .relaNAME
This section holds relocation information as described below.
If the file
has a loadable segment that includes relocation, the section's attributes
will include the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Otherwise, the bit will be off.
By convention,
is supplied by the section to which the relocations apply.
Thus a relocation
section for
-.BR .text
+.B .text
normally would have the name
.BR .rela.text .
This section is of type
.BR SHT_RELA .
.TP
-.IR .rodata
+.I .rodata
This section holds read-only data that typically contributes to a
nonwritable segment in the process image.
This section is of type
The attribute used is
.BR SHF_ALLOC .
.TP
-.IR .rodata1
+.I .rodata1
This section holds read-only data that typically contributes to a
nonwritable segment in the process image.
This section is of type
The attribute used is
.BR SHF_ALLOC .
.TP
-.IR .shstrtab
+.I .shstrtab
This section holds section names.
This section is of type
.BR SHT_STRTAB .
No attribute types are used.
.TP
-.IR .strtab
+.I .strtab
This section holds strings, most commonly the strings that represent the
names associated with symbol table entries.
If the file has a loadable
segment that includes the symbol string table, the section's attributes
will include the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Otherwise, the bit will be off.
This section is of type
.BR SHT_STRTAB .
.TP
-.IR .symtab
+.I .symtab
This section holds a symbol table.
If the file has a loadable segment
that includes the symbol table, the section's attributes will include
the
-.BR SHF_ALLOC
+.B SHF_ALLOC
bit.
Otherwise, the bit will be off.
This section is of type
.BR SHT_SYMTAB .
.TP
-.IR .text
+.I .text
This section holds the
"text",
or executable instructions, of a program.
This section is of type
.BR SHT_PROGBITS .
The attributes used are
-.BR SHF_ALLOC
+.B SHF_ALLOC
and
.BR SHF_EXECINSTR .
.\"
The 32-bit and 64-bit versions have the same members, just in a different
order.
.TP
-.IR st_name
+.I st_name
This member holds an index into the object file's symbol string table,
which holds character representations of the symbol names.
If the value
name.
Otherwise, the symbol has no name.
.TP
-.IR st_value
+.I st_value
This member gives the value of the associated symbol.
.TP
-.IR st_size
+.I st_size
Many symbols have associated sizes.
This member holds zero if the symbol
has no size or an unknown size.
.TP
-.IR st_info
+.I st_info
This member specifies the symbol's type and binding attributes:
.RS
.TP
-.BR STT_NOTYPE
+.B STT_NOTYPE
The symbol's type is not defined.
.TP
-.BR STT_OBJECT
+.B STT_OBJECT
The symbol is associated with a data object.
.TP
-.BR STT_FUNC
+.B STT_FUNC
The symbol is associated with a function or other executable code.
.TP
-.BR STT_SECTION
+.B STT_SECTION
The symbol is associated with a section.
Symbol table entries of
this type exist primarily for relocation and normally have
-.BR STB_LOCAL
+.B STB_LOCAL
bindings.
.TP
-.BR STT_FILE
+.B STT_FILE
By convention, the symbol's name gives the name of the source file
associated with the object file.
A file symbol has
-.BR STB_LOCAL
+.B STB_LOCAL
bindings, its section index is
.BR SHN_ABS ,
and it precedes the other
-.BR STB_LOCAL
+.B STB_LOCAL
symbols of the file, if it is present.
.TP
.BR STT_LOPROC ", " STT_HIPROC
Values in the inclusive range
-.RB [ STT_LOPROC ", " STT_HIPROC ]
+.RB [ STT_LOPROC ,
+.BR STT_HIPROC ]
are reserved for processor-specific semantics.
.TP
-.BR STB_LOCAL
+.B STB_LOCAL
Local symbols are not visible outside the object file containing their
definition.
Local symbols of the same name may exist in multiple files
without interfering with each other.
.TP
-.BR STB_GLOBAL
+.B STB_GLOBAL
Global symbols are visible to all object files being combined.
One file's
definition of a global symbol will satisfy another file's undefined
reference to the same symbol.
.TP
-.BR STB_WEAK
+.B STB_WEAK
Weak symbols resemble global symbols, but their definitions have lower
precedence.
.TP
.BR STB_LOPROC ", " STB_HIPROC
Values in the inclusive range
-.RB [ STB_LOPROC ", " STB_HIPROC ]
+.RB [ STB_LOPROC ,
+.BR STB_HIPROC ]
are reserved for processor-specific semantics.
.RE
.IP
value.
.RE
.TP
-.IR st_other
+.I st_other
This member defines the symbol visibility.
.RS
.TP
.PD 0
-.BR STV_DEFAULT
+.B STV_DEFAULT
Default symbol visibility rules.
Global and weak symbols are available to other modules;
references in the local module can be interposed
by definitions in other modules.
.TP
-.BR STV_INTERNAL
+.B STV_INTERNAL
Processor-specific hidden class.
.TP
-.BR STV_HIDDEN
+.B STV_HIDDEN
Symbol is unavailable to other modules;
references in the local module always resolve to the local symbol
(i.e., the symbol can't be interposed by definitions in other modules).
.TP
-.BR STV_PROTECTED
+.B STV_PROTECTED
Symbol is available to other modules,
but references in the local module always resolve to the local symbol.
.PD
.BR ELF64_ST_VISIBILITY (other)
.RE
.TP
-.IR st_shndx
+.I st_shndx
Every symbol table entry is
"defined"
in relation to some section.
.EE
.in
.TP
-.IR r_offset
+.I r_offset
This member gives the location at which to apply the relocation action.
For a relocatable file, the value is the byte offset from the beginning
of the section to the storage unit affected by the relocation.
executable file or shared object, the value is the virtual address of
the storage unit affected by the relocation.
.TP
-.IR r_info
+.I r_info
This member gives both the symbol table index with respect to which the
relocation must be made and the type of relocation to apply.
Relocation
When the text refers to a relocation
entry's relocation type or symbol table index, it means the result of
applying
-.BR ELF[32|64]_R_TYPE
+.B ELF[32|64]_R_TYPE
or
.BR ELF[32|64]_R_SYM ,
respectively, to the entry's
-.IR r_info
+.I r_info
member.
.TP
-.IR r_addend
+.I r_addend
This member specifies a constant addend used to compute the value to be
stored into the relocatable field.
.\"
.EE
.in
.TP
-.IR d_tag
+.I d_tag
This member may have any of the following values:
.RS
.TP 12
-.BR DT_NULL
+.B DT_NULL
Marks end of dynamic section
.TP
-.BR DT_NEEDED
+.B DT_NEEDED
String table offset to name of a needed library
.TP
-.BR DT_PLTRELSZ
+.B DT_PLTRELSZ
Size in bytes of PLT relocation entries
.TP
-.BR DT_PLTGOT
+.B DT_PLTGOT
Address of PLT and/or GOT
.TP
-.BR DT_HASH
+.B DT_HASH
Address of symbol hash table
.TP
-.BR DT_STRTAB
+.B DT_STRTAB
Address of string table
.TP
-.BR DT_SYMTAB
+.B DT_SYMTAB
Address of symbol table
.TP
-.BR DT_RELA
+.B DT_RELA
Address of Rela relocation table
.TP
-.BR DT_RELASZ
+.B DT_RELASZ
Size in bytes of the Rela relocation table
.TP
-.BR DT_RELAENT
+.B DT_RELAENT
Size in bytes of a Rela relocation table entry
.TP
-.BR DT_STRSZ
+.B DT_STRSZ
Size in bytes of string table
.TP
-.BR DT_SYMENT
+.B DT_SYMENT
Size in bytes of a symbol table entry
.TP
-.BR DT_INIT
+.B DT_INIT
Address of the initialization function
.TP
-.BR DT_FINI
+.B DT_FINI
Address of the termination function
.TP
-.BR DT_SONAME
+.B DT_SONAME
String table offset to name of shared object
.TP
-.BR DT_RPATH
+.B DT_RPATH
String table offset to library search path (deprecated)
.TP
-.BR DT_SYMBOLIC
+.B DT_SYMBOLIC
Alert linker to search this shared object before the executable for symbols
.TP
-.BR DT_REL
+.B DT_REL
Address of Rel relocation table
.TP
-.BR DT_RELSZ
+.B DT_RELSZ
Size in bytes of Rel relocation table
.TP
-.BR DT_RELENT
+.B DT_RELENT
Size in bytes of a Rel table entry
.TP
-.BR DT_PLTREL
+.B DT_PLTREL
Type of relocation entry to which the PLT refers (Rela or Rel)
.TP
-.BR DT_DEBUG
+.B DT_DEBUG
Undefined use for debugging
.TP
-.BR DT_TEXTREL
+.B DT_TEXTREL
Absence of this entry indicates that no relocation entries should
apply to a nonwritable segment
.TP
-.BR DT_JMPREL
+.B DT_JMPREL
Address of relocation entries associated solely with the PLT
.TP
-.BR DT_BIND_NOW
+.B DT_BIND_NOW
Instruct dynamic linker to process all relocations before
transferring control to the executable
.TP
-.BR DT_RUNPATH
+.B DT_RUNPATH
String table offset to library search path
.TP
.BR DT_LOPROC ", " DT_HIPROC
Values in the inclusive range
-.RB [ DT_LOPROC ", " DT_HIPROC ]
+.RB [ DT_LOPROC ,
+.BR DT_HIPROC ]
are reserved for processor-specific semantics
.RE
.TP
-.IR d_val
+.I d_val
This member represents integer values with various interpretations.
.TP
-.IR d_ptr
+.I d_ptr
This member represents program virtual addresses.
When interpreting
these addresses, the actual address should be computed based on the
.EE
.in
.TP
-.IR n_namesz
+.I n_namesz
The length of the name field in bytes.
The contents will immediately follow this note in memory.
The name is null terminated.
.I n_namesz
will be set to 4.
.TP
-.IR n_descsz
+.I n_descsz
The length of the descriptor field in bytes.
The contents will immediately follow the name field in memory.
.TP
-.IR n_type
+.I n_type
Depending on the value of the name field, this member may have any of the
following values:
.RS
.B NT_GNU_BUILD_ID
Unique build ID as generated by the GNU
.BR ld (1)
-.BR \-\-build\-id
+.B \-\-build\-id
option.
The desc consists of any nonzero number of bytes.
.TP
.IR e_phnum ,
.IR e_shnum ,
and
-.IR e_shstrndx
+.I e_shstrndx
respectively are
Linux extensions.
Sun, BSD, and AMD64 also support them; for further information,
.PP
Allow any user to log in from any host:
.PP
- +
+.in +4n
+.EX
++
+.EE
+.in
.PP
Allow any user from
.I host
with a matching local account to log in:
.PP
- host
+.in +4n
+.EX
+host
+.EE
+.in
.PP
Note: the use of
.I +host
.I host
to log in:
.PP
- host +
+.in +4n
+.EX
+host +
+.EE
+.in
.PP
Note: this is distinct from the previous example
since it does not require a matching local account.
.I host
to log in as any non-root user:
.PP
- host user
+.in +4n
+.EX
+host user
+.EE
+.in
.PP
Allow all users with matching local accounts from
.I host
to log in except for
.IR baduser :
.PP
- host \-baduser
- host
+.in +4n
+.EX
+host \-baduser
+host
+.EE
+.in
.PP
Deny all users from
.IR host :
.PP
- \-host
+.in +4n
+.EX
+\-host
+.EE
+.in
.PP
Note: the use of
.I "\-host\ \-user"
Allow all users with matching local accounts on all hosts in a
.IR netgroup :
.PP
- +@netgroup
+.in +4n
+.EX
++@netgroup
+.EE
+.in
.PP
Disallow all users on all hosts in a
.IR netgroup :
.PP
- \-@netgroup
+.in +4n
+.EX
+\-@netgroup
+.EE
+.in
.PP
Allow all users in a
.I netgroup
.I host
as any non-root user:
.PP
- host +@netgroup
+.in +4n
+.EX
+host +@netgroup
+.EE
+.in
.PP
Allow all users with matching local accounts on all hosts in a
.I netgroup
except
.IR baduser :
.PP
- +@netgroup \-baduser
- +@netgroup
+.in +4n
+.EX
++@netgroup \-baduser
++@netgroup
+.EE
+.in
.PP
Note: the deny statements must always precede the allow statements because
the file is processed sequentially until the first matching rule is found.
passwd \- password file
.SH DESCRIPTION
The
-.IR /etc/passwd
+.I /etc/passwd
file is a text file that describes user login accounts for the system.
It should have read permission allowed for all users (many utilities, like
.BR ls (1)
.BR hidepid "=\fIn\fP (since Linux 3.3)"
.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201
This option controls who can access the information in
-.IR /proc/[pid]
+.IR /proc/ pid
directories.
The argument,
.IR n ,
.TP 4
0
Everybody may access all
-.IR /proc/[pid]
+.IR /proc/ pid
directories.
This is the traditional behavior,
and the default if this mount option is not specified.
.TP
1
Users may not access files and subdirectories inside any
-.IR /proc/[pid]
+.IR /proc/ pid
directories but their own (the
-.IR /proc/[pid]
+.IR /proc/ pid
directories themselves remain visible).
Sensitive files such as
-.IR /proc/[pid]/cmdline
+.IR /proc/ pid /cmdline
and
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
are now protected against other users.
This makes it impossible to learn whether any user is running a
specific program
.TP
2
As for mode 1, but in addition the
-.IR /proc/[pid]
+.IR /proc/ pid
directories belonging to other users become invisible.
This means that
-.IR /proc/[pid]
+.IR /proc/ pid
entries can no longer be used to discover the PIDs on the system.
This doesn't hide the fact that a process with a specific PID value exists
(it can be learned by other means, for example, by "kill \-0 $PID"),
which could otherwise be learned by employing
.BR stat (2)
on a
-.IR /proc/[pid]
+.IR /proc/ pid
directory.
This greatly complicates an attacker's task of gathering
information about running processes (e.g., discovering whether
.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201
Specifies the ID of a group whose members are authorized to
learn process information otherwise prohibited by
-.BR hidepid
+.B hidepid
(i.e., users in this group behave as though
.I /proc
was mounted with
.IR /proc ,
there are the following general groups of files and subdirectories:
.TP
-.IR /proc/[pid] " subdirectories"
+.IR /proc/ "pid subdirectories"
Each one of these subdirectories contains files and subdirectories
exposing information about the process with the corresponding process ID.
.IP
Underneath each of the
-.I /proc/[pid]
+.IR /proc/ pid
directories, a
.I task
subdirectory contains subdirectories of the form
-.IR task/[tid] ,
+.IR task/ tid,
which contain corresponding information about each of the threads
in the process, where
.I tid
is the kernel thread ID of the thread.
.IP
The
-.I /proc/[pid]
+.IR /proc/ pid
subdirectories are visible when iterating through
.I /proc
with
to view the contents of
.IR /proc ).
.TP
-.IR /proc/[tid] " subdirectories"
+.IR /proc/ "tid subdirectories"
Each one of these subdirectories contains files and subdirectories
exposing information about the thread with the corresponding thread ID.
The contents of these directories are the same as the corresponding
-.IR /proc/[pid]/task/[tid]
+.IR /proc/ pid /task/ tid
directories.
.IP
The
-.I /proc/[tid]
+.IR /proc/ tid
subdirectories are
.I not
visible when iterating through
.I /proc/self
When a process accesses this magic symbolic link,
it resolves to the process's own
-.I /proc/[pid]
+.IR /proc/ pid
directory.
.TP
.I /proc/thread\-self
When a thread accesses this magic symbolic link,
it resolves to the process's own
-.I /proc/self/task/[tid]
+.IR /proc/self/task/ tid
directory.
.TP
.I /proc/[a\-z]*
.I /proc
hierarchy.
.TP
-.I /proc/[pid]
+.IR /proc/ pid
There is a numerical subdirectory for each running process; the
subdirectory is named by the process ID.
Each
-.I /proc/[pid]
+.IR /proc/ pid
subdirectory contains the pseudo-files and directories described below.
.IP
The files inside each
-.I /proc/[pid]
+.IR /proc/ pid
directory are normally owned by the effective user and
effective group ID of the process.
However, as a security measure, the ownership is made
-.IR root:root
+.I root:root
if the process's "dumpable" attribute is set to a value other than 1.
.IP
Before Linux 4.11,
.\" commit 68eb94f16227336a5773b83ecfa8290f1d6b78ce
-.IR root:root
+.I root:root
meant the "global" root user ID and group ID
(i.e., UID 0 and GID 0 in the initial user namespace).
Since Linux 4.11,
if the process is in a noninitial user namespace that has a
valid mapping for user (group) ID 0 inside the namespace, then
the user (group) ownership of the files under
-.I /proc/[pid]
+.IR /proc/ pid
is instead made the same as the root user (group) ID of the namespace.
This means that inside a container,
things work as expected for the container "root" user.
operation.
.IP *
The attribute was reset to the value in the file
-.IR /proc/sys/fs/suid_dumpable
+.I /proc/sys/fs/suid_dumpable
(described below), for the reasons described in
.BR prctl (2).
.RE
.IP
Resetting the "dumpable" attribute to 1 reverts the ownership of the
-.IR /proc/[pid]/*
+.IR /proc/ pid /*
files to the process's effective UID and GID.
Note, however, that if the effective UID or GID is subsequently modified,
then the "dumpable" attribute may be reset, as described in
.I after
making any desired changes to the process's effective UID or GID.
.TP
-.I /proc/[pid]/attr
+.IR /proc/ pid /attr
.\" https://lwn.net/Articles/28222/
.\" From: Stephen Smalley <sds@epoch.ncsc.mil>
.\" To: LKML and others
This directory is present only if the kernel was configured with
.BR CONFIG_SECURITY .
.TP
-.IR /proc/[pid]/attr/current " (since Linux 2.6.0)"
+.IR /proc/ pid /attr/current " (since Linux 2.6.0)"
The contents of this file represent the current
security attributes of the process.
.IP
transitions to
.BR execve (2)
(see the description of
-.IR /proc/[pid]/attr/exec ,
+.IR /proc/ pid /attr/exec ,
below).
Since Linux 2.6.11, SELinux lifted this restriction and began supporting
"set" operations via writes to this node if authorized by policy,
Other security modules may choose to support "set" operations via
writes to this node.
.TP
-.IR /proc/[pid]/attr/exec " (since Linux 2.6.0)"
+.IR /proc/ pid /attr/exec " (since Linux 2.6.0)"
This file represents the attributes to assign to the
process upon a subsequent
.BR execve (2).
calls that it may make.
In SELinux, a process can set
only its own
-.I /proc/[pid]/attr/exec
+.IR /proc/ pid /attr/exec
attribute.
.TP
-.IR /proc/[pid]/attr/fscreate " (since Linux 2.6.0)"
+.IR /proc/ pid /attr/fscreate " (since Linux 2.6.0)"
This file represents the attributes to assign to files
created by subsequent calls to
.BR open (2),
across multiple file creation calls within a program unless it is
explicitly reset.
In SELinux, a process can set only its own
-.IR /proc/[pid]/attr/fscreate
+.IR /proc/ pid /attr/fscreate
attribute.
.TP
-.IR /proc/[pid]/attr/keycreate " (since Linux 2.6.18)"
+.IR /proc/ pid /attr/keycreate " (since Linux 2.6.18)"
.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e
If a process writes a security context into this file,
all subsequently created keys
.I Documentation/keys.txt
before Linux 3.0).
.TP
-.IR /proc/[pid]/attr/prev " (since Linux 2.6.0)"
+.IR /proc/ pid /attr/prev " (since Linux 2.6.0)"
This file contains the security context of the process before the last
.BR execve (2);
that is, the previous value of
-.IR /proc/[pid]/attr/current .
+.IR /proc/ pid /attr/current .
.TP
-.IR /proc/[pid]/attr/socketcreate " (since Linux 2.6.18)"
+.IR /proc/ pid /attr/socketcreate " (since Linux 2.6.18)"
.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2
If a process writes a security context into this file,
all subsequently created sockets will be labeled with this context.
.TP
-.IR /proc/[pid]/autogroup " (since Linux 2.6.38)"
+.IR /proc/ pid /autogroup " (since Linux 2.6.38)"
.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a
See
.BR sched (7).
.TP
-.IR /proc/[pid]/auxv " (since 2.6.0)"
+.IR /proc/ pid /auxv " (since 2.6.0)"
.\" Precisely: Linux 2.6.0-test7
This contains the contents of the ELF interpreter information passed
to the process at exec time.
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/cgroup " (since Linux 2.6.24)"
+.IR /proc/ pid /cgroup " (since Linux 2.6.24)"
See
.BR cgroups (7).
.TP
-.IR /proc/[pid]/clear_refs " (since Linux 2.6.22)"
+.IR /proc/ pid /clear_refs " (since Linux 2.6.22)"
.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22)
.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32)
.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11)
to measure approximately how much memory a process is using.
One first inspects the values in the "Referenced" fields
for the VMAs shown in
-.IR /proc/[pid]/smaps
+.IR /proc/ pid /smaps
to get an idea of the memory footprint of the
process.
One then clears the PG_Referenced and ACCESSED/YOUNG bits
Clear the soft-dirty bit for all the pages associated with the process.
.\" Internally: CLEAR_REFS_SOFT_DIRTY
This is used (in conjunction with
-.IR /proc/[pid]/pagemap )
+.IR /proc/ pid /pagemap )
by the check-point restore system to discover which pages of a process
have been dirtied since the file
-.IR /proc/[pid]/clear_refs
+.IR /proc/ pid /clear_refs
was written to.
.TP
5 (since Linux 4.0)
.RE
.IP
Writing any value to
-.IR /proc/[pid]/clear_refs
+.IR /proc/ pid /clear_refs
other than those listed above has no effect.
.IP
The
-.IR /proc/[pid]/clear_refs
+.IR /proc/ pid /clear_refs
file is present only if the
.B CONFIG_PROC_PAGE_MONITOR
kernel configuration option is enabled.
.TP
-.I /proc/[pid]/cmdline
+.IR /proc/ pid /cmdline
This read-only file holds the complete command line for the process,
unless the process is a zombie.
.\" In 2.3.26, this also used to be true if the process was swapped out.
.IP
Think of this file as the command line that the process wants you to see.
.TP
-.IR /proc/[pid]/comm " (since Linux 2.6.33)"
+.IR /proc/ pid /comm " (since Linux 2.6.33)"
.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4
This file exposes the process's
.I comm
Different threads in the same process may have different
.I comm
values, accessible via
-.IR /proc/[pid]/task/[tid]/comm .
+.IR /proc/ pid /task/ tid /comm .
A thread may modify its
.I comm
value, or that of any of other thread in the same thread group (see
in
.BR clone (2)),
by writing to the file
-.IR /proc/self/task/[tid]/comm .
+.IR /proc/self/task/ tid /comm .
Strings longer than
.B TASK_COMM_LEN
(16) characters (including the terminating null byte) are silently truncated.
see
.BR core (5).
.TP
-.IR /proc/[pid]/coredump_filter " (since Linux 2.6.23)"
+.IR /proc/ pid /coredump_filter " (since Linux 2.6.23)"
See
.BR core (5).
.TP
-.IR /proc/[pid]/cpuset " (since Linux 2.6.12)"
+.IR /proc/ pid /cpuset " (since Linux 2.6.12)"
.\" and/proc/[pid]/task/[tid]/cpuset
See
.BR cpuset (7).
.TP
-.I /proc/[pid]/cwd
+.IR /proc/ pid /cwd
This is a symbolic link to the current working directory of the process.
To find out the current working directory of process 20,
for instance, you can do this:
check; see
.BR ptrace (2).
.TP
-.I /proc/[pid]/environ
+.IR /proc/ pid /environ
This file contains the initial environment that was set
when the currently executing program was started via
.BR execve (2).
check; see
.BR ptrace (2).
.TP
-.I /proc/[pid]/exe
+.IR /proc/ pid /exe
Under Linux 2.2 and later, this file is a symbolic link
containing the actual pathname of the executed command.
This symbolic link can be dereferenced normally; attempting to open
it will open the executable.
You can even type
-.I /proc/[pid]/exe
+.IR /proc/ pid /exe
to run another copy of the same executable that is being run by
-process [pid].
+process
+.IR pid .
If the pathname has been unlinked, the symbolic link will contain the
string \(aq(deleted)\(aq appended to the original pathname.
.\" The following was still true as at kernel 2.6.13
.BR ptrace (2).
.IP
Under Linux 2.0 and earlier,
-.I /proc/[pid]/exe
+.IR /proc/ pid /exe
is a pointer to the binary which was executed,
and appears as a symbolic link.
A
.BR readlink (2)
call on this file under Linux 2.0 returns a string in the format:
.IP
- [device]:inode
+.in +4n
+.EX
+[device]:inode
+.EE
+.in
.IP
For example, [0301]:1502 would be inode 1502 on device major 03 (IDE,
MFM, etc. drives) minor 01 (first partition on the first drive).
.I \-inum
option can be used to locate the file.
.TP
-.I /proc/[pid]/fd/
+.IR /proc/ pid /fd/
This is a subdirectory containing one entry for each file which the
process has open, named by its file descriptor, and which is a
symbolic link to the actual file.
.BR readlink (2)
call on this file returns a string in the format:
.IP
- type:[inode]
+.in +4n
+.EX
+type:[inode]
+.EE
+.in
.IP
For example,
.I socket:[2248868]
.BR userfaultfd (2)),
the entry will be a symbolic link with contents of the form
.IP
- anon_inode:<file-type>
+.in +4n
+.EX
+.RI anon_inode: file-type
+.EE
+.in
.IP
In many cases (but not all), the
.I file-type
but don't send their output to standard output
if no argument is supplied, can nevertheless be made to use
standard input or standard output by using
-.IR /proc/[pid]/fd
+.IR /proc/ pid /fd
files as command-line arguments.
For example, assuming that
.I \-i
.IR 0 ,
.IR 1 ,
and
-.IR 2
+.I 2
in
.IR /proc/self/fd .
Thus the example command above could be written as:
Note that for file descriptors referring to inodes (pipes and sockets, see above),
those inodes still have permission bits and ownership information
distinct from those of the
-.I /proc/[pid]/fd
+.IR /proc/ pid /fd
entry,
and that the owner may differ from the user and group IDs of the process.
An unprivileged process may lack permissions to open them, as in this example:
does not have permission to create a new file descriptor to read from that inode,
even though it can still read from its existing file descriptor 0.
.TP
-.IR /proc/[pid]/fdinfo/ " (since Linux 2.6.22)"
+.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)"
This is a subdirectory containing one entry for each file which the
process has open, named by its file descriptor.
The files in this directory are readable only by the owner of the process.
.\" commit 49d063cb353265c3af701bab215ac438ca7df36d
is the ID of the mount containing this file.
See the description of
-.IR /proc/[pid]/mountinfo .
+.IR /proc/ pid /mountinfo .
.RE
.IP
For eventfd file descriptors (see
.BR epoll_ctl (2)
for some details).
The
-.IR tfd
+.I tfd
field is the number of the file descriptor.
The
.I events
on this file descriptor would return.)
.RE
.TP
-.IR /proc/[pid]/gid_map " (since Linux 3.5)"
+.IR /proc/ pid /gid_map " (since Linux 3.5)"
See
.BR user_namespaces (7).
.TP
-.IR /proc/[pid]/io " (since kernel 2.6.20)"
+.IR /proc/ pid /io " (since kernel 2.6.20)"
.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2
This file contains I/O statistics for the process, for example:
.IP
.IR Note :
In the current implementation, things are a bit racy on 32-bit systems:
if process A reads process B's
-.I /proc/[pid]/io
+.IR /proc/ pid /io
while process B is updating one of these 64-bit counters,
process A could see an intermediate result.
.IP
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/limits " (since Linux 2.6.24)"
+.IR /proc/ pid /limits " (since Linux 2.6.24)"
This file displays the soft limit, hard limit, and units of measurement
for each of the process's resource limits (see
.BR getrlimit (2)).
.\" Added in 2.6.11; updating requires CAP_AUDIT_CONTROL
.\" CONFIG_AUDITSYSCALL
.TP
-.IR /proc/[pid]/map_files/ " (since kernel 3.3)"
+.IR /proc/ pid /map_files/ " (since kernel 3.3)"
.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e
This subdirectory contains entries corresponding to memory-mapped
files (see
.IP
Although these entries are present for memory regions that were
mapped with the
-.BR MAP_FILE
+.B MAP_FILE
flag, the way anonymous shared memory (regions created with the
.B MAP_ANON | MAP_SHARED
flags)
.IP
Capabilities are required to read the contents of the symbolic links in
this directory: before Linux 5.9, the reading process requires
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
in the initial user namespace;
since Linux 5.9, the reading process must have either
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
or
-.BR CAP_CHECKPOINT_RESTORE
+.B CAP_CHECKPOINT_RESTORE
in the user namespace where it resides.
.TP
-.I /proc/[pid]/maps
+.IR /proc/ pid /maps
A file containing the currently mapped memory regions and their access
permissions.
See
There are additional helpful pseudo-paths:
.RS
.TP
-.IR [stack]
+.I [stack]
The initial process's (also known as the main thread's) stack.
.TP
-.IR [stack:<tid>] " (from Linux 3.4 to 4.4)"
+.IR [stack: tid ] " (from Linux 3.4 to 4.4)"
.\" commit b76437579d1344b612cf1851ae610c636cec7db0 (added)
.\" commit 65376df582174ffcec9e6471bf5b0dd79ba05e4a (removed)
A thread's stack (where the
-.IR <tid>
+.I tid
is a thread ID).
It corresponds to the
-.IR /proc/[pid]/task/[tid]/
+.IR /proc/ pid /task/ tid /
path.
This field was removed in Linux 4.5, since providing this information
for a process with large numbers of threads is expensive.
.TP
-.IR [vdso]
+.I [vdso]
The virtual dynamically linked shared object.
See
.BR vdso (7).
.TP
-.IR [heap]
+.I [heap]
The process's heap.
.in
.RE
.IP
Under Linux 2.0, there is no field giving pathname.
.TP
-.I /proc/[pid]/mem
+.IR /proc/ pid /mem
This file can be used to access the pages of a process's memory through
.BR open (2),
.BR read (2),
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/mountinfo " (since Linux 2.6.26)"
+.IR /proc/ pid /mountinfo " (since Linux 2.6.26)"
.\" This info adapted from Documentation/filesystems/proc.txt
.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760
This file contains information about mounts
It supplies various information
(e.g., propagation state, root of mount for bind mounts,
identifier for each mount and its parent) that is missing from the (older)
-.IR /proc/[pid]/mounts
+.IR /proc/ pid /mounts
file, and fixes various other problems with that file
(e.g., nonextensibility,
failure to distinguish per-mount versus per-superblock options).
before Linux 5.8)
in the Linux kernel source tree.
.TP
-.IR /proc/[pid]/mounts " (since Linux 2.4.19)"
+.IR /proc/ pid /mounts " (since Linux 2.4.19)"
This file lists all the filesystems currently mounted in the
process's mount namespace (see
.BR mount_namespaces (7)).
and
.BR epoll_wait (2).)
.TP
-.IR /proc/[pid]/mountstats " (since Linux 2.6.17)"
+.IR /proc/ pid /mountstats " (since Linux 2.6.17)"
This file exports information (statistics, configuration information)
about the mounts in the process's mount namespace (see
.BR mount_namespaces (7)).
.IP
This file is readable only by the owner of the process.
.TP
-.IR /proc/[pid]/net " (since Linux 2.6.25)"
+.IR /proc/ pid /net " (since Linux 2.6.25)"
See the description of
.IR /proc/net .
.TP
-.IR /proc/[pid]/ns/ " (since Linux 3.0)"
+.IR /proc/ pid /ns/ " (since Linux 3.0)"
.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
This is a subdirectory containing one entry for each namespace that
supports being manipulated by
For more information, see
.BR namespaces (7).
.TP
-.IR /proc/[pid]/numa_maps " (since Linux 2.6.14)"
+.IR /proc/ pid /numa_maps " (since Linux 2.6.14)"
See
.BR numa (7).
.TP
-.IR /proc/[pid]/oom_adj " (since Linux 2.6.11)"
+.IR /proc/ pid /oom_adj " (since Linux 2.6.11)"
This file can be used to adjust the score used to select which process
should be killed in an out-of-memory (OOM) situation.
The kernel uses this value for a bit-shift operation of the process's
-.IR oom_score
+.I oom_score
value:
valid values are in the range \-16 to +15,
plus the special value \-17,
to update this file.
.IP
Since Linux 2.6.36, use of this file is deprecated in favor of
-.IR /proc/[pid]/oom_score_adj .
+.IR /proc/ pid /oom_score_adj .
.TP
-.IR /proc/[pid]/oom_score " (since Linux 2.6.11)"
+.IR /proc/ pid /oom_score " (since Linux 2.6.11)"
.\" See mm/oom_kill.c::badness() in pre 2.6.36 sources
.\" See mm/oom_kill.c::oom_badness() after 2.6.36
.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10
.I oom_adj
setting for the process.
.TP
-.IR /proc/[pid]/oom_score_adj " (since Linux 2.6.36)"
+.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)"
.\" Text taken from 3.7 Documentation/filesystems/proc.txt
This file can be used to adjust the badness heuristic used to select which
process gets killed in out-of-memory conditions.
allowed memory from being considered as scoring against the task.
.IP
For backward compatibility with previous kernels,
-.I /proc/[pid]/oom_adj
+.IR /proc/ pid /oom_adj
can still be used to tune the badness score.
Its value is
scaled linearly with
.IR oom_score_adj .
.IP
Writing to
-.IR /proc/[pid]/oom_score_adj
+.IR /proc/ pid /oom_score_adj
or
-.IR /proc/[pid]/oom_adj
+.IR /proc/ pid /oom_adj
will change the other with its scaled value.
.IP
The
.I oom_score_adj
value of a running process or a newly executed command.
.TP
-.IR /proc/[pid]/pagemap " (since Linux 2.6.25)"
+.IR /proc/ pid /pagemap " (since Linux 2.6.25)"
This file shows the mapping of each of the process's virtual pages
into physical page frames or swap area.
It contains one 64-bit value for each virtual page,
54\(en0
If the page is present in RAM (bit 63), then these bits
provide the page frame number, which can be used to index
-.IR /proc/kpageflags
+.I /proc/kpageflags
and
.IR /proc/kpagecount .
If the page is present in swap (bit 62),
used to encode the base-2 log of the page size.
.IP
To employ
-.IR /proc/[pid]/pagemap
+.IR /proc/ pid /pagemap
efficiently, use
-.IR /proc/[pid]/maps
+.IR /proc/ pid /maps
to determine which areas of memory are actually mapped and seek
to skip over unmapped regions.
.IP
The
-.IR /proc/[pid]/pagemap
+.IR /proc/ pid /pagemap
file is present only if the
.B CONFIG_PROC_PAGE_MONITOR
kernel configuration option is enabled.
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/personality " (since Linux 2.6.28)"
+.IR /proc/ pid /personality " (since Linux 2.6.28)"
.\" commit 478307230810d7e2a753ed220db9066dfdf88718
This read-only file exposes the process's execution domain, as set by
.BR personality (2).
check; see
.BR ptrace (2).
.TP
-.I /proc/[pid]/root
+.IR /proc/ pid /root
UNIX and Linux support the idea of a per-process root of the
filesystem, set by the
.BR chroot (2)
.IP
.\" The following was still true as at kernel 2.6.13
In a multithreaded process, the contents of the
-.I /proc/[pid]/root
+.IR /proc/ pid /root
symbolic link are not available if the main thread has already terminated
(typically by calling
.BR pthread_exit (3)).
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/projid_map " (since Linux 3.7)"
+.IR /proc/ pid /projid_map " (since Linux 3.7)"
.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d
See
.BR user_namespaces (7).
.TP
-.IR /proc/[pid]/seccomp " (Linux 2.6.12 to 2.6.22)"
+.IR /proc/ pid /seccomp " (Linux 2.6.12 to 2.6.22)"
This file can be used to read and change the process's
secure computing (seccomp) mode setting.
It contains the value 0 if the process is not in seccomp mode,
In Linux 2.6.23,
this file went away, to be replaced by the
.BR prctl (2)
-.BR PR_GET_SECCOMP
+.B PR_GET_SECCOMP
and
-.BR PR_SET_SECCOMP
+.B PR_SET_SECCOMP
operations (and later by
.BR seccomp (2)
and the
.I Seccomp
field in
-.IR /proc/[pid]/status ).
+.IR /proc/ pid /status ).
.\" FIXME Describe /proc/[pid]/sessionid
.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc
.\" CONFIG_AUDITSYSCALL
.\" Added in 2.6.9
.\" CONFIG_SCHEDSTATS
.TP
-.IR /proc/[pid]/setgroups " (since Linux 3.19)"
+.IR /proc/ pid /setgroups " (since Linux 3.19)"
See
.BR user_namespaces (7).
.TP
-.IR /proc/[pid]/smaps " (since Linux 2.6.14)"
+.IR /proc/ pid /smaps " (since Linux 2.6.14)"
This file shows memory consumption for each of the process's mappings.
(The
.BR pmap (1)
.IP
The first of these lines shows the same information as is displayed
for the mapping in
-.IR /proc/[pid]/maps .
+.IR /proc/ pid /maps .
The following lines show the size of the mapping,
the amount of the mapping that is currently resident in RAM ("Rss"),
the process's proportional share of this mapping ("Pss"),
uw - userfaultfd wprotect pages tracking (since Linux 4.3)
.IP
The
-.IR /proc/[pid]/smaps
+.IR /proc/ pid /smaps
file is present only if the
.B CONFIG_PROC_PAGE_MONITOR
kernel configuration option is enabled.
.TP
-.IR /proc/[pid]/stack " (since Linux 2.6.29)"
+.IR /proc/ pid /stack " (since Linux 2.6.29)"
.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad
This file provides a symbolic trace of the function calls in this
process's kernel stack.
check; see
.BR ptrace (2).
.TP
-.I /proc/[pid]/stat
+.IR /proc/ pid /stat
Status information about the process.
This is used by
.BR ps (1).
This does not include pages
which have not been demand-loaded in, or which are swapped out.
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
below.
.TP
(25) \fIrsslim\fP \ %lu
(31) \fIsignal\fP \ %lu
The bitmap of pending signals, displayed as a decimal number.
Obsolete, because it does not provide information on real-time signals; use
-.I /proc/[pid]/status
+.IR /proc/ pid /status
instead.
.TP
(32) \fIblocked\fP \ %lu
The bitmap of blocked signals, displayed as a decimal number.
Obsolete, because it does not provide information on real-time signals; use
-.I /proc/[pid]/status
+.IR /proc/ pid /status
instead.
.TP
(33) \fIsigignore\fP \ %lu
The bitmap of ignored signals, displayed as a decimal number.
Obsolete, because it does not provide information on real-time signals; use
-.I /proc/[pid]/status
+.IR /proc/ pid /status
instead.
.TP
(34) \fIsigcatch\fP \ %lu
The bitmap of caught signals, displayed as a decimal number.
Obsolete, because it does not provide information on real-time signals; use
-.I /proc/[pid]/status
+.IR /proc/ pid /status
instead.
.TP
(35) \fIwchan\fP \ %lu \ [PT]
This is the "channel" in which the process is waiting.
It is the address of a location in the kernel where the process is sleeping.
The corresponding symbolic name can be found in
-.IR /proc/[pid]/wchan .
+.IR /proc/ pid /wchan .
.TP
(36) \fInswap\fP \ %lu
.\" nswap was added in 2.0
.BR waitpid (2).
.RE
.TP
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
Provides information about memory usage, measured in pages.
The columns are:
.IP
.in +4n
.EX
size (1) total program size
- (same as VmSize in \fI/proc/[pid]/status\fP)
+ (same as VmSize in \fI/proc/\fPpid\fI/status\fP)
resident (2) resident set size
- (inaccurate; same as VmRSS in \fI/proc/[pid]/status\fP)
+ (inaccurate; same as VmRSS in \fI/proc/\fPpid\fI/status\fP)
shared (3) number of resident shared pages
(i.e., backed by a file)
(inaccurate; same as RssFile+RssShmem in
- \fI/proc/[pid]/status\fP)
+ \fI/proc/\fPpid\fI/status\fP)
text (4) text (code)
.\" (not including libs; broken, includes data segment)
lib (5) library (unused since Linux 2.6; always 0)
Some of these values are inaccurate because
of a kernel-internal scalability optimization.
If accurate values are required, use
-.I /proc/[pid]/smaps
+.IR /proc/ pid /smaps
or
-.I /proc/[pid]/smaps_rollup
+.IR /proc/ pid /smaps_rollup
instead, which are much slower but provide accurate, detailed information.
.TP
-.I /proc/[pid]/status
+.IR /proc/ pid /status
Provides much of the information in
-.I /proc/[pid]/stat
+.IR /proc/ pid /stat
and
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
in a format that's easier for humans to parse.
Here's an example:
.IP
The fields are as follows:
.RS
.TP
-.IR Name
+.I Name
Command run by this process.
Strings longer than
.B TASK_COMM_LEN
(16) characters (including the terminating null byte) are silently truncated.
.TP
-.IR Umask
+.I Umask
Process umask, expressed in octal with a leading zero; see
.BR umask (2).
(Since Linux 4.7.)
.TP
-.IR State
+.I State
Current state of the process.
One of
"R (running)",
or
"X (dead)".
.TP
-.IR Tgid
+.I Tgid
Thread group ID (i.e., Process ID).
.TP
-.IR Ngid
+.I Ngid
NUMA group ID (0 if none; since Linux 3.13).
.TP
-.IR Pid
+.I Pid
Thread ID (see
.BR gettid (2)).
.TP
-.IR PPid
+.I PPid
PID of parent process.
.TP
-.IR TracerPid
+.I TracerPid
PID of process tracing this process (0 if not being traced).
.TP
.IR Uid ", " Gid
Real, effective, saved set, and filesystem UIDs (GIDs).
.TP
-.IR FDSize
+.I FDSize
Number of file descriptor slots currently allocated.
.TP
-.IR Groups
+.I Groups
Supplementary group list.
.TP
-.IR NStgid
+.I NStgid
Thread group ID (i.e., PID) in each of the PID namespaces of which
-.I [pid]
+.I pid
is a member.
The leftmost entry shows the value with respect to the PID namespace
of the process that mounted this procfs (or the root namespace
.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5
(Since Linux 4.1.)
.TP
-.IR NSpid
+.I NSpid
Thread ID in each of the PID namespaces of which
-.I [pid]
+.I pid
is a member.
The fields are ordered as for
.IR NStgid .
(Since Linux 4.1.)
.TP
-.IR NSpgid
+.I NSpgid
Process group ID in each of the PID namespaces of which
-.I [pid]
+.I pid
is a member.
The fields are ordered as for
.IR NStgid .
(Since Linux 4.1.)
.TP
-.IR NSsid
+.I NSsid
descendant namespace session ID hierarchy
Session ID in each of the PID namespaces of which
-.I [pid]
+.I pid
is a member.
The fields are ordered as for
.IR NStgid .
(Since Linux 4.1.)
.TP
-.IR VmPeak
+.I VmPeak
Peak virtual memory size.
.TP
-.IR VmSize
+.I VmSize
Virtual memory size.
.TP
-.IR VmLck
+.I VmLck
Locked memory size (see
.BR mlock (2)).
.TP
-.IR VmPin
+.I VmPin
Pinned memory size
.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18
(since Linux 3.2).
These are pages that can't be moved because something needs to
directly access physical memory.
.TP
-.IR VmHWM
+.I VmHWM
Peak resident set size ("high water mark").
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR VmRSS
+.I VmRSS
Resident set size.
Note that the value here is the sum of
.IR RssAnon ,
and
.IR RssShmem .
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR RssAnon
+.I RssAnon
Size of resident anonymous memory.
.\" commit bf9683d6990589390b5178dafe8fd06808869293
(since Linux 4.5).
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR RssFile
+.I RssFile
Size of resident file mappings.
.\" commit bf9683d6990589390b5178dafe8fd06808869293
(since Linux 4.5).
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR RssShmem
+.I RssShmem
Size of resident shared memory (includes System V shared memory,
mappings from
.BR tmpfs (5),
.IR VmData ", " VmStk ", " VmExe
Size of data, stack, and text segments.
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR VmLib
+.I VmLib
Shared library code size.
.TP
-.IR VmPTE
+.I VmPTE
Page table entries size (since Linux 2.6.10).
.TP
-.IR VmPMD
+.I VmPMD
.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479
Size of second-level page tables (added in Linux 4.0; removed in Linux 4.15).
.TP
-.IR VmSwap
+.I VmSwap
.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722
Swapped-out virtual memory size by anonymous private pages;
shmem swap usage is not included (since Linux 2.6.34).
This value is inaccurate; see
-.I /proc/[pid]/statm
+.IR /proc/ pid /statm
above.
.TP
-.IR HugetlbPages
+.I HugetlbPages
Size of hugetlb memory portions
.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e
(since Linux 4.4).
.TP
-.IR CoreDumping
+.I CoreDumping
Contains the value 1 if the process is currently dumping core,
and 0 if it is not
.\" commit c643401218be0f4ab3522e0c0a63016596d6e9ca
a process that is currently dumping core,
which could result in a corrupted core dump file.
.TP
-.IR Threads
+.I Threads
Number of threads in process containing this thread.
.TP
-.IR SigQ
+.I SigQ
This field contains two slash-separated numbers that relate to
queued signals for the real user ID of this process.
The first of these is the number of currently queued
signals for this real user ID, and the second is the
resource limit on the number of queued signals for this process
(see the description of
-.BR RLIMIT_SIGPENDING
+.B RLIMIT_SIGPENDING
in
.BR getrlimit (2)).
.TP
(see
.BR capabilities (7)).
.TP
-.IR CapBnd
+.I CapBnd
Capability bounding set, expressed in hexadecimal
(since Linux 2.6.26, see
.BR capabilities (7)).
.TP
-.IR CapAmb
+.I CapAmb
Ambient capability set, expressed in hexadecimal
(since Linux 4.3, see
.BR capabilities (7)).
.TP
-.IR NoNewPrivs
+.I NoNewPrivs
.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d
Value of the
.I no_new_privs
(since Linux 4.10, see
.BR prctl (2)).
.TP
-.IR Seccomp
+.I Seccomp
.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816
Seccomp mode of the process
(since Linux 3.8, see
2 means
.BR SECCOMP_MODE_FILTER .
This field is provided only if the kernel was built with the
-.BR CONFIG_SECCOMP
+.B CONFIG_SECCOMP
kernel configuration option enabled.
.TP
-.IR Speculation_Store_Bypass
+.I Speculation_Store_Bypass
.\" commit fae1fa0fc6cca8beee3ab8ed71d54f9a78fa3f64
Speculation flaw mitigation state
(since Linux 4.17, see
.BR prctl (2)).
.TP
-.IR Cpus_allowed
+.I Cpus_allowed
Hexadecimal mask of CPUs on which this process may run
(since Linux 2.6.24, see
.BR cpuset (7)).
.TP
-.IR Cpus_allowed_list
+.I Cpus_allowed_list
Same as previous, but in "list format"
(since Linux 2.6.26, see
.BR cpuset (7)).
.TP
-.IR Mems_allowed
+.I Mems_allowed
Mask of memory nodes allowed to this process
(since Linux 2.6.24, see
.BR cpuset (7)).
.TP
-.IR Mems_allowed_list
+.I Mems_allowed_list
Same as previous, but in "list format"
(since Linux 2.6.26, see
.BR cpuset (7)).
Number of voluntary and involuntary context switches (since Linux 2.6.23).
.RE
.TP
-.IR /proc/[pid]/syscall " (since Linux 2.6.27)"
+.IR /proc/ pid /syscall " (since Linux 2.6.27)"
.\" commit ebcb67341fee34061430f3367f2e507e52ee051b
This file exposes the system call number and argument registers for the
system call currently being executed by the process,
check; see
.BR ptrace (2).
.TP
-.IR /proc/[pid]/task " (since Linux 2.6.0)"
+.IR /proc/ pid /task " (since Linux 2.6.0)"
.\" Precisely: Linux 2.6.0-test6
This is a directory that contains one subdirectory
for each thread in the process.
The name of each subdirectory is the numerical thread ID
-.RI ( [tid] )
+.RI ( tid )
of the thread (see
.BR gettid (2)).
.IP
Within each of these subdirectories, there is a set of
files with the same names and contents as under the
-.I /proc/[pid]
+.IR /proc/ pid
directories.
For attributes that are shared by all threads, the contents for
each of the files under the
-.I task/[tid]
+.IR task/ tid
subdirectories will be the same as in the corresponding
file in the parent
-.I /proc/[pid]
+.IR /proc/ pid
directory
(e.g., in a multithreaded process, all of the
-.I task/[tid]/cwd
+.IR task/ tid /cwd
files will have the same value as the
-.I /proc/[pid]/cwd
+.IR /proc/ pid /cwd
file in the parent directory, since all of the threads in a process
share a working directory).
For attributes that are distinct for each thread,
the corresponding files under
-.I task/[tid]
+.IR task/ tid
may have different values (e.g., various fields in each of the
-.I task/[tid]/status
+.IR task/ tid /status
files may be different for each thread),
.\" in particular: "children" :/
or they might not exist in
-.I /proc/[pid]
+.IR /proc/ pid
at all.
.IP
.\" The following was still true as at kernel 2.6.13
In a multithreaded process, the contents of the
-.I /proc/[pid]/task
+.IR /proc/ pid /task
directory are not available if the main thread has already terminated
(typically by calling
.BR pthread_exit (3)).
.TP
-.IR /proc/[pid]/task/[tid]/children " (since Linux 3.5)"
+.IR /proc/ pid /task/ tid /children " (since Linux 3.5)"
.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7
A space-separated list of child tasks of this task.
Each child task is represented by its TID.
.B CONFIG_PROC_CHILDREN
option.
.TP
-.IR /proc/[pid]/timers " (since Linux 3.10)"
+.IR /proc/ pid /timers " (since Linux 3.10)"
.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5
.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0
A list of the POSIX timers for this process.
rather, it is the same kernel-internal ID that is available via the
.I si_timerid
field of the
-.IR siginfo_t
+.I siginfo_t
structure (see
.BR sigaction (2)).
.TP
.I ClockID
This field identifies the clock that the timer uses for measuring time.
For most clocks, this is a number that matches one of the user-space
-.BR CLOCK_*
+.B CLOCK_*
constants exposed via
.IR <time.h> .
.B CLOCK_PROCESS_CPUTIME_ID
This file is available only when the kernel was configured with
.BR CONFIG_CHECKPOINT_RESTORE .
.TP
-.IR /proc/[pid]/timerslack_ns " (since Linux 4.6)"
+.IR /proc/ pid /timerslack_ns " (since Linux 4.6)"
.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319
.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e
This file exposes the process's "current" timer slack value,
Writing 0 to this file resets the "current" timer slack to the
"default" timer slack value.
For further details, see the discussion of
-.BR PR_SET_TIMERSLACK
+.B PR_SET_TIMERSLACK
in
.BR prctl (2).
.IP
.B CAP_SYS_NICE
capability is required to access this file.
.TP
-.IR /proc/[pid]/uid_map " (since Linux 3.5)"
+.IR /proc/ pid /uid_map " (since Linux 3.5)"
See
.BR user_namespaces (7).
.TP
-.IR /proc/[pid]/wchan " (since Linux 2.6.0)"
+.IR /proc/ pid /wchan " (since Linux 2.6.0)"
The symbolic name corresponding to the location
in the kernel where the process is sleeping.
.IP
check; see
.BR ptrace (2).
.TP
-.IR /proc/[tid]
+.IR /proc/ tid
There is a numerical subdirectory for each running thread
that is not a thread group leader
(i.e., a thread whose thread ID is not the same as its process ID);
exposing information about the thread with the thread ID
.IR tid .
The contents of these directories are the same as the corresponding
-.IR /proc/[pid]/task/[tid]
+.IR /proc/ pid /task/ tid
directories.
.IP
The
-.I /proc/[tid]
+.IR /proc/ tid
subdirectories are
.I not
visible when iterating through
which these zones are split.
The size in bytes of a certain order is given by the formula:
.IP
- (2^order)\ *\ PAGE_SIZE
+.in +4n
+.EX
+(2^order)\ *\ PAGE_SIZE
+.EE
+.in
.IP
The binary buddy allocator algorithm inside the kernel will split
one chunk into two chunks of a smaller order (thus with half the
.I Documentation/DocBook
before 4.10;
the documentation can be built using a command such as
-.IR "make htmldocs"
+.I make htmldocs
in the root directory of the kernel source tree).
.TP
.I /proc/cpuinfo
This file contains a 64-bit inode number of
the memory cgroup each page is charged to,
indexed by page frame number (see the discussion of
-.IR /proc/[pid]/pagemap ).
+.IR /proc/ pid /pagemap ).
.IP
The
-.IR /proc/kpagecgroup
+.I /proc/kpagecgroup
file is present only if the
.B CONFIG_MEMCG
kernel configuration option is enabled.
This file contains a 64-bit count of the number of
times each physical page frame is mapped,
indexed by page frame number (see the discussion of
-.IR /proc/[pid]/pagemap ).
+.IR /proc/ pid /pagemap ).
.IP
The
-.IR /proc/kpagecount
+.I /proc/kpagecount
file is present only if the
.B CONFIG_PROC_PAGE_MONITOR
kernel configuration option is enabled.
.IR /proc/kpageflags " (since Linux 2.6.25)"
This file contains 64-bit masks corresponding to each physical page frame;
it is indexed by page frame number (see the discussion of
-.IR /proc/[pid]/pagemap ).
+.IR /proc/ pid /pagemap ).
The bits are as follows:
.IP
0 - KPF_LOCKED
.BR KPF_RECLAIM ,
.BR KPF_BUDDY ,
and
-.BR KPF_LOCKED
+.B KPF_LOCKED
did not report correctly.
.IP
The
-.IR /proc/kpageflags
+.I /proc/kpageflags
file is present only if the
.B CONFIG_PROC_PAGE_MONITOR
kernel configuration option is enabled.
.IR DirectMap4M " %lu (since Linux 2.6.27)"
Number of bytes of RAM linearly mapped by kernel in 4 MB pages.
(x86 with
-.BR CONFIG_X86_64
+.B CONFIG_X86_64
or
-.BR CONFIG_X86_PAE
+.B CONFIG_X86_PAE
enabled.)
.TP
.IR DirectMap2M " %lu (since Linux 2.6.27)"
Number of bytes of RAM linearly mapped by kernel in 2 MB pages.
(x86 with neither
-.BR CONFIG_X86_64
+.B CONFIG_X86_64
nor
-.BR CONFIG_X86_PAE
+.B CONFIG_X86_PAE
enabled.)
.TP
.IR DirectMap1G " %lu (since Linux 2.6.27)"
(x86 with
-.BR CONFIG_X86_64
+.B CONFIG_X86_64
and
.B CONFIG_X86_DIRECT_GBPAGES
enabled.)
.BR network_namespaces (7)).
Thus, since Linux 2.6.25,
.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c
-.IR /proc/net
+.I /proc/net
is a symbolic link to the directory
.IR /proc/self/net ,
which contains the same files and directories as listed below.
.IR Type :
the socket type.
For
-.BR SOCK_STREAM
+.B SOCK_STREAM
sockets, this is 0001; for
-.BR SOCK_DGRAM
+.B SOCK_DGRAM
sockets, it is 0002; and for
-.BR SOCK_SEQPACKET
+.B SOCK_SEQPACKET
sockets, it is 0005.
.TP
.IR St :
Writing (e.g., an empty string) to this file resets the profiling counters;
on some architectures,
writing a binary integer "profiling multiplier" of size
-.IR sizeof(int)
+.I sizeof(int)
sets the profiling interrupt frequency.
.TP
.I /proc/scsi
is already a device known on this address or the address is invalid, an
error will be returned.
.TP
-.I /proc/scsi/[drivername]
-\fI[drivername]\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740,
+.IR /proc/scsi/ drivername
+\fIdrivername\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740,
aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic,
scsi_debug, seagate, t128, u15\-24f, ultrastore, or wd7000.
These directories show up for all drivers that registered at least one
.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0
The amount of time, measured in units of
USER_HZ (1/100ths of a second on most architectures, use
-.IR sysconf(_SC_CLK_TCK)
+.I sysconf(_SC_CLK_TCK)
to obtain the right value),
.\" 1024 on Alpha and ia64
that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line)
.I /proc/sys/fs/binfmt_misc
Documentation for files in this directory can be found
in the Linux kernel source in the file
-.IR Documentation/admin\-guide/binfmt\-misc.rst
+.I Documentation/admin\-guide/binfmt\-misc.rst
(or in
-.IR Documentation/binfmt_misc.txt
+.I Documentation/binfmt_misc.txt
on older kernels).
.TP
.IR /proc/sys/fs/dentry\-state " (since Linux 2.2)"
This file contains information about the status of the
directory cache (dcache).
The file contains six numbers,
-.IR nr_dentry ", " nr_unused ", " age_limit " (age in seconds),"
+.IR nr_dentry ,
+.IR nr_unused ,
+.I age_limit
+(age in seconds),
.I want_pages
(pages requested by system) and two dummy values.
.RS
.IR /proc/sys/fs/nr_open " (since Linux 2.6.25)"
.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b
This file imposes a ceiling on the value to which the
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
resource limit can be raised (see
.BR getrlimit (2)).
This ceiling is enforced for both unprivileged and privileged process.
The default value in this file is 1048576.
(Before Linux 2.6.25, the ceiling for
-.BR RLIMIT_NOFILE
+.B RLIMIT_NOFILE
was hard-coded to the same value.)
.TP
.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid
.RS
.IP * 3
The calling process has the
-.BR CAP_FOWNER
+.B CAP_FOWNER
capability in its user namespace
and the file UID has a mapping in the namespace.
.IP *
.IP
A system call that fails to follow a symbolic link
because of the above restrictions returns the error
-.BR EACCES
+.B EACCES
in
.IR errno .
.IP
the value in this file determines whether core dump files are
produced for set-user-ID or otherwise protected/tainted binaries.
The "dumpable" setting also affects the ownership of files in a process's
-.IR /proc/[pid]
+.IR /proc/ pid
directory, as described above.
.IP
Three different integer values can be specified:
.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant)
From Linux 2.6.27 to 3.18,
this file was used to control recomputing of the value in
-.IR /proc/sys/kernel/msgmni
+.I /proc/sys/kernel/msgmni
upon the addition or removal of memory or upon IPC namespace creation/removal.
Echoing "1" into this file enabled
.I msgmni
was 1.
.IP
Since Linux 3.19, the content of this file has no effect (because
-.IR msgmni
+.I msgmni
.\" FIXME Must document the 3.19 'msgmni' changes.
defaults to near the maximum value possible),
and reads from this file always return the value "0".
Since Linux 3.4,
.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8
only users with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability may change the value in this file.
.TP
.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname
is pruned
each time the system hits the idle loop.
.TP
-.IR /proc/sys/kernel/keys/*
+.I /proc/sys/kernel/keys/*
This directory contains various files that define parameters and limits
for the key-management facility.
These files are described in
If the value is 1, kernel pointers printed using the
.I %pK
format specifier will be replaced with zeros unless the user has the
-.BR CAP_SYSLOG
+.B CAP_SYSLOG
capability.
If the value is 2, kernel pointers printed using the
.I %pK
Since Linux 3.4,
.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8
only users with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability can change the value in this file.
.TP
.I /proc/sys/kernel/l2cr
(Only in kernels up to and including 2.6.7.)
This file shows the number of POSIX real-time signals currently queued.
.TP
-.IR /proc/[pid]/sched_autogroup_enabled " (since Linux 2.6.38)"
+.IR /proc/ pid /sched_autogroup_enabled " (since Linux 2.6.38)"
.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a
See
.BR sched (7).
.I /proc/sys/kernel/version
This file contains a string such as:
.IP
- #5 Wed Feb 25 21:49:24 MET 1998
+.in +4n
+.EX
+#5 Wed Feb 25 21:49:24 MET 1998
+.EE
+.in
.IP
The "#5" means that
this is the fifth kernel built from this source base and the
.IP
To free pagecache, use:
.IP
- echo 1 > /proc/sys/vm/drop_caches
+.in +4n
+.EX
+echo 1 > /proc/sys/vm/drop_caches
+.EE
+.in
.IP
To free dentries and inodes, use:
.IP
- echo 2 > /proc/sys/vm/drop_caches
+.in +4n
+.EX
+echo 2 > /proc/sys/vm/drop_caches
+.EE
+.in
.IP
To free pagecache, dentries, and inodes, use:
.IP
- echo 3 > /proc/sys/vm/drop_caches
+.in +4n
+.EX
+echo 3 > /proc/sys/vm/drop_caches
+.EE
+.in
.IP
Because writing to this file is a nondestructive operation and dirty objects
are not freeable, the
If a process has a filesystem group ID or any supplementary group ID that
matches this group ID,
then it can make huge-page allocations without holding the
-.BR CAP_IPC_LOCK
+.B CAP_IPC_LOCK
capability; see
.BR memfd_create (2),
.BR mmap (2),
virtual memory size, resident set size,
the CPU that the task is scheduled on,
oom_adj score (see the description of
-.IR /proc/[pid]/oom_adj ),
+.IR /proc/ pid /oom_adj ),
and command name.
This is helpful to determine why the OOM-killer was invoked
and to identify the rogue task that caused it.
.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)"
.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7
This writable file provides an alternative to
-.IR /proc/sys/vm/overcommit_ratio
+.I /proc/sys/vm/overcommit_ratio
for controlling the
.I CommitLimit
when
-.IR /proc/sys/vm/overcommit_memory
+.I /proc/sys/vm/overcommit_memory
has the value 2.
It allows the amount of memory overcommitting to be specified as
an absolute value (in kB),
rather than as a percentage, as is done with
.IR overcommit_ratio .
This allows for finer-grained control of
-.IR CommitLimit
+.I CommitLimit
on systems with extremely large memory sizes.
.IP
Only one of
-.IR overcommit_kbytes
+.I overcommit_kbytes
or
-.IR overcommit_ratio
+.I overcommit_ratio
can have an effect:
if
-.IR overcommit_kbytes
+.I overcommit_kbytes
has a nonzero value, then it is used to calculate
.IR CommitLimit ,
otherwise
-.IR overcommit_ratio
+.I overcommit_ratio
is used.
Writing a value to either of these files causes the
value in the other file to be set to zero.
.IR /proc/meminfo )
is calculated as
.IP
- CommitLimit = (total_RAM \- total_huge_TLB) *
- overcommit_ratio / 100 + total_swap
+.in +4n
+.EX
+CommitLimit = (total_RAM \- total_huge_TLB) *
+ overcommit_ratio / 100 + total_swap
+.EE
+.in
.IP
where:
.RS 12
.I CommitLimit
is instead calculated as:
.IP
- CommitLimit = overcommit_kbytes + total_swap
+.in +4n
+.EX
+CommitLimit = overcommit_kbytes + total_swap
+.EE
+.in
.IP
See also the description of
-.IR /proc/sys/vm/admin_reserve_kbytes
+.I /proc/sys/vm/admin_reserve_kbytes
and
.IR /proc/sys/vm/user_reserve_kbytes .
.TP
1 and 2 are for failover of clustering.
Select either according to your policy of failover.
.TP
-.IR /proc/sys/vm/swappiness
+.I /proc/sys/vm/swappiness
.\" The following is from Documentation/sysctl/vm.txt
The value in this file controls how aggressively the kernel will swap
memory pages.
This is intended to prevent a user from starting a single memory hogging
process, such that they cannot recover (kill the hog).
The value in this file has an effect only when
-.IR /proc/sys/vm/overcommit_memory
+.I /proc/sys/vm/overcommit_memory
is set to 2 ("overcommit never" mode).
In this case, the system reserves an amount of memory that is the minimum
of [3% of current process size,
.I /proc
filesystem,
and is identical to the
-.I /proc/self/task/[tid]
+.IR /proc/self/task/ tid
directory named by the process thread ID
-.RI ( [tid] )
+.RI ( tid )
of the same thread.
.TP
.IR /proc/timer_list " (since Linux 2.6.21)"
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgsteal_direct_dma
+.I pgsteal_direct_dma
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgscan_kswapd_dma
+.I pgscan_kswapd_dma
.\" Linux 2.6.0 had pgscan
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgscan_kswapd_high
+.I pgscan_kswapd_high
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS
.\" and
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgscan_direct_dma
+.I pgscan_direct_dma
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgscan_direct_normal
+.I pgscan_direct_normal
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS .
.TP
-.IR pgscan_direct_high
+.I pgscan_direct_high
.\" Present only if the kernel was configured with
.\" .BR CONFIG_VM_EVENT_COUNTERS
.\" and
.\"
.\" Added ndots remark by Bernhard R. Link - debian bug #182886
.\"
-.TH RESOLV.CONF 5 2021-03-22 "" "Linux Programmer's Manual"
+.TH RESOLV.CONF 5 2021-03-22 GNU "Linux Programmer's Manual"
.UC 4
.SH NAME
resolv.conf \- resolver configuration file
\fBdebug\fP
.\" Since glibc 2.2?
Sets
-.BR RES_DEBUG
+.B RES_DEBUG
in
-.IR _res.options
+.I _res.options
(effective only if glibc was built with debug support; see
.BR resolver (3)).
.TP
response from a remote name server before retrying the
query via a different name server.
This may
-.BR not
+.B not
be the total time taken by any resolver API call and there is no
guarantee that a single resolver API call maps to a single timeout.
Measured in seconds,
the default is
-.BR RES_TIMEOUT
+.B RES_TIMEOUT
(currently 5, see \fI<resolv.h>\fP).
The value for this option is silently capped to 30.
.TP
query to its name servers before giving up and returning
an error to the calling application.
The default is
-.BR RES_DFLRETRY
+.B RES_DFLRETRY
(currently 2, see \fI<resolv.h>\fP).
The value for this option is silently capped to 5.
.TP
.B rotate
.\" Since glibc 2.2
Sets
-.BR RES_ROTATE
+.B RES_ROTATE
in
.IR _res.options ,
which causes round-robin selection of name servers from among those listed.
.B no\-check\-names
.\" since glibc 2.2
Sets
-.BR RES_NOCHECKNAME
+.B RES_NOCHECKNAME
in
.IR _res.options ,
which disables the modern BIND checking of incoming hostnames and
.B inet6
.\" Since glibc 2.2
Sets
-.BR RES_USE_INET6
+.B RES_USE_INET6
in
.IR _res.options .
This has the effect of trying an AAAA query before an A query inside the
.TP
.BR ip6\-bytestring " (since glibc 2.3.4 to 2.24)"
Sets
-.BR RES_USEBSTRING
+.B RES_USEBSTRING
in
.IR _res.options .
This causes reverse IPv6 lookups to be made using the bit-label format
.TP
.BR ip6\-dotint / no\-ip6\-dotint " (glibc 2.3.4 to 2.24)"
Clear/set
-.BR RES_NOIP6DOTINT
+.B RES_NOIP6DOTINT
in
.IR _res.options .
When this option is clear
.I ip6.arpa
zone by default.
These options are available in glibc versions up to 2.24, where
-.BR no\-ip6\-dotint
+.B no\-ip6\-dotint
is the default.
Since
-.BR ip6\-dotint
+.B ip6\-dotint
support long ago ceased to be available on the Internet,
these options were removed in glibc 2.25.
.TP
.BR edns0 " (since glibc 2.6)"
Sets
-.BR RES_USE_EDNS0
+.B RES_USE_EDNS0
in
.IR _res.options .
This enables support for the DNS extensions described in RFC\ 2671.
.TP
.BR single\-request " (since glibc 2.10)"
Sets
-.BR RES_SNGLKUP
+.B RES_SNGLKUP
in
.IR _res.options .
By default, glibc performs IPv4 and IPv6 lookups in parallel since
.TP
.BR single\-request\-reopen " (since glibc 2.9)"
Sets
-.BR RES_SNGLKUPREOP
+.B RES_SNGLKUPREOP
in
.IR _res.options .
The resolver uses the same socket for the A and AAAA requests.
.TP
.BR no\-tld\-query " (since glibc 2.14)"
Sets
-.BR RES_NOTLDQUERY
+.B RES_NOTLDQUERY
in
.IR _res.options .
This option causes
.TP
.BR use\-vc " (since glibc 2.14)"
Sets
-.BR RES_USEVC
+.B RES_USEVC
in
.IR _res.options .
This option forces the use of TCP for DNS resolutions.
.TP
.BR no\-reload " (since glibc 2.26)"
Sets
-.BR RES_NORELOAD
+.B RES_NORELOAD
in
.IR _res.options .
This option disables automatic reloading of a changed configuration file.
.BR trust\-ad " (since glibc 2.31)"
.\" 446997ff1433d33452b81dfa9e626b8dccf101a4
Sets
-.BR RES_TRUSTAD
+.B RES_TRUSTAD
in
.IR _res.options .
This option controls the AD bit behavior of the stub resolver.
.\" %%%LICENSE_END
.\"
.\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI;
-.TH RPC 5 2021-03-22 "" "Linux Programmer's Manual"
+.TH RPC 5 2021-03-22 Linux "Linux Programmer's Manual"
.SH NAME
rpc \- RPC program number data base
.SH SYNOPSIS
.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt
.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu)
-.TH SHELLS 5 2020-06-09 "" "Linux Programmer's Manual"
+.TH SHELLS 5 2020-06-09 GNU "Linux Programmer's Manual"
.SH NAME
shells \- pathnames of valid login shells
.SH DESCRIPTION
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH SLABINFO 5 2021-03-22 "" "Linux Programmer's Manual"
+.TH SLABINFO 5 2021-03-22 Linux "Linux Programmer's Manual"
.SH NAME
slabinfo \- kernel slab allocator statistics
.SH SYNOPSIS
.IR limit ,
.IR batchcount ,
and
-.IR sharedfactor
+.I sharedfactor
are integers defining new values for the corresponding tunables.
The
.I limit
Only root can read and (if the kernel was configured with
.BR CONFIG_SLAB )
write the
-.IR /proc/slabinfo
+.I /proc/slabinfo
file.
.PP
The total amount of memory allocated to the SLAB/SLUB cache is shown in the
.BR slabtop (1)
.PP
The kernel source file
-.IR Documentation/vm/slub.txt
+.I Documentation/vm/slub.txt
and
.IR tools/vm/slabinfo.c .
(More precisely, the files and directories in
.B sysfs
provide a view of the
-.IR kobject
+.I kobject
structures defined internally within the kernel.)
The files under
.B sysfs
.I /sys
hierarchy.
.TP
-.IR /sys/block
+.I /sys/block
This subdirectory contains one symbolic link for each block device
that has been discovered on the system.
The symbolic links point to corresponding directories under
.IR /sys/devices .
.TP
-.IR /sys/bus
+.I /sys/bus
This directory contains one subdirectory for each of the bus types
in the kernel.
Inside each of these directories are two subdirectories:
.RS
.TP
-.IR devices
+.I devices
This subdirectory contains symbolic links to entries in
-.IR /sys/devices
+.I /sys/devices
that correspond to the devices discovered on this bus.
.TP
-.IR drivers
+.I drivers
This subdirectory contains one subdirectory for each device driver
that is loaded on this bus.
.RE
.TP
-.IR /sys/class
+.I /sys/class
This subdirectory contains a single layer of further subdirectories
for each of the device classes that have been registered on the system
(e.g., terminals, network devices, block devices, graphics devices,
Inside each of these subdirectories are symbolic links for each of the
devices in this class.
These symbolic links refer to entries in the
-.IR /sys/devices
+.I /sys/devices
directory.
.TP
-.IR /sys/class/net
+.I /sys/class/net
Each of the entries in this directory is a symbolic link
representing one of the real or virtual networking devices
that are visible in the network namespace of the process
that is accessing the directory.
Each of these symbolic links refers to entries in the
-.IR /sys/devices
+.I /sys/devices
directory.
.TP
-.IR /sys/dev
+.I /sys/dev
This directory contains two subdirectories
-.IR block /
+.I block/
and
.IR char/ ,
corresponding, respectively,
.B sysfs
directory for a device.
The symbolic links inside
-.IR /sys/dev
+.I /sys/dev
thus provide an easy way to look up the
.B sysfs
interface using the device IDs returned by a call to
.EE
.in
.TP
-.IR /sys/devices
+.I /sys/devices
This is a directory that contains a filesystem representation of
the kernel device tree,
which is a hierarchy of
.I device
structures within the kernel.
.TP
-.IR /sys/firmware
+.I /sys/firmware
This subdirectory contains interfaces for viewing and manipulating
firmware-specific objects and attributes.
.TP
-.IR /sys/fs
+.I /sys/fs
This directory contains subdirectories for some filesystems.
A filesystem will have a subdirectory here only if it chose
to explicitly create the subdirectory.
.TP
-.IR /sys/fs/cgroup
+.I /sys/fs/cgroup
This directory conventionally is used as a mount point for a
.BR tmpfs (5)
filesystem containing mount points for
.BR cgroups (7)
filesystems.
.TP
-.IR /sys/fs/smackfs
+.I /sys/fs/smackfs
The directory contains configuration files for the SMACK LSM.
See the kernel source file
.IR Documentation/admin\-guide/LSM/Smack.rst .
.TP
-.IR /sys/hypervisor
+.I /sys/hypervisor
[To be documented]
.TP
-.IR /sys/kernel
+.I /sys/kernel
This subdirectory contains various files and subdirectories that provide
information about the running kernel.
.TP
-.IR /sys/kernel/cgroup/
+.I /sys/kernel/cgroup/
For information about the files in this directory, see
.BR cgroups (7).
.TP
-.IR /sys/kernel/debug/tracing
+.I /sys/kernel/debug/tracing
Mount point for the
.I tracefs
filesystem used by the kernel's
see the kernel source file
.IR Documentation/trace/ftrace.txt .)
.TP
-.IR /sys/kernel/mm
+.I /sys/kernel/mm
This subdirectory contains various files and subdirectories that provide
information about the kernel's memory management subsystem.
.TP
-.IR /sys/kernel/mm/hugepages
+.I /sys/kernel/mm/hugepages
This subdirectory contains one subdirectory for each of the
huge page sizes that the system supports.
The subdirectory name indicates the huge page size (e.g.,
For further information, see the kernel source file
.IR Documentation/admin\-guide/mm/hugetlbpage.rst .
.TP
-.IR /sys/module
+.I /sys/module
This subdirectory contains one subdirectory
for each module that is loaded into the kernel.
The name of each directory is the name of the module.
[To be documented]
.RE
.TP
-.IR /sys/power
+.I /sys/power
[To be documented]
.SH VERSIONS
The
The kernel source file
.I Documentation/filesystems/sysfs.txt
and various other files in
-.IR Documentation/ABI
+.I Documentation/ABI
and
-.IR Documentation/*/sysfs.txt
+.I Documentation/*/sysfs.txt
.fi
.PP
The values in parentheses are suggested defaults which are used by the
-.IR curses
+.I curses
library, if the capabilities are missing.
.SH SEE ALSO
.BR ncurses (3),
.PP
The filesystem is automatically created when mounting
a filesystem with the type
-.BR tmpfs
+.B tmpfs
via a command such as the following:
.PP
.in +4n
option.
.PP
The
-.BR tmpfs
+.B tmpfs
filesystem supports extended attributes (see
.BR xattr (7)),
but
with the
.B MAP_SHARED
and
-.BR MAP_ANONYMOUS
+.B MAP_ANONYMOUS
flags).
This filesystem is available regardless of whether
the kernel was configured with the
A
.B tmpfs
filesystem mounted at
-.IR /dev/shm
+.I /dev/shm
is used for the implementation of POSIX shared memory
.RB ( shm_overview (7))
and POSIX semaphores
filesystems is shown in the
.I Shmem
field of
-.IR /proc/meminfo
+.I /proc/meminfo
and in the
.I shared
field displayed by
.BR mount (8)
.PP
The kernel source files
-.IR Documentation/filesystems/tmpfs.txt
+.I Documentation/filesystems/tmpfs.txt
and
.IR Documentation/admin\-guide/mm/transhuge.rst .
.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>.
.\" %%%LICENSE_END
.\"
-.TH TZFILE 5 2020-04-27 "" "Linux Programmer's Manual"
+.TH TZFILE 5 2020-04-27 Linux "Linux Programmer's Manual"
.SH NAME
tzfile \- timezone information
.SH DESCRIPTION
.I utmp
structures,
declared as follows in
-.IR <utmp.h>
+.I <utmp.h>
(note that this is only one of several definitions
around; details depend on the version of libc):
.PP
has no relation to
.B AF_VSOCK
and/or
-.BR AF_SMC
+.B AF_SMC
See
.UR https://www.ibm.com\:/support\:/knowledgecenter\:/en/SSB27U_6.4.0\:/com.ibm.zvm.v640.hcpb4\:/iucv.htm
.I IUCV protocol overview
This field is a structure that specifies how the caller is
to be notified when the asynchronous I/O operation completes.
Possible values for
-.IR aio_sigevent.sigev_notify
+.I aio_sigevent.sigev_notify
are
.BR SIGEV_NONE ,
.BR SIGEV_SIGNAL ,
.\" environment cannot be performed atomically then it is also possible that
.\" the environment encountered is internally inconsistent.
.TP
-.IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
-.IR MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
+.I MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
+.I MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe
functions are not safe to call in a multithreaded programs.
.\" functions are not
.\" safe to call within the safety contexts described above.
is major 8, minor 3, so you could use 'root=0x803' as an
alternative.)
.TP
-.BR "'rootdelay='"
+.B 'rootdelay='
This parameter sets the delay (in seconds) to pause before attempting
to mount the root filesystem.
.TP
-.BR "'rootflags=...'"
+.B 'rootflags=...'
This parameter sets the mount option string for the root filesystem
(see also
.BR fstab (5)).
.TP
-.BR "'rootfstype=...'"
+.B 'rootfstype=...'
The 'rootfstype' option tells the kernel to mount the root filesystem as
if it where of the type specified.
This can be useful (for example) to
print messages logged at level
.BR KERN_DEBUG .
The console loglevel can also be set on a booted system via the
-.IR /proc/sys/kernel/printk
+.I /proc/sys/kernel/printk
file (described in
.BR syslog (2)),
the
These days ram disks use the buffer cache, and grow dynamically.
For a lot of information on the current ramdisk
setup, see the kernel source file
-.IR Documentation/blockdev/ramdisk.txt
+.I Documentation/blockdev/ramdisk.txt
.RI ( Documentation/ramdisk.txt
in older kernels).
.IP
values.
This is not recommended, as it is rather complex.
It is described in the Linux kernel source file
-.IR Documentation/sound/oss/README.OSS
+.I Documentation/sound/oss/README.OSS
.RI ( drivers/sound/Readme.linux
in older kernel versions).
It accepts
.IP
This capability was added in Linux 5.8 to separate out
BPF functionality from the overloaded
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.BR CAP_CHECKPOINT_RESTORE " (since Linux 5.9)"
.\" prctl_set_mm_map().
.IP *
read the contents of the symbolic links in
-.IR /proc/[pid]/map_files
+.IR /proc/ pid /map_files
for other processes.
.RE
.PD
.IP
This capability was added in Linux 5.9 to separate out
checkpoint/restore functionality from the overloaded
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
.TP
.B CAP_CHOWN
to set the following socket options:
.BR SO_DEBUG ,
.BR SO_MARK ,
-.BR SO_PRIORITY
+.B SO_PRIORITY
(for a priority outside the range 0 to 6),
.BR SO_RCVBUFFORCE ,
and
.IP
This capability was added in Linux 5.8 to separate out
performance monitoring functionality from the overloaded
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability.
See also the kernel source file
.IR Documentation/admin\-guide/perf\-security.rst .
perform privileged
.BR syslog (2)
operations (since Linux 2.6.37,
-.BR CAP_SYSLOG
+.B CAP_SYSLOG
should be used to permit such operations);
.IP *
perform
command;
.IP *
access the same checkpoint/restore functionality that is governed by
-.BR CAP_CHECKPOINT_RESTORE
+.B CAP_CHECKPOINT_RESTORE
(but the latter, weaker capability is preferred for accessing
that functionality).
.IP *
perform the same BPF operations as are governed by
-.BR CAP_BPF
+.B CAP_BPF
(but the latter, weaker capability is preferred for accessing
that functionality).
.IP *
employ the same performance monitoring mechanisms as are governed by
-.BR CAP_PERFMON
+.B CAP_PERFMON
(but the latter, weaker capability is preferred for accessing
that functionality).
.IP *
perform privileged
.BR ioctl (2)
operations on the
-.IR /dev/random
+.I /dev/random
device (see
.BR random (4));
.IP *
perform administrative operations on many device drivers;
.IP *
modify autogroup nice values by writing to
-.IR /proc/[pid]/autogroup
+.IR /proc/ pid /autogroup
(see
.BR sched (7)).
.RE
.IR /proc/bus/pci ;
.IP *
open
-.IR /dev/mem
+.I /dev/mem
and
.IR /dev/kmem ;
.IP *
command;
.IP *
use
-.BR F_SETPIPE_SZ
+.B F_SETPIPE_SZ
to increase the capacity of a pipe above the limit specified by
.IR /proc/sys/fs/pipe\-max\-size ;
.IP *
operation;
.IP *
set
-.IR /proc/[pid]/oom_score_adj
+.IR /proc/ pid /oom_score_adj
to a value lower than the value last set by a process with
.BR CAP_SYS_RESOURCE .
.RE
View kernel addresses exposed via
.I /proc
and other interfaces when
-.IR /proc/sys/kernel/kptr_restrict
+.I /proc/sys/kernel/kptr_restrict
has the value 1.
(See the discussion of the
.I kptr_restrict
If the new feature is useless without these other features,
you should use the same capability as the other features.
.IP *
-.IR Don't
+.I Don't
choose
.B CAP_SYS_ADMIN
if you can possibly avoid it!
a new capability for your feature,
don't make or name it as a "single-use" capability.
Thus, for example, the addition of the highly specific
-.BR CAP_SYS_PACCT
+.B CAP_SYS_PACCT
was probably a mistake.
Instead, try to identify and name your new capability as a broader
silo into which other related future use cases might fit.
Each thread has the following capability sets containing zero or more
of the above capabilities:
.TP
-.IR Permitted
+.I Permitted
This is a limiting superset for the effective
capabilities that the thread may assume.
It is also a limiting superset for the capabilities that
either a set-user-ID-root program, or
a program whose associated file capabilities grant that capability).
.TP
-.IR Inheritable
+.I Inheritable
This is a set of capabilities preserved across an
.BR execve (2).
Inheritable capabilities remain inheritable when executing any program,
programs with elevated capabilities should consider using
ambient capabilities, described below.
.TP
-.IR Effective
+.I Effective
This is the set of capabilities used by the kernel to
perform permission checks for the thread.
.TP
named
.IR "security.capability" .
Writing to this extended attribute requires the
-.BR CAP_SETFCAP
+.B CAP_SETFCAP
capability.
The file capability sets,
in conjunction with the capability sets of the thread,
and not directly visible to user-space applications.
To date, the following versions are supported:
.TP
-.BR VFS_CAP_REVISION_1
+.B VFS_CAP_REVISION_1
This was the original file capability implementation,
which supported 32-bit masks for file capabilities.
.TP
than the one from which the underlying filesystem was mounted.)
.IP (2)
The thread has the
-.BR CAP_SETFCAP
+.B CAP_SETFCAP
capability over the file inode,
meaning that (a) the thread has the
.B CAP_SETFCAP
the writer's user namespace.
.PP
When a
-.BR VFS_CAP_REVISION_3
+.B VFS_CAP_REVISION_3
.I security.capability
extended attribute is created, the root user ID of the creating thread's
user namespace is saved in the extended attribute.
.B SECBIT_NO_CAP_AMBIENT_RAISE
Setting this flag disallows raising ambient capabilities via the
.BR prctl (2)
-.BR PR_CAP_AMBIENT_RAISE
+.B PR_CAP_AMBIENT_RAISE
operation.
.PP
Each of the above "base" flags has a companion "locked" flag.
.B CAP_SETPCAP
capability is required to modify the flags.
Note that the
-.BR SECBIT_*
+.B SECBIT_*
constants are available only after including the
.I <linux/securebits.h>
header file.
the executing process regardless of which user namespace it resides in,
only privileged processes are permitted to associate capabilities with a file.
Here, "privileged" means a process that has the
-.BR CAP_SETFCAP
+.B CAP_SETFCAP
capability in the user namespace where the filesystem was mounted
(normally the initial user namespace).
This limitation renders file capabilities useless for certain use cases.
but also the namespace root user ID.
.PP
As with a binary that has
-.BR VFS_CAP_REVISION_2
+.B VFS_CAP_REVISION_2
file capabilities, a binary with
-.BR VFS_CAP_REVISION_3
+.B VFS_CAP_REVISION_3
file capabilities confers capabilities to a process during
.BR execve ().
However, capabilities are conferred only if the binary is executed by
kernel configuration option.
.PP
The
-.I /proc/[pid]/task/TID/status
+.IR /proc/ pid /task/TID/status
file can be used to view the capability sets of a thread.
The
-.I /proc/[pid]/status
+.IR /proc/ pid /status
file shows the capability sets of a process's main thread.
Before Linux 3.8, nonexistent capabilities were shown as being
enabled (1) in these sets.
capability can manipulate the capabilities of threads other than itself.
However, this is only theoretically possible,
since no thread ever has
-.BR CAP_SETPCAP
+.B CAP_SETPCAP
in either of these cases:
.IP * 2
In the pre-2.6.25 implementation the system-wide capability bounding set,
Cgroup namespaces virtualize the view of a process's cgroups (see
.BR cgroups (7))
as seen via
-.IR /proc/[pid]/cgroup
+.IR /proc/ pid /cgroup
and
-.IR /proc/[pid]/mountinfo .
+.IR /proc/ pid /mountinfo .
.PP
Each cgroup namespace has its own set of cgroup root directories.
These root directories are the base points for the relative
locations displayed in the corresponding records in the
-.IR /proc/[pid]/cgroup
+.IR /proc/ pid /cgroup
file.
When a process creates a new cgroup namespace using
.BR clone (2)
or
.BR unshare (2)
with the
-.BR CLONE_NEWCGROUP
+.B CLONE_NEWCGROUP
flag, its current
cgroups directories become the cgroup root directories
of the new namespace.
and the cgroups version 2 unified hierarchy.)
.PP
When reading the cgroup memberships of a "target" process from
-.IR /proc/[pid]/cgroup ,
+.IR /proc/ pid /cgroup ,
the pathname shown in the third field of each record will be
relative to the reading process's root directory
for the corresponding cgroup hierarchy.
From the new shell started by
.BR unshare (1),
we then inspect the
-.IR /proc/[pid]/cgroup
+.IR /proc/ pid /cgroup
files of, respectively, the new shell,
a process that is in the initial cgroup namespace
.RI ( init ,
Thus, the new shell's cgroup membership is displayed as \(aq/\(aq.)
.PP
However, when we look in
-.IR /proc/self/mountinfo
+.I /proc/self/mountinfo
we see the following anomaly:
.PP
.in +4n
.IR X ,
also owned by user ID 9000,
that is namespaced under the cgroup
-.IR /cg/1/2
+.I /cg/1/2
(i.e.,
.I X
was placed in a new cgroup namespace via
or
.BR unshare (2)
with the
-.BR CLONE_NEWCGROUP
+.B CLONE_NEWCGROUP
flag).
.RE
.IP
In the absence of cgroup namespacing, because the cgroup directory
-.IR /cg/1
+.I /cg/1
is owned (and writable) by UID 9000 and process
.I X
is also owned by user ID 9000, process
.I X
would be able to modify the contents of cgroups files
(i.e., change cgroup settings) not only in
-.IR /cg/1/2
+.I /cg/1/2
but also in the ancestor cgroup directory
.IR /cg/1 .
Namespacing process
-.IR X
+.I X
under the cgroup directory
.IR /cg/1/2 ,
in combination with suitable mount operations
accounting for the CPU time used by a cgroup,
and freezing and resuming execution of the processes in a cgroup.
Subsystems are sometimes also known as
-.IR "resource controllers"
+.I resource controllers
(or simply, controllers).
.PP
The cgroups for a controller are arranged in a
and management of the cgroup hierarchies became rather complex.
A longer description of these problems can be found in the kernel
source file
-.IR Documentation/admin\-guide/cgroup\-v2.rst
+.I Documentation/admin\-guide/cgroup\-v2.rst
(or
-.IR Documentation/cgroup\-v2.txt
+.I Documentation/cgroup\-v2.txt
in Linux 4.17 and earlier).
.PP
Because of the problems with the initial cgroups implementation
Each control group is represented by a directory, with each of its child
control cgroups represented as a child directory.
For instance,
-.IR /user/joe/1.session
+.I /user/joe/1.session
represents control group
.IR 1.session ,
which is a child of cgroup
.\"
.SS Mounting v1 controllers
The use of cgroups requires a kernel built with the
-.BR CONFIG_CGROUP
+.B CONFIG_CGROUP
option.
In addition, each of the v1 controllers has an associated
configuration option that must be set in order to employ that controller.
.PP
It is possible to comount multiple controllers against the same hierarchy.
For example, here the
-.IR cpu
+.I cpu
and
-.IR cpuacct
+.I cpuacct
controllers are comounted against a single hierarchy:
.PP
.in +4n
Each of the cgroups version 1 controllers is governed
by a kernel configuration option (listed below).
Additionally, the availability of the cgroups feature is governed by the
-.BR CONFIG_CGROUPS
+.B CONFIG_CGROUPS
kernel configuration option.
.TP
.IR cpu " (since Linux 2.6.24; " \fBCONFIG_CGROUP_SCHED\fP )
when a system is busy.
This does not limit a cgroup's CPU usage if the CPUs are not busy.
For further information, see
-.IR Documentation/scheduler/sched\-design\-CFS.rst
+.I Documentation/scheduler/sched\-design\-CFS.rst
(or
-.IR Documentation/scheduler/sched\-design\-CFS.txt
+.I Documentation/scheduler/sched\-design\-CFS.txt
in Linux 5.2 and earlier).
.IP
In Linux 3.2,
an upper limit on the CPU time allocated to the processes in a cgroup.
This upper limit applies even if there is no other competition for the CPU.
Further information can be found in the kernel source file
-.IR Documentation/scheduler/sched\-bwc.rst
+.I Documentation/scheduler/sched\-bwc.rst
(or
-.IR Documentation/scheduler/sched\-bwc.txt
+.I Documentation/scheduler/sched\-bwc.txt
in Linux 5.2 and earlier).
.TP
.IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP )
This provides accounting for CPU usage by groups of processes.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/cpuacct.rst
+.I Documentation/admin\-guide/cgroup\-v1/cpuacct.rst
(or
-.IR Documentation/cgroup\-v1/cpuacct.txt
+.I Documentation/cgroup\-v1/cpuacct.txt
in Linux 5.2 and earlier).
.TP
.IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP )
a specified set of CPUs and NUMA nodes.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst
+.I Documentation/admin\-guide/cgroup\-v1/cpusets.rst
(or
-.IR Documentation/cgroup\-v1/cpusets.txt
+.I Documentation/cgroup\-v1/cpusets.txt
in Linux 5.2 and earlier).
.
.TP
memory, and swap used by cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/memory.rst
+.I Documentation/admin\-guide/cgroup\-v1/memory.rst
(or
-.IR Documentation/cgroup\-v1/memory.txt
+.I Documentation/cgroup\-v1/memory.txt
in Linux 5.2 and earlier).
.TP
.IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP )
violate existing rules for the target or ancestor cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/devices.rst
+.I Documentation/admin\-guide/cgroup\-v1/devices.rst
(or
-.IR Documentation/cgroup\-v1/devices.txt
+.I Documentation/cgroup\-v1/devices.txt
in Linux 5.2 and earlier).
.TP
.IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP )
The
-.IR freezer
+.I freezer
cgroup can suspend and restore (resume) all processes in a cgroup.
Freezing a cgroup
.I /A
to be frozen.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/freezer\-subsystem.rst
+.I Documentation/admin\-guide/cgroup\-v1/freezer\-subsystem.rst
(or
-.IR Documentation/cgroup\-v1/freezer\-subsystem.txt
+.I Documentation/cgroup\-v1/freezer\-subsystem.txt
in Linux 5.2 and earlier).
.TP
.IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP )
leaving the cgroup, not to traffic arriving at the cgroup.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/net_cls.rst
+.I Documentation/admin\-guide/cgroup\-v1/net_cls.rst
(or
-.IR Documentation/cgroup\-v1/net_cls.txt
+.I Documentation/cgroup\-v1/net_cls.txt
in Linux 5.2 and earlier).
.TP
.IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP )
upper I/O rate limits on a device.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/blkio\-controller.rst
+.I Documentation/admin\-guide/cgroup\-v1/blkio\-controller.rst
(or
-.IR Documentation/cgroup\-v1/blkio\-controller.txt
+.I Documentation/cgroup\-v1/blkio\-controller.txt
in Linux 5.2 and earlier).
.TP
.IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP )
This allows priorities to be specified, per network interface, for cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/net_prio.rst
+.I Documentation/admin\-guide/cgroup\-v1/net_prio.rst
(or
-.IR Documentation/cgroup\-v1/net_prio.txt
+.I Documentation/cgroup\-v1/net_prio.txt
in Linux 5.2 and earlier).
.TP
.IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP )
This supports limiting the use of huge pages by cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/hugetlb.rst
+.I Documentation/admin\-guide/cgroup\-v1/hugetlb.rst
(or
-.IR Documentation/cgroup\-v1/hugetlb.txt
+.I Documentation/cgroup\-v1/hugetlb.txt
in Linux 5.2 and earlier).
.TP
.IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP )
in a cgroup (and its descendants).
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/pids.rst
+.I Documentation/admin\-guide/cgroup\-v1/pids.rst
(or
-.IR Documentation/cgroup\-v1/pids.txt
+.I Documentation/cgroup\-v1/pids.txt
in Linux 5.2 and earlier).
.TP
.IR rdma " (since Linux 4.11; " \fBCONFIG_CGROUP_RDMA\fP )
RDMA/IB-specific resources per cgroup.
.IP
Further information can be found in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v1/rdma.rst
+.I Documentation/admin\-guide/cgroup\-v1/rdma.rst
(or
-.IR Documentation/cgroup\-v1/rdma.txt
+.I Documentation/cgroup\-v1/rdma.txt
in Linux 5.2 and earlier).
.\"
.SS Creating cgroups and moving processes
Only one PID at a time should be written to this file.
.PP
Writing the value 0 to a
-.IR cgroup.procs
+.I cgroup.procs
file causes the writing process to be moved to the corresponding cgroup.
.PP
When writing a PID into the
.PP
Within a hierarchy, a process can be a member of exactly one cgroup.
Writing a process's PID to a
-.IR cgroup.procs
+.I cgroup.procs
file automatically removes it from the cgroup of
which it was previously a member.
.PP
and
.BR gettid (2))
to the
-.IR tasks
+.I tasks
file in a cgroup directory.
This file can be read to discover the set of threads
that are members of the cgroup.
a cgroup in the hierarchy becomes empty.
The pathname of the newly empty cgroup (relative to the cgroup mount point)
is provided as the sole command-line argument when the
-.IR release_agent
+.I release_agent
program is invoked.
The
-.IR release_agent
+.I release_agent
program might remove the cgroup directory,
or perhaps repopulate it with a process.
.PP
The default value of the
-.IR release_agent
+.I release_agent
file is empty, meaning that no release agent is invoked.
.PP
The content of the
.in
.PP
Whether or not the
-.IR release_agent
+.I release_agent
program is invoked when a particular cgroup becomes empty is determined
by the value in the
-.IR notify_on_release
+.I notify_on_release
file in the corresponding cgroup directory.
If this file contains the value 0, then the
-.IR release_agent
+.I release_agent
program is not invoked.
If it contains the value 1, the
-.IR release_agent
+.I release_agent
program is invoked.
The default value for this file in the root cgroup is 0.
At the time when a new cgroup is created,
The details are somewhat more subtle than this, and are described below.
.IP 3.
Active cgroups must be specified via the files
-.IR cgroup.controllers
+.I cgroup.controllers
and
.IR cgroup.subtree_control .
.IP 4.
controller has been removed.
.IP 5.
An improved mechanism for notification of empty cgroups is provided by the
-.IR cgroup.events
+.I cgroup.events
file.
.PP
For more changes, see the
-.IR Documentation/admin\-guide/cgroup\-v2.rst
+.I Documentation/admin\-guide/cgroup\-v2.rst
file in the kernel source
(or
-.IR Documentation/cgroup\-v2.txt
+.I Documentation/cgroup\-v2.txt
in Linux 4.17 and earlier).
.
.PP
it can in some cases be simpler to boot the system with
selected v1 controllers disabled.
To do this, specify the
-.IR cgroup_no_v1=list
+.I cgroup_no_v1=list
option on the kernel boot command line;
.I list
is a comma-separated list of the names of the controllers to disable,
.\"
.SS Cgroups v2 mount options
The following options
-.RI ( "mount \-o" )
+.RI ( mount\~\-o )
can be specified when mounting the group v2 filesystem:
.TP
.IR nsdelegate " (since Linux 4.15)"
.\"
.SS Cgroups v2 controllers
The following controllers, documented in the kernel source file
-.IR Documentation/admin\-guide/cgroup\-v2.rst
+.I Documentation/admin\-guide/cgroup\-v2.rst
(or
-.IR Documentation/cgroup\-v2.txt
+.I Documentation/cgroup\-v2.txt
in Linux 4.17 and earlier),
are supported in cgroups version 2:
.TP
.SS Cgroups v2 subtree control
Each cgroup in the v2 hierarchy contains the following two files:
.TP
-.IR cgroup.controllers
+.I cgroup.controllers
This read-only file exposes a list of the controllers that are
.I available
in this cgroup.
.TP
.I cgroup.subtree_control
This is a list of controllers that are
-.IR active
+.I active
.RI ( enabled )
in the cgroup.
The set of controllers in this file is a subset of the set in the
-.IR cgroup.controllers
+.I cgroup.controllers
of this cgroup.
The set of active controllers is modified by writing strings to this file
containing space-delimited controller names,
.PP
The following keys may appear in this file:
.TP
-.IR populated
+.I populated
The value of this key is either 1,
if this cgroup or any of its descendants has member processes,
or otherwise 0.
or 0 if it is not.
.PP
The
-.IR cgroup.events
+.I cgroup.events
file can be monitored, in order to receive notification when the value of
one of its keys changes.
Such monitoring can be done using
.BR inotify (7),
which notifies changes as
-.BR IN_MODIFY
+.B IN_MODIFY
events, or
.BR poll (2),
which notifies changes by returning the
and
.B POLLERR
bits in the
-.IR revents
+.I revents
field.
.\"
.SS Cgroup v2 release notification
Cgroups v2 provides a new mechanism for obtaining notification
when a cgroup becomes empty.
The cgroups v1
-.IR release_agent
+.I release_agent
and
-.IR notify_on_release
+.I notify_on_release
files are removed, and replaced by the
.I populated
key in the
-.IR cgroup.events
+.I cgroup.events
file.
This key either has the value 0,
meaning that the cgroup (and its descendants)
.PP
The cgroups v2 release-notification mechanism
offers the following advantages over the cgroups v1
-.IR release_agent
+.I release_agent
mechanism:
.IP * 3
It allows for cheaper notification,
since a single process can monitor multiple
-.IR cgroup.events
+.I cgroup.events
files (using the techniques described earlier).
By contrast, the cgroups v1 mechanism requires the expense of creating
a process for each notification.
.SS Cgroups v2 cgroup.stat file
.\" commit ec39225cca42c05ac36853d11d28f877fde5c42e
Each cgroup in the v2 hierarchy contains a read-only
-.IR cgroup.stat
+.I cgroup.stat
file (first introduced in Linux 4.14)
that consists of lines containing key-value pairs.
The following keys currently appear in this file:
.BR EAGAIN ).
.IP
Writing the string
-.IR """max"""
+.I """max"""
to this file means that no limit is imposed.
The default value in this file is
-.IR """max""" .
+.I """max""" .
.TP
.IR cgroup.max.descendants " (since Linux 4.14)"
.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1
.BR EAGAIN ).
.IP
Writing the string
-.IR """max"""
+.I """max"""
to this file means that no limit is imposed.
The default value in this file is
.IR """max""" .
and that there are not yet any child cgroups under that cgroup,
the ownership of the following is changed to the user ID of the delegatee:
.TP
-.IR /dlgt_grp
+.I /dlgt_grp
Changing the ownership of the root of the subtree means that any new
cgroups created under the subtree (and the files they contain)
will also be owned by the delegatee.
.TP
-.IR /dlgt_grp/cgroup.procs
+.I /dlgt_grp/cgroup.procs
Changing the ownership of this file means that the delegatee
can move processes into the root of the delegated subtree.
.TP
a domain subtree, but currently this serves no purpose,
since, as described below, it is not possible to move a thread between
domain cgroups by writing its thread ID to the
-.IR cgroup.threads
+.I cgroup.threads
file.)
.IP
In cgroups v1, the corresponding file that should instead be delegated is the
the resources that are distributed into the delegated subtree.
.PP
See also the discussion of the
-.IR /sys/kernel/cgroup/delegate
+.I /sys/kernel/cgroup/delegate
file in NOTES for information about further delegatable files in cgroups v2.
.PP
After the aforementioned steps have been performed,
.BR EPERM .
Processes inside the cgroup namespace can still write to delegatable
files in the root directory of the cgroup namespace such as
-.IR cgroup.procs
+.I cgroup.procs
and
.IR cgroup.subtree_control ,
and can create subhierarchy underneath the root directory.
.\"
.SS Cgroup delegation containment rules
Some delegation
-.IR "containment rules"
+.I containment rules
ensure that the delegatee can move processes between cgroups within the
delegated subtree,
but can't move processes from outside the delegated subtree into
the subtree or vice versa.
A nonprivileged process (i.e., the delegatee) can write the PID of
a "target" process into a
-.IR cgroup.procs
+.I cgroup.procs
file only if all of the following are true:
.IP * 3
The writer has write permission on the
.PP
Notwithstanding the initial design decision in cgroups v2,
there were use cases for certain controllers, notably the
-.IR cpu
+.I cpu
controller,
for which thread-level granularity of control was meaningful and useful.
To accommodate such use cases, Linux 4.14 added
Thread mode allows the following:
.IP * 3
The creation of
-.IR "threaded subtrees"
+.I threaded subtrees
in which the threads of a process may
be spread across cgroups inside the tree.
(A threaded subtree may contain multiple multithreaded processes.)
.IP *
The concept of
-.IR "threaded controllers",
+.IR "threaded controllers" ,
which can distribute resources across the cgroups in a threaded subtree.
.IP *
A relaxation of the "no internal processes rule",
the "type" of a cgroup.
This file contains one of the following type values:
.TP
-.I "domain"
+.I domain
This is a normal v2 cgroup that provides process-granularity control.
If a process is a member of this cgroup,
then all threads of the process are (by definition) in the same cgroup.
and provides the same behavior that was provided for
cgroups in the initial cgroups v2 implementation.
.TP
-.I "threaded"
+.I threaded
This cgroup is a member of a threaded subtree.
Threads can be added to this cgroup,
and controllers can be enabled for the cgroup.
.TP
-.I "domain threaded"
+.I domain threaded
This is a domain cgroup that serves as the root of a threaded subtree.
This cgroup type is also known as "threaded root".
.TP
-.I "domain invalid"
+.I domain invalid
This is a cgroup inside a threaded subtree
that is in an "invalid" state.
Processes can't be added to the cgroup,
and controllers can't be enabled for the cgroup.
The only thing that can be done with this cgroup (other than deleting it)
is to convert it to a
-.IR threaded
+.I threaded
cgroup by writing the string
-.IR """threaded"""
+.I """threaded"""
to the
.I cgroup.type
file.
The first pathway proceeds as follows:
.IP 1. 3
We write the string
-.IR """threaded"""
+.I """threaded"""
to the
.I cgroup.type
file of a cgroup
-.IR y/z
+.I y/z
that currently has the type
.IR domain .
This has the following effects:
.RS
.IP * 3
The type of the cgroup
-.IR y/z
+.I y/z
becomes
.IR threaded .
.IP *
(also known as the "threaded root").
.IP *
All other cgroups under
-.IR y
+.I y
that were not already of type
-.IR threaded
+.I threaded
(because they were inside already existing threaded subtrees
under the new threaded root)
are converted to type
.RE
.IP 2.
We write the string
-.IR """threaded"""
+.I """threaded"""
to each of the
-.IR "domain invalid"
+.I domain invalid
cgroups under
.IR y ,
in order to convert them to the type
.IR threaded .
As a consequence of this step, all threads under the threaded root
now have the type
-.IR threaded
+.I threaded
and the threaded subtree is now fully usable.
The requirement to write
-.IR """threaded"""
+.I """threaded"""
to each of these cgroups is somewhat cumbersome,
but allows for possible future extensions to the thread-mode model.
.PP
All of the descendant cgroups of
.I x
that were not already of type
-.IR threaded
+.I threaded
are converted to type
.IR "domain invalid" .
.RE
.IP 2.
As before, we make the threaded subtree usable by writing the string
-.IR """threaded"""
+.I """threaded"""
to each of the
-.IR "domain invalid"
+.I domain invalid
cgroups under
.IR y ,
in order to convert them to the type
file:
.IP * 3
Only the string
-.IR """threaded"""
+.I """threaded"""
may be written.
In other words, the only explicit transition that is possible is to convert a
.I domain
.IR threaded .
.IP *
The effect of writing
-.IR """threaded"""
+.I """threaded"""
depends on the current value in
.IR cgroup.type ,
as follows:
.RS
.IP \(bu 3
-.IR domain
+.I domain
or
.IR "domain threaded" :
start the creation of a threaded subtree
.IP *
No domain controllers may be enabled in
.IR x 's
-.IR cgroup.subtree_control
+.I cgroup.subtree_control
file.
.PP
If any of the above constraints is violated, then an attempt to write
-.IR """threaded"""
+.I """threaded"""
to a
-.IR cgroup.type
+.I cgroup.type
file fails with the error
.BR ENOTSUP .
.\"
.SS The """domain threaded""" cgroup type
According to the pathways described above,
the type of a cgroup can change to
-.IR "domain threaded"
+.I domain threaded
in either of the following cases:
.IP * 3
The string
-.IR """threaded"""
+.I """threaded"""
is written to a child cgroup.
.IP *
A threaded controller is enabled inside the cgroup and
a process is made a member of the cgroup.
.PP
A
-.IR "domain threaded"
+.I domain threaded
cgroup,
.IR x ,
can revert to the type
-.IR domain
+.I domain
if the above conditions no longer hold true\(emthat is, if all
.I threaded
child cgroups of
no longer has member processes.
.PP
When a
-.IR "domain threaded"
+.I domain threaded
cgroup
-.IR x
+.I x
reverts to the type
.IR domain :
.IP * 3
All
-.IR "domain invalid"
+.I domain invalid
descendants of
.I x
that are not in lower-level threaded subtrees revert to the type
(If there are realtime threads in nonroot cgroups, then a
.BR write (2)
of the string
-.IR """+cpu"""
+.I """+cpu"""
to the
.I cgroup.subtree_control
file fails with the error
.IP 4.
This field contains the value 1 if this controller is enabled,
or 0 if it has been disabled (via the
-.IR cgroup_disable
+.I cgroup_disable
kernel command-line boot parameter).
.RE
.TP
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
-.TH COMPLEX 7 2021-03-22 "" "Linux Programmer's Manual"
+.TH COMPLEX 7 2021-03-22 GNU "Linux Programmer's Manual"
.SH NAME
complex \- basics of complex mathematics
.SH SYNOPSIS
subset of its parent's.
.IP *
It can be marked
-.IR cpu_exclusive
+.I cpu_exclusive
only if its parent is.
.IP *
It can be marked
-.IR mem_exclusive
+.I mem_exclusive
only if its parent is.
.IP *
If it is
.BR migratepages (8),
.BR numactl (8)
.PP
-.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst
+.I Documentation/admin\-guide/cgroup\-v1/cpusets.rst
in the Linux kernel source tree
.\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8
(or
-.IR Documentation/cgroup\-v1/cpusets.txt
+.I Documentation/cgroup\-v1/cpusets.txt
before Linux 4.18, and
-.IR Documentation/cpusets.txt
+.I Documentation/cpusets.txt
before Linux 2.6.29)
.IR "controlling terminal" .
The controlling terminal is established when the session leader
first opens a terminal (unless the
-.BR O_NOCTTY
+.B O_NOCTTY
flag is specified when calling
.BR open (2)).
A terminal may be the controlling terminal of at most one session.
Only the foreground job may read from the terminal;
when a process in the background attempts to read from the terminal,
its process group is sent a
-.BR SIGTTIN
+.B SIGTTIN
signal, which suspends the job.
If the
-.BR TOSTOP
+.B TOSTOP
flag has been set for the terminal (see
.BR termios (3)),
then only the foreground job may write to the terminal;
writes from background job cause a
-.BR SIGTTOU
+.B SIGTTOU
signal to be generated, which suspends the job.
When terminal keys that generate a signal (such as the
.I interrupt
.BR F_GETOWN_EX ,
.BR F_SETOWN ,
and
-.BR F_SETOWN_EX
+.B F_SETOWN_EX
operations in
.BR fcntl (2).
.SS User and group identifiers
The filesystem user and group IDs are a Linux extension.
.SH NOTES
Various fields in the
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
file show the process credentials described above.
See
.BR proc (5)
.PP
The initial environment of the shell is populated in various ways,
such as definitions from
-.IR /etc/environment
+.I /etc/environment
that are processed by
.BR pam_env (8)
for all users at login time (on systems that employ
.BR pam (8)).
In addition, various shell initialization scripts, such as the system-wide
-.IR /etc/profile
+.I /etc/profile
script and per-user initializations script may include commands
that add variables to the shell's environment;
see the manual page of your preferred shell for details.
.PP
Bourne-style shells support the syntax
.PP
- NAME=value command
+.in +4n
+.EX
+NAME=value command
+.EE
+.in
.PP
to create an environment variable definition only in the scope
of the process that executes
.BR LC_MONETARY ,
.BR LC_NUMERIC ,
and
-.BR LC_TIME
+.B LC_TIME
(see
.BR locale (7)
for further details of the
-.BR LC_*
+.B LC_*
environment variables).
.TP
.B PATH
.IP *
.BR LD_LIBRARY_PATH ", " LD_PRELOAD ,
and other
-.BR LD_*
+.B LD_*
variables influence the behavior of the dynamic loader/linker.
See also
.BR ld.so (8).
The set of file descriptors that is being monitored via
an epoll file descriptor can be viewed via the entry for
the epoll file descriptor in the process's
-.IR /proc/[pid]/fdinfo
+.IR /proc/ pid /fdinfo
directory.
See
.BR proc (5)
.PP
The use of one of the flags
.BR FAN_REPORT_FID ,
-.BR FAN_REPORT_DIR_FID
+.B FAN_REPORT_DIR_FID
in
.BR fanotify_init (2)
influences what data structures are returned to the event listener for each
.B FAN_Q_OVERFLOW
The event queue exceeded the limit on number of events.
This limit can be overridden by specifying the
-.BR FAN_UNLIMITED_QUEUE
+.B FAN_UNLIMITED_QUEUE
flag when calling
.BR fanotify_init (2).
.TP
A file was closed.
This is a synonym for:
.IP
- FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
+.in +4n
+.EX
+FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
+.EE
+.in
.PP
To check for any move event, the following bit mask may be used:
.TP
A file or directory was moved.
This is a synonym for:
.IP
- FAN_MOVED_FROM | FAN_MOVED_TO
+.in +4n
+.EX
+FAN_MOVED_FROM | FAN_MOVED_TO
+.EE
+.in
.PP
The following bits may appear in
.I mask
.BR fanotify_mark (2)
for additional details.
The
-.BR FAN_ONDIR
+.B FAN_ONDIR
flag is reported in an event mask only if the fanotify group identifies
filesystem objects by file handles.
.PP
field value of
.BR FAN_EVENT_INFO_TYPE_FID .
When an fanotify file descriptor is created using the combination of
-.BR FAN_REPORT_FID
+.B FAN_REPORT_FID
and
.BR FAN_REPORT_DIR_FID ,
there may be two information records attached to the event:
The value of
.I len
is the size of the additional information record including the
-.IR fanotify_event_info_header
+.I fanotify_event_info_header
itself.
The total size of all additional information records is not expected
to be bigger than
(
-.IR event_len
+.I event_len
\-
-.IR metadata_len
+.I metadata_len
).
.TP
.I fsid
and
.BR FAN_MOVE ,
the
-.IR file_handle
+.I file_handle
identifies the modified directory and not the created/deleted/moved child
object.
If the value of
field is
.BR FAN_EVENT_INFO_TYPE_FID ,
the
-.IR file_handle
+.I file_handle
identifies the object correlated to the event.
If the value of
.I info_type
field is
.BR FAN_EVENT_INFO_TYPE_DFID ,
the
-.IR file_handle
+.I file_handle
identifies the directory object correlated to the event or the parent directory
of a non-directory object correlated to the event.
If the value of
field is
.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
the
-.IR file_handle
+.I file_handle
identifies the same directory object that would be reported with
-.BR FAN_EVENT_INFO_TYPE_DFID
+.B FAN_EVENT_INFO_TYPE_DFID
and the file handle is followed by a null terminated string that identifies the
name of a directory entry in that directory, or '.' to identify the directory
object itself.
This macro uses the length indicated in the
.I event_len
field of the metadata structure pointed to by
-.IR meta
+.I meta
to calculate the address of the next metadata structure that follows
.IR meta .
.I len
.I len
by the number of bytes in the metadata structure that
has been skipped over (i.e., it subtracts
-.IR meta\->event_len
+.I meta\->event_len
from
.IR len ).
.PP
to deny the file operation.
.PP
If access is denied, the requesting application call will receive an
-.BR EPERM
+.B EPERM
error.
Additionally, if the notification group has been created with the
.B FAN_ENABLE_AUDIT
.IP * 3
On Linux, a filesystem object may be accessible through multiple paths,
for example, a part of a filesystem may be remounted using the
-.IR \-\-bind
+.I \-\-bind
option of
.BR mount (8).
A listener that marked a mount will be notified only of events that were
First, though, a summary of a few details for the impatient:
.IP * 3
The macros that you most likely need to use in modern source code are
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
(for definitions from various versions of POSIX.1),
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
(for definitions from various versions of SUS),
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
(for GNU and/or Linux specific stuff), and
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(to get definitions that would normally be provided by default).
.IP *
Certain macros are defined with default values.
Full details of the defaults are given later in this man page.
.IP *
Defining
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value of 600 or greater produces the same effects as defining
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
with a value of 200112L or greater.
Where one sees
.IP
.in
.IP *
Defining
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value of 700 or greater produces the same effects as defining
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
with a value of 200809L or greater.
Where one sees
.IP
If
.B __STRICT_ANSI__
is not defined, or
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
is defined with a value greater than or equal to 500
.I and
neither
.RE
.IP
In addition, defining
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value of 500 or greater produces the same effects as defining
.BR _XOPEN_SOURCE_EXTENDED .
.TP
with a value of 500 or more also produces the same effect as defining
.BR _XOPEN_SOURCE_EXTENDED .
Use of
-.BR _XOPEN_SOURCE_EXTENDED
+.B _XOPEN_SOURCE_EXTENDED
in new source code should be avoided.
.IP
Since defining
(The primary change in C95 was support for international character sets.)
.IP
Invoking the C compiler with the option
-.IR \-std=c99
+.I \-std=c99
produces the same effects as defining this macro.
.TP
.BR _ISOC11_SOURCE " (since glibc 2.16)"
.BR _ISOC99_SOURCE ).
.IP
Invoking the C compiler with the option
-.IR \-std=c11
+.I \-std=c11
produces the same effects as defining this macro.
.TP
.B _LARGEFILE64_SOURCE
.I _FILE_OFFSET_BITS=64
should be employed.
.TP
-.BR _LARGEFILE_SOURCE
+.B _LARGEFILE_SOURCE
This macro was historically used to expose certain functions (specifically
.BR fseeko (3)
and
and
.BR ftell (3))
that use
-.IR "long"
+.I long
for file offsets.
This macro is implicitly defined if
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
is defined with a value greater than or equal to 500.
New programs should not employ this macro;
defining
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
as just described or defining
.B _FILE_OFFSET_BITS
with the value 64 is the preferred mechanism to achieve the same result.
It now has the same effect as defining
.BR _DEFAULT_SOURCE ,
but generates a compile-time warning (unless
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
.\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78
is also defined).
Use
.B _DEFAULT_SOURCE
instead.
To allow code that requires
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
in glibc 2.19 and earlier and
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
in glibc 2.20 and later to compile without warnings, define
.I both
.B _BSD_SOURCE
be disabled,
as happens when individual macros are explicitly defined,
or the compiler is invoked in one of its "standard" modes (e.g.,
-.IR "cc\ \-std=c99" ).
+.IR cc\~\-std=c99 ).
Defining
.B _DEFAULT_SOURCE
without defining other individual macros
On glibc 2.19 and earlier, these defaults were approximately equivalent
to explicitly defining the following:
.IP
- cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809
+.in +4n
+.EX
+cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809
+.EE
+.in
.TP
.BR _ATFILE_SOURCE " (since glibc 2.4)"
Defining this macro with any value causes header files to expose
see
.BR openat (2).
Since glibc 2.10, this macro is also implicitly defined if
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
is defined with a value greater than or equal to 200809L.
.TP
.B _GNU_SOURCE
In addition, various GNU-specific extensions are also exposed.
.IP
Since glibc 2.19, defining
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
also has the effect of implicitly defining
.BR _DEFAULT_SOURCE .
In glibc versions before 2.20, defining
-.BR _GNU_SOURCE
+.B _GNU_SOURCE
also had the effect of implicitly defining
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
and
.BR _SVID_SOURCE .
.TP
.IP
However, glibc has been thread-safe by default for many years;
since glibc 2.3, the only effect of defining
-.BR _REENTRANT
+.B _REENTRANT
has been to enable one or two of the same declarations that
are also enabled by defining
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
with a value of 199606L or greater.
.IP
.B _REENTRANT
has no effect.
.IP
This macro is automatically defined if one compiles with
-.IR "cc\ \-pthread" .
+.IR cc\~\-pthread .
.TP
.B _THREAD_SAFE
Synonym for the (deprecated)
.SS Default definitions, implicit definitions, and combining definitions
If no feature test macros are explicitly defined,
then the following feature test macros are defined by default:
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
(in glibc 2.19 and earlier),
-.BR _SVID_SOURCE
+.B _SVID_SOURCE
(in glibc 2.19 and earlier),
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(since glibc 2.19),
.BR _POSIX_SOURCE ,
and
If any of
.BR __STRICT_ANSI__ ,
.BR _ISOC99_SOURCE ,
-.BR _ISOC11_SOURCE
+.B _ISOC11_SOURCE
(since glibc 2.18),
.BR _POSIX_SOURCE ,
.BR _POSIX_C_SOURCE ,
.BR _XOPEN_SOURCE ,
-.BR _XOPEN_SOURCE_EXTENDED
+.B _XOPEN_SOURCE_EXTENDED
(in glibc 2.11 and earlier),
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
(in glibc 2.19 and earlier),
or
.B _SVID_SOURCE
.BR _BSD_SOURCE ,
.BR _SVID_SOURCE ,
and
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
are not defined by default.
.PP
If
FIFO special files can be created by
.BR mkfifo (3),
and are indicated by
-.IR "ls\ \-l"
+.I ls\~\-l
with the file type \(aqp\(aq.
.SH SEE ALSO
.BR mkfifo (1),
.BR set_tid_address (2),
.BR pthreads (7)
.PP
-.IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux"
+.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux
(proceedings of the Ottawa Linux Symposium 2002),
futex example library, futex-*.tar.bz2
.UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
.I bash
one can force the classical behavior using this command:
.PP
- shopt \-s nullglob
+.in +4n
+.EX
+shopt \-s nullglob
+.EE
+.in
.\" In Bash v1, by setting allow_null_glob_expansion=true
.PP
(Similar problems occur elsewhere.
For example, where old scripts have
.PP
-.nf
- rm \`find . \-name "*\(ti"\`
-.fi
+.in +4n
+.EX
+rm \`find . \-name "*\(ti"\`
+.EE
+.in
.PP
new scripts require
.PP
-.nf
- rm \-f nosuchfile \`find . \-name "*\(ti"\`
-.fi
+.in +4n
+.EX
+rm \-f nosuchfile \`find . \-name "*\(ti"\`
+.EE
+.in
.PP
to avoid error messages from
.I rm
.I /run
This directory contains information which describes the system since it was booted.
Once this purpose was served by
-.IR /var/run
+.I /var/run
and programs may continue to use it.
.TP
.I /sbin
.IR icmp_ratelimit " (integer; default: 1000; since Linux 2.4.10)"
.\" The following taken from 2.6.28-rc4 Documentation/networking/ip-sysctl.txt
Limit the maximum rates for sending ICMP packets whose type matches
-.IR icmp_ratemask
+.I icmp_ratemask
(see below) to specific targets.
0 to disable any limiting,
otherwise the minimum space between responses in milliseconds.
.BR mount (2).)
In addition, the atime timestamp
is not updated if a file is opened with the
-.BR O_NOATIME
+.B O_NOATIME
flag; see
.BR open (2).
.TP
(see below) as the
.IR "file type" ,
the 12 bits corresponding to the mask 07777 as the
-.IR "file mode bits"
+.I file mode bits
and the least significant 9 bits (0777) as the
.IR "file permission bits" .
.PP
.PP
The definitions of most of the above file type test macros
are provided if any of the following feature test macros is defined:
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
(in glibc 2.19 and earlier),
-.BR _SVID_SOURCE
+.B _SVID_SOURCE
(in glibc 2.19 and earlier),
or
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(in glibc 2.20 and later).
In addition, definitions of all of the above macros except
-.BR S_IFSOCK
+.B S_IFSOCK
and
.BR S_ISSOCK ()
are provided if
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
is defined.
.PP
The definition of
-.BR S_IFSOCK
+.B S_IFSOCK
can also be exposed either by defining
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value of 500 or greater or (since glibc 2.24) by defining both
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
.PP
The definition of
.BR S_ISSOCK ()
is exposed if any of the following feature test macros is defined:
-.BR _BSD_SOURCE
+.B _BSD_SOURCE
(in glibc 2.19 and earlier),
-.BR _DEFAULT_SOURCE
+.B _DEFAULT_SOURCE
(in glibc 2.20 and later),
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with a value of 500 or greater,
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
with a value of 200112L or greater, or (since glibc 2.24) by defining both
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
.PP
process.
.SH CONFORMING TO
If you need to obtain the definition of the
-.IR blkcnt_t
+.I blkcnt_t
or
-.IR blksize_t
+.I blksize_t
types from
.IR <sys/stat.h> ,
then define
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
with the value 500 or greater (before including
.I any
header files).
.BR S_ISDIR ()
and so on.
The
-.BR S_IF*
+.B S_IF*
constants are present in POSIX.1-2001 and later.
.PP
The
.I /proc
directory,
while various files under
-.IR /sys
+.I /sys
report a size of 4096 bytes, even though the file content is smaller.
For such files, one should simply try to read as many bytes as possible
(and append \(aq\e0\(aq to the returned buffer
is like
.BR inotify_init (2),
but has a
-.IR flags
+.I flags
argument that provides access to some extra functionality.
.IP *
.BR inotify_add_watch (2)
.BR EINVAL .
Specifying a buffer of size
.PP
- sizeof(struct inotify_event) + NAME_MAX + 1
+.in +4n
+.EX
+sizeof(struct inotify_event) + NAME_MAX + 1
+.EE
+.in
.PP
will be sufficient to read at least one event.
.SS inotify events
Two additional convenience macros are defined:
.RS 4
.TP
-.BR IN_MOVE
+.B IN_MOVE
Equates to
.BR "IN_MOVED_FROM | IN_MOVED_TO" .
.TP
-.BR IN_CLOSE
+.B IN_CLOSE
Equates to
.BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" .
.RE
Suppose an application is watching the directory
.I dir
and the file
-.IR dir/myfile
+.I dir/myfile
for all events.
The examples below show some events that will be generated
for these two objects.
Generates an
.B IN_ATTRIB
event for
-.IR myfile
+.I myfile
and an
.B IN_CREATE
event for
.RE
.PP
Suppose that
-.IR dir1/xx
+.I dir1/xx
and
-.IR dir2/yy
+.I dir2/yy
are (the only) links to the same file, and an application is watching
.IR dir1 ,
.IR dir2 ,
.TP
unlink("dir2/yy");
Generates an
-.BR IN_ATTRIB
+.B IN_ATTRIB
event for
-.IR xx
+.I xx
(because its link count changes)
and an
.B IN_DELETE
.BR IN_ATTRIB ,
.BR IN_DELETE_SELF ,
and
-.BR IN_IGNORED
+.B IN_IGNORED
events for
.IR xx ,
and an
-.BR IN_DELETE
+.B IN_DELETE
event for
.IR dir1 .
.RE
.PP
Suppose an application is watching the directory
-.IR dir
+.I dir
and (the empty) directory
.IR dir/subdir .
The following examples show some events that may be generated.
structure (described in
.BR sigaction (2))
that is passed to the signal handler has the following fields set:
-.IR si_fd
+.I si_fd
is set to the inotify file descriptor number;
-.IR si_signo
+.I si_signo
is set to the signal number;
-.IR si_code
+.I si_code
is set to
.BR POLL_IN ;
and
The set of watch descriptors that is being monitored via
an inotify file descriptor can be viewed via the entry for
the inotify file descriptor in the process's
-.IR /proc/[pid]/fdinfo
+.IR /proc/ pid /fdinfo
directory.
See
.BR proc (5)
.IR /proc ,
.IR /sys ,
and
-.IR /dev/pts
+.I /dev/pts
are not monitorable with inotify.
.PP
The inotify API does not report file accesses and modifications that
is thus inherently racy.
(Don't forget that if an object is renamed outside of a monitored directory,
there may not even be an
-.BR IN_MOVED_TO
+.B IN_MOVED_TO
event.)
Heuristic approaches (e.g., assume the events are always consecutive)
can be used to ensure a match in most cases,
.BR stat (2),
.BR fanotify (7)
.PP
-.IR Documentation/filesystems/inotify.txt
+.I Documentation/filesystems/inotify.txt
in the Linux kernel source tree
An IP socket is created using
.BR socket (2):
.PP
- socket(AF_INET, socket_type, protocol);
+.in +4n
+.EX
+socket(AF_INET, socket_type, protocol);
+.EE
+.in
.PP
Valid socket types include
.B SOCK_STREAM
.I sin_port
contains the port in network byte order.
The port numbers below 1024 are called
-.IR "privileged ports"
+.I privileged ports
(or sometimes:
.IR "reserved ports" ).
Only a privileged process
contains the host interface address in network byte order.
.I in_addr
should be assigned one of the
-.BR INADDR_*
+.B INADDR_*
values
(e.g.,
.BR INADDR_LOOPBACK )
Stop receiving multicast data from a specific source in a given group.
This is valid only after the application has subscribed
to the multicast group using either
-.BR IP_ADD_MEMBERSHIP
+.B IP_ADD_MEMBERSHIP
or
.BR IP_ADD_SOURCE_MEMBERSHIP .
.IP
specified dynamic IP address to be up at the time that
the application is trying to bind to it.
This option is the per-socket equivalent of the
-.IR ip_nonlocal_bind
+.I ip_nonlocal_bind
.I /proc
interface described below.
.TP
.in
.PP
There are two macros,
-.BR MCAST_INCLUDE
+.B MCAST_INCLUDE
and
.BR MCAST_EXCLUDE ,
which can be used to specify the filtering mode.
or
.B SOCK_RAW
sockets by setting a value of
-.BR IP_PMTUDISC_PROBE
+.B IP_PMTUDISC_PROBE
(available since Linux 2.6.22).
This is also particularly useful for diagnostic tools such as
.BR tracepath (8)
socket option).
Enabling this socket option requires superuser privileges
(the
-.BR CAP_NET_ADMIN
+.B CAP_NET_ADMIN
capability).
.IP
TProxy redirection with the iptables TPROXY target also requires that
.BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
Unblock previously blocked multicast source.
Returns
-.BR EADDRNOTAVAIL
+.B EADDRNOTAVAIL
when given source is not being blocked.
.IP
Argument is an
and returns the required length via
.IR optlen .
The caller should allocate at least
-.BR NAME_MAX
+.B NAME_MAX
bytes for the buffer initially, although this is not guaranteed
to be sufficient.
Resizing the buffer to the returned length
.RE
.IP
Allocation of ephemeral ports starts with the first number in
-.IR ip_local_port_range
+.I ip_local_port_range
and ends with the second number.
If the range of ephemeral ports is exhausted,
then the relevant system call returns an error (but see BUGS).
.IP
Note that the port range in
-.IR ip_local_port_range
+.I ip_local_port_range
should not conflict with the ports used by masquerading
(although the case is handled).
Also, arbitrary choices may cause problems with some firewall packet
.BR IP_RECVERR ,
.BR IP_ROUTER_ALERT ,
and
-.BR IP_TRANSPARENT
+.B IP_TRANSPARENT
are Linux-specific.
.\" IP_XFRM_POLICY is Linux-specific
.\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
(0.0.0.0) and
.B INADDR_BROADCAST
(255.255.255.255) are byte-order-neutral.
- This means
+This means
.BR htonl (3)
has no effect on them.
.SS Compatibility
If a prohibited or restricted feature is accessed or used, the kernel will emit
a message that looks like:
.PP
-.RS
- Lockdown: X: Y is restricted, see man kernel_lockdown.7
-.RE
+.in +4n
+.EX
+Lockdown: X: Y is restricted, see man kernel_lockdown.7
+.EE
+.in
.PP
where X indicates the process name and Y indicates what is restricted.
.PP
.IR """user""" ,
but it does not provide reading (i.e., the
.BR keyctl (2)
-.BR KEYCTL_READ
+.B KEYCTL_READ
operation),
meaning that the key payload is never visible from user space.
This is suitable for storing username-password pairs
that should not be readable from user space.
.IP
The description of a
-.IR """logon"""
+.I """logon"""
key
.I must
start with a non-empty colon-delimited prefix whose purpose
is to identify the service to which the key belongs.
(Note that this differs from keys of the
-.IR """user"""
+.I """user"""
type, where the inclusion of a prefix is recommended but is not enforced.)
.TP
.IR """big_key""" " (since Linux 3.13)"
.BR KEY_SPEC_SESSION_KEYRING ,
.BR KEY_SPEC_PROCESS_KEYRING ,
and
-.BR KEY_SPEC_THREAD_KEYRING
+.B KEY_SPEC_THREAD_KEYRING
can be used to refer to the caller's own instances of these keyrings.
.TP
User keyrings
and
.BR request_key (2),
the special keyring values
-.BR KEY_SPEC_USER_KEYRING
+.B KEY_SPEC_USER_KEYRING
and
-.BR KEY_SPEC_USER_SESSION_KEYRING
+.B KEY_SPEC_USER_SESSION_KEYRING
can be used to refer to the caller's own instances of these keyrings.
.IP
A link to the user keyring is placed in a new session keyring by
for storing keys associated with each GID known to the kernel,
is not so far implemented, is unlikely to be implemented.
Nevertheless, the constant
-.BR KEY_SPEC_GROUP_KEYRING
+.B KEY_SPEC_GROUP_KEYRING
has been defined for this keyring.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Possession
This field contains descriptive information about the key.
For most key types, it has the form
.IP
- name[: extra\-info]
+.in +4n
+.EX
+name[: extra\-info]
+.EE
+.in
.IP
The
.I name
.IR """user""" " and " """logon"""
The size in bytes of the key payload (expressed in decimal).
.TP
-.IR """keyring"""
+.I """keyring"""
The number of keys linked to the keyring,
or the string
-.IR empty
+.I empty
if there are no keys linked to the keyring.
.TP
-.IR """big_key"""
+.I """big_key"""
The payload size in bytes, followed either by the string
.IR [file] ,
if the key payload exceeds the threshold that means that the
.RE
.IP
For the
-.IR """.request_key_auth"""
+.I """.request_key_auth"""
key type
(authorization key; see
.BR request_key (2)),
the description field has the form shown in the following example:
.IP
- key:c9a9b19 pid:28880 ci:10
+.in +4n
+.EX
+key:c9a9b19 pid:28880 ci:10
+.EE
+.in
.IP
The three subfields are as follows:
.RS
after which revoked and expired keys will be garbage collected.
The purpose of having such an interval is so that there is a window
of time where user space can see an error (respectively
-.BR EKEYREVOKED
+.B EKEYREVOKED
and
.BR EKEYEXPIRED )
that indicates what happened to the key.
.BR request\-key (8)
.PP
The kernel source files
-.IR Documentation/crypto/asymmetric\-keys.txt
+.I Documentation/crypto/asymmetric\-keys.txt
and under
-.IR Documentation/security/keys
+.I Documentation/security/keys
(or, before Linux 4.13, in the file
.IR Documentation/security/keys.txt ).
Nevertheless, the history is visible in vestiges of information
about Linux libc that remain in a few manual pages,
in particular, references to
-.IR libc4
+.I libc4
and
.IR libc5 .
.SS Other C libraries
functions to ease the use of this information.
The GNU gettext family of
functions also obey the environment variable
-.BR LANGUAGE
+.B LANGUAGE
(containing a colon-separated list of locales)
if the category is set to a valid locale other than
.BR """C""" .
.TP
.B REPORTING BUGS
The
-.IR man-pages
+.I man-pages
project doesn't use a REPORTING BUGS section in manual pages.
Information on reporting bugs is instead supplied in the
script-generated COLOPHON section.
.TP
.B COPYRIGHT
The
-.IR man-pages
+.I man-pages
project doesn't use a COPYRIGHT section in manual pages.
Copyright information is instead maintained in the page source.
In pages where this section is present,
.SH FORMATTING AND WORDING CONVENTIONS
The following subsections note some details for preferred formatting and
wording conventions in various sections of the pages in the
-.IR man-pages
+.I man-pages
project.
.SS SYNOPSIS
Wrap the function prototype(s) in a
For examples of all of the above, see the source code of various pages.
.SH STYLE GUIDE
The following subsections describe the preferred style for the
-.IR man-pages
+.I man-pages
project.
For details not covered below, the Chicago Manual of Style
is usually a good source;
.TE
.PP
See also the discussion
-.IR "Hyphenation of attributive compounds"
+.I Hyphenation of attributive compounds
below.
.SS Terms to avoid
The following table lists some terms to avoid using in man pages,
UnixWare
.SS NULL, NUL, null pointer, and null byte
A
-.IR "null pointer"
+.I null pointer
is a pointer that points to nothing,
and is normally indicated by the constant
.IR NULL .
On the other hand,
.I NUL
is the
-.IR "null byte",
+.IR "null byte" ,
a byte with the value 0, represented in C via the character constant
.IR \(aq\e0\(aq .
.PP
This produces proper hyperlinks that can be used in a web browser,
when rendering a page with, say:
.PP
- BROWSER=firefox man -H pagename
+.in +4n
+.EX
+BROWSER=firefox man -H pagename
+.EE
+.in
.SS Use of e.g., i.e., etc., a.k.a., and similar
In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
"cf.", and "a.k.a." should be avoided,
.IR "ls\ \-l"),
use the following form in the man page source:
.PP
- \e\-
+.in +4n
+.EX
+\e\-
+.EE
+.in
.PP
This guideline applies also to code examples.
.PP
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF,
use "\e(aq" ("apostrophe quote"); for example
.PP
- \e(aqC\e(aq
+.in +4n
+.EX
+\e(aqC\e(aq
+.EE
+.in
.PP
where
.I C
The following command can be used to format your source code to
something close to the preferred style:
.IP
- indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
+.in +4n
+.EX
+indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
+.EE
+.in
.IP *
For consistency, all example programs should terminate using either of:
.IP
- exit(EXIT_SUCCESS);
- exit(EXIT_FAILURE);
+.in +4n
+.EX
+exit(EXIT_SUCCESS);
+exit(EXIT_FAILURE);
+.EE
+.in
.IP
Avoid using the following forms to terminate a program:
.IP
- exit(0);
- exit(1);
- return n;
+.in +4n
+.EX
+exit(0);
+exit(1);
+return n;
+.EE
+.in
.IP *
If there is extensive explanatory text before the
program source code, mark off the source code
(e.g., \-1 or NULL).
Because they typically return a floating-point number,
the mathematical functions declared in
-.IR <math.h>
+.I <math.h>
indicate an error using other mechanisms.
There are two error-reporting mechanisms:
the older one sets
will see distinct single-directory hierarchies.
.PP
The views provided by the
-.IR /proc/[pid]/mounts ,
-.IR /proc/[pid]/mountinfo ,
+.IR /proc/ pid /mounts ,
+.IR /proc/ pid /mountinfo ,
and
-.IR /proc/[pid]/mountstats
+.IR /proc/ pid /mountstats
files (all described in
.BR proc (5))
correspond to the mount namespace in which the process with the PID
-.IR [pid]
+.I pid
resides.
(All of the processes that reside in the same mount namespace
will see the same view in these files.)
or
.BR unshare (2)
with the
-.BR CLONE_NEWNS
+.B CLONE_NEWNS
flag.
When a new mount namespace is created,
its mount list is initialized as follows:
.I events
between namespaces
(or, more precisely, between the mounts that are members of a
-.IR "peer group"
+.I peer group
that are propagating events to one another).
.PP
Each mount is marked (via
as having one of the following
.IR "propagation types" :
.TP
-.BR MS_SHARED
+.B MS_SHARED
This mount shares events with members of a peer group.
Mount and unmount events immediately under this mount will propagate
to the other mounts that are members of the peer group.
Conversely, mount and unmount events that take place under
peer mounts will propagate to this mount.
.TP
-.BR MS_PRIVATE
+.B MS_PRIVATE
This mount is private; it does not have a peer group.
Mount and unmount events do not propagate into or out of this mount.
.TP
-.BR MS_SLAVE
+.B MS_SLAVE
Mount and unmount events propagate into this mount from
a (master) shared peer group.
Mount and unmount events under this mount do not propagate to any peer.
with a peer group of which it is a member.
(More precisely, one peer group can be the slave of another peer group.)
.TP
-.BR MS_UNBINDABLE
+.B MS_UNBINDABLE
This is like a private mount,
and in addition this mount can't be bind mounted.
Attempts to bind mount this mount
.RB ( mount (2)
with the
-.BR MS_BIND
+.B MS_BIND
flag) will fail.
.IP
When a recursive bind mount
.RB ( mount (2)
with the
-.BR MS_BIND
+.B MS_BIND
and
-.BR MS_REC
+.B MS_REC
flags) is performed on a directory subtree,
any bind mounts within the subtree are automatically pruned
(i.e., not replicated)
.PP
Note that a mount's propagation type determines whether
mounts and unmounts of mounts
-.I "immediately under"
+.I immediately under
the mount are propagated.
Thus, the propagation type does not affect propagation of events for
grandchildren and further removed descendant mounts.
of the mount.
.PP
Members are added to a
-.IR "peer group"
+.I peer group
when a mount is marked as shared and either:
.IP * 3
the mount is replicated during the creation of a new mount namespace; or
.PP
The propagation type of the mounts in a mount namespace
can be discovered via the "optional fields" exposed in
-.IR /proc/[pid]/mountinfo .
+.IR /proc/ pid /mountinfo .
(See
.BR proc (5)
for details of this file.)
This mount is a slave and receives propagation from shared peer group
.IR X .
This tag will always appear in conjunction with a
-.IR master:X
+.I master:X
tag.
Here,
-.IR X
+.I X
is the closest dominant peer group under the process's root directory.
If
-.IR X
+.I X
is the immediate master of the mount,
or if there is no dominant peer group under the same root,
then only the
-.IR master:X
+.I master:X
field is present and not the
-.IR propagate_from:X
+.I propagate_from:X
field.
For further details, see below.
.TP
-.IR unbindable
+.I unbindable
This is an unbindable mount.
.PP
If none of the above tags is present, then this is a private mount.
.in
.PP
From the
-.IR /proc/self/mountinfo
+.I /proc/self/mountinfo
output, we see that
-.IR /mntS
+.I /mntS
is a shared mount in peer group 1, and that
-.IR /mntP
+.I /mntP
has no optional tags, indicating that it is a private mount.
The first two fields in each record in this file are the unique
ID for this mount, and the mount ID of the parent mount.
We can further inspect this file to see that the parent mount of
-.IR /mntS
+.I /mntS
and
-.IR /mntP
+.I /mntP
is the root directory,
.IR / ,
which is mounted as private:
These new mounts maintain the same propagation types,
but have unique mount IDs.
(The
-.IR \-\-propagation\ unchanged
+.I \-\-propagation\~unchanged
option prevents
.BR unshare (1)
from marking all mounts as private when creating a new mount namespace,
which it does by default.)
.PP
In the second terminal, we then create submounts under each of
-.IR /mntS
+.I /mntS
and
-.IR /mntP
+.I /mntP
and inspect the set-up:
.PP
.in +4n
.in
.PP
From the above, it can be seen that
-.IR /mntS/a
+.I /mntS/a
was created as shared (inheriting this setting from its parent mount) and
-.IR /mntP/b
+.I /mntP/b
was created as a private mount.
.PP
Returning to the first terminal and inspecting the set-up,
we see that the new mount created under the shared mount
-.IR /mntS
+.I /mntS
propagated to its peer mount (in the initial mount namespace),
but the new mount created under the private mount
-.IR /mntP
+.I /mntP
did not propagate:
.PP
.in +4n
.in
.PP
From the above output, we see that
-.IR /mntY
+.I /mntY
is now a slave mount that is receiving propagation events from
the shared peer group with the ID 2.
.PP
Continuing in the new namespace, we create submounts under each of
-.IR /mntX
+.I /mntX
and
.IR /mntY :
.PP
.PP
When we inspect the state of the mounts in the new mount namespace,
we see that
-.IR /mntX/a
+.I /mntX/a
was created as a new shared mount
(inheriting the "shared" setting from its parent mount) and
-.IR /mntY/b
+.I /mntY/b
was created as a private mount:
.PP
.in +4n
.PP
Returning to the first terminal (in the initial mount namespace),
we see that the mount
-.IR /mntX/a
+.I /mntX/a
propagated to the peer (the shared
.IR /mntX ),
but the mount
-.IR /mntY/b
+.I /mntY/b
was not propagated:
.PP
.in +4n
.in
.PP
Now we create a new mount under
-.IR /mntY
+.I /mntY
in the first shell:
.PP
.in +4n
Under
.IR /home/henry ,
we have not only recursively added the
-.IR /mntX
+.I /mntX
and
-.IR /mntY
+.I /mntY
mounts, but also the recursive mounts of those directories under
-.IR /home/cecilia
+.I /home/cecilia
that were created in the previous step.
Upon repeating the step for a third user,
it becomes obvious that the explosion is exponential in nature:
.SS Propagation type transitions
The following table shows the effect that applying a new propagation type
(i.e.,
-.IR "mount \-\-make\-xxxx")
+.IR mount\~\-\-make\-xxxx )
has on the existing propagation type of a mount.
The rows correspond to existing propagation types,
and the columns are the new propagation settings.
The propagation type of the resulting mount,
.IR B/b ,
depends on the propagation types of the mounts
-.IR A
+.I A
and
.IR B ,
and is summarized in the following table.
The propagation type of the resulting mount,
.IR B/b ,
depends on the propagation types of the mounts
-.IR A
+.I A
and
.IR B ,
and is summarized in the following table.
.I B
and do not have submounts under them are unmounted.
.\"
-.SS The /proc/[pid]/mountinfo "propagate_from" tag
+.SS The /proc/ pid /mountinfo "propagate_from" tag
The
.I propagate_from:X
tag is shown in the optional fields of a
-.IR /proc/[pid]/mountinfo
+.IR /proc/ pid /mountinfo
record in cases where a process can't see a slave's immediate master
(i.e., the pathname of the master is not reachable from
the filesystem root directory)
Then the
.BR chroot (1)
command is used to make the
-.IR /tmp/etc
+.I /tmp/etc
mount point unreachable from the root directory,
creating a situation where the master of
-.IR /mnt/tmp/etc
+.I /mnt/tmp/etc
is not reachable from the (new) root directory of the process.
.PP
First, we bind mount the root directory onto
-.IR /mnt
+.I /mnt
and then bind mount
-.IR /proc
+.I /proc
at
-.IR /mnt/proc
+.I /mnt/proc
so that after the later
.BR chroot (1)
the
.in
.PP
Next, we ensure that the
-.IR /mnt
+.I /mnt
mount is a shared mount in a new peer group (with no peers):
.PP
.in +4n
.in
.PP
Next, we bind mount
-.IR /mnt/etc
+.I /mnt/etc
onto
.IR /tmp/etc :
.PP
.PP
Initially, these two mounts are in the same peer group,
but we then make the
-.IR /tmp/etc
+.I /tmp/etc
a slave of
.IR /mnt/etc ,
and then make
-.IR /tmp/etc
+.I /tmp/etc
shared as well,
so that it can propagate events to the next slave in the chain:
.PP
.in
.PP
Then we bind mount
-.IR /tmp/etc
+.I /tmp/etc
onto
.IR /mnt/tmp/etc .
Again, the two mounts are initially in the same peer group,
but we then make
-.IR /mnt/tmp/etc
+.I /mnt/tmp/etc
a slave of
.IR /tmp/etc :
.PP
.in
.PP
From the above, we see that
-.IR /mnt
+.I /mnt
is the master of the slave
.IR /tmp/etc ,
which in turn is the master of the slave
We then
.BR chroot (1)
to the
-.IR /mnt
+.I /mnt
directory, which renders the mount with ID 267 unreachable
from the (new) root directory:
.PP
Above, we see that the mount with ID 273
is a slave whose master is the peer group 105.
The mount point for that master is unreachable, and so a
-.IR propagate_from
+.I propagate_from
tag is displayed, indicating that the closest dominant peer group
(i.e., the nearest reachable mount in the slave chain)
is the peer group with the ID 102 (corresponding to the
-.IR /mnt
+.I /mnt
mount point before the
.BR chroot (1)
was performed.
Notwithstanding the fact that the default propagation type
for new mount is in many cases
.BR MS_PRIVATE ,
-.BR MS_SHARED
+.B MS_SHARED
is typically more useful.
For this reason,
.BR systemd (1)
automatically remounts all mounts as
-.BR MS_SHARED
+.B MS_SHARED
on system startup.
Thus, on most modern systems, the default propagation type is in practice
.BR MS_SHARED .
in the new namespace,
.BR unshare (1)
(since
-.IR util\-linux
+.I util\-linux
version 2.27) in turn reverses the step performed by
.BR systemd (1),
by making all mounts private in the new namespace.
.in
.PP
To prevent this, one can use the
-.IR "\-\-propagation\ unchanged"
+.I \-\-propagation\~unchanged
option to
.BR unshare (1).
.PP
.BR nsenter (1)
to enter the mount and user namespaces corresponding to "ns1".
In that terminal window, we then recursively bind mount
-.IR /mnt/x
+.I /mnt/x
at the location
.IR /mnt/ppp .
.IP
.BR pivot_root (8),
.BR umount (8)
.PP
-.IR Documentation/filesystems/sharedsubtree.rst
+.I Documentation/filesystems/sharedsubtree.rst
in the kernel source tree.
Each message queue is identified by a name of the form
.IR /somename ;
that is, a null-terminated string of up to
-.BI NAME_MAX
+.B NAME_MAX
(i.e., 255) characters consisting of an initial slash,
followed by one or more characters, none of which are slashes.
Two processes can operate on the same queue by passing the same name to
A new queue's default
.I mq_maxmsg
value will be the smaller of
-.IR msg_default
+.I msg_default
and
.IR msg_max .
Up until Linux 2.6.28, the default
limit is ignored for privileged processes
.RB ( CAP_SYS_RESOURCE ),
but the
-.BR HARD_MSGMAX
+.B HARD_MSGMAX
ceiling is nevertheless imposed.
.IP
The definition of
-.BR HARD_MSGMAX
+.B HARD_MSGMAX
has changed across kernel versions:
.RS
.IP * 3
Up to Linux 2.6.32:
-.IR "131072\ /\ sizeof(void\ *)"
+.I 131072\~/\~sizeof(void\~*)
.IP *
Linux 2.6.33 to 3.4:
-.IR "(32768\ *\ sizeof(void\ *) / 4)"
+.I (32768\~*\~sizeof(void\~*) / 4)
.IP *
Since Linux 3.5:
.\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a
The minimum and maximum are as for
.IR /proc/sys/fs/mqueue/msgsize_max .
If
-.IR msgsize_default
+.I msgsize_default
exceeds
.IR msgsize_max ,
a new queue's default
limit is ignored for privileged process
.RB ( CAP_SYS_RESOURCE ),
but, since Linux 3.5, the
-.BR HARD_MSGSIZEMAX
+.B HARD_MSGSIZEMAX
ceiling is enforced for privileged processes.
.TP
.I /proc/sys/fs/mqueue/queues_max
system call allows the calling process to join an existing namespace.
The namespace to join is specified via a file descriptor that refers to
one of the
-.IR /proc/[pid]/ns
+.IR /proc/ pid /ns
files described below.
.TP
.BR unshare (2)
and
.BR unshare (2)
in most cases requires the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability, since, in the new namespace,
the creator will have the power to change global resources
that are visible to other processes that are subsequently created in,
.\"
.SS The /proc/[pid]/ns/ directory
Each process has a
-.IR /proc/[pid]/ns/
+.IR /proc/ pid /ns/
.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
subdirectory containing one entry for each namespace that
supports being manipulated by
they appear as symbolic links.
If two processes are in the same namespace,
then the device IDs and inode numbers of their
-.IR /proc/[pid]/ns/xxx
+.IR /proc/ pid /ns/ xxx
symbolic links will be the same; an application can check this using the
.I stat.st_dev
.\" Eric Biederman: "I reserve the right for st_dev to be significant
.PP
The symbolic links in this subdirectory are as follows:
.TP
-.IR /proc/[pid]/ns/cgroup " (since Linux 4.6)"
+.IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
This file is a handle for the cgroup namespace of the process.
.TP
-.IR /proc/[pid]/ns/ipc " (since Linux 3.0)"
+.IR /proc/ pid /ns/ipc " (since Linux 3.0)"
This file is a handle for the IPC namespace of the process.
.TP
-.IR /proc/[pid]/ns/mnt " (since Linux 3.8)"
+.IR /proc/ pid /ns/mnt " (since Linux 3.8)"
.\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
This file is a handle for the mount namespace of the process.
.TP
-.IR /proc/[pid]/ns/net " (since Linux 3.0)"
+.IR /proc/ pid /ns/net " (since Linux 3.0)"
This file is a handle for the network namespace of the process.
.TP
-.IR /proc/[pid]/ns/pid " (since Linux 3.8)"
+.IR /proc/ pid /ns/pid " (since Linux 3.8)"
.\" commit 57e8391d327609cbf12d843259c968b9e5c1838f
This file is a handle for the PID namespace of the process.
This handle is permanent for the lifetime of the process
(i.e., a process's PID namespace membership never changes).
.TP
-.IR /proc/[pid]/ns/pid_for_children " (since Linux 4.12)"
+.IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)"
.\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08
This file is a handle for the PID namespace of
child processes created by this process.
(see
.BR pid_namespaces (7)),
so the file may differ from
-.IR /proc/[pid]/ns/pid .
+.IR /proc/ pid /ns/pid .
The symbolic link gains a value only after the first child process
is created in the namespace.
(Beforehand,
.BR readlink (2)
of the symbolic link will return an empty buffer.)
.TP
-.IR /proc/[pid]/ns/time " (since Linux 5.6)"
+.IR /proc/ pid /ns/time " (since Linux 5.6)"
This file is a handle for the time namespace of the process.
.TP
-.IR /proc/[pid]/ns/time_for_children " (since Linux 5.6)"
+.IR /proc/ pid /ns/time_for_children " (since Linux 5.6)"
This file is a handle for the time namespace of
child processes created by this process.
This can change as a consequence of calls to
(see
.BR time_namespaces (7)),
so the file may differ from
-.IR /proc/[pid]/ns/time .
+.IR /proc/ pid /ns/time .
.TP
-.IR /proc/[pid]/ns/user " (since Linux 3.8)"
+.IR /proc/ pid /ns/user " (since Linux 3.8)"
.\" commit cde1975bc242f3e1072bde623ef378e547b73f91
This file is a handle for the user namespace of the process.
.TP
-.IR /proc/[pid]/ns/uts " (since Linux 3.0)"
+.IR /proc/ pid /ns/uts " (since Linux 3.0)"
This file is a handle for the UTS namespace of the process.
.PP
Permission to dereference or read
on the number of namespaces of various types that can be created.
The files are as follows:
.TP
-.IR max_cgroup_namespaces
+.I max_cgroup_namespaces
The value in this file defines a per-user limit on the number of
cgroup namespaces that may be created in the user namespace.
.TP
-.IR max_ipc_namespaces
+.I max_ipc_namespaces
The value in this file defines a per-user limit on the number of
ipc namespaces that may be created in the user namespace.
.TP
-.IR max_mnt_namespaces
+.I max_mnt_namespaces
The value in this file defines a per-user limit on the number of
mount namespaces that may be created in the user namespace.
.TP
-.IR max_net_namespaces
+.I max_net_namespaces
The value in this file defines a per-user limit on the number of
network namespaces that may be created in the user namespace.
.TP
-.IR max_pid_namespaces
+.I max_pid_namespaces
The value in this file defines a per-user limit on the number of
PID namespaces that may be created in the user namespace.
.TP
The value in this file defines a per-user limit on the number of
time namespaces that may be created in the user namespace.
.TP
-.IR max_user_namespaces
+.I max_user_namespaces
The value in this file defines a per-user limit on the number of
user namespaces that may be created in the user namespace.
.TP
-.IR max_uts_namespaces
+.I max_uts_namespaces
The value in this file defines a per-user limit on the number of
uts namespaces that may be created in the user namespace.
.PP
These factors include the following:
.IP * 3
An open file descriptor or a bind mount exists for the corresponding
-.IR /proc/[pid]/ns/*
+.IR /proc/ pid /ns/*
file.
.IP *
The namespace is hierarchical (i.e., a PID or user namespace),
.IP *
It is a PID namespace,
and there is a process that refers to the namespace via a
-.IR /proc/[pid]/ns/pid_for_children
+.IR /proc/ pid /ns/pid_for_children
symbolic link.
.IP *
It is a time namespace,
and there is a process that refers to the namespace via a
-.IR /proc/[pid]/ns/time_for_children
+.IR /proc/ pid /ns/time_for_children
symbolic link.
.IP *
It is an IPC namespace, and a corresponding mount of an
selects the kernel module or netlink group to communicate with.
The currently assigned netlink families are:
.TP
-.BR NETLINK_ROUTE
+.B NETLINK_ROUTE
Receives routing and link updates and may be used to modify the routing
tables (both IPv4 and IPv6), IP addresses, link parameters,
neighbor setups, queueing disciplines, traffic classes, and
.BR NETLINK_W1 " (Linux 2.6.13 to 2.16.17)"
Messages from 1-wire subsystem.
.TP
-.BR NETLINK_USERSOCK
+.B NETLINK_USERSOCK
Reserved for user-mode socket protocols.
.TP
.BR NETLINK_FIREWALL " (up to and including Linux 3.4)"
After a long period of being declared obsolete (in favor of the more advanced
.I nfnetlink_queue
feature),
-.BR NETLINK_FIREWALL
+.B NETLINK_FIREWALL
was removed in Linux 3.5.
.TP
.BR NETLINK_SOCK_DIAG " (since Linux 3.3)"
.BR NETLINK_NFLOG " (up to and including Linux 3.16)"
Netfilter/iptables ULOG.
.TP
-.BR NETLINK_XFRM
+.B NETLINK_XFRM
.\" FIXME More details on NETLINK_XFRM needed.
IPsec.
.TP
See
.I Documentation/driver\-api/connector.rst
(or
-.IR /Documentation/connector/connector.*
+.I /Documentation/connector/connector.*
.\" commit baa293e9544bea71361950d071579f0e4d5713ed
in kernel 5.2 and earlier)
in the Linux kernel source tree for further information.
.BR NETLINK_GENERIC ,
.BR NETLINK_ROUTE ,
and
-.BR NETLINK_SELINUX
+.B NETLINK_SELINUX
groups allow other users to receive messages.
No groups allow other users to send messages.
.SS Socket options
.TP
.I mapped=<pages>
Total number of mapped pages, if different from
-.IR dirty
+.I dirty
and
.I anon
pages.
.I /proc
interface are available only
if the kernel was configured and built with the
-.BR CONFIG_NUMA
+.B CONFIG_NUMA
option.
.SS Library support
Link with \fI\-lnuma\fP
.B SOCK_DGRAM
for cooked packets with the link-level header removed.
The link-level header information is available in a common format in a
-.IR sockaddr_ll
+.I sockaddr_ll
structure.
.I protocol
is the IEEE 802.3 protocol number in network byte order.
no packets are received.
.BR bind (2)
can optionally be called with a nonzero
-.IR sll_protocol
+.I sll_protocol
to start receiving packets for the protocols specified.
.PP
In order to create a packet socket, a process must have the
.I struct sockaddr_ll
to bind the packet socket to an interface.
Fields used for binding are
-.IR sll_family
+.I sll_family
(should be
.BR AF_PACKET ),
.IR sll_protocol ,
with level
.BR SOL_PACKET .
.TP
-.BR PACKET_ADD_MEMBERSHIP
+.B PACKET_ADD_MEMBERSHIP
.PD 0
.TP
-.BR PACKET_DROP_MEMBERSHIP
+.B PACKET_DROP_MEMBERSHIP
.PD
Packet sockets can be used to configure physical-layer multicasting
and promiscuous mode.
over network-layer address and optional transport-layer port fields.
.IP *
The load-balance mode
-.BR PACKET_FANOUT_LB
+.B PACKET_FANOUT_LB
implements a round-robin algorithm.
.IP *
-.BR PACKET_FANOUT_CPU
+.B PACKET_FANOUT_CPU
selects the socket based on the CPU that the packet arrived on.
.IP *
-.BR PACKET_FANOUT_ROLLOVER
+.B PACKET_FANOUT_ROLLOVER
processes all data on a single socket, moving to the next when one
becomes backlogged.
.IP *
-.BR PACKET_FANOUT_RND
+.B PACKET_FANOUT_RND
selects the socket using a pseudo-random number generator.
.IP *
-.BR PACKET_FANOUT_QM
+.B PACKET_FANOUT_QM
.\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd
(available since Linux 3.14)
selects the socket using the recorded queue_mapping of the received skb.
Fanout mode and options are communicated in the second 16 bits of the
integer option value.
The flag
-.BR PACKET_FANOUT_FLAG_ROLLOVER
+.B PACKET_FANOUT_FLAG_ROLLOVER
enables the roll over mechanism as a backup strategy: if the
original fanout algorithm selects a backlogged socket, the packet
rolls over to the next available one.
the default is to reset its
.I tp_status
to
-.BR TP_STATUS_WRONG_FORMAT
+.B TP_STATUS_WRONG_FORMAT
and abort the transmission immediately.
The malformed packet blocks itself and subsequently enqueued packets from
being sent.
and the transmission process restarted via
.BR send (2).
However, if
-.BR PACKET_LOSS
+.B PACKET_LOSS
is set, any malformed packet will be skipped, its
.I tp_status
reset to
metadata structure and alignment padding.
This integer option reserves additional headroom.
.TP
-.BR PACKET_RX_RING
+.B PACKET_RX_RING
Create a memory-mapped ring buffer for asynchronous packet reception.
The packet socket reserves a contiguous region of application address
space, lays it out into an array of packet slots and copies packets
During normal operation, the new
.I tp_status
value has at least the
-.BR TP_STATUS_USER
+.B TP_STATUS_USER
bit set to signal that a received packet has been stored.
When the application has finished processing a packet, it transfers
ownership of the slot back to the socket by setting
.IP
Packet sockets implement multiple variants of the packet ring.
The implementation details are described in
-.IR Documentation/networking/packet_mmap.rst
+.I Documentation/networking/packet_mmap.rst
in the Linux kernel source tree.
.TP
-.BR PACKET_STATISTICS
+.B PACKET_STATISTICS
Retrieve packet socket statistics in the form of a structure
.IP
.in +4n
packet is copied into the ring.
This integer option selects the type of timestamp.
Besides the default, it support the two hardware formats described in
-.IR Documentation/networking/timestamping.rst
+.I Documentation/networking/timestamping.rst
in the Linux kernel source tree.
.TP
.BR PACKET_TX_RING " (since Linux 2.6.31)"
.\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1
Create a memory-mapped ring buffer for packet transmission.
This option is similar to
-.BR PACKET_RX_RING
+.B PACKET_RX_RING
and takes the same arguments.
The application writes packets into slots with
.I tp_status
equal to
-.BR TP_STATUS_AVAILABLE
+.B TP_STATUS_AVAILABLE
and schedules them for transmission by changing
.I tp_status
to
to
.BR TP_STATUS_AVAILABLE .
It immediately aborts the transmission on error unless
-.BR PACKET_LOSS
+.B PACKET_LOSS
is set.
.TP
.BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)"
.\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279
By default,
-.BR PACKET_RX_RING
+.B PACKET_RX_RING
creates a packet receive ring of variant
.BR TPACKET_V1 .
To create another variant, configure the desired variant by setting this
.SS Compatibility
In Linux 2.0, the only way to get a packet socket was with the call:
.PP
- socket(AF_INET, SOCK_PACKET, protocol)
+.in +4n
+.EX
+socket(AF_INET, SOCK_PACKET, protocol)
+.EE
+.in
.PP
This is still supported, but deprecated and strongly discouraged.
The main difference between the two methods is that
include file for physical-layer protocols.
.PP
The Linux kernel source tree.
-.IR Documentation/networking/filter.rst
+.I Documentation/networking/filter.rst
describes how to apply Berkeley Packet Filters to packet sockets.
-.IR tools/testing/selftests/net/psock_tpacket.c
+.I tools/testing/selftests/net/psock_tpacket.c
contains example source code for all available versions of
-.BR PACKET_RX_RING
+.B PACKET_RX_RING
and
.BR PACKET_TX_RING .
operation is performed,
the persistent key's expiration timer is reset to the value in:
.PP
- /proc/sys/kernel/keys/persistent_keyring_expiry
+.in +4n
+.EX
+/proc/sys/kernel/keys/persistent_keyring_expiry
+.EE
+.in
.PP
Should the timeout be reached,
the persistent keyring will be removed and
operation.)
This operation allows the calling thread to get the persistent keyring
corresponding to its own UID or, if the thread has the
-.BR CAP_SETUID
+.B CAP_SETUID
capability, the persistent keyring corresponding to some other UID
in the same user namespace.
.SH NOTES
Each user namespace owns a keyring called
-.IR .persistent_register
+.I .persistent_register
that contains links to all of the persistent keys in that namespace.
(The
-.IR .persistent_register
+.I .persistent_register
keyring can be seen when reading the contents of the
-.IR /proc/keys
+.I /proc/keys
file for the UID 0 in the namespace.)
The
.BR keyctl_get_persistent (3)
operation looks for a key with a name of the form
-.IR _persistent.<UID>
+.IR _persistent. UID
in that keyring,
creates the key if it does not exist, and links it into the keyring.
.SH SEE ALSO
(i.e., the process created using
.BR clone (2)
with the
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
flag, or the first child created by a process after a call to
.BR unshare (2)
using the
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
flag) has the PID 1, and is the "init" process for the namespace (see
.BR init (1)).
This process becomes the parent of any child processes that are orphaned
.PP
If the "init" process of a PID namespace terminates,
the kernel terminates all of the processes in the namespace via a
-.BR SIGKILL
+.B SIGKILL
signal.
This behavior reflects the fact that the "init" process
is essential for the correct operation of a PID namespace.
process has terminated.
Such scenarios can occur when, for example,
a process uses an open file descriptor for a
-.I /proc/[pid]/ns/pid
+.IR /proc/ pid /ns/pid
file corresponding to a process that was in a namespace to
.BR setns (2)
into that namespace after the "init" process has terminated.
Changing PID namespaces is a one-way operation.
.PP
The
-.BR NS_GET_PARENT
+.B NS_GET_PARENT
.BR ioctl (2)
operation can be used to discover the parental relationship
between PID namespaces; see
and calls to
.BR unshare (2)
with the
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
flag cause children subsequently created
by the caller to be placed in a different PID namespace from the caller.
(Since Linux 4.12, that PID namespace is shown via the
-.IR /proc/[pid]/ns/pid_for_children
+.IR /proc/ pid /ns/pid_for_children
file, as described in
.BR namespaces (7).)
These calls do not, however,
.B CLONE_NEWPID
flag only once.
After it has performed this operation, its
-.IR /proc/PID/ns/pid_for_children
+.IR /proc/ pid /ns/pid_for_children
symbolic link will be empty until the first child is created in the namespace.
.\"
.\" ============================================================
.\"
.SS Compatibility of CLONE_NEWPID with other CLONE_* flags
In current versions of Linux,
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
can't be combined with
.BR CLONE_THREAD .
Threads are required to be in the same PID namespace such that
.\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0
.\" when CLONE_NEWPID|CLONE_VM was disallowed
In earlier versions of Linux,
-.BR CLONE_NEWPID
+.B CLONE_NEWPID
was additionally disallowed (failing with the error
.BR EINVAL )
in combination with
-.BR CLONE_SIGHAND
+.B CLONE_SIGHAND
.\" (restriction lifted in faf00da544045fdc1454f3b9e6d7f65c841de302)
(before Linux 4.3) as well as
.\" (restriction lifted in e79f525e99b04390ca4d2366309545a836c03bf1)
-.BR CLONE_VM
+.B CLONE_VM
(before Linux 3.12).
The changes that lifted these restrictions have also been ported to
earlier stable kernels.
A
.I /proc
filesystem shows (in the
-.I /proc/[pid]
+.IR /proc/ pid
directories) only processes visible in the PID namespace
of the process that performed the mount, even if the
.I /proc
.BR ps (1)
work correctly.
If a new mount namespace is simultaneously created by including
-.BR CLONE_NEWNS
+.B CLONE_NEWNS
in the
-.IR flags
+.I flags
argument of
.BR clone (2)
or
Since Linux 2.6.35, the default pipe capacity is 16 pages,
but the capacity can be queried and set using the
.BR fcntl (2)
-.BR F_GETPIPE_SZ
+.B F_GETPIPE_SZ
and
-.BR F_SETPIPE_SZ
+.B F_SETPIPE_SZ
operations.
See
.BR fcntl (2)
.I int
buffer pointed to by the final argument of the call:
.PP
- ioctl(fd, FIONREAD, &nbytes);
+.in +4n
+.EX
+ioctl(fd, FIONREAD, &nbytes);
+.EE
+.in
.PP
The
.B FIONREAD
.\" commit b492e95be0ae672922f4734acf3f5d35c30be948
An upper limit, in pages, on the capacity that an unprivileged user
(one without the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability)
can set for a pipe.
.IP
which permits creating up to 1024 pipes with the default capacity.
.PP
Before Linux 4.9, some bugs affected the handling of the
-.IR pipe\-user\-pages\-soft
+.I pipe\-user\-pages\-soft
and
-.IR pipe\-user\-pages\-hard
+.I pipe\-user\-pages\-hard
limits; see BUGS.
.\"
.SS PIPE_BUF
bidirectional pipe semantics.
.SS BUGS
Before Linux 4.9, some bugs affected the handling of the
-.IR pipe\-user\-pages\-soft
+.I pipe\-user\-pages\-soft
and
-.IR pipe\-user\-pages\-hard
+.I pipe\-user\-pages\-hard
limits when using the
.BR fcntl (2)
-.BR F_SETPIPE_SZ
+.B F_SETPIPE_SZ
operation to change a pipe's capacity:
.\" These bugs where remedied by a series of patches, in particular,
.\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and
.BR PROT_READ ,
.BR PROT_WRITE ,
and
-.BR PROT_EXEC
+.B PROT_EXEC
permissions passed to system calls such as
.BR mprotect (2)
and
.PP
If a process performs an access that violates pkey
restrictions, it receives a
-.BR SIGSEGV
+.B SIGSEGV
signal.
See
.BR sigaction (2)
implications to perform the additional checks needed to disallow it.
Implementation of the necessary checks is left up to applications.
Applications may implement these checks by searching the
-.IR /proc/[pid]/smaps
+.IR /proc/ pid /smaps
file for memory regions with the pkey assigned.
Further details can be found in
.BR proc (5).
Details of how to do this can be found in the Intel Software
Developers Manual.
The kernel performs this enumeration and exposes the information in
-.IR /proc/cpuinfo
+.I /proc/cpuinfo
under the "flags" field.
The string "pku" in this field indicates hardware support for protection
keys and the string "ospke" indicates that the kernel contains and has
.PP
The Linux pkey system calls are available only if the kernel was
configured and built with the
-.BR CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS
+.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS
option.
.SH EXAMPLES
The program below allocates a page of memory with read and write permissions.
.BR TIOCSTART ,
.BR TIOCUCNTL ,
and
-.BR TIOCREMOTE
+.B TIOCREMOTE
have not been implemented under Linux.
.SH SEE ALSO
.BR ioctl_tty (2),
source; the
.I random
source is selected by specifying the
-.BR GRND_RANDOM
+.B GRND_RANDOM
flag to the system call.
(The
.BR getentropy (3)
.SS Choice of random source
Unless you are doing long-term key generation (and most likely not even
then), you probably shouldn't be reading from the
-.IR /dev/random
+.I /dev/random
device or employing
.BR getrandom (2)
with the
-.BR GRND_RANDOM
+.B GRND_RANDOM
flag.
Instead, either read from the
-.IR /dev/urandom
+.I /dev/urandom
device or employ
.BR getrandom (2)
without the
.B GRND_RANDOM
flag.
The cryptographic algorithms used for the
-.IR urandom
+.I urandom
source are quite conservative, and so should be sufficient for all purposes.
.PP
The disadvantage of
.\"
.ie t .ds dg \(dg
.el .ds dg (!)
-.TH REGEX 7 2020-08-13 "" "Linux Programmer's Manual"
+.TH REGEX 7 2020-08-13 GNU "Linux Programmer's Manual"
.SH NAME
regex \- POSIX.2 regular expressions
.SH DESCRIPTION
auditing function.
.PP
To employ the auditing interface, the environment variable
-.BR LD_AUDIT
+.B LD_AUDIT
must be defined to contain a colon-separated list of shared libraries,
each of which can implement (parts of) the auditing API.
When an auditable event occurs,
.\" but don't seem to be called for dynamically loaded libs?
.\" Is this the same on Solaris?
The following flags can be ORed into
-.IR *flags
+.I *flags
to change this default behavior:
.TP 22
.B LA_SYMB_NOPLTENTER
.IR refcook ,
.IR defcook ,
and
-.IR symname
+.I symname
are as for
.BR la_symbind* ().
.PP
.PP
.\" FIXME . Is the following correct?
The
-.IR framesizep
+.I framesizep
argument points to a
-.IR "long\ int"
+.I long\~int
buffer that can be used to explicitly set the frame size
used for the call to this PLT entry.
If different
.IR refcook ,
.IR defcook ,
and
-.IR symname
+.I symname
are as for
.BR la_symbind* ().
.PP
and
.I outregs
arguments (but does provide a
-.IR retval
+.I retval
argument with the function return value).
.SH BUGS
In glibc versions up to and include 2.9,
The value type for
.B IFLA_STATS
is
-.IR "struct rtnl_link_stats"
+.I struct rtnl_link_stats
.RI ( "struct net_device_stats"
in Linux 2.4 and earlier).
.TP
.BR ICMPV6_ROUTER_PREF_LOW ,
.BR ICMPV6_ROUTER_PREF_MEDIUM ,
and
-.BR ICMPV6_ROUTER_PREF_HIGH
+.B ICMPV6_ROUTER_PREF_HIGH
defined incw
.IR <linux/icmpv6.h> .
.IP
.BR LWTUNNEL_ENCAP_IP ,
.BR LWTUNNEL_ENCAP_ILA ,
or
-.BR LWTUNNEL_ENCAP_IP6
+.B LWTUNNEL_ENCAP_IP6
defined in
.IR <linux/lwtunnel.h> .
.IP
which is the CPU time necessary for executing the job.
The moment when a task wakes up
because a new job has to be executed is called the
-.IR "arrival time"
+.I arrival time
(also referred to as the request time or release time).
The
-.IR "start time"
+.I start time
is the time at which a task starts its execution.
The
-.I "absolute deadline"
+.I absolute deadline
is thus obtained by adding the relative deadline to the arrival time.
.PP
The following diagram clarifies these terms:
computation time (or worst-case execution time for hard real-time tasks),
Deadline to the relative deadline, and Period to the period of the task.
Thus, for
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
scheduling, we have:
.PP
.in +4n
.IR sched_runtime ,
.IR sched_deadline ,
and
-.IR sched_period
+.I sched_period
fields of the
.I sched_attr
structure; see
.\" "make sched_period the same as sched_deadline".
.\" This needs to be documented.
If
-.IR sched_period
+.I sched_period
is specified as 0, then it is made the same as
.IR sched_deadline .
.PP
The kernel requires that:
.PP
- sched_runtime <= sched_deadline <= sched_period
+.in +4n
+.EX
+sched_runtime <= sched_deadline <= sched_period
+.EE
+.in
.PP
.\" See __checkparam_dl in kernel/sched/core.c
In addition, under the current implementation,
.PP
In order to fulfill the guarantees that are made when
a thread is admitted to the
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
policy,
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
threads are the highest priority (user controllable) threads in the
system; if any
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
thread is runnable,
it will preempt any thread scheduled under one of the other policies.
.PP
that can be used to influence the CPU scheduler to
favor or disfavor a process in scheduling decisions.
It affects the scheduling of
-.BR SCHED_OTHER
+.B SCHED_OTHER
and
-.BR SCHED_BATCH
+.B SCHED_BATCH
(see below) processes.
The nice value can be modified using
.BR nice (2),
.\" Since kernel 1.3.43, Linux has the range \-20..19.
.PP
The degree to which the nice value affects the relative scheduling of
-.BR SCHED_OTHER
+.B SCHED_OTHER
processes likewise varies across UNIX systems and
across Linux kernel versions.
.PP
that require it (e.g., some audio applications).
.PP
On Linux, the
-.BR RLIMIT_NICE
+.B RLIMIT_NICE
resource limit can be used to define a limit to which
an unprivileged process's nice value can be raised; see
.BR setrlimit (2)
specifying the
.B SCHED_FLAG_RESET_ON_FORK
flag in
-.IR attr.sched_flags
+.I attr.sched_flags
when calling
.BR sched_setattr (2).
.PP
.PP
The reset-on-fork feature is intended for media-playback applications,
and can be used to prevent applications evading the
-.BR RLIMIT_RTTIME
+.B RLIMIT_RTTIME
resource limit (see
.BR getrlimit (2))
by creating multiple child processes.
or
.BR SCHED_RR ,
the policy is reset to
-.BR SCHED_OTHER
+.B SCHED_OTHER
in child processes.
.IP *
If the calling process has a negative nice value,
.PP
After the reset-on-fork flag has been enabled,
it can be reset only if the thread has the
-.BR CAP_SYS_NICE
+.B CAP_SYS_NICE
capability.
This flag is disabled in child processes created by
.BR fork (2).
A thread must be privileged
.RB ( CAP_SYS_NICE )
in order to set or modify a
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
policy.
.PP
Since Linux 2.6.12, the
matches the real or effective user ID of the target thread.
.IP *
Special rules apply for the
-.BR SCHED_IDLE
+.B SCHED_IDLE
policy.
In Linux kernels before 2.6.39,
an unprivileged thread operating under this policy cannot
change its policy, regardless of the value of its
-.BR RLIMIT_RTPRIO
+.B RLIMIT_RTPRIO
resource limit.
In Linux kernels since 2.6.39,
.\" commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8
an unprivileged thread can switch to either the
-.BR SCHED_BATCH
+.B SCHED_BATCH
or the
-.BR SCHED_OTHER
+.B SCHED_OTHER
policy so long as its nice value falls within the range permitted by its
-.BR RLIMIT_NICE
+.B RLIMIT_NICE
resource limit (see
.BR getrlimit (2)).
.PP
.BR SCHED_FIFO ,
.BR SCHED_RR ,
or
-.BR SCHED_DEADLINE
+.B SCHED_DEADLINE
policy can potentially block all other threads from accessing
the CPU forever.
Prior to Linux 2.6.25, the only way of preventing a runaway real-time
Since Linux 2.6.25, there are other techniques for dealing with runaway
real-time and deadline processes.
One of these is to use the
-.BR RLIMIT_RTTIME
+.B RLIMIT_RTTIME
resource limit to set a ceiling on the CPU time that
a real-time process may consume.
See
allocated to (say) a root shell that can be used to kill a runaway process.
Both of these files specify time values in microseconds:
.TP
-.IR /proc/sys/kernel/sched_rt_period_us
+.I /proc/sys/kernel/sched_rt_period_us
This file specifies a scheduling period that is equivalent to
100% CPU bandwidth.
The value in this file can range from 1 to
giving an operating range of 1 microsecond to around 35 minutes.
The default value in this file is 1,000,000 (1 second).
.TP
-.IR /proc/sys/kernel/sched_rt_runtime_us
+.I /proc/sys/kernel/sched_rt_runtime_us
The value in this file specifies how much of the "period" time
can be used by all real-time and deadline scheduled processes
on the system.
workloads such as building the Linux kernel with large numbers of
parallel build processes (i.e., the
.BR make (1)
-.BR \-j
+.B \-j
flag).
.PP
This feature operates in conjunction with the
.IR /proc/sys/kernel/sched_autogroup_enabled ;
a value of 0 disables the feature, while a value of 1 enables it.
The default value in this file is 1, unless the kernel was booted with the
-.IR noautogroup
+.I noautogroup
parameter.
.PP
A new autogroup is created when a new session is created via
to confine all the processes to the same CPU on an SMP system).
The first group contains ten CPU-bound processes from
a kernel build started with
-.IR "make\ \-j10" .
+.IR "make\~\-j10" .
The other contains a single CPU-bound process: a video player.
The effect of autogrouping is that the two groups will
each receive half of the CPU cycles.
jobs on the system.
.PP
A process's autogroup (task group) membership can be viewed via the file
-.IR /proc/[pid]/autogroup :
+.IR /proc/ pid /autogroup :
.PP
.in +4n
.EX
.BR SCHED_OTHER ,
.BR SCHED_BATCH ,
and
-.BR SCHED_IDLE
+.B SCHED_IDLE
policies), the CFS scheduler employs a technique known as "group scheduling",
if the kernel was configured with the
-.BR CONFIG_FAIR_GROUP_SCHED
+.B CONFIG_FAIR_GROUP_SCHED
option (which is typical).
.PP
Under group scheduling, threads are scheduled in "task groups".
the sole CPU-bound processes in different sessions
(e.g., different terminal windows,
each of whose jobs are tied to different autogroups),
-.IR "modifying the nice value of the process in one of the sessions"
-.IR "has no effect"
+.I modifying the nice value of the process in one of the sessions
+.I has no effect
in terms of the scheduler's decisions relative to the
process in the other session.
.\" More succinctly: the nice(1) command is in many cases a no-op since
.IR Documentation/scheduler/sched\-rt\-group.txt ,
.IR Documentation/scheduler/sched\-design\-CFS.txt ,
and
-.IR Documentation/scheduler/sched\-nice\-design.txt
+.I Documentation/scheduler/sched\-nice\-design.txt
field specifies how notification is to be performed.
This field can have one of the following values:
.TP
-.BR SIGEV_NONE
+.B SIGEV_NONE
A "null" notification: don't do anything when the event occurs.
.TP
-.BR SIGEV_SIGNAL
+.B SIGEV_SIGNAL
Notify the process by sending the signal specified in
.IR sigev_signo .
.IP
The same information is also available if the signal is accepted using
.BR sigwaitinfo (2).
.TP
-.BR SIGEV_THREAD
+.B SIGEV_THREAD
Notify the process by invoking
.I sigev_notify_function
"as if" it were the start function of a new thread.
If the signal handler was installed by a call to
.BR sigaction (2)
that specified the
-.BR SA_ONSTACK
+.B SA_ONSTACK
flag and the thread has defined an alternate signal stack (using
.BR sigaltstack (2)),
then that stack is installed.
.PP
Which of these two behaviors occurs depends on the interface and
whether or not the signal handler was established using the
-.BR SA_RESTART
+.B SA_RESTART
flag (see
.BR sigaction (2)).
The details vary across UNIX systems;
If a blocked call to one of the following interfaces is interrupted
by a signal handler, then the call is automatically restarted
after the signal handler returns if the
-.BR SA_RESTART
+.B SA_RESTART
flag was used; otherwise the call fails with the error
.BR EINTR :
.\" The following system calls use ERESTARTSYS,
.BR flock (2)
and
the
-.BR F_SETLKW
+.B F_SETLKW
and
-.BR F_OFD_SETLKW
+.B F_OFD_SETLKW
operations of
.BR fcntl (2)
.IP *
.BR recvfrom (2),
.BR recvmmsg (2)
(also with a non-NULL
-.IR timeout
+.I timeout
argument),
and
.BR recvmsg (2).
.SS Interruption of system calls and library functions by stop signals
On Linux, even in the absence of signal handlers,
certain blocking interfaces can fail with the error
-.BR EINTR
+.B EINTR
after the process is stopped by one of the stop signals
and then resumed via
.BR SIGCONT .
.BR recvfrom (2),
.BR recvmmsg (2)
(also with a non-NULL
-.IR timeout
+.I timeout
argument),
and
.BR recvmsg (2).
field of the
.I "struct nlmsghdr"
header has the
-.BR NLM_F_DUMP
+.B NLM_F_DUMP
flag set, it means that a list of sockets is being requested;
otherwise it is a query about an individual socket.
.\"
.PP
The following attributes are reported back without any specific request:
.TP
-.BR UNIX_DIAG_SHUTDOWN
+.B UNIX_DIAG_SHUTDOWN
The payload associated with this attribute is __u8 value which represents
bits of
.BR shutdown (2)
.TP
.I udiag_state
This is set to one of
-.BR TCP_LISTEN
+.B TCP_LISTEN
or
.BR TCP_ESTABLISHED .
.TP
The payload associated with
.B UNIX_DIAG_MEMINFO
and
-.BR INET_DIAG_SKMEMINFO
+.B INET_DIAG_SKMEMINFO
netlink attributes is an array of the following __u32 values:
.TP
.B SK_MEMINFO_RMEM_ALLOC
.PP
.B UNIX_DIAG_MEMINFO
and
-.BR INET_DIAG_SKMEMINFO
+.B INET_DIAG_SKMEMINFO
were introduced in Linux 3.6.
.SH CONFORMING TO
The NETLINK_SOCK_DIAG API is Linux-specific.
To allow any type of socket address to be passed to
interfaces in the sockets API,
the type
-.IR "struct sockaddr"
+.I struct sockaddr
is defined.
The purpose of this type is purely to allow casting of
domain-specific socket address types to a "generic" type,
packet's data length, the packet is allowed to proceed unmodified.
.IP
The argument for
-.BR SO_ATTACH_FILTER
+.B SO_ATTACH_FILTER
is a
.I sock_fprog
structure, defined in
.in
.IP
The argument for
-.BR SO_ATTACH_BPF
+.B SO_ATTACH_BPF
is a file descriptor returned by the
.BR bpf (2)
system call and must refer to a program of type
.TP
.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF
For use with the
-.BR SO_REUSEPORT
+.B SO_REUSEPORT
option, these options allow the user to set a classic BPF
.RB ( SO_ATTACH_REUSEPORT_CBPF )
or an extended BPF
.RB ( SO_ATTACH_REUSEPORT_EBPF )
program which defines how packets are assigned to
the sockets in the reuseport group (that is, all sockets which have
-.BR SO_REUSEPORT
+.B SO_REUSEPORT
set and are using the same local address to receive packets).
.IP
The BPF program must return an index between 0 and N\-1 representing
(where N is the number of sockets in the group).
If the BPF program returns an invalid index,
socket selection will fall back to the plain
-.BR SO_REUSEPORT
+.B SO_REUSEPORT
mechanism.
.IP
Sockets are numbered in the order in which they are added to the group
These options may be set repeatedly at any time on any socket in the group
to replace the current BPF program used by all sockets in the group.
.IP
-.BR SO_ATTACH_REUSEPORT_CBPF
+.B SO_ATTACH_REUSEPORT_CBPF
takes the same argument type as
-.BR SO_ATTACH_FILTER
+.B SO_ATTACH_FILTER
and
-.BR SO_ATTACH_REUSEPORT_EBPF
+.B SO_ATTACH_REUSEPORT_EBPF
takes the same argument type as
.BR SO_ATTACH_BPF .
.IP
.I optlen
argument should contain the buffer size available
to receive the device name and is recommended to be
-.BR IFNAMSIZ
+.B IFNAMSIZ
bytes.
The real device name length is reported back in the
.I optlen
These two options, which are synonyms,
may be used to remove the classic or extended BPF
program attached to a socket with either
-.BR SO_ATTACH_FILTER
+.B SO_ATTACH_FILTER
or
.BR SO_ATTACH_BPF .
The option value is ignored.
.IP
The typical use case is for a privileged process to set up a raw socket
(an operation that requires the
-.BR CAP_NET_RAW
+.B CAP_NET_RAW
capability), apply a restrictive filter, set the
-.BR SO_LOCK_FILTER
+.B SO_LOCK_FILTER
option,
and then either drop its privileges or pass the socket file descriptor
to an unprivileged process via a UNIX domain socket.
.IP
Once the
-.BR SO_LOCK_FILTER
+.B SO_LOCK_FILTER
option has been enabled, attempts to change or remove the filter
attached to a socket, or to disable the
-.BR SO_LOCK_FILTER
+.B SO_LOCK_FILTER
option will fail with the error
.BR EPERM .
.TP
sockets, sets the value of the "peek offset" for the
.BR recv (2)
system call when used with
-.BR MSG_PEEK
+.B MSG_PEEK
flag.
.IP
When this option is set to a negative value
traditional behavior is provided:
.BR recv (2)
with the
-.BR MSG_PEEK
+.B MSG_PEEK
flag will peek data from the front of the queue.
.IP
When the option is set to a value greater than or equal to zero,
If data is removed from the front of the queue via a call to
.BR recv (2)
(or similar) without the
-.BR MSG_PEEK
+.B MSG_PEEK
flag, the "peek offset" will be decreased by the number of bytes removed.
In other words, receiving data without the
.B MSG_PEEK
.IP
For datagram sockets, if the "peek offset" points to the middle of a packet,
the data returned will be marked with the
-.BR MSG_TRUNC
+.B MSG_TRUNC
flag.
.IP
The following example serves to illustrate the use of
.BR SO_PEEK_OFF .
Suppose a stream socket has the following queued input data:
.IP
- aabbccddeeff
+.in +4n
+.EX
+aabbccddeeff
+.EE
+.in
.IP
The following sequence of
.BR recv (2)
and the timeout has been reached, then \-1 is returned with
.I errno
set to
-.BR EAGAIN
+.B EAGAIN
or
.BR EWOULDBLOCK ,
.\" in fact to EAGAIN
.IP
Background: this option was added when waking up on an error condition
occurred only via the
-.IR readfds
+.I readfds
and
-.IR writefds
+.I writefds
sets of
.BR select (2).
The option was added to allow monitoring for error conditions via the
and
.BR poll (2)
will busy poll when they operate on sockets with
-.BR SO_BUSY_POLL
+.B SO_BUSY_POLL
set and no events to report are found.
.IP
In both cases,
The argument is a pointer to a
.IR pid_t .
For further details, see the description of
-.BR F_SETOWN
+.B F_SETOWN
in
.BR fcntl (2).
.TP
.BR EINVAL .
Otherwise, a four-byte value is placed in the data buffer.
This value is the number of elements that can be read from (for
-.IR mbox_stat
+.I mbox_stat
and
.IR ibox_stat )
or written to (for
.IR wbox_stat )
the respective mailbox without blocking or returning an
-.BR EAGAIN
+.B EAGAIN
error.
.RE
.TP
flag.
.RE
.TP
-.IR /fpcr
+.I /fpcr
This file provides access to the Floating Point Status and
Control Register (fcpr) as a binary, four-byte file.
The operations on the
the input data or will be updated to the bitwise OR operation
of the old value and the input data, depending on the contents
of the
-.IR signal1_type
+.I signal1_type
or
-.IR signal2_type
+.I signal2_type
files respectively.
.RE
.TP
.IR /signal1_type ", " /signal2_type
These two files change the behavior of the
-.IR signal1
+.I signal1
and
-.IR signal2
+.I signal2
notification files.
They contain a numeric ASCII string which is read
as either "1" or "0".
.B SPU_CREATE_NOSCHED
flag.
.TP
-.IR /cntl
+.I /cntl
This file provides access to the SPU Run Control and SPU status
registers, as an ASCII string.
The following operations are supported:
4.2BSD was released in 1983.
.IP
Earlier major BSD releases included
-.IR 3BSD
+.I 3BSD
(1980),
.I 4BSD
(1980),
.B POSIX.1c " (formerly known as \fIPOSIX.4a\fP)"
IEEE Std 1003.1c-1995, which describes the POSIX threads interfaces.
.TP
-.BR POSIX.1d
+.B POSIX.1d
IEEE Std 1003.1c-1999, which describes additional real-time extensions.
.TP
.B POSIX.1g
Using the combination of the
.B O_PATH
and
-.BR O_NOFOLLOW
+.B O_NOFOLLOW
flags to
.BR open (2)
yields a file descriptor that can be passed as the
-.IR dirfd
+.I dirfd
argument in system calls such as
.BR fstatat (2),
.BR fchownat (2),
.PP
By default
(i.e., if the
-.BR AT_SYMLINK_FOLLOW
+.B AT_SYMLINK_FOLLOW
flag is not specified), if
.BR name_to_handle_at (2)
is applied to a symbolic link, it yields a handle for the symbolic link
component, and the part following the final slash (i.e.,
.IR c )
is called the
-.IR basename
+.I basename
component.
.\"
.SS Treatment of symbolic links in system calls
and
.IR st_ctime \(emtyped
as
-.IR time_t
+.I time_t
that recorded timestamps with one-second precision.
.PP
Since Linux 2.5.48, the
Nanosecond timestamps were standardized in POSIX.1-2008,
and, starting with version 2.12,
glibc exposes the nanosecond component names if
-.BR _POSIX_C_SOURCE
+.B _POSIX_C_SOURCE
is defined with the value 200809L or greater, or
-.BR _XOPEN_SOURCE
+.B _XOPEN_SOURCE
is defined with the value 700 or greater.
Up to and including glibc 2.19,
the definitions of the nanoseconds components are also defined if
.I include/net/tcp.h
should be modified to keep
.IP
- TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog
+.in +4n
+.EX
+TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog
+.EE
+.in
.IP
and the kernel should be
recompiled.
on a socket.
The default value is calculated using the formula
.IP
- max(87380, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128))
+.in +4n
+.EX
+max(87380, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128))
+.EE
+.in
.IP
(On Linux 2.4, the default is 87380*2 bytes,
lowered to 87380 in low-memory systems).
on a socket.
The default value is calculated using the formula
.IP
- max(65536, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128))
+.in +4n
+.EX
+max(65536, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128))
+.EE
+.in
.IP
(On Linux 2.4, the default value is 128\ kB,
lowered 64\ kB depending on low-memory systems.)
This option allows the caller to set the TCP congestion control
algorithm to be used, on a per-socket basis.
Unprivileged processes are restricted to choosing one of the algorithms in
-.IR tcp_allowed_congestion_control
+.I tcp_allowed_congestion_control
(described above).
Privileged processes
.RB ( CAP_NET_ADMIN )
can choose from any of the available congestion-control algorithms
(see the description of
-.IR tcp_available_congestion_control
+.I tcp_available_congestion_control
above).
.TP
.BR TCP_CORK " (since Linux 2.2)"
.\" commit message.
.\"
This option takes an
-.IR "unsigned int"
+.I unsigned int
as an argument.
When the value is greater than 0,
it specifies the maximum amount of time in milliseconds that transmitted
when the handshake has not completed yet.
Thus the data exchange can commence before the handshake completes.
This option requires enabling the server-side support on sysctl
-.IR net.ipv4.tcp_fastopen
+.I net.ipv4.tcp_fastopen
(see above).
For TCP Fast Open client-side support,
see
This flag causes the received bytes of data to be discarded,
rather than passed back in a caller-supplied buffer.
Since Linux 2.4.4,
-.BR MSG_TRUNC
+.B MSG_TRUNC
also has this effect when used in conjunction with
-.BR MSG_OOB
+.B MSG_OOB
to receive out-of-band data.
.SS Ioctls
The following
.I "calendar time"
via the
.BR clock_gettime (2)
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock,
which returns time (in seconds and nanoseconds) that have
elapsed since the Epoch;
.SH DESCRIPTION
Time namespaces virtualize the values of two system clocks:
.IP \(bu 2
-.BR CLOCK_MONOTONIC
+.B CLOCK_MONOTONIC
(and likewise
-.BR CLOCK_MONOTONIC_COARSE
+.B CLOCK_MONOTONIC_COARSE
and
.BR CLOCK_MONOTONIC_RAW ),
a nonsettable clock that represents monotonic time since\(emas
described by POSIX\(em"some unspecified point in the past".
.IP \(bu
-.BR CLOCK_BOOTTIME
+.B CLOCK_BOOTTIME
(and likewise
.BR CLOCK_BOOTTIME_ALARM ),
a nonsettable clock that is identical to
Currently, the only way to create a time namespace is by calling
.BR unshare (2)
with the
-.BR CLONE_NEWTIME
+.B CLONE_NEWTIME
flag.
This call creates a new time namespace but does
.I not
This allows clock offsets (see below) for the new namespace
to be set before the first process is placed in the namespace.
The
-.IR /proc/[pid]/ns/time_for_children
+.IR /proc/ pid /ns/time_for_children
symbolic link shows the time namespace in which
the children of a process will be created.
(A process can use a file descriptor opened on
on this file fail with the error
.BR EACCES .
In order to write to the
-.IR timens_offsets
+.I timens_offsets
file, a process must have the
-.BR CAP_SYS_TIME
+.B CAP_SYS_TIME
capability in the user namespace that owns the time namespace.
.PP
Writes to the
.TP
.B EPERM
The caller does not have the
-.BR CAP_SYS_TIME
+.B CAP_SYS_TIME
capability.
.TP
.B ERANGE
.I offset-secs
can't be set to a value such that the time on the corresponding clock
inside the namespace would exceed half of the value of the kernel constant
-.BR KTIME_SEC_MAX
+.B KTIME_SEC_MAX
(this limits the clock value to a maximum of approximately 146 years).
.RE
.PP
option.
.PP
Note that time namespaces do not virtualize the
-.BR CLOCK_REALTIME
+.B CLOCK_REALTIME
clock.
Virtualization of this clock was avoided for reasons of complexity
and overhead within the kernel.
For compatibility with the initial implementation, when writing a
.I clock-id
to the
-.IR /proc/[pid]/timens_offsets
+.IR /proc/ pid /timens_offsets
file, the numerical values of the IDs can be written
instead of the symbolic names show above; i.e., 1 instead of
.IR monotonic ,
and boot-time clocks have different values in the new time namespace.
.PP
Examining the
-.I /proc/[pid]/ns/time
+.IR /proc/ pid /ns/time
and
-.I /proc/[pid]/ns/time_for_children
+.IR /proc/ pid /ns/time_for_children
symbolic links, we see that the shell is a member of the initial time
namespace, but its children are created in the new namespace.
.PP
.TP
.I pressure
This value was introduced to follow the format of
-.IR tcp_mem
+.I tcp_mem
(see
.BR tcp (7)).
.TP
.PP
The following two options are specific to UDP-Lite.
.TP
-.BR UDPLITE_SEND_CSCOV
+.B UDPLITE_SEND_CSCOV
This option sets the sender checksum coverage and takes an
.I int
as argument, with a checksum coverage value in the range 0..2^16-1.
If in doubt, the current coverage value can always be queried using
.BR getsockopt (2).
.TP
-.BR UDPLITE_RECV_CSCOV
+.B UDPLITE_RECV_CSCOV
This is the receiver-side analogue and uses the same argument format
and value range as
.BR UDPLITE_SEND_CSCOV .
Part 1 of the standard (ISO 10646-1)
defines the first 65534 code positions (0x0000 to 0xfffd), which form
the
-.IR "Basic Multilingual Plane"
+.I Basic Multilingual Plane
(BMP), that is plane 0 in group 0.
Part 2 of the standard (ISO 10646-2)
adds characters to group 0 outside the BMP in several
(by one of the system calls noted above),
its length is
.IP
- offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1
+.in +4n
+.EX
+offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1
+.EE
+.in
.IP
and
.I sun_path
.IR abstract :
an abstract socket address is distinguished (from a pathname socket)
by the fact that
-.IR sun_path[0]
+.I sun_path[0]
is a null byte (\(aq\e0\(aq).
The socket's address in this namespace is given by the additional
bytes in
-.IR sun_path
+.I sun_path
that are covered by the specified length of the address structure.
(Null bytes in the name have no special significance.)
The name has no connection with filesystem pathnames.
the returned
.I addrlen
is greater than
-.IR "sizeof(sa_family_t)"
+.I sizeof(sa_family_t)
(i.e., greater than 2), and the name of the socket is contained in
the first
-.IR "(addrlen \- sizeof(sa_family_t))"
+.I (addrlen \- sizeof(sa_family_t))
bytes of
.IR sun_path .
.SS Pathname sockets
.I sockaddr_un
structure should have a value of at least:
.IP
-.nf
- offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1
-.fi
+.in +4n
+.EX
+offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1
+.EE
+.in
.IP
or, more simply,
.I addrlen
.B SO_PASSSEC
Enables receiving of the SELinux security label of the peer socket
in an ancillary message of type
-.BR SCM_SECURITY
+.B SCM_SECURITY
(see below).
.IP
The value given as an argument to
.\" commit 37a9a8df8ce9de6ea73349c9ac8bdf6ba4ec4f70
in Linux 4.2.
.TP
-.BR SO_PEEK_OFF
+.B SO_PEEK_OFF
See
.BR socket (7).
.TP
and returns the required length via
.IR optlen .
The caller should allocate at least
-.BR NAME_MAX
+.B NAME_MAX
bytes for the buffer initially, although this is not guaranteed
to be sufficient.
Resizing the buffer to the returned length
.IR sizeof(sa_family_t) ,
.\" i.e., sizeof(short)
or the
-.BR SO_PASSCRED
+.B SO_PASSCRED
socket option was specified for a socket that was
not explicitly bound to an address,
then the socket is autobound to an abstract address.
in the receiving process.
.IP
The kernel constant
-.BR SCM_MAX_FD
+.B SCM_MAX_FD
defines a limit on the number of file descriptors in the array.
Attempting to send an array larger than this limit causes
.BR sendmsg (2)
to fail with the error
.BR EINVAL .
-.BR SCM_MAX_FD
+.B SCM_MAX_FD
has the value 253
(or 255 in kernels
.\" commit bba14de98753cb6599a2dae0e520714b2153522d
The received ancillary data is a null-terminated string containing
the security context.
The receiver should allocate at least
-.BR NAME_MAX
+.B NAME_MAX
bytes in the data portion of the ancillary message for this data.
.IP
To receive the security context, the
If the space allocated for receiving incoming ancillary data is too small
then the ancillary data is truncated to the number of headers
that will fit in the supplied buffer (or, in the case of an
-.BR SCM_RIGHTS
+.B SCM_RIGHTS
file descriptor list, the list of file descriptors may be truncated).
If no buffer is provided for incoming ancillary data (i.e., the
.I msg_control
is NULL),
then the incoming ancillary data is discarded.
In both of these cases, the
-.BR MSG_CTRUNC
+.B MSG_CTRUNC
flag will be set in the
.I msg.msg_flags
value returned by
It occurs if the number of "in-flight" file descriptors exceeds the
.B RLIMIT_NOFILE
resource limit and the caller does not have the
-.BR CAP_SYS_RESOURCE
+.B CAP_SYS_RESOURCE
capability.
An in-flight file descriptor is one that has been sent using
.BR sendmsg (2)
reference to it is closed.
.PP
To pass file descriptors or credentials over a
-.BR SOCK_STREAM
+.B SOCK_STREAM
socket, you must
send or receive at least one byte of nonancillary data in the same
.BR sendmsg (2)
.PP
Applications that retrieve socket addresses can (portably) code
to handle the possibility that there is no null terminator in
-.IR sun_path
+.I sun_path
by respecting the fact that the number of valid bytes in the pathname is:
.PP
- strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
+.in +4n
+.EX
+strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
+.EE
+.in
.\" The following patch to amend kernel behavior was rejected:
.\" http://thread.gmane.org/gmane.linux.kernel.api/2437
.\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path
URI but their use is limited to their reserved purpose
(conflicting data must be escaped before forming the URI):
.IP
- ; / ? : @ & = + $ ,
+.in +4n
+.EX
+; / ? : @ & = + $ ,
+.EE
+.in
.PP
Unreserved characters may be included in a URI.
Unreserved characters
decimal digits, and the following
limited set of punctuation marks and symbols:
.IP
- \- _ . ! \(ti * ' ( )
+.in +4n
+.EX
+\- _ . ! \(ti * ' ( )
+.EE
+.in
.PP
All other characters must be escaped.
An escaped octet is encoded as a character triplet, consisting of the
or
.BR clone (2)
with the
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
flag.
.PP
The kernel imposes (since version 3.11) a limit of 32 nested levels of
or
.BR clone (2)
without the
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
flag is a member of the same user namespace as its parent.
A single-threaded process can join another user namespace with
.BR setns (2)
if it has the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
in that namespace;
upon doing so, it gains a full set of capabilities in that namespace.
.PP
or
.BR unshare (2)
with the
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
flag makes the new child process (for
.BR clone (2))
or the caller (for
a member of the new user namespace created by the call.
.PP
The
-.BR NS_GET_PARENT
+.B NS_GET_PARENT
.BR ioctl (2)
operation can be used to discover the parental relationship
between user namespaces; see
The child process created by
.BR clone (2)
with the
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
flag starts out with a complete set
of capabilities in the new user namespace.
Likewise, a process that creates a new user namespace using
or
.BR unshare (2)
using the
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
flag
or a call to
.BR setns (2)
.RS 4
.PD 0
.IP * 2
-.IR /proc
+.I /proc
(since Linux 3.8)
.IP *
-.IR /sys
+.I /sys
(since Linux 3.8)
.IP *
-.IR devpts
+.I devpts
(since Linux 3.9)
.IP *
.BR tmpfs (5)
(since Linux 3.9)
.IP *
-.IR ramfs
+.I ramfs
(since Linux 3.9)
.IP *
-.IR mqueue
+.I mqueue
(since Linux 3.9)
.IP *
-.IR bpf
+.I bpf
.\" commit b2197755b2633e164a439682fb05a9b5ea48f706
(since Linux 4.4)
.IP *
-.IR overlayfs
+.I overlayfs
.\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f
.\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224
(since Linux 5.11)
that process to the mount the cgroup version 2 filesystem and
cgroup version 1 named hierarchies
(i.e., cgroup filesystems mounted with the
-.IR """none,name="""
+.I """none,name="""
option).
.PP
Holding
.PP
Note, however, that mounting block-based filesystems can be done
only by a process that holds
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
in the initial user namespace.
.\"
.\" ============================================================
in the user namespace that owns the nonuser namespace.
.PP
If
-.BR CLONE_NEWUSER
+.B CLONE_NEWUSER
is specified along with other
.B CLONE_NEW*
flags in a single
in that user namespace.
.PP
The
-.BR NS_GET_USERNS
+.B NS_GET_USERNS
.BR ioctl (2)
operation can be used to discover the user namespace
that owns a nonuser namespace; see
it starts out without a mapping of user IDs (group IDs)
to the parent user namespace.
The
-.IR /proc/[pid]/uid_map
+.IR /proc/ pid /uid_map
and
-.IR /proc/[pid]/gid_map
+.IR /proc/ pid /gid_map
files (available since Linux 3.5)
.\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
expose the mappings for user and group IDs
.PP
The description in the following paragraphs explains the details for
.IR uid_map ;
-.IR gid_map
+.I gid_map
is exactly the same,
but each instance of "user ID" is replaced by "group ID".
.PP
.I uid_map
file exposes the mapping of user IDs from the user namespace
of the process
-.IR pid
+.I pid
to the user namespace of the process that opened
-.IR uid_map
+.I uid_map
(but see a qualification to this point below).
In other words, processes that are in different user namespaces
will potentially see different values when reading from a particular
How field two is interpreted depends on whether the process that opened
.I uid_map
and the process
-.IR pid
+.I pid
are in the same user namespace, as follows:
.RS
.IP a) 3
and the length of the range is the largest 32-bit unsigned integer.
This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
This is deliberate:
-.IR "(uid_t)\ \-1"
+.I (uid_t)\~\-1
is used in several interfaces (e.g.,
.BR setreuid (2))
as a way to specify "no user ID".
Leaving
-.IR "(uid_t)\ \-1"
+.I (uid_t)\~\-1
unmapped and unusable guarantees that there will be no
confusion when using these interfaces.
.\"
files.
.PP
The lines written to
-.IR uid_map
+.I uid_map
.RI ( gid_map )
must conform to the following validity rules:
.IP * 3
.BR EINVAL .
.PP
In order for a process to write to the
-.I /proc/[pid]/uid_map
-.RI ( /proc/[pid]/gid_map )
+.IR /proc/ pid /uid_map
+.RI ( /proc/ pid /gid_map )
file, all of the following permission requirements must be met:
.IP 1. 3
The writing process must have the
-.BR CAP_SETUID
+.B CAP_SETUID
.RB ( CAP_SETGID )
capability in the user namespace of the process
.IR pid .
in the parent user namespace.
.IP 4.
If updating
-.IR /proc/[pid]/uid_map
+.IR /proc/ pid /uid_map
to create a mapping that maps UID 0 in the parent namespace,
then one of the following must be true:
.RS
.IP * 3
if writing process is in the parent user namespace,
then it must have the
-.BR CAP_SETFCAP
+.B CAP_SETFCAP
capability in that user namespace; or
.IP *
if the writing process is in the child user namespace,
then the process that created the user namespace must have had the
-.BR CAP_SETFCAP
+.B CAP_SETFCAP
capability when the namespace was created.
.RE
.IP
One of the following two cases applies:
.RS
.IP * 3
-.IR Either
+.I Either
the writing process has the
-.BR CAP_SETUID
+.B CAP_SETUID
.RB ( CAP_SETGID )
capability in the
.I parent
in the parent user namespace.
.RE
.IP * 3
-.IR Or
+.I Or
otherwise all of the following restrictions apply:
.RS
.IP + 3
system call must first be denied by writing
.RI \(dq deny \(dq
to the
-.I /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
file (see below) before writing to
.IR gid_map .
.RE
.BR quotactl (2).)
.PP
Project ID mappings are defined by writing to the
-.I /proc/[pid]/projid_map
+.IR /proc/ pid /projid_map
file (present since
.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d
Linux 3.7).
.PP
The validity rules for writing to the
-.I /proc/[pid]/projid_map
+.IR /proc/ pid /projid_map
file are as for writing to the
.I uid_map
file; violation of these rules causes
.BR EINVAL .
.PP
The permission rules for writing to the
-.I /proc/[pid]/projid_map
+.IR /proc/ pid /projid_map
file are as follows:
.IP 1. 3
The writing process must either be in the user namespace of the process
Writing
.RI \(dq deny \(dq
to the
-.I /proc/[pid]/setgroups
+.I /proc/ pid /setgroups
file before writing to
-.I /proc/[pid]/gid_map
+.I /proc/ pid /gid_map
.\" Things changed in Linux 3.19
.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
will permanently disable
.BR setgroups (2)
in a user namespace and allow writing to
-.I /proc/[pid]/gid_map
+.I /proc/ pid /gid_map
without having the
-.BR CAP_SETGID
+.B CAP_SETGID
capability in the parent user namespace.
.\"
.\" ============================================================
.\"
-.SS The /proc/[pid]/setgroups file
+.SS The /proc/ pid /setgroups file
.\"
.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
.\"
The
-.I /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
file displays the string
.RI \(dq allow \(dq
if processes in the user namespace that contains the process
.BR setgroups (2)
is not permitted in that user namespace.
Note that regardless of the value in the
-.I /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
file (and regardless of the process's capabilities), calls to
.BR setgroups (2)
are also not permitted if
-.IR /proc/[pid]/gid_map
+.IR /proc/ pid /gid_map
has not yet been set.
.PP
A privileged process (one with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
capability in the namespace) may write either of the strings
.RI \(dq allow \(dq
or
.I before
writing a group ID mapping
for this user namespace to the file
-.IR /proc/[pid]/gid_map .
+.IR /proc/ pid /gid_map .
Writing the string
.RI \(dq deny \(dq
prevents any process in the user namespace from employing
.PP
The essence of the restrictions described in the preceding
paragraph is that it is permitted to write to
-.I /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
only so long as calling
.BR setgroups (2)
is disallowed because
-.I /proc/[pid]/gid_map
+.IR /proc/ pid /gid_map
has not been set.
This ensures that a process cannot transition from a state where
.BR setgroups (2)
.RI \(dq allow \(dq.
.PP
Once
-.IR /proc/[pid]/gid_map
+.IR /proc/ pid /gid_map
has been written to
(which has the effect of enabling
.BR setgroups (2)
by writing
.RI \(dq deny \(dq
to
-.IR /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
(the write fails with the error
.BR EPERM ).
.PP
A child user namespace inherits the
-.IR /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
setting from its parent.
.PP
If the
this user namespace.
.PP
The
-.I /proc/[pid]/setgroups
+.I /proc/ pid /setgroups
file was added in Linux 3.19,
but was backported to many earlier stable kernel series,
because it addresses a security issue.
might allow a process file access that it did not formerly have.
Before the existence of user namespaces this was not a concern,
since only a privileged process (one with the
-.BR CAP_SETGID
+.B CAP_SETGID
capability) could call
.BR setgroups (2).
However, with the introduction of user namespaces,
users to drop groups and thus gain file access
that they did not previously have.
The
-.I /proc/[pid]/setgroups
+.IR /proc/ pid /setgroups
file was added to address this security issue,
by denying any pathway for an unprivileged process to drop groups with
.BR setgroups (2).
to the overflow user ID (group ID);
the default value for the overflow user ID (group ID) is 65534.
See the descriptions of
-.IR /proc/sys/kernel/overflowuid
+.I /proc/sys/kernel/overflowuid
and
-.IR /proc/sys/kernel/overflowgid
+.I /proc/sys/kernel/overflowgid
in
.BR proc (5).
.PP
.B IPC_STAT
operations,
credentials exposed by
-.IR /proc/[pid]/status
+.IR /proc/ pid /status
and the files in
.IR /proc/sysvipc/* ,
credentials returned via the
in the user namespace.
.PP
The
-.BR CAP_FOWNER
+.B CAP_FOWNER
capability is treated somewhat exceptionally:
.\" These are the checks performed by the kernel function
.\" inode_owner_or_capable(). There is one exception to the exception:
but the process's effective user (group) ID is left unchanged.
(This mirrors the semantics of executing a set-user-ID or set-group-ID
program that resides on a filesystem that was mounted with the
-.BR MS_NOSUID
+.B MS_NOSUID
flag, as described in
.BR mount (2).)
.\"
or
.BR unshare (2)
with the
-.BR CLONE_NEWUTS
+.B CLONE_NEWUTS
flag, the hostname and domain of the new UTS namespace are copied
from the corresponding values in the caller's UTS namespace.
.PP
This is used only for locating the vsyscall entry point and is frequently
omitted or set to 0 (meaning it's not available).
This tag is a throwback to the initial vDSO work (see
-.IR History
+.I History
below) and its use should be avoided.
.SS File format
Since the vDSO is a fully formed ELF image, you can do symbol lookups on it.
it will automatically compile and link the vDSO code for you.
You will frequently find it under the architecture-specific directory:
.PP
- find arch/$ARCH/ \-name \(aq*vdso*.so*\(aq \-o \-name \(aq*gate*.so*\(aq
+.in +4n
+.EX
+find arch/$ARCH/ \-name \(aq*vdso*.so*\(aq \-o \-name \(aq*gate*.so*\(aq
+.EE
+.in
.\"
.SS vDSO names
The name of the vDSO varies across architectures.
Simply call into the appropriate offset via the branch instruction,
for example:
.PP
- ble <offset>(%sr2, %r0)
+.in +4n
+.EX
+ble <offset>(%sr2, %r0)
+.EE
+.in
.if t \{\
.ft CW
\}
Bound sockets are automatically updated to the new CID.
.SS Ioctls
The following ioctls are available on the
-.IR /dev/vsock
+.I /dev/vsock
device.
.TP
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
for testing applications on a single host and for debugging.
.PP
The local CID obtained with
-.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID
+.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
can be used for the same purpose, but it is preferable to use
.B VMADDR_CID_LOCAL .
.SH ERRORS
.SS Extended attribute namespaces
Attribute names are null-terminated strings.
The attribute name is always specified in the fully qualified
-.IR namespace.attribute
+.I namespace.attribute
form, for example,
.IR user.mime_type ,
.IR trusted.md5sum ,
.IR system ,
.IR trusted ,
and
-.IR user
+.I user
extended attribute classes are defined as described below.
Additional classes may be added in the future.
.SS Extended security attributes
.BR GCONV_PATH .
However, iconv module configuration caching is used only when
the environment variable
-.BR GCONV_PATH
+.B GCONV_PATH
is not set.
.SH OPTIONS
.TP
Setting the prefix to
.IR foo ,
the gconv module configuration would be read from
-.IR foo/usr/lib/gconv/gconv\-modules
+.I foo/usr/lib/gconv/gconv\-modules
and the cache would be written to
.IR foo/usr/lib/gconv/gconv\-modules.cache .
.TP
.BR DT_RUNPATH ,
.BR DT_AUDIT ,
and
-.BR DT_DEPAUDIT
+.B DT_DEPAUDIT
of ELF binaries,
.IP o 3
in the arguments to the
.I lib64
depending on the architecture
(e.g., on x86-64, it expands to
-.IR lib64
+.I lib64
and
on x86-32, it expands to
.IR lib ).
On some architectures, the Linux kernel doesn't provide a platform
string to the dynamic linker.
The value of this string is taken from the
-.BR AT_PLATFORM
+.B AT_PLATFORM
value in the auxiliary vector (see
.BR getauxval (3)).
.\" To get an idea of the places that $PLATFORM would match,
.IR ORIGIN ,
.IR LIB ,
and
-.IR PLATFORM
+.I PLATFORM
are interpreted as for the
-.BR LD_LIBRARY_PATH
+.B LD_LIBRARY_PATH
environment variable.
.TP
.BI \-\-inhibit\-rpath " list"
.I list
are delimited by colons or spaces.
The objects are preloaded as explained in the description of the
-.BR LD_PRELOAD
+.B LD_PRELOAD
environment variable below.
.IP
By contrast with
.BR LD_PRELOAD ,
the
-.BR \-\-preload
+.B \-\-preload
option provides a way to perform preloading for a single executable
without affecting preloading performed in any child process that executes
a new program.
Each shared object can inform the dynamic linker of the minimum kernel ABI
version that it requires.
(This requirement is encoded in an ELF note section that is viewable via
-.IR "readelf\ \-n"
+.I readelf\~\-n
as a section labeled
.BR NT_GNU_ABI_TAG .)
At run time,
will reject loading shared objects that specify minimum ABI versions
that exceed that ABI version.
.IP
-.BR LD_ASSUME_KERNEL
+.B LD_ASSUME_KERNEL
can be used to
cause the dynamic linker to assume that it is running on a system with
a different kernel ABI version.
On systems that provide multiple versions of a shared object
(in different directories in the search path) that have
different minimum kernel ABI version requirements,
-.BR LD_ASSUME_KERNEL
+.B LD_ASSUME_KERNEL
can be used to select the version of the object that is used
(dependent on the directory search order).
.IP
Historically, the most common use of the
-.BR LD_ASSUME_KERNEL
+.B LD_ASSUME_KERNEL
feature was to manually select the older
LinuxThreads POSIX threads implementation on systems that provided both
LinuxThreads and NPTL
.IR $ORIGIN ,
.IR $LIB ,
and
-.IR $PLATFORM
+.I $PLATFORM
(or the versions using curly braces around the names)
as described above in
.IR "Dynamic string tokens" .
if they have set-user-ID mode bit enabled (which is not typical).
.IP
Within the names specified in the
-.BR LD_PRELOAD
+.B LD_PRELOAD
list, the dynamic linker understands the tokens
.IR $ORIGIN ,
.IR $LIB ,
and
-.IR $PLATFORM
+.I $PLATFORM
(or the versions using curly braces around the names)
as described above in
.IR "Dynamic string tokens" .
.RS
.IP (1) 4
The
-.BR LD_PRELOAD
+.B LD_PRELOAD
environment variable.
.IP (2)
The
file (described below).
.RE
.TP
-.BR LD_TRACE_LOADED_OBJECTS
+.B LD_TRACE_LOADED_OBJECTS
If set (to any value), causes the program to list its dynamic
dependencies, as if run by
.BR ldd (1),
.IR "Runtime Linker Auditing Interface" .
.IP
Within the names specified in the
-.BR LD_AUDIT
+.B LD_AUDIT
list, the dynamic linker understands the tokens
.IR $ORIGIN ,
.IR $LIB ,
and
-.IR $PLATFORM
+.I $PLATFORM
(or the versions using curly braces around the names)
as described above in
.IR "Dynamic string tokens" .
do not update the GOT (global offset table) and PLT (procedure linkage table)
after resolving a function symbol.
By combining the use of this variable with
-.BR LD_DEBUG
+.B LD_DEBUG
(with the categories
-.IR bindings
+.I bindings
and
.IR symbols ),
one can observe all run-time function bindings.
.TP 12
.I help
Specifying
-.IR help
+.I help
in the value of this variable does not run the specified program,
and displays a help message about which categories can be specified in this
environment variable.
.TP
.I all
Print all debugging information (except
-.IR statistics
+.I statistics
and
.IR unused ;
see below).
Since glibc 2.3.4,
.B LD_DEBUG
is ignored in secure-execution mode, unless the file
-.IR /etc/suid\-debug
+.I /etc/suid\-debug
exists (the content of the file is irrelevant).
.TP
.BR LD_DEBUG_OUTPUT " (since glibc 2.1)"
"\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile".
.IP
Since glibc 2.2.5,
-.BR LD_PROFILE
+.B LD_PROFILE
is ignored in secure-execution mode.
.TP
.BR LD_PROFILE_OUTPUT " (since glibc 2.1)"
.IP
.B LD_PROFILE_OUTPUT
is ignored in secure-execution mode; instead
-.IR /var/profile
+.I /var/profile
is always used.
(This detail is relevant only before glibc 2.2.5,
since in later glibc versions,
the dynamic linker
will first try to map executable pages using the
.BR mmap (2)
-.BR MAP_32BIT
+.B MAP_32BIT
flag, and fall back to mapping without that flag if that attempt fails.
NB: MAP_32BIT will map to the low 2\ GB (not 4\ GB) of the address space.
.IP
File containing a whitespace-separated list of ELF shared objects to
be loaded before the program.
See the discussion of
-.BR LD_PRELOAD
+.B LD_PRELOAD
above.
If both
-.BR LD_PRELOAD
+.B LD_PRELOAD
and
.I /etc/ld.so.preload
are employed, the libraries specified by
-.BR LD_PRELOAD
+.B LD_PRELOAD
are preloaded first.
.I /etc/ld.so.preload
has a system-wide effect,
and in the trusted directories,
.I /lib
and
-.IR /usr/lib
+.I /usr/lib
(on some 64-bit architectures such as x86-64,
.I /lib
and
-.IR /usr/lib
+.I /usr/lib
are the trusted directories for 32-bit libraries, while
.I /lib64
and
-.IR /usr/lib64
+.I /usr/lib64
are used for 64-bit libraries).
.PP
The cache is used by the run-time linker,
.BR ln (1)
program, it is statically linked.
This means that if for some reason the dynamic linker is not working,
-.BR sln
+.B sln
can be used to make symbolic links to dynamic libraries.
.PP
The command line has two forms.
.I filelist
is a list of space-separated pathname pairs,
and the effect is as if
-.BR sln
+.B sln
was executed once for each line of the file,
with the two pathnames as the arguments.
.PP
.\" This page is in the public domain
.\" %%%LICENSE_END
.\"
-.TH TZSELECT 8 2021-03-22 "" "Linux System Administration"
+.TH TZSELECT 8 2021-03-22 GNU "Linux System Administration"
.SH NAME
tzselect \- select a timezone
.SH SYNOPSIS
projects / thirdparty / man-pages.git / commitdiff
