@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Files
Visiting a file means reading a file into a buffer. Once this is
done, we say that the buffer is @dfn{visiting} that file, and call the
-file ``the visited file'' of the buffer.
+file @dfn{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
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''.
+you and another user will both lock the same file simultaneously.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
@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 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,
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
+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
non-@code{nil} value for @var{id-format} if you use the returned
@acronym{UID} or @acronym{GID}.
+Accessor functions are provided to access the elements in this list.
+The accessors are mentioned along with the descriptions of the
+elements below.
+
The elements of the list, in order, are:
@enumerate 0
@item
@code{t} for a directory, a string for a symbolic link (the name
-linked to), or @code{nil} for a text file.
+linked to), or @code{nil} for a text file
+(@code{file-attribute-type}).
@c Wordy so as to prevent an overfull hbox. --rjc 15mar92
@item
-The number of names the file has. Alternate names, also known as hard
-links, can be created by using the @code{add-name-to-file} function
-(@pxref{Changing Files}).
+The number of names the file has (@code{file-attribute-link-number}).
+Alternate names, also known as hard links, can be created by using the
+@code{add-name-to-file} function (@pxref{Changing Files}).
@item
-The file's @acronym{UID}, normally as a string. However, if it does
-not correspond to a named user, the value is a number.
+The file's @acronym{UID}, normally as a string
+(@code{file-attribute-user-id}). However, if it does not correspond
+to a named user, the value is a number.
@item
-The file's @acronym{GID}, likewise.
+The file's @acronym{GID}, likewise (@code{file-attribute-group-id}).
@item
-The time of last access, as a list of four integers @code{(@var{sec-high}
-@var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.) Note that on
-some FAT-based filesystems, only the date of last access is recorded,
-so this time will always hold the midnight of the day of last access.
+The time of last access, as a list of four integers
+@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}
+(@code{file-attribute-access-time}). (This is similar to the value of
+@code{current-time}; see @ref{Time of Day}.) Note that on some
+FAT-based filesystems, only the date of last access is recorded, so
+this time will always hold the midnight of the day of last access.
@cindex modification time of file
@item
-The time of last modification as a list of four integers (as above).
-This is the last time when the file's contents were modified.
+The time of last modification as a list of four integers (as above)
+(@code{file-attribute-modification-time}). This is the last time when
+the file's contents were modified.
@item
-The time of last status change as a list of four integers (as above).
-This is the time of the last change to the file's access mode bits,
-its owner and group, and other information recorded in the filesystem
-for the file, beyond the file's contents.
+The time of last status change as a list of four integers (as above)
+(@code{file-attribute-status-change-time}). This is the time of the
+last change to the file's access mode bits, its owner and group, and
+other information recorded in the filesystem for the file, beyond the
+file's contents.
@item
-The size of the file in bytes. This is floating point if the size is
-too large to fit in a Lisp integer.
+The size of the file in bytes (@code{file-attribute-size}). 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}.
+The file's modes, as a string of ten letters or dashes, as in
+@samp{ls -l} (@code{file-attribute-modes}).
@item
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,
-then the value has the
+The file's inode number (@code{file-attribute-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, 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
-@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
-the high bits, @var{middle} the middle 24 bits, and @var{low} the low
-16 bits.
+bits. If the inode number is too wide for even that, the value is of
+the form @code{(@var{high} @var{middle} . @var{low})}, where
+@code{high} holds the high bits, @var{middle} the middle 24 bits, and
+@var{low} the low 16 bits.
@item
-The filesystem number of the device that the file is on. Depending on
-the magnitude of the value, this can be either an integer or a cons
-cell, in the same manner as the inode number. This element and the
-file's inode number together give enough information to distinguish
-any two files on the system---no two files can have the same values
-for both of these numbers.
+The filesystem number of the device that the file is on
+@code{file-attribute-device-number}). Depending on the magnitude of
+the value, this can be either an integer or a cons cell, in the same
+manner as the inode number. This element and the file's inode number
+together give enough information to distinguish any two files on the
+system---no two files can have the same values for both of these
+numbers.
@end enumerate
For example, here are the file attributes for @file{files.texi}:
directory).
@item "lh"
-is owned by the user with name "lh".
+is owned by the user with name @samp{lh}.
@item "users"
-is in the group with name "users".
+is in the group with name @samp{users}.
@item (20614 64019 50040 152000)
was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
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
+file access controls than the basic Unix-style permissions
discussed in the previous sections.
@cindex access control list
@cindex setting modes of files
The functions in this section rename, copy, delete, link, and set
-the modes (permissions) of files.
+the modes (permissions) of files. They all signal a @code{file-error}
+error if they fail to perform their function, reporting the
+system-dependent error message that describes the reason for the
+failure.
In the functions that have an argument @var{newname}, if a file by the
name of @var{newname} already exists, the actions taken depend on the
@cindex file with multiple names
@cindex file hard link
This function gives the file named @var{oldname} the additional name
-@var{newname}. This means that @var{newname} becomes a new ``hard
-link'' to @var{oldname}.
+@var{newname}. This means that @var{newname} becomes a new hard
+link to @var{oldname}.
In the first part of the following example, we list two files,
@file{foo} and @file{foo3}.
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.
+given by the bitwise complement of the @samp{umask} value.
The argument @var{mode} should be an integer which specifies the
permissions, similar to @code{set-file-modes} above. Only the lowest
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}.
+The return value is @code{t} if the attributes are successfully set,
+otherwise it is @code{nil}.
@xref{Extended Attributes}.
@end defun
@end defun
@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension'', if any,
+This function returns @var{filename}'s final extension, if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
follows the last @samp{.} in the last name component (minus any
@file{foo}. It returns @code{""} for null extensions, as in
@file{foo.}. If the last component of a file name begins with a
@samp{.}, that @samp{.} doesn't count as the beginning of an
-extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
+extension. Thus, @file{.emacs}'s extension is @code{nil}, not
@samp{.emacs}.
If @var{period} is non-@code{nil}, then the returned value includes
@end example
@end defun
-@defun directory-name-p filename
-This function returns non-@code{nil} if @var{filename} ends with a
-forward slash (@samp{/}) character.
-@end defun
-
@node Directory Names
@subsection Directory Names
@cindex directory name
+@cindex directory file name
@cindex file name of directory
A @dfn{directory name} is the name of a directory. A directory is
-actually a kind of file, so it has a file name, which is related to
-the directory name but not identical to it. (This is not quite the
-same as the usual Unix terminology.) These two different names for
-the same entity are related by a syntactic transformation. On GNU and
-Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash. On MS-DOS
-the relationship is more complicated.
-
- The difference between a directory name and its name as a file is
+actually a kind of file, so it has a file name (called the
+@dfn{directory file name}, which is related to the directory name but
+not identical to it. (This is not quite the same as the usual Unix
+terminology.) These two different names for the same entity are
+related by a syntactic transformation. On GNU and Unix systems, this
+is simple: a directory name ends in a slash, whereas the directory
+file name lacks that slash. On MS-DOS the relationship is more
+complicated.
+
+ The difference between directory name and directory file name is
subtle but crucial. When an Emacs variable or function argument is
-described as being a directory name, a file name of a directory is not
+described as being a directory name, a directory file name is not
acceptable. When @code{file-name-directory} returns a string, that is
always a directory name.
- The following two functions convert between directory names and file
-names. They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
+ The following two functions convert between directory names and
+directory file names. They do nothing special with environment
+variable substitutions such as @samp{$HOME}, and the constructs
+@samp{~}, @samp{.} and @samp{..}.
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory. On
-most systems, this means appending a slash to the string (if it does not
-already end in one).
+that the operating system will interpret as the name of a directory (a
+directory name). On most systems, this means appending a slash to the
+string (if it does not already end in one).
@example
@group
@end example
@end defun
+@defun directory-name-p filename
+This function returns non-@code{nil} if @var{filename} ends with a
+directory separator character. This is the forward slash @samp{/} on
+Unix and GNU systems; MS-Windows and MS-DOS recognize both the forward
+slash and the backslash @samp{\} as directory separators.
+@end defun
+
@defun directory-file-name dirname
-This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file. On most
-systems, this means removing the final slash (or backslash) from the
-string.
+This function returns a string representing @var{dirname} in a form
+that the operating system will interpret as the name of a file (a
+directory file name). On most systems, this means removing the final
+slash (or backslash) from the string.
@example
@group
because this is not portable. Always use
@code{file-name-as-directory}.
+ To avoid the issues mentioned above, or if the @var{dirname} value
+might be nil (for example, from an element of @code{load-path}), use:
+
+@example
+(expand-file-name @var{relfile} @var{dirname})
+@end example
+
To convert a directory name to its abbreviation, use this
function:
@noindent
This is for the sake of filesystems that have the concept of a
-``superroot'' above the root directory @file{/}. On other filesystems,
+superroot above the root directory @file{/}. On other filesystems,
@file{/../} is interpreted exactly the same as @file{/}.
Note that @code{expand-file-name} does @emph{not} expand environment
@var{filename} with the environment variable values. Following
standard Unix shell syntax, @samp{$} is the prefix to substitute an
environment variable value. If the input contains @samp{$$}, that is
-converted to @samp{$}; this gives the user a way to ``quote'' a
+converted to @samp{$}; this gives the user a way to quote a
@samp{$}.
The environment variable name is the series of alphanumeric characters
that can be read.
@end defun
-@defun directory-files-recursively directory match &optional include-directories
-Return all files under @var{directory} whose file names match
-@var{match} recursively. The file names are returned ``depth first'',
-meaning that contents of sub-directories are returned before contents
-of the directories. If @var{include-directories} is non-@code{nil},
-also return directory names that have matching names.
+@defun directory-files-recursively directory regexp &optional include-directories
+Return all files under @var{directory} whose names match @var{regexp}.
+This function searches the specified @var{directory} and its
+sub-directories, recursively, for files whose basenames (i.e., without
+the leading directories) match the specified @var{regexp}, and returns
+a list of the absolute file names of the matching files
+(@pxref{Relative File Names, absolute file names}). The file names
+are returned in depth-first order, meaning that files in some
+sub-directory are returned before the files in its parent directory.
+In addition, matching files found in each subdirectory are sorted
+alphabetically by their basenames. By default, directories whose
+names match @var{regexp} are omitted from the list, but if the
+optional argument @var{include-directories} is non-@code{nil}, they
+are included.
@end defun
@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
@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-notify-valid-p},
@code{file-ownership-preserved-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-remote-p}, @code{file-selinux-context},
@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-notify-valid-p},
@code{file-ownership-pre@discretionary{}{}{}served-p},
@code{file-readable-p}, @code{file-regular-p},
@code{file-remote-p}, @code{file-selinux-context},
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way''. It should always reinvoke the primitive
+operation in the usual way. It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
Handlers that don't really do anything special for actual access to the
file---such as the ones that implement completion of host names for
remote file names---should have a non-@code{nil} @code{safe-magic}
-property. For instance, Emacs normally ``protects'' directory names
+property. For instance, Emacs normally protects directory names
it finds in @code{PATH} from becoming magic, if they look like magic
file names, by prefixing them with @samp{/:}. But if the handler that
would be used for them has a non-@code{nil} @code{safe-magic}
@end defun
@defun unhandled-file-name-directory filename
-This function returns the name of a directory that is not magic. It
-uses the directory part of @var{filename} if that is not magic. For a
-magic file name, it invokes the file name handler, which therefore
-decides what value to return. If @var{filename} is not accessible
-from a local process, then the file name handler should indicate it by
-returning @code{nil}.
+This function returns the name of a directory that is not magic. For
+a non-magic @var{filename} it returns the corresponding directory name
+(@pxref{Directory Names}). For a magic @var{filename}, it invokes the
+file name handler, which therefore decides what value to return. If
+@var{filename} is not accessible from a local process, then the file
+name handler should indicate that by returning @code{nil}.
This is useful for running a subprocess; every subprocess must have a
non-magic directory to serve as its current directory, and this function