[Selinux-commits] SF.net SVN: selinux: [2486] trunk/libselinux/man

[<ew...@us...>]

Revision: 2486
          http://svn.sourceforge.net/selinux/?rev=2486&view=rev
Author:   ewalsh
Date:     2007-06-20 11:39:27 -0700 (Wed, 20 Jun 2007)

Log Message:
-----------
Add man pages for new labeling and callback interfaces.

Signed-off-by: Eamon Walsh <ew...@ty...>

Modified Paths:
--------------
    trunk/libselinux/man/Makefile

Added Paths:
-----------
    trunk/libselinux/man/man3/selabel_close.3
    trunk/libselinux/man/man3/selabel_lookup.3
    trunk/libselinux/man/man3/selabel_open.3
    trunk/libselinux/man/man3/selabel_stats.3
    trunk/libselinux/man/man3/selinux_set_callback.3
    trunk/libselinux/man/man5/
    trunk/libselinux/man/man5/selabel_file.5
    trunk/libselinux/man/man5/selabel_media.5
    trunk/libselinux/man/man5/selabel_x.5

Modified: trunk/libselinux/man/Makefile
===================================================================
--- trunk/libselinux/man/Makefile	2007-06-20 18:35:39 UTC (rev 2485)
+++ trunk/libselinux/man/Makefile	2007-06-20 18:39:27 UTC (rev 2486)
@@ -1,10 +1,13 @@
 # Installation directories.
 MAN8DIR ?= $(DESTDIR)/usr/share/man/man8
+MAN5DIR ?= $(DESTDIR)/usr/share/man/man5
 MAN3DIR ?= $(DESTDIR)/usr/share/man/man3
 
 install:
 	mkdir -p $(MAN3DIR)
+	mkdir -p $(MAN5DIR)
 	mkdir -p $(MAN8DIR)
 	install -m 644 man3/*.3 $(MAN3DIR)
+	install -m 644 man5/*.5 $(MAN5DIR)
 	install -m 644 man8/*.8 $(MAN8DIR)
 

Added: trunk/libselinux/man/man3/selabel_close.3
===================================================================
--- trunk/libselinux/man/man3/selabel_close.3	                        (rev 0)
+++ trunk/libselinux/man/man3/selabel_close.3	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1 @@
+.so man3/selabel_open.3

Added: trunk/libselinux/man/man3/selabel_lookup.3
===================================================================
--- trunk/libselinux/man/man3/selabel_lookup.3	                        (rev 0)
+++ trunk/libselinux/man/man3/selabel_lookup.3	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,78 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_lookup" "3" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_lookup \- obtain SELinux security context from a string label.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "int selabel_lookup(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup('u
+.BI "security_context_t *" context ,
+.br
+.BI "const char *" key ", int " type ");"
+.in
+.sp
+.BI "int selabel_lookup_raw(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup_raw('u
+.BI "security_context_t *" context ,
+.br
+.BI "const char *" key ", int " type ");"
+
+.SH "DESCRIPTION"
+.B selabel_lookup
+performs a lookup operation on the handle 
+.IR hnd ,
+returning the result in the memory pointed to by 
+.IR context ,
+which must be freed by the caller using
+.BR freecon (3).
+The 
+.I key
+and
+.I type
+parameters are the inputs to the lookup operation and are interpreted according to the specific backend that 
+.I handle
+is open on.
+
+.B selabel_lookup_raw
+behaves identically to 
+.B selabel_lookup
+but does not perform context translation.
+
+.SH "RETURN VALUE"
+On success, zero is returned.  On error, \-1 is returned and
+.I errno
+is set appropriately.
+
+.SH "ERRORS"
+.TP
+.B ENOENT
+No context corresponding to the input 
+.I key
+and
+.I type
+was found.
+.TP
+.B EINVAL
+The
+.I key
+and/or
+.I type
+inputs are invalid, or the context being returned failed validation.
+.TP
+.B ENOMEM
+An attempt to allocate memory failed.
+
+.SH "AUTHOR"
+Eamon Walsh <ew...@ty...>
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR selabel_stats (3),
+.BR selinux_set_callback (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man3/selabel_open.3
===================================================================
--- trunk/libselinux/man/man3/selabel_open.3	                        (rev 0)
+++ trunk/libselinux/man/man3/selabel_open.3	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,98 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_open" "3" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_open, selabel_close \- userspace SELinux labeling interface.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "struct selabel_handle *selabel_open(int " backend , 
+.in +\w'struct selabel_handle *selabel_open('u
+.BI "struct selinux_opt *" options ,
+.br
+.BI "unsigned " nopt ");"
+.in
+.sp
+.BI "void selabel_close(struct selabel_handle *" hnd ");"
+
+.SH "DESCRIPTION"
+.B selabel_open
+is used to initialize a labeling handle to be used for lookup operations.  The 
+.I backend
+argument specifies which backend is to be opened; the list of current backends appears in 
+.B BACKENDS
+below.
+
+The 
+.I options
+argument should be NULL or a pointer to an array of 
+.B selinux_opt
+structures of length
+.IR nopt :
+
+.RS
+.ta 4n 16n 24n
+.nf
+struct selinux_opt {
+	int	type;
+	const char	*value;
+};
+.fi
+.ta
+.RE
+
+The available option types are described in 
+.B GLOBAL OPTIONS
+below as well as in the documentation for each individual backend.  The return value on success is a non-NULL value for use in subsequent label operations.
+
+.B selabel_close
+terminates use of a handle, freeing any internal resources associated with it.  After this call has been made, the handle must not be used again.
+
+.SH "GLOBAL OPTIONS"
+Global options which may be passed to
+.B selabel_open
+include the following:
+
+.TP
+.B SELABEL_OPT_UNUSED
+The option with a type code of zero is a no-op.  Thus an array of options may be initizalized to zero and any untouched elements will not cause an error.
+.TP
+.B SELABEL_OPT_VALIDATE
+A non-null value for this option enables context validation.  By default,
+.BR security_check_context (3)
+is used; a custom validation function can be provided via
+.BR selinux_set_callback (3).
+Note that an invalid context may not be treated as an error unless it is actually encountered during a lookup operation.
+
+.SH "BACKENDS"
+
+.TP
+.B SELABEL_CTX_FILE
+File contexts backend, described in 
+.BR selabel_file (3).
+.TP
+.B SELABEL_CTX_MEDIA
+Media contexts backend, described in 
+.BR selabel_media (3).
+.TP
+.B SELABEL_CTX_X
+X Windows contexts backend, described in 
+.BR selabel_x (3).
+
+.SH "RETURN VALUE"
+A non-NULL handle value is returned on success.  On error, NULL is returned and
+.I errno
+is set appropriately.
+
+.SH "AUTHOR"
+Eamon Walsh <ew...@ty...>
+
+.SH "SEE ALSO"
+.BR selabel_lookup (3),
+.BR selabel_stats (3),
+.BR selinux_set_callback (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man3/selabel_stats.3
===================================================================
--- trunk/libselinux/man/man3/selabel_stats.3	                        (rev 0)
+++ trunk/libselinux/man/man3/selabel_stats.3	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,35 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_stats" "3" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_stats \- obtain SELinux labeling statistics.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "void selabel_lookup(struct selabel_handle *" hnd ");"
+
+.SH "DESCRIPTION"
+.B selabel_stats
+causes zero or more messages to be printed containing backend-specific information about number of queries performed, number of unused entries, or other operational information.
+
+The messages are printed to standard error by default; a custom logging function can be provided via 
+.BR selinux_set_callback (3).
+
+.SH "RETURN VALUE"
+None.
+
+.SH "ERRORS"
+None.
+
+.SH "AUTHOR"
+Eamon Walsh <ew...@ty...>
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR selabel_lookup (3),
+.BR selinux_set_callback (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man3/selinux_set_callback.3
===================================================================
--- trunk/libselinux/man/man3/selinux_set_callback.3	                        (rev 0)
+++ trunk/libselinux/man/man3/selinux_set_callback.3	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,95 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selinux_set_callback" "3" "20 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selinux_set_callback \- userspace SELinux callback facilities.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.BI "void selinux_set_callback(int " type ", union selinux_callback " callback ");"
+
+.SH "DESCRIPTION"
+.B selinux_set_callback
+sets the callback indicated by
+.I type
+to the value of
+.IR callback ,
+which should be passed as a function pointer cast to type
+.B union
+.BR selinux_callback .
+
+All callback functions should return a negative value with
+.I errno
+set appropriately on error.
+
+The available values for 
+.I type
+are:
+.TP
+.B SELABEL_CB_LOG
+.BI "int (*" func_log ") (int " type ", const char *" fmt ", ...);"
+
+This callback is used for logging and should process the 
+.BR printf (3)
+style 
+.I fmt
+string and arguments as appropriate.  The
+.I type
+argument indicates the type of message and will be set to one of the following:
+
+.B SELINUX_ERROR
+.br
+.B SELINUX_WARNING
+.br
+.B SELINUX_INFO
+.br
+.B SELINUX_AVC
+
+.TP
+.B SELABEL_CB_AUDIT
+.BI "int (*" func_audit ") (void *" auditdata ", security_class_t " cls ,
+.in +\w'int (*func_audit) ('u
+.BI "char *" msgbuf ", size_t " msgbufsize ");"
+.in
+
+This callback is used for supplemental auditing in AVC messages.  The
+.I auditdata
+and
+.I cls
+arguments are the values passed to
+.BR avc_has_perm (3).
+A human-readable interpretation should be printed to
+.I msgbuf
+using no more than
+.I msgbufsize
+characters.
+
+.TP
+.B SELABEL_CB_VALIDATE
+.BI "int (*" func_validate ") (security_context_t *" ctx ");"
+
+This callback is used for context validation.  The callback may optionally modify the input context by setting the target of the 
+.I ctx
+pointer to a new context.  In this case, the old value should be freed with
+.BR freecon (3).
+The value of
+.I errno
+should be set to
+.B EINVAL
+to indicate an invalid context.
+
+.SH "RETURN VALUE"
+None.
+
+.SH "ERRORS"
+None.
+
+.SH "AUTHOR"
+Eamon Walsh <ew...@ty...>
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR avc_init (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man5/selabel_file.5
===================================================================
--- trunk/libselinux/man/man5/selabel_file.5	                        (rev 0)
+++ trunk/libselinux/man/man5/selabel_file.5	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,48 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_file" "5" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_file \- userspace SELinux labeling interface: file contexts backend.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "int selabel_lookup(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup('u
+.BI "security_context_t *" context ,
+.br
+.BI "const char *" path ", int " mode ");"
+
+.SH "DESCRIPTION"
+The file contexts backend maps from pathname/mode combinations into security contexts.  It is used to find the appropriate context for each file when relabeling a file system.
+
+The
+.I path
+argument should be set to the full pathname of the file whose assigned context is being checked.  The 
+.I mode
+argument should be set to the mode bits of the file, as determined by 
+.BR lstat (2).
+
+.SH "OPTIONS"
+In addition to the global options described in 
+.BR selabel_open (3),
+this backend recognizes the following options:
+
+.TP
+.B SELABEL_OPT_PATH
+A non-null value for this option specifies a path to a file that will be opened in lieu of the standard file contexts file.  This value is also used as the base name for determining the names of local customization files.
+.TP
+.B SELABEL_OPT_BASEONLY
+A non-null value for this option indicates that any local customizations to the file contexts mapping should be ignored.
+.TP
+.B SELABEL_OPT_SUBSET
+A non-null value for this option is interpreted as a path prefix, for example "/etc".  Only file context specifications starting with the given prefix are loaded.  This may increase lookup performance, however any attempt to look up a path not starting with the given prefix will fail.
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR selabel_lookup (3),
+.BR selabel_stats (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man5/selabel_media.5
===================================================================
--- trunk/libselinux/man/man5/selabel_media.5	                        (rev 0)
+++ trunk/libselinux/man/man5/selabel_media.5	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,37 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_media" "5" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_media \- userspace SELinux labeling interface: media contexts backend.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "int selabel_lookup(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup('u
+.BI "security_context_t *" context ,
+.br
+.BI "const char *" device_name ", int " unused ");"
+
+.SH "DESCRIPTION"
+The media contexts backend maps from media device names such as "cdrom" or "floppy" into security contexts.  It is used to find the appropriate context for establishing context mounts on these devices.
+
+The integer lookup argument is currently unused and should be set to zero.
+
+.SH "OPTIONS"
+In addition to the global options described in 
+.BR selabel_open (3),
+this backend recognizes the following options:
+
+.TP
+.B SELABEL_OPT_PATH
+A non-null value for this option specifies a path to a file that will be opened in lieu of the standard media contexts file.  
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR selabel_lookup (3),
+.BR selabel_stats (3),
+.BR selinux (8)
+

Added: trunk/libselinux/man/man5/selabel_x.5
===================================================================
--- trunk/libselinux/man/man5/selabel_x.5	                        (rev 0)
+++ trunk/libselinux/man/man5/selabel_x.5	2007-06-20 18:39:27 UTC (rev 2486)
@@ -0,0 +1,54 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh (ew...@ty...) 2007
+.TH "selabel_x" "5" "18 Jun 2007" "" "SELinux API documentation"
+.SH "NAME"
+selabel_x \- userspace SELinux labeling interface: X Window System contexts backend.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.br
+.B #include <selinux/label.h>
+.sp
+.BI "int selabel_lookup(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup('u
+.BI "security_context_t *" context ,
+.br
+.BI "const char *" object_name ", int " object_type ");"
+
+.SH "DESCRIPTION"
+The X contexts backend maps from X Window System object names into security contexts.  It is used to find the appropriate context for X Window System objects whose significance and/or usage semantics are determined primarily by name.  This backend is also used to determine the default context for labeling remotely connected X clients.
+
+The
+.I object_type
+argument should be set to one of the following values:
+.TP
+.B SELABEL_X_PROP
+The
+.I object_name
+argument specifies the name of a window property, such as "WM_NAME".
+.TP
+.B SELABEL_X_EXT
+The
+.I object_name
+argument specifies the name of a protocol extension, such as "RENDER".
+.TP
+.B SELABEL_X_CLIENT
+The
+.I object_name
+argument is ignored and should be set to NULL.  The default context for labeling remote X clients is returned.
+
+.SH "OPTIONS"
+In addition to the global options described in 
+.BR selabel_open (3),
+this backend recognizes the following options:
+
+.TP
+.B SELABEL_OPT_PATH
+A non-null value for this option specifies a path to a file that will be opened in lieu of the standard X contexts file.  
+
+.SH "SEE ALSO"
+.BR selabel_open (3),
+.BR selabel_lookup (3),
+.BR selabel_stats (3),
+.BR selinux (8)
+


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.