@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Files
@chapter Files
This chapter describes the Emacs Lisp functions and variables to
-find, create, view, save, and otherwise work with files and file
+find, create, view, save, and otherwise work with files and
directories. A few other file-related functions are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{Backups and Auto-Saving}.
Many of the file functions take one or more arguments that are file
-names. A file name is actually a string. Most of these functions
-expand file name arguments by calling @code{expand-file-name}, so that
+names. A file name is a string. Most of these functions expand file
+name arguments using the function @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
-@samp{../}). @xref{File Name Expansion}.
+@file{../}). @xref{File Name Expansion}.
In addition, certain @dfn{magic} file names are handled specially.
For example, when a remote file name is specified, Emacs accesses the
-file over the network via an appropriate protocol (@pxref{Remote
-Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is
+file over the network via an appropriate protocol. @xref{Remote
+Files,, Remote Files, emacs, The GNU Emacs Manual}. This handling is
done at a very low level, so you may assume that all the functions
described in this chapter accept magic file names as file name
arguments, except where noted. @xref{Magic File Names}, for details.
file ``the visited file'' of the buffer.
A file and a buffer are two different things. A file is information
-recorded permanently in the computer (unless you delete it). A buffer,
-on the other hand, is information inside of Emacs that will vanish at
-the end of the editing session (or when you kill the buffer). Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file. The copy in the buffer is what
-you modify with editing commands. Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
-@dfn{save} the buffer, which means copying the altered buffer contents
-back into the file.
-
- In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file'', rather than, ``I am editing a buffer that I
-will soon save as a file of the same name''. Humans do not usually need
-to make the distinction explicit. When dealing with a computer program,
-however, it is good to keep the distinction in mind.
+recorded permanently in the computer (unless you delete it). A
+buffer, on the other hand, is information inside of Emacs that will
+vanish at the end of the editing session (or when you kill the
+buffer). When a buffer is visiting a file, it contains information
+copied from the file. The copy in the buffer is what you modify with
+editing commands. Changes to the buffer do not change the file; to
+make the changes permanent, you must @dfn{save} the buffer, which
+means copying the altered buffer contents back into the file.
+
+ Despite the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa. Indeed, we
+say, ``I am editing a file'', rather than, ``I am editing a buffer
+that I will soon save as a file of the same name''. Humans do not
+usually need to make the distinction explicit. When dealing with a
+computer program, however, it is good to keep the distinction in mind.
@menu
* Visiting Functions:: The usual interface functions for visiting.
which are sometimes useful in user Lisp code: @code{create-file-buffer}
and @code{after-find-file}. This section explains how to use them.
+@c FIXME This does not describe the default behavior, because
+@c uniquify is enabled by default and advises this function.
+@c This is confusing. uniquify should be folded into the function proper.
@defun create-file-buffer filename
This function creates a suitably named buffer for visiting
@var{filename}, and returns it. It uses @var{filename} (sans directory)
as the name if that name is free; otherwise, it appends a string such as
@samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
+Note that the @file{uniquify} library affects the result of this
+function. @xref{Uniquify,,, emacs, The GNU Emacs Manual}.
@strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer.
@section Reading from Files
@cindex reading from files
- You can copy a file from the disk and insert it into a buffer
-using the @code{insert-file-contents} function. Don't use the user-level
-command @code{insert-file} in a Lisp program, as that sets the mark.
+ To copy the contents of a file into a buffer, use the function
+@code{insert-file-contents}. (Don't use the command
+@code{insert-file} in a Lisp program, as that sets the mark.)
@defun insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file @var{filename} into the
file name and its last save file modtime. This feature is used by
@code{find-file-noselect} and you probably should not use it yourself.
-If @var{beg} and @var{end} are non-@code{nil}, they should be integers
-specifying the portion of the file to insert. In this case, @var{visit}
-must be @code{nil}. For example,
+If @var{beg} and @var{end} are non-@code{nil}, they should be numbers
+that are byte offsets specifying the portion of the file to insert.
+In this case, @var{visit} must be @code{nil}. For example,
@example
(insert-file-contents filename nil 0 500)
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any). If @var{append} is an
-integer, @code{write-region} seeks to that byte offset from the start
+to the existing file contents (if any). If @var{append} is a
+number, @code{write-region} seeks to that byte offset from the start
of the file and writes the data from there.
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
When two users edit the same file at the same time, they are likely
to interfere with each other. Emacs tries to prevent this situation
from arising by recording a @dfn{file lock} when a file is being
-modified. (File locks are not implemented on Microsoft systems.)
+modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.
+stored in the same directory as the file you are editing. (On file
+systems that do not support symbolic links, a regular file is used.)
When you access files using NFS, there may be a small probability that
you and another user will both lock the same file ``simultaneously''.
This function locks the file @var{filename}, if the current buffer is
modified. The argument @var{filename} defaults to the current buffer's
visited file. Nothing is done if the current buffer is not visiting a
-file, or is not modified, or if the system does not support locking.
+file, or is not modified, or if the option @code{create-lockfiles} is
+@code{nil}.
@end defun
@defun unlock-buffer
This function unlocks the file being visited in the current buffer,
if the buffer is modified. If the buffer is not modified, then
the file should not be locked, so this function does nothing. It also
-does nothing if the current buffer is not visiting a file, or if the
-system does not support locking.
+does nothing if the current buffer is not visiting a file, or is not locked.
@end defun
- File locking is not supported on some systems. On systems that do not
-support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
-@code{file-locked-p} do nothing and return @code{nil}. It is also
-possible to disable locking, by setting the variable @code{create-lockfiles}.
-
@defopt create-lockfiles
If this variable is @code{nil}, Emacs does not lock files.
@end defopt
@end itemize
If you wish, you can replace the @code{ask-user-about-lock} function
-with your own version that makes the decision in another way. The code
-for its usual definition is in @file{userlock.el}.
+with your own version that makes the decision in another way.
@end defun
@node Information about Files
@section Information about Files
@cindex file, information about
- The functions described in this section all operate on strings that
-designate file names. With a few exceptions, all the functions have
-names that begin with the word @samp{file}. These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
+ This section describes the functions for retrieving various types of
+information about files (or directories or symbolic links), such as
+whether a file is readable or writable, and its size. These functions
+all take arguments which are file names. Except where noted, these
+arguments need to specify existing files, or an error is signaled.
+
+@cindex file names, trailing whitespace
+@cindex trailing blanks in file names
+ Be careful with file names that end in spaces. On some filesystems
+(notably, MS-Windows), trailing whitespace characters in file names
+are silently and automatically ignored.
@menu
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
-* File Attributes:: How large is it? Any other names? Etc.
+* File Attributes:: File sizes, modification times, etc.
+* Extended Attributes:: Extended file attributes for access control.
* Locating Files:: How to find a file in standard places.
@end menu
@cindex accessibility of a file
@cindex file accessibility
- These functions test for permission to access a file in specific
-ways. Unless explicitly stated otherwise, they recursively follow
-symbolic links for their file name arguments, at all levels (at the
-level of the file itself and at all levels of parent directories).
+ These functions test for permission to access a file for reading,
+writing, or execution. Unless explicitly stated otherwise, they
+recursively follow symbolic links for their file name arguments, at
+all levels (at the level of the file itself and at all levels of
+parent directories).
+
+ On some operating systems, more complex sets of access permissions
+can be specified, via mechanisms such as Access Control Lists (ACLs).
+@xref{Extended Attributes}, for how to query and set those
+permissions.
@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears
containing directories, regardless of the permissions of the file
itself.)
-If the file does not exist, or if fascist access control policies
-prevent you from finding the attributes of the file, this function
-returns @code{nil}.
+If the file does not exist, or if access control policies prevent you
+from finding its attributes, this function returns @code{nil}.
Directories are files, so @code{file-exists-p} returns @code{t} when
given a directory name. However, symbolic links are treated
@defun file-readable-p filename
This function returns @code{t} if a file named @var{filename} exists
and you can read it. It returns @code{nil} otherwise.
-
-@example
-@group
-(file-readable-p "files.texi")
- @result{} t
-@end group
-@group
-(file-exists-p "/usr/spool/mqueue")
- @result{} t
-@end group
-@group
-(file-readable-p "/usr/spool/mqueue")
- @result{} nil
-@end group
-@end example
@end defun
-@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it. It returns @code{nil} otherwise. On Unix and
but the specified directory does exist and you can write in that
directory.
-In the third example below, @file{foo} is not writable because the
-parent directory does not exist, even though the user could create such
-a directory.
+In the example below, @file{foo} is not writable because the parent
+directory does not exist, even though the user could create such a
+directory.
@example
@group
-(file-writable-p "~/foo")
- @result{} t
-@end group
-@group
-(file-writable-p "/foo")
- @result{} nil
-@end group
-@group
(file-writable-p "~/no-such-dir/foo")
@result{} nil
@end group
@end example
@end defun
-@c Emacs 19 feature
@defun file-accessible-directory-p dirname
This function returns @code{t} if you have permission to open existing
files in the directory whose name as a file is @var{dirname};
@file{/foo/}) or the file name of a file which is a directory
(such as @file{/foo}, without the final slash).
-Example: after the following,
+For example, from the following we deduce that any attempt to read a
+file in @file{/foo/} will give an error:
@example
(file-accessible-directory-p "/foo")
@result{} nil
@end example
-
-@noindent
-we can deduce that any attempt to read a file in @file{/foo/} will
-give an error.
@end defun
@defun access-file filename string
using @var{string} as the error message text.
@end defun
-@defun file-ownership-preserved-p filename
+@defun file-ownership-preserved-p filename &optional group
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged. It also
returns @code{t} for nonexistent files.
+If the optional argument @var{group} is non-@code{nil}, this function
+also checks that the file's group would be unchanged.
+
If @var{filename} is a symbolic link, then, unlike the other functions
discussed here, @code{file-ownership-preserved-p} does @emph{not}
replace @var{filename} with its target. However, it does recursively
follow symbolic links at all levels of parent directories.
@end defun
-@defun file-newer-than-file-p filename1 filename2
-@cindex file age
-@cindex file modification time
-This function returns @code{t} if the file @var{filename1} is
-newer than file @var{filename2}. If @var{filename1} does not
-exist, it returns @code{nil}. If @var{filename1} does exist, but
-@var{filename2} does not, it returns @code{t}.
-
-In the following example, assume that the file @file{aug-19} was written
-on the 19th, @file{aug-20} was written on the 20th, and the file
-@file{no-file} doesn't exist at all.
+@defun file-modes filename
+@cindex mode bits
+@cindex file permissions
+@cindex permissions, file
+@cindex file modes
+This function returns the @dfn{mode bits} of @var{filename}---an
+integer summarizing its read, write, and execution permissions.
+Symbolic links in @var{filename} are recursively followed at all
+levels. If the file does not exist, the return value is @code{nil}.
+
+@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bits. For example, if the
+low-order bit is 1, the file is executable by all users; if the
+second-lowest-order bit is 1, the file is writable by all users; etc.
+The highest possible value is 4095 (7777 octal), meaning that everyone
+has read, write, and execute permission, the @acronym{SUID} bit is set
+for both others and group, and the sticky bit is set.
+
+@xref{Changing Files}, for the @code{set-file-modes} function, which
+can be used to set these permissions.
@example
@group
-(file-newer-than-file-p "aug-19" "aug-20")
- @result{} nil
+(file-modes "~/junk/diffs")
+ @result{} 492 ; @r{Decimal integer.}
@end group
@group
-(file-newer-than-file-p "aug-20" "aug-19")
- @result{} t
+(format "%o" 492)
+ @result{} "754" ; @r{Convert to octal.}
@end group
+
@group
-(file-newer-than-file-p "aug-19" "no-file")
- @result{} t
+(set-file-modes "~/junk/diffs" #o666)
+ @result{} nil
@end group
+
@group
-(file-newer-than-file-p "no-file" "aug-19")
- @result{} nil
+$ ls -l diffs
+-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
@end group
@end example
-You can use @code{file-attributes} to get a file's last modification
-time as a list of four integers. @xref{File Attributes}.
+@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}
+(@pxref{File Attributes}).
@end defun
@node Kinds of Files
@defun file-symlink-p filename
@cindex file symbolic links
If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} function returns the (non-recursive) link target
-as a string. (Determining the file name that the link points to from
-the target is nontrivial.) First, this function recursively follows
-symbolic links at all levels of parent directories.
-
-If the file @var{filename} is not a symbolic link (or there is no such file),
+@code{file-symlink-p} function returns its (non-recursive) link target
+as a string. (The link target string is not necessarily the full
+absolute file name of the target; determining the full file name that
+the link points to is nontrivial, see below.) If the leading
+directories of @var{filename} include symbolic links, this function
+recursively follows them.
+
+If the file @var{filename} is not a symbolic link, or does not exist,
@code{file-symlink-p} returns @code{nil}.
+Here are a few examples of using this function:
+
@example
@group
-(file-symlink-p "foo")
+(file-symlink-p "not-a-symlink")
@result{} nil
@end group
@group
(file-symlink-p "sym-link")
- @result{} "foo"
+ @result{} "not-a-symlink"
@end group
@group
(file-symlink-p "sym-link2")
@end group
@end example
-@c !!! file-symlink-p: should show output of ls -l for comparison
+Note that in the third example, the function returned @file{sym-link},
+but did not proceed to resolve it, although that file is itself a
+symbolic link. This is what we meant by ``non-recursive'' above---the
+process of following the symbolic links does not recurse if the link
+target is itself a link.
+
+The string that this function returns is what is recorded in the
+symbolic link; it may or may not include any leading directories.
+This function does @emph{not} expand the link target to produce a
+fully-qualified file name, and in particular does not use the leading
+directories, if any, of the @var{filename} argument if the link target
+is not an absolute file name. Here's an example:
+
+@example
+@group
+(file-symlink-p "/foo/bar/baz")
+ @result{} "some-file"
+@end group
+@end example
+
+@noindent
+Here, although @file{/foo/bar/baz} was given as a fully-qualified file
+name, the result is not, and in fact does not have any leading
+directories at all. And since @file{some-file} might itself be a
+symbolic link, you cannot simply prepend leading directories to it,
+nor even naively use @code{expand-file-name} (@pxref{File Name
+Expansion}) to produce its absolute file name.
+
+For this reason, this function is seldom useful if you need to
+determine more than just the fact that a file is or isn't a symbolic
+link. If you actually need the file name of the link target, use
+@code{file-chase-links} or @code{file-truename}, described in
+@ref{Truenames}.
@end defun
The next two functions recursively follow symbolic links at
other I/O device).
@end defun
-@defun file-equal-p file1 file2
-This function returns @code{t} if the files @var{file1} and
-@var{file2} name the same file. If @var{file1} or @var{file2} does
-not exist, the return value is unspecified.
-@end defun
-
-@defun file-in-directory-p file dir
-This function returns @code{t} if @var{file} is a file in directory
-@var{dir}, or in a subdirectory of @var{dir}. It also returns
-@code{t} if @var{file} and @var{dir} are the same directory. It
-compares the @code{file-truename} values of the two directories
-(@pxref{Truenames}). If @var{dir} does not name an existing
-directory, the return value is @code{nil}.
-@end defun
-
@node Truenames
@subsection Truenames
@cindex truename (of file)
substitute-in-file-name}.
If you may need to follow symbolic links preceding @samp{..}@:
-appearing as a name component, you should make sure to call
-@code{file-truename} without prior direct or indirect calls to
-@code{expand-file-name}, as otherwise the file name component
-immediately preceding @samp{..} will be ``simplified away'' before
-@code{file-truename} is called. To eliminate the need for a call to
-@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
-same way that @code{expand-file-name} does. @xref{File Name
-Expansion,, Functions that Expand Filenames}.
+appearing as a name component, call @code{file-truename} without prior
+direct or indirect calls to @code{expand-file-name}. Otherwise, the
+file name component immediately preceding @samp{..} will be
+``simplified away'' before @code{file-truename} is called. To
+eliminate the need for a call to @code{expand-file-name},
+@code{file-truename} handles @samp{~} in the same way that
+@code{expand-file-name} does. @xref{File Name Expansion,, Functions
+that Expand Filenames}.
@end defun
@defun file-chase-links filename &optional limit
@result{} "/home/foo/hello"
@end example
- @xref{Buffer File Name}, for related information.
+@defun file-equal-p file1 file2
+This function returns @code{t} if the files @var{file1} and
+@var{file2} name the same file. This is similar to comparing their
+truenames, except that remote file names are also handled in an
+appropriate manner. If @var{file1} or @var{file2} does not exist, the
+return value is unspecified.
+@end defun
+
+@defun file-in-directory-p file dir
+This function returns @code{t} if @var{file} is a file in directory
+@var{dir}, or in a subdirectory of @var{dir}. It also returns
+@code{t} if @var{file} and @var{dir} are the same directory. It
+compares the truenames of the two directories. If @var{dir} does not
+name an existing directory, the return value is @code{nil}.
+@end defun
@node File Attributes
-@subsection Other Information about Files
+@subsection File Attributes
+@cindex file attributes
This section describes the functions for getting detailed
-information about a file, other than its contents. This information
-includes the mode bits that control access permissions, the owner and
-group numbers, the number of names, the inode number, the size, and
-the times of access and modification.
+information about a file, including the owner and group numbers, the
+number of names, the inode number, the size, and the times of access
+and modification.
-@defun file-modes filename
-@cindex file permissions
-@cindex permissions, file
-@cindex file attributes
-@cindex file modes
-This function returns the @dfn{mode bits} describing the @dfn{file
-permissions} of @var{filename}, as an integer. It recursively follows
-symbolic links in @var{filename} at all levels. If @var{filename}
-does not exist, the return value is @code{nil}.
-
-@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
-Manual}, for a description of mode bits. If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order
-bit is 1, then the file is writable by all users, etc. The highest
-value returnable is 4095 (7777 octal), meaning that everyone has read,
-write, and execute permission, that the @acronym{SUID} bit is set for
-both others and group, and that the sticky bit is set.
+@defun file-newer-than-file-p filename1 filename2
+@cindex file age
+@cindex file modification time
+This function returns @code{t} if the file @var{filename1} is
+newer than file @var{filename2}. If @var{filename1} does not
+exist, it returns @code{nil}. If @var{filename1} does exist, but
+@var{filename2} does not, it returns @code{t}.
+
+In the following example, assume that the file @file{aug-19} was written
+on the 19th, @file{aug-20} was written on the 20th, and the file
+@file{no-file} doesn't exist at all.
@example
@group
-(file-modes "~/junk/diffs")
- @result{} 492 ; @r{Decimal integer.}
+(file-newer-than-file-p "aug-19" "aug-20")
+ @result{} nil
@end group
@group
-(format "%o" 492)
- @result{} "754" ; @r{Convert to octal.}
+(file-newer-than-file-p "aug-20" "aug-19")
+ @result{} t
@end group
-
@group
-(set-file-modes "~/junk/diffs" #o666)
- @result{} nil
+(file-newer-than-file-p "aug-19" "no-file")
+ @result{} t
@end group
-
@group
-% ls -l diffs
- -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
+(file-newer-than-file-p "no-file" "aug-19")
+ @result{} nil
@end group
@end example
-
-@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
target. However, they both recursively follow symbolic links at all
levels of parent directories.
-@defun file-nlinks filename
-This functions returns the number of names (i.e., hard links) that
-file @var{filename} has. If the file does not exist, then this function
-returns @code{nil}. Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files they
-link to.
-
-@example
-@group
-% ls -l foo*
--rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
--rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
-@end group
-
-@group
-(file-nlinks "foo")
- @result{} 2
-@end group
-@group
-(file-nlinks "doesnt-exist")
- @result{} nil
-@end group
-@end example
-@end defun
-
@defun file-attributes filename &optional id-format
@anchor{Definition of file-attributes}
This function returns a list of attributes of file @var{filename}. If
@item
The file's @acronym{UID}, normally as a string. However, if it does
-not correspond to a named user, the value is an integer or a floating
-point number.
+not correspond to a named user, the value is a number.
@item
The file's @acronym{GID}, likewise.
for the file, beyond the file's contents.
@item
-The size of the file in bytes. If the size is too large to fit in a
-Lisp integer, this is a floating point number.
+The size of the file in bytes. This is floating point if the size is
+too large to fit in a Lisp integer.
@item
The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.
@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
+An unspecified value, present for backward compatibility.
@item
The file's inode number. If possible, this is an integer. If the
inode number is too large to be represented as an integer in Emacs
-Lisp but dividing it by @math{2^16} yields a representable integer,
+Lisp but dividing it by @math{2^{16}} yields a representable integer,
then the value has the
form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
bits. If the inode number is too wide for even that, the value is of the form
(20000 23 0 0)
(20614 64555 902289 872000)
122295 "-rw-rw-rw-"
- nil (5888 2 . 43978)
+ t (5888 2 . 43978)
(15479 . 46724))
@end group
@end example
@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
-@item nil
-would retain the same @acronym{GID} if it were recreated.
+@item t
+is merely a placeholder; it carries no information.
@item (5888 2 . 43978)
has an inode number of 6473924464520138.
@end table
@end defun
+@defun file-nlinks filename
+This function returns the number of names (i.e., hard links) that
+file @var{filename} has. If the file does not exist, this function
+returns @code{nil}. Note that symbolic links have no effect on this
+function, because they are not considered to be names of the files
+they link to.
+
+@example
+@group
+$ ls -l foo*
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
+@end group
+
+@group
+(file-nlinks "foo")
+ @result{} 2
+@end group
+@group
+(file-nlinks "doesnt-exist")
+ @result{} nil
+@end group
+@end example
+@end defun
+
+@node Extended Attributes
+@subsection Extended File Attributes
+@cindex extended file attributes
+
+On some operating systems, each file can be associated with arbitrary
+@dfn{extended file attributes}. At present, Emacs supports querying
+and setting two specific sets of extended file attributes: Access
+Control Lists (ACLs) and SELinux contexts. These extended file
+attributes are used, on some systems, to impose more sophisticated
+file access controls than the basic ``Unix-style'' permissions
+discussed in the previous sections.
+
+@cindex access control list
+@cindex ACL entries
@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}.
+ A detailed explanation of ACLs and SELinux is beyond the scope of
+this manual. For our purposes, each file can be associated with an
+@dfn{ACL}, which specifies its properties under an ACL-based file
+control system, and/or an @dfn{SELinux context}, which specifies its
+properties under the SELinux system.
+
+@defun file-acl filename
+This function returns the ACL for the file @var{filename}. The exact
+Lisp representation of the ACL is unspecified (and may change in
+future Emacs versions), but it is the same as what @code{set-file-acl}
+takes for its @var{acl} argument (@pxref{Changing Files}).
+
+The underlying ACL implementation is platform-specific; on GNU/Linux
+and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs
+emulates the POSIX ACL interface with native file security APIs.
+
+If Emacs was not compiled with ACL support, or the file does not exist
+or is inaccessible, or Emacs was unable to determine the ACL entries
+for any other reason, then the return value is @code{nil}.
+@end defun
@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.
+This function returns the SELinux context of the file @var{filename},
+as a list of the form @code{(@var{user} @var{role} @var{type}
+@var{range})}. The list 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. The return value has the
+same form as what @code{set-file-selinux-context} takes for its
+@var{context} argument (@pxref{Changing Files}).
+
+If Emacs was not compiled with SELinux support, or the file does not
+exist or is inaccessible, or if the system does not support SELinux,
+then the return value is @code{(nil nil nil nil)}.
+@end defun
+
+@defun file-extended-attributes filename
+This function returns an alist of the Emacs-recognized extended
+attributes of file @var{filename}. Currently, it serves as a
+convenient way to retrieve both the ACL and SELinux context; you can
+then call the function @code{set-file-extended-attributes}, with the
+returned alist as its second argument, to apply the same file access
+attributes to another file (@pxref{Changing Files}).
-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)}.
+One of the elements is @code{(acl . @var{acl})}, where @var{acl} has
+the same form returned by @code{file-acl}.
+
+Another element is @code{(selinux-context . @var{context})}, where
+@var{context} is the SELinux context, in the same form returned by
+@code{file-selinux-context}.
@end defun
@node Locating Files
-@subsection How to Locate Files in Standard Places
+@subsection Locating Files in Standard Places
@cindex locate file in path
@cindex find file in path
@example
@group
-% ls -li fo*
-81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo
+84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
@end group
@end example
@end group
@group
-% ls -li fo*
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2
+84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
@end group
@end example
@end group
@group
-% ls -li fo*
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3
@end group
@end example
same effect as renaming, aside from momentary intermediate states.
@end deffn
-@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux
+@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-extended-attributes
This command copies the file @var{oldname} to @var{newname}. An
error is signaled if @var{oldname} does not exist. If @var{newname}
names a directory, it copies @var{oldname} into that directory,
interactive call, a prefix argument specifies a non-@code{nil} value
for @var{time}.
-This function copies the file modes, too.
-
If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
system decide the user and group ownership of the new file (this is
usually set to the user running Emacs). If @var{preserve-uid-gid} is
file. This works only on some operating systems, and only if you have
the correct permissions to do so.
-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}).
+If the optional argument @var{preserve-permissions} is non-@code{nil},
+this function copies the file modes (or ``permissions'') of
+@var{oldname} to @var{newname}, as well as the Access Control List and
+SELinux context (if any). @xref{Information about Files}.
+
+Otherwise, the file modes of @var{newname} are left unchanged if it is
+an existing file, and set to those of @var{oldname}, masked by the
+default file permissions (see @code{set-default-file-modes} below), if
+@var{newname} is to be newly created. The Access Control List or
+SELinux context are not copied over in either case.
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@cindex permissions, file
@cindex file modes, setting
@deffn Command set-file-modes filename mode
-This function sets the @dfn{file mode} (or @dfn{file permissions}) of
+This function sets the @dfn{file mode} (or @dfn{permissions}) of
@var{filename} to @var{mode}. It recursively follows symbolic links
at all levels for @var{filename}.
@noindent
specifies that the file should be readable and writable for its owner,
readable for group members, and readable for all other users.
-@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
Manual}, for a description of mode bit specifications.
Interactively, @var{mode} is read from the minibuffer using
@defun set-default-file-modes mode
@cindex umask
-This function sets the default file permissions for new files created
-by Emacs and its subprocesses. Every file created with Emacs
-initially has these permissions, or a subset of them
-(@code{write-region} will not grant execute permissions even if the
-default file permissions allow execution). On Unix and GNU/Linux, the
-default permissions are given by the bitwise complement of the
-``umask'' value.
+This function sets the default permissions for new files created by
+Emacs and its subprocesses. Every file created with Emacs initially
+has these permissions, or a subset of them (@code{write-region} will
+not grant execute permissions even if the default file permissions
+allow execution). On Unix and GNU/Linux, the default permissions are
+given by the bitwise complement of the ``umask'' value.
The argument @var{mode} should be an integer which specifies the
permissions, similar to @code{set-file-modes} above. Only the lowest
permissions.
@end defun
+@defmac with-file-modes mode body@dots{}
+This macro evaluates the @var{body} forms with the default
+permissions for new files temporarily set to @var{modes} (whose value
+is as for @code{set-file-modes} above). When finished, it restores
+the original default file permissions, and returns the value of the
+last form in @var{body}.
+
+This is useful for creating private files, for example.
+@end defmac
+
@defun default-file-modes
This function returns the default file permissions, as an integer.
@end defun
mode bits of @var{base-file}. If @var{base-file} is omitted or
@code{nil}, the function uses @code{0} as the base mode bits. The
complete and relative specifications can be combined, as in
-@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
+@code{"u+r,g+rx,o+r,g-w"}. @xref{File permissions,,, coreutils, The
@sc{gnu} @code{Coreutils} Manual}, for a description of file mode
specifications.
@end defun
@defun file-modes-symbolic-to-number modes &optional base-modes
This function converts a symbolic file mode specification in
-@var{modes} into the equivalent integer value. If the symbolic
+@var{modes} into the equivalent integer. If the symbolic
specification is based on an existing file, that file's mode bits are
taken from the optional argument @var{base-modes}; if that argument is
omitted or @code{nil}, it defaults to 0, i.e., no access rights at
(@pxref{Time of Day}).
@end defun
+@defun set-file-extended-attributes filename attribute-alist
+This function sets the Emacs-recognized extended file attributes for
+@code{filename}. The second argument @var{attribute-alist} should be
+an alist of the same form returned by @code{file-extended-attributes}.
+@xref{Extended Attributes}.
+@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.
+This function sets the SELinux security context for @var{filename} to
+@var{context}. The @var{context} argument should be a list
+@code{(@var{user} @var{role} @var{type} @var{range})}, where each
+element is a string. @xref{Extended Attributes}.
+
+The function returns @code{t} if it succeeds in setting the SELinux
+context of @var{filename}. It returns @code{nil} if the context was
+not set (e.g., if SELinux is disabled, or if Emacs was compiled
+without SELinux support).
+@end defun
+
+@defun set-file-acl filename acl
+This function sets the Access Control List for @var{filename} to
+@var{acl}. The @var{acl} argument should have the same form returned
+by the function @code{file-acl}. @xref{Extended Attributes}.
+
+The function returns @code{t} if it successfully sets the ACL of
+@var{filename}, @code{nil} otherwise.
@end defun
@node File Names
(expand-file-name "foo" "/usr/spool/")
@result{} "/usr/spool/foo"
@end group
-@group
-(expand-file-name "$HOME/foo")
- @result{} "/xcssun/users/rms/lewis/$HOME/foo"
-@end group
@end example
If the part of the combined file name before the first slash is
@file{/../} is interpreted exactly the same as @file{/}.
Note that @code{expand-file-name} does @emph{not} expand environment
-variables; only @code{substitute-in-file-name} does that.
+variables; only @code{substitute-in-file-name} does that:
+
+@example
+@group
+(expand-file-name "$HOME/foo")
+ @result{} "/xcssun/users/rms/lewis/$HOME/foo"
+@end group
+@end example
Note also that @code{expand-file-name} does not follow symbolic links
at any level. This results in a difference between the way
In the following example, suppose that @file{~rms/lewis} is the current
default directory, and has five files whose names begin with @samp{f}:
@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
+@file{file.c.~2~}.
@example
@group
In the following example, suppose that the current default directory
has five files whose names begin with @samp{f}: @file{foo},
@file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
+@file{file.c.~2~}.
@example
@group
@code{file-name-completion} usually ignores file names that end in any
string in this list. It does not ignore them when all the possible
completions end in one of these suffixes. This variable has no effect
-on @code{file-name-all-completions}.@refill
+on @code{file-name-all-completions}.
A typical value might look like this:
@code{dired-compress-file}, @code{dired-uncache},@*
@code{expand-file-name},
@code{file-accessible-directory-p},
+@code{file-acl},
@code{file-attributes},
@code{file-directory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-in-directory-p},
+@code{file-local-copy},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-name-directory},
@code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
@code{file-ownership-preserved-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-in-directory-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-remote-p}, @code{file-selinux-context},
@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
-@code{file-equal-p}, @code{find-backup-file-name},
+@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
@code{make-directory-internal},
@code{make-symbolic-link},@*
@code{process-file},
-@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},@*
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},
@code{file-accessible-direc@discretionary{}{}{}tory-p},
+@code{file-acl},
@code{file-attributes},
-@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-direc@discretionary{}{}{}tory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-in-directory-p},
+@code{file-local-copy},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-name-directory},
@code{file-name-nondirec@discretionary{}{}{}tory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
@code{file-ownership-pre@discretionary{}{}{}served-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-remote-p}, @code{file-selinux-context},
+@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
-@code{load}, @code{make-direc@discretionary{}{}{}tory},
+@code{load},
+@code{make-auto-save-file-name},
+@code{make-direc@discretionary{}{}{}tory},
@code{make-direc@discretionary{}{}{}tory-internal},
@code{make-symbolic-link},
@code{process-file},
-@code{rename-file}, @code{set-file-modes},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},
HCoop / bpt / emacs.git / blobdiff