@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c 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
@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
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
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
@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.
@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)
(15479 . 46724))
@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,
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
can operate on file names that do not refer to an existing file or
directory.
+@findex cygwin-convert-file-name-from-windows
+@findex cygwin-convert-file-name-to-windows
+@cindex MS-Windows file-name syntax
+@cindex converting file names from/to MS-Windows syntax
On MS-DOS and MS-Windows, these functions (like the function that
actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
where backslashes separate the components, as well as Unix syntax; but
they always return Unix syntax. This enables Lisp programs to specify
file names in Unix syntax and work properly on all systems without
-change.
+change.@footnote{In MS-Windows versions of Emacs compiled for the Cygwin
+environment, you can use the functions
+@code{cygwin-convert-file-name-to-windows} and
+@code{cygwin-convert-file-name-from-windows} to convert between the
+two file-name syntaxes.}
@menu
* File Name Components:: The directory part of a file name, and the rest.
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
(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