@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 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
@var{filename} in the minibuffer.
@end deffn
+@deffn Command find-file-literally filename
+This command visits @var{filename}, like @code{find-file} does, but it
+does not perform any format conversions (@pxref{Format Conversion}),
+character code conversions (@pxref{Coding Systems}), or end-of-line
+conversions (@pxref{Coding System Basics, End of line conversion}).
+The buffer visiting the file is made unibyte, and its major mode is
+Fundamental mode, regardless of the file name. File local variable
+specifications in the file (@pxref{File Local Variables}) are
+ignored, and automatic decompression and adding a newline at the end
+of the file due to @code{require-final-newline} (@pxref{Saving
+Buffers, require-final-newline}) are also disabled.
+
+Note that if Emacs already has a buffer visiting the same file
+non-literally, it will not visit the same file literally, but instead
+just switch to the existing buffer. If you want to be sure of
+accessing a file's contents literally, you should create a temporary
+buffer and then read the file contents into it using
+@code{insert-file-contents-literally} (@pxref{Reading from Files}).
+@end deffn
+
@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It
returns a buffer visiting the file @var{filename}. You may make the
and never treat wildcard characters specially.
@end defopt
-@defvar find-file-hook
+@defopt find-file-hook
The value of this variable is a list of functions to be called after a
file is visited. The file's local-variables specification (if any) will
have been processed before the hooks are run. The buffer visiting the
file is current when the hook functions are run.
This variable is a normal hook. @xref{Hooks}.
-@end defvar
+@end defopt
@defvar find-file-not-found-functions
The value of this variable is a list of functions to be called when
used, and in many cases only some of the functions are called.
@end defvar
+@defvar find-file-literally
+This buffer-local variable, if set to a non-@code{nil} value, makes
+@code{save-buffer} behave as if the buffer were visiting its file
+literally, i.e. without conversions of any kind. The command
+@code{find-file-literally} sets this variable's local value, but other
+equivalent functions and commands can do that as well, e.g.@: to avoid
+automatic addition of a newline at the end of the file. This variable
+is permanent local, so it is unaffected by changes of major modes.
+@end defvar
+
@node Subroutines of Visiting
@comment node-name, next, previous, up
@subsection Subroutines of Visiting
Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents,
-including end-of-line conversion.
+including end-of-line conversion. However, if the file contains null
+bytes, it is by default visited without any code conversions; see
+@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
+control this behavior.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@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
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+ On MS-DOS, there is no such thing as an ``executable'' file mode bit.
+So Emacs 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
+as executable files. This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}. Directories are also
+reported with executable bit set, for compatibility with Unix.
+
@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate file in path
(@pxref{Time of Day}).
@end defun
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
- On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs 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
-as executable files. This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}. Directories are also
-reported with executable bit set, for compatibility with Unix.
-
@node File Names
@section File Names
@cindex file names
because this is not portable. Always use
@code{file-name-as-directory}.
-@cindex directory name abbreviation
- Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links. Sometimes the users recognize
-primarily the link's name as ``the name'' of the directory, and find it
-annoying to see the directory's ``real'' name. If you define the link
-name as an abbreviation for the ``real'' name, Emacs shows users the
-abbreviation instead.
-
-@defvar directory-abbrev-alist
-The variable @code{directory-abbrev-alist} contains an alist of
-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{^}.
-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.
-
-You can set this variable in @file{site-init.el} to describe the
-abbreviations appropriate for your site.
-
-Here's an example, from a system on which file system @file{/home/fsf}
-and so on are normally accessed through symbolic links named @file{/fsf}
-and so on.
-
-@example
-(("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
-@end example
-@end defvar
-
To convert a directory name to its abbreviation, use this
function:
@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,
+This function returns an abbreviated form of @var{filename}. It
+applies the abbreviations specified in @code{directory-abbrev-alist}
+(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
+then 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 this function for directory names and for file names,
because it recognizes abbreviations even as part of the name.
@end defun
truncate the @var{string} prefix to fit into the 8+3 file-name limits.
@end defun
-@defvar temporary-file-directory
+@defopt temporary-file-directory
@cindex @code{TMPDIR} environment variable
@cindex @code{TMP} environment variable
@cindex @code{TEMP} environment variable
put the file in. However, if you expect the file to be small, you
should use @code{small-temporary-file-directory} first if that is
non-@code{nil}.
-@end defvar
+@end defopt
-@defvar small-temporary-file-directory
+@defopt small-temporary-file-directory
This variable specifies the directory name for
creating certain temporary files, which are likely to be small.
(or small-temporary-file-directory
temporary-file-directory)))
@end example
-@end defvar
+@end defopt
@node File Name Completion
@subsection File Name Completion
@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
with @code{delete-file}. These special functions exist to create and
delete directories.
-@defun make-directory dirname &optional parents
-This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, as is always the case in an
+@findex mkdir
+@deffn Command make-directory dirname &optional parents
+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.
-@end defun
-@defun delete-directory dirname
-This function deletes the directory named @var{dirname}. The function
+@code{mkdir} is an alias for this.
+@end deffn
+
+@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.
-This function only follows symbolic links at the level of parent
-directories.
-@end defun
+@code{delete-directory} only follows symbolic links at the level of
+parent directories.
+@end deffn
@node Magic File Names
@section Making Certain File Names ``Magic''
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},
and @code{write-region} for writing a buffer into a file.
@menu
-* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}
+* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}.
* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
@end menu
@item regexp
A regular expression which is used to recognize files represented in
-this format.
+this format. If @code{nil}, the format is never applied automatically.
@item from-fn
A shell command or function to decode data in this format (to convert
in the order of appearance in the list.
@deffn Command format-write-file file format &optional confirm
-This command writes the current buffer contents into the file
-@var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer. That is, it sets the buffer-local value
-of @code{buffer-file-format} to @var{format}. It then appends any
-elements of the previous value with a non-nil @var{preserve} flag (see
-above), if they are not already present in the new value.
-The argument @var{format} is a list of format names.
-Except for the @var{format} argument, this command
-is similar to @code{write-file}. In particular, @var{confirm} has the
-same meaning and interactive treatment as the corresponding argument
-to @code{write-file}. @xref{Definition of write-file}.
+This command writes the current buffer contents into the file @var{file}
+in a format based on @var{format}, which is a list of format names. It
+constructs the actual format starting from @var{format}, then appending
+any elements from the value of @code{buffer-file-format} with a non-nil
+@var{preserve} flag (see above), if they are not already present in
+@var{format}. It then updates @code{buffer-file-format} with this
+format, making it the default for future saves. Except for the
+@var{format} argument, this command is similar to @code{write-file}. In
+particular, @var{confirm} has the same meaning and interactive treatment
+as the corresponding argument to @code{write-file}. @xref{Definition of
+write-file}.
@end deffn
@deffn Command format-find-file file format
@c ??? for `write-region-annotate-functions', below? --ttn
In contrast, when reading, the annotations intermixed with the text
-are handled immediately. @code{insert-file-contents} sets point to the
-beginning of some text to be converted, then calls the conversion
+are handled immediately. @code{insert-file-contents} sets point to
+the beginning of some text to be converted, then calls the conversion
functions with the length of that text. These functions should always
-return with point at the beginning of the inserted text. This approach
-makes sense for reading because annotations removed by the first
-converter can't be mistakenly processed by a later converter.
-
- Each conversion function should scan for the annotations it
-recognizes, remove the annotation, modify the buffer text (to set a text
-property, for example), and return the updated length of the text, as it
-stands after those changes. The value returned by one function becomes
-the argument to the next function.
+return with point at the beginning of the inserted text. This
+approach makes sense for reading because annotations removed by the
+first converter can't be mistakenly processed by a later converter.
+Each conversion function should scan for the annotations it
+recognizes, remove the annotation, modify the buffer text (to set a
+text property, for example), and return the updated length of the
+text, as it stands after those changes. The value returned by one
+function becomes the argument to the next function.
@defvar write-region-annotate-functions
A list of functions for @code{write-region} to call. Each function in
to be written. These functions should not alter the contents of the
buffer. Instead, they should return annotations.
-@c ??? Following adapted from comment in `build_annotations' (fileio.c).
-@c ??? Perhaps this is intended for internal use only?
-@c ??? Someone who understands this, please reword it. --ttn
-As a special case, if a function returns with a different buffer
-current, Emacs takes it to mean the current buffer contains altered text
-to be output, and discards all previous annotations because they should
-have been dealt with by this function.
+As a special case, a function may return with a different buffer
+current. Emacs takes this to mean that the current buffer contains
+altered text to be output. It therefore changes the @var{start} and
+@var{end} arguments of the @code{write-region} call, giving them the
+values of @code{point-min} and @code{point-max} in the new buffer,
+respectively. It also discards all previous annotations, because they
+should have been dealt with by this function.
+@end defvar
+
+@defvar write-region-post-annotation-function
+The value of this variable, if non-@code{nil}, should be a function.
+This function is called, with no arguments, after @code{write-region}
+has completed.
+
+If any function in @code{write-region-annotate-functions} returns with
+a different buffer current, Emacs calls
+@code{write-region-post-annotation-function} more than once. Emacs
+calls it with the last buffer that was current, and again with the
+buffer before that, and so on back to the original buffer.
+
+Thus, a function in @code{write-region-annotate-functions} can create
+a buffer, give this variable the local value of @code{kill-buffer} in
+that buffer, set up the buffer with altered text, and make the buffer
+current. The buffer will be killed after @code{write-region} is done.
@end defvar
@defvar after-insert-file-functions