From fa74b241a324c5c44c4223c2d1b4c2fcb605eb72 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 25 Feb 2012 17:07:23 +0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 7 +++++ doc/lispref/backups.texi | 13 ++++---- doc/lispref/files.texi | 64 ++++++++++++++++++++++++++++------------ src/ChangeLog | 3 ++ src/fileio.c | 19 ++++++++---- 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 + * 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 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 + * 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; -- 2.39.2