[PATCH] libselinux: improve getcon(3) man page

[PATCH] libselinux: improve getcon(3) man page

[Christian Göttsche]

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.

Signed-off-by: Christian Göttsche <cgzones@googlemail.com>
---
 libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 12 deletions(-)

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

Re: [PATCH] libselinux: improve getcon(3) man page

[Petr Lautrbach]

Christian Göttsche <cgzones@googlemail.com> writes:

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


> 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.
>
> Signed-off-by: Christian Göttsche <cgzones@googlemail.com>
>

Acked-by: Petr Lautrbach <plautrba@redhat.com>

Thanks!


> ---
>  libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
>  1 file changed, 29 insertions(+), 12 deletions(-)
>
> diff --git a/libselinux/man/man3/getcon.3 b/libselinux/man/man3/getcon.3
> index 67872a4d..e7e394f3 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
> @@ -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)"
> -- 
> 2.32.0.rc2

Re: [PATCH] libselinux: improve getcon(3) man page

[Petr Lautrbach]

Petr Lautrbach <plautrba@redhat.com> writes:

> Christian Göttsche <cgzones@googlemail.com> writes:
>
>> 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.
>
>
>> 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.
>>
>> Signed-off-by: Christian Göttsche <cgzones@googlemail.com>
>>
>
> Acked-by: Petr Lautrbach <plautrba@redhat.com>

Merged.


> Thanks!
>
>
>> ---
>>  libselinux/man/man3/getcon.3 | 41 +++++++++++++++++++++++++-----------
>>  1 file changed, 29 insertions(+), 12 deletions(-)
>>
>> diff --git a/libselinux/man/man3/getcon.3 b/libselinux/man/man3/getcon.3
>> index 67872a4d..e7e394f3 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
>> @@ -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)"
>> -- 
>> 2.32.0.rc2