Skip to contentSkip to conversation

Improve getcon man page

RFC PATCH In review Christian Göttsche 2 participants 2 messages Jul 24, 2020 – Jul 27, 2020 SELinux security module

lore
Share & tools
lore
#0 lore raw

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
index 67872a4d..b618691f 100644
@@ -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
maintainer
#1 lore raw
Quoted 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
index 67872a4d..b618691f 100644

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

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.