Improve getcon man page
RFC PATCH 1/1 Improve getcon man page
- Improve formatting of section DESCRIPTION by adding list points
- Mention errno is set on failure
- Mention the returned context is guaranteed to be non NULL on success
---
I am not an expert writing man pages by hand, so I am not 100% convinced about the format. (It looked fine on Debian via man ./getcon.3)
libselinux/man/man3/getcon.3 | 38 ++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-)
libselinux/man/man3/getcon.3 +28 -10
@@ -7,7 +7,7 @@ freecon, freeconary \- free memory associated with SELinux security contexts getpeercon \- get security context of a peer socket setcon \- set current security context of a process -. + .SH "SYNOPSIS" .B #include <selinux/selinux.h> .sp
@@ -34,27 +34,36 @@ setcon \- set current security context of a process .BI "int setcon(char *" context ); .sp .BI "int setcon_raw(char *" context ); -. + .SH "DESCRIPTION" +.TP .BR getcon () retrieves the context of the current process, which must be free'd with -freecon. +.BR freecon (). +.TP .BR getprevcon () same as getcon but gets the context before the last exec. +.TP .BR getpidcon () -returns the process context for the specified PID. +returns the process context for the specified PID, which must be free'd with +.BR freecon (). +.TP .BR getpeercon () -retrieves context of peer socket, and set -.BI * context -to refer to it, which must be free'd with +retrieves the context of the peer socket, which must be free'd with .BR freecon (). +.TP .BR freecon () frees the memory allocated for a security context. +If +.I con +is NULL, no operation is performed. + +.TP .BR freeconary () frees the memory allocated for a context array.
@@ -62,6 +71,7 @@ If .I con is NULL, no operation is performed. +.TP .BR setcon () sets the current security context of the process to a new value. Note that use of this function requires that the entire application be
@@ -110,6 +120,8 @@ context and the .BR setcon () will fail if it is not allowed by policy. +.TP +.BR *_raw() .BR getcon_raw (), .BR getprevcon_raw (), .BR getpidcon_raw (),
@@ -118,9 +130,15 @@ and .BR setcon_raw () behave identically to their non-raw counterparts but do not perform context translation. -. + .SH "RETURN VALUE" -On error \-1 is returned. On success 0 is returned. -. +On error \-1 is returned with errno set. On success 0 is returned. + +On success all this +.BR *_get() +functions guarantee to allocate and set +.I *context +to a non\-NULL security context. + .SH "SEE ALSO" .BR selinux "(8), " setexeccon "(3)"
Signature · 1 line
2.28.0.rc2
Stephen Smalley
maintainerQuoted 11 lines · Christian Göttsche
- Improve formatting of section DESCRIPTION by adding list points
- Mention errno is set on failure
- Mention the returned context is guaranteed to be non NULL on success
---libselinux/man/man3/getcon.3 +0
-0
libselinux/man/man3/getcon.3 context and the · line 124
Quoted 5 lines
libselinux/man/man3/getcon.3 +2
-0@@ -110,6 +120,8 @@ context and the .BR setcon () will fail if it is not allowed by policy. +.TP +.BR *_raw()
What's this?
Quoted 6 lines
libselinux/man/man3/getcon.3 +0
-0.BR getcon_raw (), .BR getprevcon_raw (), .BR getpidcon_raw (),@@ -118,9 +130,15 @@ and .BR setcon_raw () behave identically to their non-raw counterparts but do not perform context
libselinux/man/man3/getcon.3 and · line 138
Quoted 10 lines
libselinux/man/man3/getcon.3 +5
-3translation. -. + .SH "RETURN VALUE" -On error \-1 is returned. On success 0 is returned. -. +On error \-1 is returned with errno set. On success 0 is returned. + +On success all this +.BR *_get()
Do you mean get*()? Probably should just enumerate them all since there aren't very many.
libselinux/man/man3/getcon.3 and · line 142
Quoted 4 lines
libselinux/man/man3/getcon.3 +4
-0+functions guarantee to allocate and set +.I *context +to a non\-NULL security context. +
I guess technically if we are going to make this promise, then libselinux ought to explicitly implement it on the offhand chance that there is a kernel bug or someone calls one of these libselinux functions while running some other security module that doesn't provide the same guarantee.