@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Files, Backups and Auto-Saving, Documentation, Top
-@comment node-name, next, previous, up
+@node Files
@chapter Files
This chapter describes the Emacs Lisp functions and variables to
When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}). The error
message is in most cases obtained from the operating system, according
-to locale @code{system-message-locale}, and decoded using coding system
+to locale @code{system-messages-locale}, and decoded using coding system
@code{locale-coding-system} (@pxref{Locales}).
@menu
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.'' Humans do not usually need
+``I am editing a file'', rather than, ``I am editing a buffer that I
+will soon save as a file of the same name''. Humans do not usually need
to make the distinction explicit. When dealing with a computer program,
however, it is good to keep the distinction in mind.
@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
+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
+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
The @code{find-file-noselect} function uses two important subroutines
@defopt require-final-newline
This variable determines whether files may be written out that do
@emph{not} end with a newline. If the value of the variable is
-@code{t}, then @code{save-buffer} silently adds a newline at the end of
-the file whenever the buffer being saved does not already end in one.
-If the value of the variable is non-@code{nil}, but not @code{t}, then
-@code{save-buffer} asks the user whether to add a newline each time the
-case arises.
+@code{t}, then @code{save-buffer} silently adds a newline at the end
+of the buffer whenever it does not already end in one. If the value
+is @code{visit}, Emacs adds a missing newline just after it visits the
+file. If the value is @code{visit-save}, Emacs adds a missing newline
+both on visiting and on saving. For any other non-@code{nil} value,
+@code{save-buffer} asks the user whether to add a newline each time
+the case arises.
If the value of the variable is @code{nil}, then @code{save-buffer}
doesn't add newlines at all. @code{nil} is the default value, but a few
Name}).
@node Reading from Files
-@comment node-name, next, previous, up
@section Reading from Files
@cindex reading from files
@ref{Magic File Names}.
@node Writing to Files
-@comment node-name, next, previous, up
@section Writing to Files
@cindex writing to files
stored in the same directory as the file you are editing.
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
File locking is not supported on some systems. On systems that do not
support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
-@code{file-locked-p} do nothing and return @code{nil}.
+@code{file-locked-p} do nothing and return @code{nil}. It is also
+possible to disable locking, by setting the variable @code{create-lockfiles}.
+
+@defopt create-lockfiles
+If this variable is @code{nil}, Emacs does not lock files.
+@end defopt
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
@end menu
@node Testing Accessibility
-@comment node-name, next, previous, up
@subsection Testing Accessibility
@cindex accessibility of a file
@cindex file accessibility
using @var{string} as the error message text.
@end defun
-@defun file-ownership-preserved-p filename
+@defun file-ownership-preserved-p filename &optional group
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged. It also
returns @code{t} for nonexistent files.
+If the optional argument @var{group} is non-@code{nil}, this function
+also checks that the file's group would be unchanged.
+
If @var{filename} is a symbolic link, then, unlike the other functions
discussed here, @code{file-ownership-preserved-p} does @emph{not}
replace @var{filename} with its target. However, it does recursively
@end example
You can use @code{file-attributes} to get a file's last modification
-time as a list of two numbers. @xref{File Attributes}.
+time as a list of four integers. @xref{File Attributes}.
@end defun
@node Kinds of Files
-@comment node-name, next, previous, up
@subsection Distinguishing Kinds of Files
This section describes how to distinguish various kinds of files, such
@xref{Buffer File Name}, for related information.
@node File Attributes
-@comment node-name, next, previous, up
@subsection Other Information about Files
This section describes the functions for getting detailed
The file's @acronym{GID}, likewise.
@item
-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
+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.
@cindex modification time of file
@item
-The time of last modification as a list of two integers (as above).
+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.
@item
-The time of last status change as a list of two integers (as above).
+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.
as in @samp{ls -l}.
@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
+An unspecified value, present for backward compatibility.
@item
The file's inode number. If possible, this is an integer. If the
@group
(file-attributes "files.texi" 'string)
@result{} (nil 1 "lh" "users"
- (19145 42977)
- (19141 59576)
- (18340 17300)
+ (20614 64019 50040 152000)
+ (20000 23 0 0)
+ (20614 64555 902289 872000)
122295 "-rw-rw-rw-"
- nil (5888 2 . 43978)
+ t (5888 2 . 43978)
(15479 . 46724))
@end group
@end example
@item "users"
is in the group with name "users".
-@item (19145 42977)
-was last accessed on Oct 5 2009, at 10:01:37.
+@item (20614 64019 50040 152000)
+was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
-@item (19141 59576)
-last had its contents modified on Oct 2 2009, at 13:49:12.
+@item (20000 23 0 0)
+was last modified on July 15, 2001, at 08:53:43 UTC.
-@item (18340 17300)
-last had its status changed on Feb 2 2008, at 12:19:00.
+@item (20614 64555 902289 872000)
+last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
@item 122295
is 122295 bytes long. (It may not contain 122295 characters, though,
@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 t
+is merely a placeholder; it carries no information.
@item (5888 2 . 43978)
has an inode number of 6473924464520138.
The predicate is passed the candidate file name as its single
argument. If @var{predicate} is @code{nil} or omitted,
@code{locate-file} uses @code{file-readable-p} as the predicate.
-@xref{Kinds of Files}, for other useful predicates, e.g.@:
+@xref{Kinds of Files}, for other useful predicates, e.g.,
@code{file-executable-p} and @code{file-directory-p}.
For compatibility, @var{predicate} can also be one of the symbols
@var{modes} into the equivalent integer value. If the symbolic
specification is based on an existing file, that file's mode bits are
taken from the optional argument @var{base-modes}; if that argument is
-omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at
+omitted or @code{nil}, it defaults to 0, i.e., no access rights at
all.
@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
not an extension.
@end defun
+@defun file-name-base &optional filename
+This function is the composition of @code{file-name-sans-extension}
+and @code{file-name-nondirectory}. For example,
+
+@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
@subsection Absolute and Relative File Names
@end defun
@node Directory Names
-@comment node-name, next, previous, up
@subsection Directory Names
@cindex directory name
@cindex file name of directory
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
@example
(defun display-time-file-nonempty-p (file)
- (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
+ (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 (nth 7 (file-attributes
+ (file-chase-links file)))))))
@end example
@end defopt
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
+any elements from the value of @code{buffer-file-format} with a
+non-@code{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
HCoop / bpt / emacs.git / blobdiff