* 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.
* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
@end menu
functions and variables that access the visited file name of a buffer or
that find an existing buffer by its visited file name.
+ In a Lisp program, if you want to look at the contents of a file but
+not alter it, the fastest way is to use @code{insert-file-contents} in a
+temporary buffer. Visiting the file is not necessary and takes longer.
+@xref{Reading from Files}.
+
@deffn Command find-file filename
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a
@end example
@end defun
-@deffn Command find-alternate-file filename
-This command selects a buffer visiting the file @var{filename}, then
-kills the buffer that was previously displayed in the selected window.
-It is useful if you have visited the wrong file by mistake, so that you
-can get rid of the buffer that you did not want to create, at the same
-time as you visit the file you intended.
-
-When this command is called interactively, it prompts for @var{filename}.
-@end deffn
-
@deffn Command find-file-other-window filename
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window. It may use another
@end deffn
@deffn Command view-file filename
-This command visits @var{filename} in View mode, returning to the
-previous buffer when done. View mode is a mode that allows you to skim
-rapidly through the file but does not let you modify it. Entering View
-mode runs the normal hook @code{view-mode-hook}. @xref{Hooks}.
+This command visits @var{filename} in View mode, and displays it in a
+recursive edit, returning to the previous buffer when done. View mode
+is a mode that allows you to skim rapidly through the file but does not
+let you modify it. Entering View mode runs the normal hook
+@code{view-mode-hook}. @xref{Hooks}.
When @code{view-file} is called interactively, it prompts for
@var{filename}.
@strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer.
+It also does not use the default major mode.
@example
@group
@defvar write-contents-hooks
This works just like @code{write-file-hooks}, but it is intended for
hooks that pertain to the contents of the file, as opposed to hooks that
-pertain to where the file came from. Typically major mode commands make
-buffer-local bindings for this variable.
+pertain to where the file came from. Such hooks are usually set up by
+major modes, as buffer-local bindings for this variable.
+
+This variable automatically becomes buffer-local whenever it is set;
+switching to a new major mode always resets this variable. When you use
+@code{add-hooks} to add an element to this hook, you should @emph{not}
+specify a non-@code{nil} @var{local} argument, since this variable is
+used @emph{only} locally.
@end defvar
@c Emacs 19 feature
prevents problems such as a lack of disk space from resulting in an
invalid file.
-(This feature worked differently in older Emacs versions.)
+As a side effect, backups are necessarily made by copying. @xref{Rename
+or Copy}. Yet, at the same time, saving a precious file always breaks
+all hard links between the file you save and other file names.
-Some modes set this non-@code{nil} locally in particular buffers.
+Some modes set this variable non-@code{nil} locally in particular
+buffers.
@end defvar
@defopt require-final-newline
@defun insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file @var{filename} into the
-current buffer after point. It returns a list of the absolute file name
+current buffer after point. It returns a list of the absolute file name
and the length of the data inserted. An error is signaled if
@var{filename} is not the name of a file that can be read.
-To set up saved text properties, @code{insert-file-contents} calls the
-functions in the list @code{after-insert-file-functions}. For more
-information, see @ref{Saving Properties}.
+The function @code{insert-file-contents} checks the file contents
+against the defined file formats, and converts the file contents if
+appropriate. @xref{Format Conversion}. It also calls the functions in
+the list @code{after-insert-file-functions}; see @ref{Saving
+Properties}.
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
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.
-To output information about text properties, @code{write-region} calls
-the functions in the list @code{write-region-annotation-functions}. For
-more information, see @ref{Saving Properties}.
+The function @code{write-region} converts the data which it writes to
+the appropriate file formats specified by @code{buffer-file-format}.
+@xref{Format Conversion}. It also calls the functions in the list
+@code{write-region-annotate-functions}; see @ref{Saving Properties}.
Normally, @code{write-region} displays a message @samp{Wrote file
@var{filename}} in the echo area. If @var{visit} is neither @code{t}
give an error.
@end defun
+@defun file-ownership-preserved-p filename
+This function returns @code{t} if deleting the file @var{filename} and
+then creating it anew would keep the file's owner unchanged.
+@end defun
+
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
@comment node-name, next, previous, up
@subsection Distinguishing Kinds of Files
- This section describes how to distinguish directories and symbolic
-links from ordinary files.
+ This section describes how to distinguish various kinds of files, such
+as directories, symbolic links, and ordinary files.
@defun file-symlink-p filename
@cindex file symbolic links
@end example
@end defun
+@defun file-regular-p filename
+This function returns @code{t} if the file @var{filename} exists and is
+a regular file (not a directory, symbolic link, named pipe, terminal, or
+other I/O device).
+@end defun
+
@node Truenames
@subsection Truenames
@cindex truename (of file)
is in the group with @sc{gid} 75.
@item (8489 20284)
-was last accessed on Aug 19 00:09. Unfortunately, you cannot convert
-this number into a time string in Emacs.
+was last accessed on Aug 19 00:09.
@item (8489 20284)
was last modified on Aug 19 00:09.
@end example
@end defun
+@defun file-name-sans-extension filename
+This function returns @var{filename} minus its ``extension,'' if any.
+The extension, in a file name, is the part that starts with the last
+@samp{.} in the last name component. For example,
+
+@example
+(file-name-sans-extension "foo.lose.c")
+ @result{} "foo.lose"
+(file-name-sans-extension "big.hack/foo")
+ @result{} "big.hack/foo"
+@end example
+@end defun
+
@node Directory Names
@comment node-name, next, previous, up
@subsection Directory Names
@defun delete-directory dirname
This function 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} in that case.
+must use @code{delete-directory} for them. If the directory contains
+any files, @code{delete-directory} signals an error.
@end defun
@node Magic File Names
@noindent
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@code{delete-file},@*
+@code{diff-latest-backup-file},
@code{directory-file-name},
-@code{diff-latest-backup-file}, @code{directory-files},
+@code{directory-files},
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},@*
@code{file-accessible-directory-p},
@code{file-name-as-directory}, @code{file-name-completion},
@code{file-name-directory}, @code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
-@code{file-readable-p}, @code{file-symlink-p}, @code{file-truename},
-@code{file-writable-p}, @code{insert-directory},@*
+@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
+@code{file-truename}, @code{file-writable-p},
+@code{get-file-buffer},
+@code{insert-directory},
@code{insert-file-contents}, @code{load}, @code{make-directory},
@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
is a good way to come up with one.
@end defun
+@node Format Conversion
+@section File Format Conversion
+
+@cindex file format conversion
+@cindex encoding file formats
+@cindex decoding file formats
+ The variable @code{format-alist} defines a list of @dfn{file formats},
+which describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+@defvar format-alist
+This list contains one format definition for each defined file format.
+@end defvar
+
+@cindex format definition
+Each format definition is a list of this form:
+
+@example
+(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
+@end example
+
+Here is what the elements in a format definition mean:
+
+@table @var
+@item name
+The name of this format.
+
+@item doc-string
+A documentation string for the format.
+
+@item regexp
+A regular expression which is used to recognize files represented in
+this format.
+
+@item from-fn
+A function to call to decode data in this format (to convert file data into
+the usual Emacs data representation).
+
+The @var{from-fn} is called with two args, @var{begin} and @var{end},
+which specify the part of the buffer it should convert. It should convert
+the text by editing it in place. Since this can change the length of the
+text, @var{from-fn} should return the modified end position.
+
+One responsibility of @var{from-fn} is to make sure that the beginning
+of the file no longer matches @var{regexp}. Otherwise it is likely to
+get called again.
+
+@item to-fn
+A function to call to encode data in this format (to convert
+the usual Emacs data representation into this format).
+
+The @var{to-fn} is called with two args, @var{begin} and @var{end},
+which specify the part of the buffer it should convert. There are
+two ways it can do the conversion:
+
+@itemize @bullet
+@item
+By editing the buffer in place. In this case, @var{to-fn} should
+return the end-position of the range of text, as modified.
+
+@item
+By returning a list of annotations. This is a list of elements of the
+form @code{(@var{position} . @var{string})}, where @var{position} is an
+integer specifying the relative position in the text to be written, and
+@var{string} is the annotation to add there. The list must be sorted in
+order of position when @var{to-fn} returns it.
+
+When @code{write-region} actually writes the text from the buffer to the
+file, it intermixes the specified annotations at the corresponding
+positions. All this takes place without modifying the buffer.
+@end itemize
+
+@item modify
+A flag, @code{t} if the encoding function modifies the buffer, and
+@code{nil} if it works by returning a list of annotations.
+
+@item mode
+A mode function to call after visiting a file converted from this
+format.
+@end table
+
+The function @code{insert-file-contents} automatically recognizes file
+formats when it reads the specified file. It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format. Then it checks all the known formats over again.
+It keeps checking them until none of them is applicable.
+
+Visiting a file, with @code{find-file-noselect} or the commands that use
+it, performs conversion likewise (because it calls
+@code{insert-file-contents}); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable @code{buffer-file-format}.
+
+@defvar buffer-file-format
+This variable states the format of the visited file. More precisely,
+this is a list of the file format names that were decoded in the course
+of visiting the current buffer's file. It is always local in all
+buffers.
+@end defvar
+
+When @code{write-region} writes data into a file, it first calls the
+encoding functions for the formats listed in @code{buffer-file-format},
+in the order of appearance in the list.
+
+@defun format-write-file file format
+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. The argument @var{format} is a list of format
+names.
+@end defun
+
+@defun format-find-file file format
+This command finds the file @var{file}, converting it according to
+format @var{format}. It also makes @var{format} the default if the
+buffer is saved later.
+
+The argument @var{format} is a list of format names. If @var{format} is
+@code{nil}, no conversion takes place. Interactively, typing just
+@key{RET} for @var{format} specifies @code{nil}.
+@end defun
+
+@defun format-insert-file file format %optional beg end
+This command inserts the contents of file @var{file}, converting it
+according to format @var{format}. If @var{beg} and @var{end} are
+non-@code{nil}, they specify which part of the file to read, as in
+@code{insert-file-contents} (@pxref{Reading from Files}).
+
+The return value is like what @code{insert-file-contents} returns: a
+list of the absolute file name and the length of the data inserted
+(after conversion).
+
+The argument @var{format} is a list of format names. If @var{format} is
+@code{nil}, no conversion takes place. Interactively, typing just
+@key{RET} for @var{format} specifies @code{nil}.
+@end defun
+
+@defvar auto-save-file-format
+This variable specifies the format to use for auto-saving. Its value is
+a list of format names, just like the value of
+@code{buffer-file-format}; but it is used instead of
+@code{buffer-file-format} for writing auto-save files. This variable
+is always local in all buffers.
+@end defvar
+
@node Files and MS-DOS
@section Files and MS-DOS
@cindex MS-DOS file types
Emacs on MS-DOS makes a distinction between text files and binary
files. This is necessary because ordinary text files on MS-DOS use a
two character sequence between lines: carriage-return and linefeed
-(CRLF). Emacs expects just a newline character (a linefeed) between
+(@sc{crlf}). Emacs expects just a newline character (a linefeed) between
lines. When Emacs reads or writes a text file on MS-DOS, it needs to
convert the line separators. This means it needs to know which files
are text files and which are binary. It makes this decision when