[RFC PATCH] Improve getcon man page

[RFC PATCH] Improve getcon man page

[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
---
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(-)

diff --git a/libselinux/man/man3/getcon.3 b/libselinux/man/man3/getcon.3
index 67872a4d..b618691f 100644
--- a/libselinux/man/man3/getcon.3
+++ b/libselinux/man/man3/getcon.3
@@ -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)"
-- 
2.28.0.rc2

Re: [RFC PATCH] Improve getcon man page

[Stephen Smalley]

On Fri, Jul 24, 2020 at 1:57 PM Christian Göttsche
<cgzones@googlemail.com> wrote:
>
> - 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
> ---

> diff --git a/libselinux/man/man3/getcon.3 b/libselinux/man/man3/getcon.3
> index 67872a4d..b618691f 100644
> --- a/libselinux/man/man3/getcon.3
> +++ b/libselinux/man/man3/getcon.3
> @@ -110,6 +120,8 @@ context and the
>  .BR setcon ()
>  will fail if it is not allowed by policy.
>
> +.TP
> +.BR *_raw()

What's this?

>  .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()

Do you mean get*()?  Probably should just enumerate them all since
there aren't very many.

> +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.