Document SELinux support functions in Lisp manual.

* doc/lispref/backups.texi (Making Backups): Return value of backup-buffer is
changed.

* doc/lispref/files.texi (File Attributes): Document file-selinux-context.
(Changing Files): Link to it.
(Changing Files): Document set-file-selinux-context.

* fileio.c (Ffile_selinux_context, Fset_file_selinux_context):
Doc fix.

5 files changed, 75 insertions, 31 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 089aa8ba096..30abe19d192 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,12 @@
 2012-02-25  Chong Yidong  <cyd@gnu.org>
 
+        * files.texi (File Attributes): Document file-selinux-context.
+        (Changing Files): Link to it.
+        (Changing Files): Document set-file-selinux-context.
+
+        * backups.texi (Making Backups): Return value of backup-buffer is
+        changed.
+
         * searching.texi (Regexp Backslash): Add index entry (Bug#10869).
 
 2012-02-24  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index a4b3a0b9bef..de41efacdeb 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -57,12 +57,13 @@ buffer, if appropriate.  It is called by @code{save-buffer} before
 saving the buffer the first time.
 
 If a backup was made by renaming, the return value is a cons cell of
-the form (@var{modes} . @var{backupname}), where @var{modes} are the
-mode bits of the original file, as returned by @code{file-modes}
-(@pxref{File Attributes,, Other Information about Files}), and
-@var{backupname} is the name of the backup.  In all other cases, that
-is, if a backup was made by copying or if no backup was made, this
-function returns @code{nil}.
+the form (@var{modes} @var{context} @var{backupname}), where
+@var{modes} are the mode bits of the original file, as returned by
+@code{file-modes} (@pxref{File Attributes,, Other Information about
+Files}), @var{context} is a list describing the original file's
+SELinux context (@pxref{File Attributes}), and @var{backupname} is the
+name of the backup.  In all other cases, that is, if a backup was made
+by copying or if no backup was made, this function returns @code{nil}.
 @end defun
 
 @defvar buffer-backed-up
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 69e0003a46b..39e6549f4b9 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1129,6 +1129,18 @@ both others and group, and that the sticky bit is set.
 
 @xref{Changing Files}, for functions that change file permissions,
 such as @code{set-file-modes}.
+
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+@strong{MS-DOS note:} On MS-DOS, there is no such thing as an
+``executable'' file mode bit.  So @code{file-modes} considers a file
+executable if its name ends in one of the standard executable
+extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
+others.  Files that begin with the Unix-standard @samp{#!} signature,
+such as shell and Perl scripts, are also considered executable.
+Directories are also reported as executable, for compatibility with
+Unix.  These conventions are also followed by @code{file-attributes},
+below.
 @end defun
 
   If the @var{filename} argument to the next two functions is a
@@ -1304,16 +1316,26 @@ is on the file-system device whose number is 1014478468.
 @end table
 @end defun
 
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
-  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others.  Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files.  This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}.  Directories are also
-reported with executable bit set, for compatibility with Unix.
+@cindex SELinux context
+  SELinux is a Linux kernel feature which provides more sophisticated
+file access controls than ordinary ``Unix-style'' file permissions.
+If Emacs has been compiled with SELinux support on a system with
+SELinux enabled, you can use the function @code{file-selinux-context}
+to retrieve a file's SELinux security context.  For the function
+@code{set-file-selinux-context}, see @ref{Changing Files}.
+
+@defun file-selinux-context filename
+This function returns the SELinux security context of the file
+@var{filename}.  This return value is a list of the form
+@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements
+are the context's user, role, type, and range respectively, as Lisp
+strings.  See the SELinux documentation for details about what these
+actually mean.
+
+If the file does not exist or is inaccessible, or if the system does
+not support SELinux, or if Emacs was not compiled with SELinux
+support, then the return value is @code{(nil nil nil nil)}.
+@end defun
 
 @node Locating Files
 @subsection How to Locate Files in Standard Places
@@ -1528,15 +1550,9 @@ non-@code{nil}, we attempt to copy the user and group ownership of the
 file.  This works only on some operating systems, and only if you have
 the correct permissions to do so.
 
-@cindex SELinux
-If the optional argument @var{preserve-selinux} is non-@code{nil}, we
-attempt to copy the SELinux@footnote{@samp{Security-Enhanced Linux}
-is a kernel feature that allows for finer access controls to be set on
-files, and a system security policy to define who can access what.
-The functions @code{file-selinux-context} and @code{set-file-selinux-context}
-get and set, respectively, the SELinux properties of a file.}
-context of the file.  For this to work, Emacs must have been built
-with libselinux support.
+If the optional argument @var{preserve-selinux} is non-@code{nil}, and
+Emacs has been compiled with SELinux support, this function attempts
+to copy the file's SELinux context (@pxref{File Attributes}).
 @end deffn
 
 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
@@ -1667,6 +1683,16 @@ time and must be in the format returned by @code{current-time}
 (@pxref{Time of Day}).
 @end defun
 
+@defun set-file-selinux-context filename context
+This function sets the SELinux security context of the file
+@var{filename} to @var{context}.  @xref{File Attributes}, for a brief
+description of SELinux contexts.  The @var{context} argument should be
+a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
+return value of @code{file-selinux-context}.  The function does
+nothing if SELinux is disabled, or if Emacs was compiled without
+SELinux support.
+@end defun
+
 @node File Names
 @section File Names
 @cindex file names
diff --git a/src/ChangeLog b/src/ChangeLog
index 7b546244792..1566d6258af 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-25  Chong Yidong  <cyd@gnu.org>
 
+        * fileio.c (Ffile_selinux_context, Fset_file_selinux_context):
+        Doc fix.
+
         * xselect.c (Fx_selection_exists_p): Doc fix.
         (x_clipboard_manager_save_all): Print an informative message
         before saving to clipboard manager.
diff --git a/src/fileio.c b/src/fileio.c
index 839dc07b6ce..7efe919a9f0 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -2798,9 +2798,13 @@ See `file-symlink-p' to distinguish symlinks.  */)
 
 DEFUN ("file-selinux-context", Ffile_selinux_context,
        Sfile_selinux_context, 1, 1, 0,
-       doc: /* Return SELinux context of file named FILENAME,
-as a list ("user", "role", "type", "range"). Return (nil, nil, nil, nil)
-if file does not exist, is not accessible, or SELinux is disabled */)
+       doc: /* Return SELinux context of file named FILENAME.
+The return value is a list (USER ROLE TYPE RANGE), where the list
+elements are strings naming the user, role, type, and range of the
+file's SELinux security context.
+
+Return (nil nil nil nil) if the file is nonexistent or inaccessible,
+or if SELinux is disabled, or if Emacs lacks SELinux support.  */)
   (Lisp_Object filename)
 {
   Lisp_Object absname;
@@ -2853,9 +2857,12 @@ if file does not exist, is not accessible, or SELinux is disabled */)
 
 DEFUN ("set-file-selinux-context", Fset_file_selinux_context,
        Sset_file_selinux_context, 2, 2, 0,
-       doc: /* Set SELinux context of file named FILENAME to CONTEXT
-as a list ("user", "role", "type", "range"). Has no effect if SELinux
-is disabled. */)
+       doc: /* Set SELinux context of file named FILENAME to CONTEXT.
+CONTEXT should be a list (USER ROLE TYPE RANGE), where the list
+elements are strings naming the components of a SELinux context.
+
+This function does nothing if SELinux is disabled, or if Emacs was not
+compiled with SELinux support.  */)
   (Lisp_Object filename, Lisp_Object context)
 {
   Lisp_Object absname;