[Emacs-diffs] /srv/bzr/emacs/trunk r107422: Document SELinux support functions in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107422
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-25 17:07:23 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/backups.texi
  doc/lispref/files.texi
  src/ChangeLog
  src/fileio.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-25 04:03:43 +0000
+++ b/doc/lispref/ChangeLog     2012-02-25 09:07:23 +0000
@@ -1,5 +1,12 @@
 2012-02-25  Chong Yidong  <address@hidden>
 
+       * 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  <address@hidden>

=== modified file 'doc/lispref/backups.texi'
--- a/doc/lispref/backups.texi  2012-02-04 22:04:12 +0000
+++ b/doc/lispref/backups.texi  2012-02-25 09:07:23 +0000
@@ -57,12 +57,13 @@
 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
address@hidden 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
address@hidden are the mode bits of the original file, as returned by
address@hidden (@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

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2012-02-21 13:24:48 +0000
+++ b/doc/lispref/files.texi    2012-02-25 09:07:23 +0000
@@ -1129,6 +1129,18 @@
 
 @xref{Changing Files}, for functions that change file permissions,
 such as @code{set-file-modes}.
+
address@hidden MS-DOS and file modes
address@hidden file modes and MS-DOS
address@hidden 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 @@
 @end table
 @end defun
 
address@hidden MS-DOS and file modes
address@hidden 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},
address@hidden, and some others.  Files that begin with the Unix-standard
address@hidden signature, such as shell and Perl scripts, are also considered
-as executable files.  This is reflected in the values returned by
address@hidden and @code{file-attributes}.  Directories are also
-reported with executable bit set, for compatibility with Unix.
address@hidden 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
address@hidden, see @ref{Changing Files}.
+
address@hidden file-selinux-context filename
+This function returns the SELinux security context of the file
address@hidden  This return value is a list of the form
address@hidden(@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)}.
address@hidden defun
 
 @node Locating Files
 @subsection How to Locate Files in Standard Places
@@ -1528,15 +1550,9 @@
 file.  This works only on some operating systems, and only if you have
 the correct permissions to do so.
 
address@hidden SELinux
-If the optional argument @var{preserve-selinux} is address@hidden, we
-attempt to copy the address@hidden@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 address@hidden, 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 @@
 (@pxref{Time of Day}).
 @end defun
 
address@hidden set-file-selinux-context filename context
+This function sets the SELinux security context of the file
address@hidden 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.
address@hidden defun
+
 @node File Names
 @section File Names
 @cindex file names

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-02-25 03:01:11 +0000
+++ b/src/ChangeLog     2012-02-25 09:07:23 +0000
@@ -1,5 +1,8 @@
 2012-02-25  Chong Yidong  <address@hidden>
 
+       * 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.

=== modified file 'src/fileio.c'
--- a/src/fileio.c      2012-02-21 13:24:48 +0000
+++ b/src/fileio.c      2012-02-25 09:07:23 +0000
@@ -2798,9 +2798,13 @@
 
 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 @@
 
 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;