@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
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}:
@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:
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
@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