SELinux Archive on lore.kernel.org
 help / color / Atom feed
* [RFC PATCH] Improve getcon man page
@ 2020-07-24 17:55 Christian Göttsche
  2020-07-27 13:38 ` Stephen Smalley
  0 siblings, 1 reply; 2+ messages in thread
From: Christian Göttsche @ 2020-07-24 17:55 UTC (permalink / raw)
  To: selinux

- 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


^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: [RFC PATCH] Improve getcon man page
  2020-07-24 17:55 [RFC PATCH] Improve getcon man page Christian Göttsche
@ 2020-07-27 13:38 ` Stephen Smalley
  0 siblings, 0 replies; 2+ messages in thread
From: Stephen Smalley @ 2020-07-27 13:38 UTC (permalink / raw)
  To: Christian Göttsche; +Cc: SElinux list

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.

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, back to index

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-24 17:55 [RFC PATCH] Improve getcon man page Christian Göttsche
2020-07-27 13:38 ` Stephen Smalley

SELinux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/selinux/0 selinux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 selinux selinux/ https://lore.kernel.org/selinux \
		selinux@vger.kernel.org
	public-inbox-index selinux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.selinux


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git