Use a single-font-change macro for a single argument.
The output from "nroff" and "groff" is unchanged.
Signed-off-by: Bjarni Ingi Gislason <bjarniig@xxxxxxxxx>
---
man2/seccomp.2 | 186 ++++++++++++++++++++++++-------------------------
1 file changed, 93 insertions(+), 93 deletions(-)
diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 191ad3582..41f7dfbf5 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -48,10 +48,10 @@ system call operates on the Secure Computing (seccomp) state of the
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),
@@ -61,7 +61,7 @@ The only system calls that the calling thread is permitted to make are
and
.BR sigreturn (2).
Other system calls result in the delivery of a
-.BR SIGKILL
+.B SIGKILL
signal.
Strict secure computing mode is useful for number-crunching
applications that may need to execute untrusted byte code, perhaps
@@ -72,21 +72,21 @@ Note that although the calling thread can no longer call
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
@@ -95,13 +95,13 @@ to set the hard limit for
.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:
@@ -112,7 +112,7 @@ prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT);
.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 .
@@ -123,7 +123,7 @@ arguments.
If the filter is invalid,
.BR seccomp ()
fails, returning
-.BR EINVAL
+.B EINVAL
in
.IR errno .
.IP
@@ -140,9 +140,9 @@ the existing filters will be preserved across a call to
.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.
@@ -156,9 +156,9 @@ prctl(PR_SET_NO_NEW_PRIVS, 1);
.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
@@ -183,13 +183,13 @@ This will increase evaluation time, but allows for further reduction of
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
@@ -199,11 +199,11 @@ prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args);
.in
.IP
The recognized
-.IR flags
+.I flags
are:
.RS
.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.
@@ -215,18 +215,18 @@ If any thread cannot synchronize to the same filter tree,
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.
.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.
.RE
.TP
@@ -239,14 +239,14 @@ since the kernel treats all unknown actions as
.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.
.SS Filters
When adding filters via
.BR SECCOMP_SET_MODE_FILTER ,
-.IR args
+.I args
points to a filter program:
.PP
.in +4n
@@ -274,7 +274,7 @@ struct sock_filter { /* Filter block */
.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
@@ -302,7 +302,7 @@ the calling conventions of multiple architectures
.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 a whitelisting approach whenever
@@ -313,19 +313,19 @@ are blacklisted), and it is often possible to alter the
representation of a value without altering its meaning, leading to
a blacklist 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/
@@ -341,11 +341,11 @@ is used on the system call number to tell the two ABIs apart.
This means that in order to create a seccomp-based
blacklist for system calls performed through the x86-64 ABI,
it is necessary to not only check that
-.IR arch
+.I arch
equals
.BR AUDIT_ARCH_X86_64 ,
but also to explicitly reject all system calls that contain
-.BR __X32_SYSCALL_BIT
+.B __X32_SYSCALL_BIT
in
.IR nr .
.PP
@@ -364,7 +364,7 @@ and
system calls to prevent the program from subverting such checks.)
.PP
When checking values from
-.IR args
+.I args
against a blacklist, keep in mind that arguments are often
silently truncated before being processed, but after the seccomp check.
For example, this happens if the i386 ABI is used on an
@@ -420,10 +420,10 @@ This value results in immediate termination of the process,
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
@@ -440,7 +440,7 @@ To a parent process that is waiting on this process (using
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 )
@@ -455,7 +455,7 @@ killed by a
.B SIGSYS
signal.
See
-.BR SECCOMP_RET_KILL_PROCESS
+.B SECCOMP_RET_KILL_PROCESS
above.
.IP
.\" See these commits:
@@ -474,16 +474,16 @@ Since Linux 4.11,
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.
.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
@@ -497,12 +497,12 @@ associated with signal:
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
@@ -511,7 +511,7 @@ will contain
.IP *
.I si_errno
will contain the
-.BR SECCOMP_RET_DATA
+.B SECCOMP_RET_DATA
portion of the filter return value.
.RE
.IP
@@ -520,17 +520,17 @@ The program counter will be as though the system call happened
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_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.
@@ -541,13 +541,13 @@ set to
.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
@@ -578,24 +578,24 @@ This value results in the system call being executed after
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)"
@@ -611,24 +611,24 @@ A read-write ordered list of seccomp filter return actions that
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 .
@@ -651,18 +651,18 @@ If the action is
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
@@ -675,7 +675,7 @@ On success,
.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.
@@ -684,48 +684,48 @@ 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 cause of 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 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)" .
.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 ,
@@ -735,10 +735,10 @@ was not valid or the length of the filter program was zero or exceeded
.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
@@ -748,14 +748,14 @@ Note that for the purposes of calculating this limit,
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
@@ -774,16 +774,16 @@ you may prefer to employ the
library, which provides a front-end for generating seccomp filters.
.PP
The
-.IR Seccomp
+.I Seccomp
field of the
-.IR /proc/[pid]/status
+.I /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
@@ -903,7 +903,7 @@ The
.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 EXAMPLE
The program below accepts four or more arguments.
@@ -1127,12 +1127,12 @@ and
.BR seccomp_export_bpf (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)
--
2.20.1
