Use a single-font-style macro (".B", ".I") for a single argument.
Remove unneeded quotation marks (").
The output from "nroff" and "groff" is unchanged, except for the style
of some quotation marks (") in the file "cgroups.7".
Signed-off-by: Bjarni Ingi Gislason <bjarniig@xxxxxxxxx>
---
man7/cgroup_namespaces.7 | 20 +++---
man7/cgroups.7 | 148 +++++++++++++++++++--------------------
2 files changed, 84 insertions(+), 84 deletions(-)
diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7
index 72a473cf6..b47a857b3 100644
--- a/man7/cgroup_namespaces.7
+++ b/man7/cgroup_namespaces.7
@@ -33,21 +33,21 @@ For an overview of namespaces, see
Cgroup namespaces virtualize the view of a process's cgroups (see
.BR cgroups (7))
as seen via
-.IR /proc/[pid]/cgroup
+.I /proc/[pid]/cgroup
and
.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
+.I /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, it enters a new cgroup namespace in which its current
cgroups directories become the cgroup root directories
of the new namespace.
@@ -108,7 +108,7 @@ to create a process running a new shell in new cgroup and mount namespaces:
.EE
.PP
We then inspect the
-.IR /proc/[pid]/cgroup
+.I /proc/[pid]/cgroup
files of, respectively, the new shell process started by the
.BR unshare (1)
command, a process that is in the original cgroup namespace
@@ -142,7 +142,7 @@ in the new cgroup namespace is also
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
.EX
@@ -216,7 +216,7 @@ We have a process,
.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
@@ -224,23 +224,23 @@ 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, then 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
diff --git a/man7/cgroups.7 b/man7/cgroups.7
index a2dd7efa6..e4eeccb72 100644
--- a/man7/cgroups.7
+++ b/man7/cgroups.7
@@ -52,7 +52,7 @@ such as limiting the amount of CPU time and memory available to a cgroup,
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
@@ -115,7 +115,7 @@ the directory tree mirrors the control group hierarchy.
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
@@ -151,7 +151,7 @@ implementation, and subsequently restored in a more limited form
.\"
.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.
@@ -174,9 +174,9 @@ mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu
.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
@@ -252,7 +252,7 @@ have been moved from those cgroups to the root cgroup.
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 )
@@ -305,7 +305,7 @@ Further information can be found in the kernel source file
.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
@@ -405,7 +405,7 @@ echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs
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
@@ -414,7 +414,7 @@ all threads in the process are moved into the new cgroup at once.
.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
@@ -433,7 +433,7 @@ another cgroup by writing its thread ID
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.
@@ -458,15 +458,15 @@ can be used to register the pathname of a program that may be invoked when
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
@@ -481,16 +481,16 @@ mount -o release_agent=pathname ...
.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,
@@ -537,7 +537,7 @@ only in leaf nodes (cgroups that do not themselves contain child cgroups).
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.
@@ -551,7 +551,7 @@ file that is employed by the
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
@@ -591,7 +591,7 @@ makes heavy use of some v1 controllers by default,
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,
@@ -650,7 +650,7 @@ controllers.
.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.
@@ -660,11 +660,11 @@ file in the parent 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,
@@ -760,9 +760,9 @@ the "no internal processes" rule has been relaxed in some cases.
With cgroups v2, a new mechanism is provided to obtain notification
about 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 a new, more general-purpose file,
.IR cgroup.events .
This read-only file contains key-value pairs
@@ -776,13 +776,13 @@ contain no (nonzombie) processes,
or 1, meaning that the cgroup contains member processes.
.PP
The
-.IR cgroup.events
+.I cgroup.events
file can be monitored, in order to receive notification when a cgroup
transitions between the populated and unpopulated states (or vice versa).
When monitoring this file using
.BR inotify (7),
transitions generate
-.BR IN_MODIFY
+.B IN_MODIFY
events, and when monitoring the file using
.BR poll (2),
transitions cause the bits
@@ -790,7 +790,7 @@ transitions cause the bits
and
.B POLLERR
to be returned in the
-.IR revents
+.I revents
field.
.PP
The cgroups v2 release-notification mechanism provided by the
@@ -798,11 +798,11 @@ The cgroups v2 release-notification mechanism provided by the
field of the
.I cgroup.events
file offers at least two advantages over the cgroups v1
-.IR release_agent
+.I release_agent
mechanism.
First, it allows for cheaper notification,
since a single process can monitor multiple
-.IR cgroup.events
+.I cgroup.events
files.
By contrast, the cgroups v1 mechanism requires the creation
of a process for each notification.
@@ -812,7 +812,7 @@ a container associated with the newly empty cgroup.
.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:
@@ -850,10 +850,10 @@ fails with the error
.BR EAGAIN ).
.IP
Writing the string
-.IR """max"""
+.RI """" max """"
to this file means that no limit is imposed.
The default value in this file is
-.IR """max""" .
+.RI """" max """."
.TP
.IR cgroup.max.descendants " (since Linux 4.14)"
.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1
@@ -865,10 +865,10 @@ fails with the error
.BR EAGAIN ).
.IP
Writing the string
-.IR """max"""
+.RI """" max """"
to this file means that no limit is imposed.
The default value in this file is
-.IR """max""" .
+.RI """" max """."
.\"
.SH CGROUPS DELEGATION: DELEGATING A HIERARCHY TO A LESS PRIVILEGED USER
In the context of cgroups,
@@ -901,12 +901,12 @@ Assuming that we want to delegate the hierarchy rooted at (say)
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
@@ -926,7 +926,7 @@ This permits the delegatee to write thread IDs to the file.
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
@@ -946,7 +946,7 @@ and the delegatee should not have permission to change
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,
@@ -996,7 +996,7 @@ will fail with the error
.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.
@@ -1075,14 +1075,14 @@ with the desired options after boot-up.
.\"
.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
@@ -1146,7 +1146,7 @@ cgroups.)
.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
@@ -1156,7 +1156,7 @@ for cgroups v2.
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.)
@@ -1201,9 +1201,9 @@ 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"""
+.RI """" threaded """"
to the
.I cgroup.type
file.
@@ -1245,18 +1245,18 @@ There are two pathways that lead to the creation of a threaded subtree.
The first pathway proceeds as follows:
.IP 1. 3
We write the string
-.IR """threaded"""
+.RI """" 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 *
@@ -1268,9 +1268,9 @@ The parent cgroup is the root of a threaded subtree
(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
@@ -1282,19 +1282,19 @@ will also have the type
.RE
.IP 2.
We write the string
-.IR """threaded"""
+.RI """" 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"""
+.RI """" threaded """"
to each of these cgroups is somewhat cumbersome,
but allows for possible future extensions to the thread-mode model.
.PP
@@ -1319,15 +1319,15 @@ becomes
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"""
+.RI """" threaded """"
to each of the
-.IR "domain invalid"
+.I domain invalid
cgroups under
.IR y ,
in order to convert them to the type
@@ -1429,7 +1429,7 @@ A number of rules apply when writing to the
file:
.IP * 3
Only the string
-.IR """threaded"""
+.RI """" threaded """"
may be written.
In other words, the only explicit transition that is possible is to convert a
.I domain
@@ -1437,13 +1437,13 @@ cgroup to type
.IR threaded .
.IP *
The effect of writing
-.IR """threaded"""
+.RI """" 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
@@ -1479,35 +1479,35 @@ can itself have member processes.)
.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"""
+.RI """" 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"""
+.RI """" 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
@@ -1518,14 +1518,14 @@ no longer has threaded controllers enabled or
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
@@ -1542,7 +1542,7 @@ and
.I threaded
cgroups.
If the string
-.I """threaded"""
+.RI """" threaded """"
is written to the
.I cgroup.type
file of one of the children of the root cgroup, then
@@ -1584,7 +1584,7 @@ if all realtime threads are in the root cgroup.
(If there are realtime threads in nonroot cgroups, then a
.BR write (2)
of the string
-.IR """+cpu"""
+.RI """" +cpu """"
to the
.I cgroup.subtree_control
file fails with the error
@@ -1662,7 +1662,7 @@ The number of control groups in this hierarchy using this controller.
.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
--
2.20.1
