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
@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 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
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
(@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
\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;
\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;
HCoop / bpt / emacs.git / commitdiff