@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
* Changing Files:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
-* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Create/Delete Dirs:: Creating and Deleting Directories.
+* Magic File Names:: Defining "magic" special handling
+ for certain file names.
* Format Conversion:: Conversion to and from various file formats.
@end menu
@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.
+* Truenames:: Eliminating symbolic links from a file name.
* File Attributes:: How large is it? Any other names? Etc.
* Locating Files:: How to find a file in standard places.
@end menu
The time of last access, as a list of two integers.
The first integer has the high-order 16 bits of time,
the second has the low 16 bits. (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.)
+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 two integers (as above).
-@cindex modification time of file
+This is the last time when the file's contents were modified.
@item
The time of last status change as a list of two 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.
@item
The size of the file in bytes. If the size is too large to fit in a
deleted and recreated; @code{nil} otherwise.
@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, then
-the value has the form @code{(@var{high} . @var{low})}, where @var{low}
-holds the low 16 bits.
+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 still fits into a 32-bit integer, then the value has the
+form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
+bits. If the inode is wider than 32 bits, the value is of the form
+@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
+the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low
+16 bits.
@item
-The file system number of the file system that the file is in.
-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. 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}:
@group
(file-attributes "files.texi" 'string)
@result{} (nil 1 "lh" "users"
- (8489 20284)
- (8489 20284)
- (8489 20285)
- 14906 "-rw-rw-rw-"
- nil 129500 -32252)
+ (19145 42977)
+ (19141 59576)
+ (18340 17300)
+ 122295 "-rw-rw-rw-"
+ nil (5888 2 . 43978)
+ (15479 . 46724))
@end group
@end example
@item "users"
is in the group with name "users".
-@item (8489 20284)
-was last accessed on Aug 19 00:09.
+@item (19145 42977)
+was last accessed on Oct 5 2009, at 10:01:37.
-@item (8489 20284)
-was last modified on Aug 19 00:09.
+@item (19141 59576)
+last had its contents modified on Oct 2 2009, at 13:49:12.
-@item (8489 20285)
-last had its inode changed on Aug 19 00:09.
+@item (18340 17300)
+last had its status changed on Feb 2 2008, at 12:19:00.
-@item 14906
-is 14906 bytes long. (It may not contain 14906 characters, though,
-if some of the bytes belong to multibyte sequences.)
+@item 122295
+is 122295 bytes long. (It may not contain 122295 characters, though,
+if some of the bytes belong to multibyte sequences, and also if the
+end-of-line format is CR-LF.)
@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 129500
-has an inode number of 129500.
-@item -32252
-is on file system number -32252.
+@item (5888 2 . 43978)
+has an inode number of 6473924464520138.
+
+@item (15479 . 46724)
+is on the file-system device whose number is 1014478468.
@end table
@end defun
not an extension.
@end defun
-@ignore
-Andrew Innes says that this
-
-@c @defvar directory-sep-char
-This variable holds the character that Emacs normally uses to separate
-file name components. The default value is @code{?/}, but on MS-Windows
-you can set it to @code{?\\}; then the functions that transform file names
-use backslashes in their output.
-
-File names using backslashes work as input to Lisp primitives even on
-MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
-value of @code{?/}.
-@end defvar
-@end ignore
@node Relative File Names
@subsection Absolute and Relative File Names
abbreviations to use for file directories. Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name. The @var{from} string is
-actually a regular expression; it should always start with @samp{^}.
+actually a regular expression; it ought to always start with @samp{\`}.
The @var{to} string should be an ordinary absolute directory name. Do
not use @samp{~} to stand for a home directory in that string. The
function @code{abbreviate-file-name} performs these substitutions.
and so on.
@example
-(("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
+(("\\`/home/fsf" . "/fsf")
+ ("\\`/home/gp" . "/gp")
+ ("\\`/home/gd" . "/gd"))
@end example
@end defopt
@defun abbreviate-file-name filename
@anchor{Definition of abbreviate-file-name}
This function applies abbreviations from @code{directory-abbrev-alist}
-to its argument, and substitutes @samp{~} for the user's home
-directory. You can use it for directory names and for file names,
-because it recognizes abbreviations even as part of the name.
+to its argument, and also substitutes @samp{~} for the user's home
+directory if the argument names a file in the home directory or one of
+its subdirectories. (If the home directory is a root directory, it is
+not replaced with @samp{~}, because this does not make the result
+shorter on many systems.) You can use it for directory names and for
+file names, because it recognizes abbreviations even as part of the
+name.
@end defun
@node File Name Expansion
@end defvar
@node Create/Delete Dirs
-@section Creating and Deleting Directories
-@cindex creating and deleting directories
+@section Creating, Copying and Deleting Directories
+@cindex creating, copying and deleting directories
@c Emacs 19 features
Most Emacs Lisp file-manipulation functions get errors when used on
@code{mkdir} is an alias for this.
@end deffn
-@deffn Command delete-directory dirname
+@deffn Command copy-directory dirname newname &optional keep-time parents
+This command copies the directory named @var{dirname} to
+@var{newname}. If @var{newname} names an existing directory,
+@var{dirname} will be copied to a subdirectory there.
+
+It always sets the file modes of the copied files to match the
+corresponding original file.
+
+The third arg @var{keep-time} non-@code{nil} means to preserve the
+modification time of the copied files. A prefix arg makes
+@var{keep-time} non-@code{nil}.
+
+Noninteractively, the last argument @var{parents} says whether to
+create parent directories if they don't exist. Interactively,
+this happens by default.
+@end deffn
+
+@deffn Command delete-directory dirname &optional recursive
This command deletes the directory named @var{dirname}. The function
@code{delete-file} does not work for files that are directories; you
-must use @code{delete-directory} for them. If the directory contains
-any files, @code{delete-directory} signals an error.
+must use @code{delete-directory} for them. If @var{recursive} is
+@code{nil}, and the directory contains any files,
+@code{delete-directory} signals an error.
@code{delete-directory} only follows symbolic links at the level of
parent directories.
regular expression), plus a handler that implements all the primitive
Emacs file operations for file names that do match.
+@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
handler. Each element has this form:
@noindent
@code{access-file}, @code{add-name-to-file},
@code{byte-compiler-base-file-name},@*
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
+@code{copy-directory}, @code{copy-file},
+@code{delete-directory}, @code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
@code{directory-files},
@flushleft
@code{access-file}, @code{add-name-to-file},
@code{byte-com@discretionary{}{}{}piler-base-file-name},
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
+@code{copy-directory}, @code{copy-file},
+@code{delete-directory}, @code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
@code{directory-files},
is a good way to come up with one.
@end defun
+@defopt remote-file-name-inhibit-cache
+Whether to use the remote file-name cache for read access.
+
+File attributes of remote files are cached for better performance. If
+they are changed out of Emacs' control, the cached values become
+invalid, and must be reread.
+
+When set to @code{nil}, cached values are always used. This shall be
+set with care. When set to @code{t}, cached values are never used.
+ALthough this is the safest value, it could result in performance
+degradation.
+
+A compromise is to set it to a positive number. This means that
+cached values are used for that amount of seconds since they were
+cached.
+
+In case a remote file is checked regularly, it might be reasonable to
+let-bind this variable to a value less then the time period between
+two checks. Example:
+
+@example
+(defun display-time-file-nonempty-p (file)
+ (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
+ (and (file-exists-p file)
+ (< 0 (nth 7 (file-attributes (file-chase-links file)))))))
+@end example
+@end defopt
+
@node Format Conversion
@section File Format Conversion
HCoop / bpt / emacs.git / blobdiff