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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 089aa8b..30abe19 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,12 @@
 2012-02-25  Chong Yidong  <cyd@gnu.org>
 
 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>
        * 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 a4b3a0b..de41efa 100644 (file)
--- 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
 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
 @end defun
 
 @defvar buffer-backed-up

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 69e0003..39e6549 100644 (file)
--- 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}.
 
 @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
 @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
 
 @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
 
 @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.
 
 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
 @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
 
 (@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
 @node File Names
 @section File Names
 @cindex file names

diff --git a/src/ChangeLog b/src/ChangeLog
index 7b54624..1566d62 100644 (file)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-25  Chong Yidong  <cyd@gnu.org>
 
 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.
        * 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 839dc07..7efe919 100644 (file)
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -2798,9 +2798,13 @@ See `file-symlink-p' to distinguish symlinks.  */)
 \f
 DEFUN ("file-selinux-context", Ffile_selinux_context,
        Sfile_selinux_context, 1, 1, 0,
 \f
 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;
   (Lisp_Object filename)
 {
   Lisp_Object absname;


@@ -2853,9 +2857,12 @@ if file does not exist, is not accessible, or SELinux is disabled */)
 \f
 DEFUN ("set-file-selinux-context", Fset_file_selinux_context,
        Sset_file_selinux_context, 2, 2, 0,
 \f
 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;
   (Lisp_Object filename, Lisp_Object context)
 {
   Lisp_Object absname;