Add libselinux man pages for colour functions

Add man pages for selinux_raw_context_to_color(5), selinux_colors_path(3) and secolors.conf(5).

Signed-off-by: Richard Haines <richard_c_haines@btinternet.com>
Signed-off-by: Steve Lawrence <slawrence@tresys.com>

2 files changed, 160 insertions, 0 deletions

diff --git a/libselinux/man/man3/selinux_colors_path.3 b/libselinux/man/man3/selinux_colors_path.3
new file mode 100644
index 00000000..851d81dc
--- /dev/null
+++ b/libselinux/man/man3/selinux_colors_path.3
@@ -0,0 +1,36 @@
+.TH "selinux_colors_path" "3" "08 April 2011" "SELinux API documentation"
+
+.SH "NAME"
+selinux_colors_path \- Return a path to the active SELinux policy color configuration file.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.B const char *selinux_colors_path(void);
+
+.SH "DESCRIPTION"
+.B selinux_colors_path
+returns the path to the active policy color configuration file. 
+.sp
+The path is built from the path returned by 
+.BR selinux_policy_root "(3)"
+with 
+.B /secolor.conf
+appended.
+.sp
+This optional configuration file whose format is shown in 
+.BR secolor.conf "(5),"
+controls the colors to be associated with the 
+.I raw
+context components of the
+.BR selinux_raw_context_to_color "(3)"
+function when information is to be displayed by an SELinux color-aware application.
+
+.SH "RETURN VALUE"
+On success, the path to the active policy color configuration file is returned. If a path is not available NULL is returned.
+
+.SH "ERRORS"
+None.
+
+.SH "SEE ALSO"
+.BR selinux "(8), " selinux_policy_root "(3), " selinux_config "(5), " selinux_raw_context_to_color "(3), " secolor.conf  "(5)"
+
diff --git a/libselinux/man/man3/selinux_raw_context_to_color.3 b/libselinux/man/man3/selinux_raw_context_to_color.3
new file mode 100644
index 00000000..af12877d
--- /dev/null
+++ b/libselinux/man/man3/selinux_raw_context_to_color.3
@@ -0,0 +1,124 @@
+.TH "selinux_raw_context_to_color" "3" "08 April 2011" "SELinux API documentation"
+
+.SH "NAME"
+selinux_raw_context_to_color \- Return RGB color string for an SELinux security context.
+
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.BI "int selinux_raw_context_to_color(security_context_t " raw ", "
+.RS
+.BI "char **" color_str ");"
+.RE
+
+.SH "DESCRIPTION"
+.B selinux_raw_context_to_color
+returns a 
+.I color_str
+associated to the raw context 
+.I raw
+provided that the 
+.BR mcstransd "(8)"
+daemon is running, the policy is an MLS type policy (MCS or MLS) and there is a color configuration file
+.BR secolors.conf "(5)"
+(see the
+.B FILES
+section).
+.sp
+The 
+.I color_str
+string is a space separated list of eight hexadecimal RGB triples, each prefixed by a hash character (#). These represent the user:role:type:range components of the foreground and background colors. An example string is shown in the 
+.B EXAMPLE
+section.
+
+The returned
+.I color_str
+string must be freed with 
+.BR free "(3)." 
+
+If a color has not been configured for a specific user, role, type and/or range component of context 
+.IR raw ","
+then
+.B selinux_raw_context_to_color
+will select the color returned in 
+.I color_str
+in order of precedence as follows:
+.RS
+role, type, range
+.br
+user, type, range
+.br
+user, role, range 
+.br
+user, role, type 
+.br
+.RE
+
+If there are no entries in the 
+.B secolor.conf
+file for any of the components of context 
+.I raw
+(or the file is not present), then the default string returned in 
+.I color_str
+is:
+.sp
+.RS
+----- user ---- ---- role ----  ---- type ----  ---- range ----
+.br
+#000000 #ffffff #000000 #ffffff #000000 #ffffff #000000 #ffffff
+.sp
+.RE
+
+.SH "RETURN VALUE"
+On success, zero is returned.
+.br
+On failure, \-1 is returned with 
+.I errno
+set appropriately.
+
+.SH "ERRORS"
+.B ENOENT
+If the 
+.BR mcstransd "(8)"
+daemon is not running. 
+
+.SH "FILES"
+.B selinux_raw_context_to_color
+obtains the translated entry from the active policy 
+.BR secolors.conf "(5)"
+file as returned by
+.BR selinux_colors_path "(3)."
+The file format is described in 
+.BR secolors.conf "(5)."
+
+.SH "NOTES"
+1. The primary use of 
+.B selinux_raw_context_to_color
+is to return a color that corresponds to a range, that can then be used to highlight information at different MLS levels.
+.sp
+2. The 
+.BR mcstransd "(8)"
+daemon process security level must dominate the 
+.I raw
+security level passed to it by the 
+.B selinux_raw_context_to_color
+function. If not, the range color selected will be as defined by the order of precedence.
+
+.SH "EXAMPLE"
+.B selinux_raw_context_to_color
+returns the foreground and background colors of the context string components (user:role:type:range) as RGB triples as follows:
+.sp
+
+      user     :       role      :      type      :      range
+.br
+  fg       bg  :   fg       bg   :  fg       bg   :  fg       bg  
+.br
+#000000 #ffffff  #ffffff #000000  #d2b48c #ffa500  #000000 #008000
+.br
+ black   white :  white   black  : tan    orange  : black   green 
+.br
+
+.SH "SEE ALSO"
+.BR selinux "(8), " selinux_colors_path "(3), " mcstransd "(8), " secolor.conf "(5), " selinux_raw_to_trans_context "(3), " selinux_trans_to_raw_context "(3), " free "(3)"
+
+