Skip to contentSkip to conversation

cap_get_proc.3: Typo fixes

PATCH In review Michael Kerrisk (man-pages) 2 participants 5 messages Jun 10, 2020 – Jun 11, 2020 Security (LSM)

lore
Share & tools
lore
#0 lore raw

PATCH 1/4 cap_get_proc.3: Typo fixes

---
 doc/cap_get_proc.3 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
doc/cap_get_proc.3 +3 -3
index 3eef3f7..c2ce212 100644
@@ -87,7 +87,7 @@ with a
 .I  cap
 as an argument returns the current value of this bounding set
 capability flag in effect for the current process. This operation is
-unpriveged. Note, a macro function
+unprivileged. Note, a macro function
 .BR "CAP_IS_SUPPORTED(cap_value_t " cap )
 is provided that evaluates to true (1) if the system supports the
 specified capability,
@@ -216,7 +216,7 @@ On failure,
 .I errno
 is set to
 .BR EINVAL ,
-.BR EPERM,
+.BR EPERM ,
 or
 .BR ENOMEM .
 .SH "CONFORMING TO"
@@ -298,7 +298,7 @@ Linux.  Note that, by default, the only processes that have
 available to them are processes started as a kernel thread.
 (Typically this includes
 .BR init (8),
-kflushd and kswapd). You will need to recompile the kernel to modify
+kflushd and kswapd.) You will need to recompile the kernel to modify
 this default.
 .SH EXAMPLE
 The code segment below raises the
Signature · 1 line
2.26.2
#1 lore raw

PATCH 2/4 cap_get_proc.3: for cap_get_pid(), pid==0 means "the calling process"

It's useful to know that when cap_get_pid() gets pid==0, it returns the caller's capabilities.

---
 doc/cap_get_proc.3 | 3 +++
 1 file changed, 3 insertions(+)
doc/cap_get_proc.3 +3 -0
index c2ce212..0238601 100644
@@ -78,6 +78,9 @@ see
 .BR cap_init (3),
 with the process capabilities of the process indicated by
 .IR pid .
+(If
+.I pid
+is 0, then the calling process's capabilities are returned.)
 This information can also be obtained from the
 .I /proc/<pid>/status
 file.
Signature · 1 line
2.26.2
#2 lore raw

PATCH 3/4 getpcaps.8: Note that pid==0 displays capabilities of getpcaps itself

In reply to Michael Kerrisk (man-pages)

When experimenting with capabilities, it's useful to know that pid==0 causes getpcaps to display its own capabilities.

---
 doc/getpcaps.8 | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)
doc/getpcaps.8 +8 -1
index be9935f..aaaf0a2 100644
@@ -10,7 +10,14 @@ getpcaps \- display process capabilities
 .B getpcaps
 displays the capabilities on the processes indicated by the
 .I pid
-value(s) given on the commandline. The capabilities are displayed in
+value(s) given on the command line.
+A
+.I pid
+of 0 displays the capabilities of the process that is running
+.B getpcaps
+itself.
+.PP
+The capabilities are displayed in
 the
 .BR cap_from_text (3)
 format.
Signature · 1 line
2.26.2
#3 lore raw

PATCH 4/4 cap_get_proc.3: change "current process" to "calling process"

In reply to Michael Kerrisk (man-pages)

The term "current process" is kernel-developer speak that is often not understood by user-space programmers. Change to "calling process", which is clearer.

---
 doc/cap_get_proc.3 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
doc/cap_get_proc.3 +10 -10
index 0238601..b0a61d1 100644
@@ -89,7 +89,7 @@ file.
 with a
 .I  cap
 as an argument returns the current value of this bounding set
-capability flag in effect for the current process. This operation is
+capability flag in effect for the calling process. This operation is
 unprivileged. Note, a macro function
 .BR "CAP_IS_SUPPORTED(cap_value_t " cap )
 is provided that evaluates to true (1) if the system supports the
@@ -122,11 +122,11 @@ capability set must have a raised
 .BR CAP_SETPCAP .
 Further, to raise a specific ambient capability the
 .IR inheritable " and " permitted
-sets of the current process must contain the specified capability, and
+sets of the calling process must contain the specified capability, and
 raised ambient bits will only be retained as long as this remains true.
 .PP
 .BR cap_reset_ambient ()
-resets all of the ambient capabilities for the current process to
+resets all of the ambient capabilities for the calling process to
 their lowered value. To complete successfully, the prevailing
 .I effective
 capability set must have a raised
@@ -139,12 +139,12 @@ changes to the inheritable set by the program code without explicitly
 fixing up the ambient set can also drop ambient bits.
 .PP
 .BR cap_get_secbits ()
-returns the securebits of the current process. These bits affect the
-way in which the current process implements things like setuid-root
+returns the securebits of the calling process. These bits affect the
+way in which the calling process implements things like setuid-root
 fixup and ambient capabilities.
 .PP
 .BR cap_set_secbits ()
-attempts to modify the securebits of the current process. Note
+attempts to modify the securebits of the calling process. Note
 .B CAP_SETPCAP
 must be in the effective capability set for this to be effective. Some
 settings lock the sub-states of the securebits, so attempts to set values
@@ -274,13 +274,13 @@ attempts to set the capabilities of some other process(es),
 If
 .I pid
 is positive it refers to a specific process;  if it is zero, it refers
-to the current process; \-1 refers to all processes other than the
-current process and process '1' (typically 
+to the calling process; \-1 refers to all processes other than the
+calling process and process '1' (typically 
 .BR init (8));
 other negative values refer to the
 .I \-pid
 process group.  In order to use this function, the kernel must support
-it and the current process must have
+it and the calling process must have
 .B CAP_SETPCAP
 raised in its Effective capability set. The capabilities set in the
 target process(es) are those contained in
@@ -288,7 +288,7 @@ target process(es) are those contained in
 Kernels that support filesystem capabilities redefine the semantics of
 .B CAP_SETPCAP
 and on such systems this function will always fail for any target not
-equal to the current process.
+equal to the calling process.
 .BR capsetp ()
 returns zero for success, and \-1 on failure.
 
Signature · 1 line
2.26.2
#4 lore raw

Re: [PATCH 4/4] cap_get_proc.3: change "current process" to "calling process"

Thanks. All applied:

https://git.kernel.org/pub/scm/libs/libcap/libcap.git/commit/?id=589f1f1624528a5153e27f6c54ae49d7beaa183f

Cheers

Andrew

Quoted 82 lines · Michael Kerrisk (man-pages)

The term "current process" is kernel-developer speak that is often not understood by user-space programmers. Change to "calling process", which is clearer.

---
 doc/cap_get_proc.3 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
doc/cap_get_proc.3 +10 -11
index 0238601..b0a61d1 100644
@@ -89,7 +89,7 @@ file.
 with a
 .I  cap
 as an argument returns the current value of this bounding set
-capability flag in effect for the current process. This operation is
+capability flag in effect for the calling process. This operation is
 unprivileged. Note, a macro function
 .BR "CAP_IS_SUPPORTED(cap_value_t " cap )
 is provided that evaluates to true (1) if the system supports the
@@ -122,11 +122,11 @@ capability set must have a raised
 .BR CAP_SETPCAP .
 Further, to raise a specific ambient capability the
 .IR inheritable " and " permitted
-sets of the current process must contain the specified capability, and
+sets of the calling process must contain the specified capability, and
 raised ambient bits will only be retained as long as this remains true.
 .PP
 .BR cap_reset_ambient ()
-resets all of the ambient capabilities for the current process to
+resets all of the ambient capabilities for the calling process to
 their lowered value. To complete successfully, the prevailing
 .I effective
 capability set must have a raised
@@ -139,12 +139,12 @@ changes to the inheritable set by the program code without explicitly
 fixing up the ambient set can also drop ambient bits.
 .PP
 .BR cap_get_secbits ()
-returns the securebits of the current process. These bits affect the
-way in which the current process implements things like setuid-root
+returns the securebits of the calling process. These bits affect the
+way in which the calling process implements things like setuid-root
 fixup and ambient capabilities.
 .PP
 .BR cap_set_secbits ()
-attempts to modify the securebits of the current process. Note
+attempts to modify the securebits of the calling process. Note
 .B CAP_SETPCAP
 must be in the effective capability set for this to be effective. Some
 settings lock the sub-states of the securebits, so attempts to set values
@@ -274,13 +274,13 @@ attempts to set the capabilities of some other process(es),
 If
 .I pid
 is positive it refers to a specific process;  if it is zero, it refers
-to the current process; \-1 refers to all processes other than the
-current process and process '1' (typically
+to the calling process; \-1 refers to all processes other than the
+calling process and process '1' (typically
 .BR init (8));
 other negative values refer to the
 .I \-pid
 process group.  In order to use this function, the kernel must support
-it and the current process must have
+it and the calling process must have
 .B CAP_SETPCAP
 raised in its Effective capability set. The capabilities set in the
 target process(es) are those contained in
@@ -288,7 +288,7 @@ target process(es) are those contained in
 Kernels that support filesystem capabilities redefine the semantics of
 .B CAP_SETPCAP
 and on such systems this function will always fail for any target not
-equal to the current process.
+equal to the calling process.
 .BR capsetp ()
 returns zero for success, and \-1 on failure.
 
--

2.26.2