Skip to contentSkip to conversation

libselinux: improve getcon(3) man page

PATCH In review Christian Göttsche 2 participants 3 messages Jun 1, 2021 – Jun 9, 2021 SELinux security module

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 libselinux: improve getcon(3) man page

Improve formatting of section DESCRIPTION by adding list points. Mention errno is set on failure.
Mention the returned context might be NULL if SELinux is not enabled. Align setcon/_raw parameter by adding const.

---
 libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 12 deletions(-)
libselinux/man/man3/getcon.3 +29 -12
index 67872a4d..e7e394f3 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
@@ -31,30 +31,39 @@ setcon \- set current security context of a process
 .sp
 .BI "void freeconary(char **" con );
 .sp
-.BI "int setcon(char *" context );
+.BI "int setcon(const char *" context );
 .sp
-.BI "int setcon_raw(char *" context );
-.
+.BI "int setcon_raw(const 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,14 @@ 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.
+
+.SH "NOTES"
+The retrieval functions might return success and set
+.I *context
+to NULL if and only if SELinux is not enabled.
+
 .SH "SEE ALSO"
 .BR selinux "(8), " setexeccon "(3)"
Signature · 1 line
2.32.0.rc2
Acked-by on v1 1/1
#1 lore raw
Quoted 1 line · Christian Göttsche

Improve formatting of section DESCRIPTION by adding list points.

I checked several man pages and it doesn't look like a common construct multi function man pages. But I haven't found any specific guideline related to this and it looks better.

Quoted 6 lines

Mention errno is set on failure.
Mention the returned context might be NULL if SELinux is not enabled. Align setcon/_raw parameter by adding const.

Thanks!

Quoted 102 lines
---
 libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 12 deletions(-)
libselinux/man/man3/getcon.3 +29 -12
index 67872a4d..e7e394f3 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
@@ -31,30 +31,39 @@ setcon \- set current security context of a process
 .sp
 .BI "void freeconary(char **" con );
 .sp
-.BI "int setcon(char *" context );
+.BI "int setcon(const char *" context );
 .sp
-.BI "int setcon_raw(char *" context );
-.
+.BI "int setcon_raw(const 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,14 @@ 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.
+
+.SH "NOTES"
+The retrieval functions might return success and set
+.I *context
+to NULL if and only if SELinux is not enabled.
+
 .SH "SEE ALSO"
 .BR selinux "(8), " setexeccon "(3)"
Signature · 1 line
2.32.0.rc2
#2 lore raw
Quoted 9 lines · Petr Lautrbach
Quoted 1 line · Christian Göttsche

Improve formatting of section DESCRIPTION by adding list points.

I checked several man pages and it doesn't look like a common construct multi function man pages. But I haven't found any specific guideline related to this and it looks better.

Quoted 8 lines
Quoted 6 lines

Mention errno is set on failure.
Mention the returned context might be NULL if SELinux is not enabled. Align setcon/_raw parameter by adding const.

Merged.

Quoted 105 lines

Thanks!

Quoted 102 lines
---
 libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 12 deletions(-)
libselinux/man/man3/getcon.3 +29 -12
index 67872a4d..e7e394f3 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
@@ -31,30 +31,39 @@ setcon \- set current security context of a process
 .sp
 .BI "void freeconary(char **" con );
 .sp
-.BI "int setcon(char *" context );
+.BI "int setcon(const char *" context );
 .sp
-.BI "int setcon_raw(char *" context );
-.
+.BI "int setcon_raw(const 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,14 @@ 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.
+
+.SH "NOTES"
+The retrieval functions might return success and set
+.I *context
+to NULL if and only if SELinux is not enabled.
+
 .SH "SEE ALSO"
 .BR selinux "(8), " setexeccon "(3)"
Signature · 1 line
2.32.0.rc2