diff options
Diffstat (limited to 'doc/lispref/files.texi')
| -rw-r--r-- | doc/lispref/files.texi | 92 |
1 files changed, 48 insertions, 44 deletions
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 403a21b3365..5c99ea2781c 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1299,36 +1299,34 @@ Alternate names, also known as hard links, can be created by using the @item 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. +to a named user, the value is an integer. @item 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})} -(@code{file-attribute-access-time}). (This is similar to the value of -@code{current-time}; see @ref{Time of Day}.) The value is truncated +The time of last access as a Lisp timestamp +(@code{file-attribute-status-change-time}). The timestamp is in the +style of @code{current-time} (@pxref{Time of Day}) and is truncated to that of the filesystem's timestamp resolution; for example, 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 the last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above) +The time of last modification as a Lisp timestamp (@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) +The time of last status change as a Lisp timestamp (@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 (@code{file-attribute-size}). 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}). @item The file's modes, as a string of ten letters or dashes, as in @@ -1338,21 +1336,13 @@ The file's modes, as a string of ten letters or dashes, as in An unspecified value, present for backward compatibility. @item -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. +The file's inode number (@code{file-attribute-inode-number}), +a nonnegative integer. @item 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 +@code{file-attribute-device-number}), an integer. +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. @@ -1368,8 +1358,8 @@ For example, here are the file attributes for @file{files.texi}: (20000 23 0 0) (20614 64555 902289 872000) 122295 "-rw-rw-rw-" - t (5888 2 . 43978) - (15479 . 46724)) + t 6473924464520138 + 1014478468) @end group @end example @@ -1410,10 +1400,10 @@ has a mode of read and write access for the owner, group, and world. @item t is merely a placeholder; it carries no information. -@item (5888 2 . 43978) +@item 6473924464520138 has an inode number of 6473924464520138. -@item (15479 . 46724) +@item 1014478468 is on the file-system device whose number is 1014478468. @end table @end defun @@ -1567,13 +1557,16 @@ For compatibility, @var{predicate} can also be one of the symbols a list of one or more of these symbols. @end defun -@defun executable-find program +@defun executable-find program &optional remote This function searches for the executable file of the named @var{program} and returns the absolute file name of the executable, including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories +the file is not found. The function searches in all the directories in @code{exec-path}, and tries all the file-name extensions in @code{exec-suffixes} (@pxref{Subprocess Creation}). + +If @var{remote} is non-@code{nil}, and @code{default-directory} is a +remote directory, @var{program} is searched on the respective remote host. @end defun @node Changing Files @@ -2131,7 +2124,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part, not an extension. @end defun -@defun file-name-base &optional filename +@defun file-name-base filename This function is the composition of @code{file-name-sans-extension} and @code{file-name-nondirectory}. For example, @@ -2139,8 +2132,6 @@ and @code{file-name-nondirectory}. For example, (file-name-base "/my/home/foo.c") @result{} "foo" @end example - -The @var{filename} argument defaults to @code{buffer-file-name}. @end defun @node Relative File Names @@ -2376,8 +2367,10 @@ start with @samp{~}.) Otherwise, the current buffer's value of @end example If the part of @var{filename} before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first +@samp{~}, it expands to your home directory, which is typically +specified by the value of the @env{HOME} environment variable +(@pxref{General Variables,,, emacs, The GNU Emacs Manual}). +If the part before the first slash is @samp{~@var{user}} and if @var{user} is a valid login name, it expands to @var{user}'s home directory. If you do not want this expansion for a relative @var{filename} that @@ -2927,7 +2920,7 @@ are included. This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead of returning a list of file names, it returns for each file a -list @code{(@var{filename} @var{attributes})}, where @var{attributes} +list @code{(@var{filename} . @var{attributes})}, where @var{attributes} is what @code{file-attributes} returns for that file. The optional argument @var{id-format} has the same meaning as the corresponding argument to @code{file-attributes} (@pxref{Definition @@ -3004,10 +2997,16 @@ This command creates a directory named @var{dirname}. If @var{parents} is non-@code{nil}, as is always the case in an interactive call, that means to create the parent directories first, if they don't already exist. - @code{mkdir} is an alias for this. @end deffn +@deffn Command make-empty-file filename &optional parents +This command creates an empty file named @var{filename}. +As @code{make-directory}, this command creates parent directories +if @var{parents} is non-@code{nil}. +If @var{filename} already exists, this command signals an error. +@end deffn + @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents This command copies the directory named @var{dirname} to @var{newname}. If @var{newname} is a directory name, @@ -3068,7 +3067,7 @@ expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that match. -@cindex file handler +@cindex file name handler @vindex file-name-handler-alist The variable @code{file-name-handler-alist} holds a list of handlers, together with regular expressions that determine when to apply each @@ -3139,8 +3138,8 @@ first, before handlers for jobs such as remote file access. @code{directory-file-name}, @code{directory-files}, @code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, +@code{dired-compress-file}, @code{dired-uncache}, +@code{exec-path}, @code{expand-file-name},@* @code{file-accessible-directory-p}, @code{file-acl}, @code{file-attributes}, @@ -3161,7 +3160,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-preserved-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-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @@ -3171,6 +3171,7 @@ first, before handlers for jobs such as remote file access. @code{make-directory}, @code{make-directory-internal}, @code{make-nearby-temp-file}, +@code{make-process}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3196,7 +3197,7 @@ first, before handlers for jobs such as remote file access. @code{directory-files}, @code{directory-files-and-at@discretionary{}{}{}tributes}, @code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, +@code{exec-path}, @code{expand-file-name}, @code{file-accessible-direc@discretionary{}{}{}tory-p}, @code{file-acl}, @code{file-attributes}, @@ -3217,7 +3218,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-pre@discretionary{}{}{}served-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-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, @code{get-file-buffer}, @code{insert-directory}, @@ -3226,6 +3228,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @code{make-direc@discretionary{}{}{}tory-internal}, +@code{make-process}, @code{make-symbolic-link}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3353,8 +3356,8 @@ If @code{file-remote-p} returns the same identifier for two different filenames, that means they are stored on the same file system and can be accessed locally with respect to each other. This means, for example, that it is possible to start a remote process accessing both -files at the same time. Implementers of file handlers need to ensure -this principle is valid. +files at the same time. Implementers of file name handlers need to +ensure this principle is valid. @var{identification} specifies which part of the identifier shall be returned as string. @var{identification} can be the symbol @@ -3424,8 +3427,9 @@ between consecutive checks. For example: (let ((remote-file-name-inhibit-cache (- display-time-interval 5))) (and (file-exists-p file) - (< 0 (nth 7 (file-attributes - (file-chase-links file))))))) + (< 0 (file-attribute-size + (file-attributes + (file-chase-links file))))))) @end example @end defopt |