Mercurial > emacs
changeset 84067:d39de40c9c66
Move here from ../../lispref
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:19:55 +0000 |
| parents | 955480881db0 |
| children | c5bc1b7f62d7 |
| files | doc/lispref/files.texi |
| diffstat | 1 files changed, 3108 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/files.texi Thu Sep 06 04:19:55 2007 +0000 @@ -0,0 +1,3108 @@ +@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 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/files +@node Files, Backups and Auto-Saving, Documentation, Top +@comment node-name, next, previous, up +@chapter Files + + In Emacs, you can find, create, view, save, and otherwise work with +files and file directories. This chapter describes most of the +file-related functions of Emacs Lisp, but a few others are described in +@ref{Buffers}, and those related to backups and auto-saving are +described in @ref{Backups and Auto-Saving}. + + Many of the file functions take one or more arguments that are file +names. A file name is actually a string. Most of these functions +expand file name arguments by calling @code{expand-file-name}, so that +@file{~} is handled correctly, as are relative file names (including +@samp{../}). These functions don't recognize environment variable +substitutions such as @samp{$HOME}. @xref{File Name Expansion}. + + 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 +@code{locale-coding-system} (@pxref{Locales}). + +@menu +* Visiting Files:: Reading files into Emacs buffers for editing. +* Saving Buffers:: Writing changed buffers back into files. +* Reading from Files:: Reading files into buffers without visiting. +* Writing to Files:: Writing new files from parts of buffers. +* File Locks:: Locking and unlocking files, to prevent + simultaneous editing by two people. +* Information about Files:: Testing existence, accessibility, size of files. +* 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. +* Format Conversion:: Conversion to and from various file formats. +@end menu + +@node Visiting Files +@section Visiting Files +@cindex finding files +@cindex visiting files + + Visiting a file means reading a file into a buffer. Once this is +done, we say that the buffer is @dfn{visiting} that file, and call the +file ``the visited file'' of the buffer. + + A file and a buffer are two different things. A file is information +recorded permanently in the computer (unless you delete it). A buffer, +on the other hand, is information inside of Emacs that will vanish at +the end of the editing session (or when you kill the buffer). Usually, +a buffer contains information that you have copied from a file; then we +say the buffer is visiting that file. The copy in the buffer is what +you modify with editing commands. Such changes to the buffer do not +change the file; therefore, to make the changes permanent, you must +@dfn{save} the buffer, which means copying the altered buffer contents +back into the file. + + 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 +to make the distinction explicit. When dealing with a computer program, +however, it is good to keep the distinction in mind. + +@menu +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use. +@end menu + +@node Visiting Functions +@subsection Functions for Visiting Files + + This section describes the functions normally used to visit files. +For historical reasons, these functions have names starting with +@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for +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 &optional wildcards +This command selects a buffer visiting the file @var{filename}, +using an existing buffer if there is one, and otherwise creating a +new buffer and reading the file into it. It also returns that buffer. + +Aside from some technical details, the body of the @code{find-file} +function is basically equivalent to: + +@smallexample +(switch-to-buffer (find-file-noselect filename nil nil wildcards)) +@end smallexample + +@noindent +(See @code{switch-to-buffer} in @ref{Displaying Buffers}.) + +If @var{wildcards} is non-@code{nil}, which is always true in an +interactive call, then @code{find-file} expands wildcard characters in +@var{filename} and visits all the matching files. + +When @code{find-file} is called interactively, it prompts for +@var{filename} in the minibuffer. +@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 +buffer current or display it in a window if you wish, but this +function does not do so. + +The function returns an existing buffer if there is one; otherwise it +creates a new buffer and reads the file into it. When +@code{find-file-noselect} uses an existing buffer, it first verifies +that the file has not changed since it was last visited or saved in +that buffer. If the file has changed, this function asks the user +whether to reread the changed file. If the user says @samp{yes}, any +edits previously made in the buffer are lost. + +Reading the file involves decoding the file's contents (@pxref{Coding +Systems}), including end-of-line conversion, and format conversion +(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, +then @code{find-file-noselect} expands wildcard characters in +@var{filename} and visits all the matching files. + +This function displays warning or advisory messages in various peculiar +cases, unless the optional argument @var{nowarn} is non-@code{nil}. For +example, if it needs to create a buffer, and there is no file named +@var{filename}, it displays the message @samp{(New file)} in the echo +area, and leaves the buffer empty. + +The @code{find-file-noselect} function normally calls +@code{after-find-file} after reading the file (@pxref{Subroutines of +Visiting}). That function sets the buffer major mode, parses local +variables, warns the user if there exists an auto-save file more recent +than the file just visited, and finishes by running the functions in +@code{find-file-hook}. + +If the optional argument @var{rawfile} is non-@code{nil}, then +@code{after-find-file} is not called, and the +@code{find-file-not-found-functions} are not run in case of failure. +What's more, a non-@code{nil} @var{rawfile} value suppresses coding +system conversion and format conversion. + +The @code{find-file-noselect} function usually returns the buffer that +is visiting the file @var{filename}. But, if wildcards are actually +used and expanded, it returns a list of buffers that are visiting the +various files. + +@example +@group +(find-file-noselect "/etc/fstab") + @result{} #<buffer fstab> +@end group +@end example +@end defun + +@deffn Command find-file-other-window filename &optional wildcards +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 +existing window or split a window; see @ref{Displaying Buffers}. + +When this command is called interactively, it prompts for +@var{filename}. +@end deffn + +@deffn Command find-file-read-only filename &optional wildcards +This command selects a buffer visiting the file @var{filename}, like +@code{find-file}, but it marks the buffer as read-only. @xref{Read Only +Buffers}, for related functions and variables. + +When this command is called interactively, it prompts for +@var{filename}. +@end deffn + +@deffn Command view-file filename +This command visits @var{filename} using View mode, returning to the +previous buffer when you exit View mode. View mode is a minor mode that +provides commands to skim rapidly through the file, but does not let you +modify the text. 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}. +@end deffn + +@defopt find-file-wildcards +If this variable is non-@code{nil}, then the various @code{find-file} +commands check for wildcard characters and visit all the files that +match them (when invoked interactively or when their @var{wildcards} +argument is non-@code{nil}). If this option is @code{nil}, then +the @code{find-file} commands ignore their @var{wildcards} argument +and never treat wildcard characters specially. +@end defopt + +@defvar 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 + +@defvar find-file-not-found-functions +The value of this variable is a list of functions to be called when +@code{find-file} or @code{find-file-noselect} is passed a nonexistent +file name. @code{find-file-noselect} calls these functions as soon as +it detects a nonexistent file. It calls them in the order of the list, +until one of them returns non-@code{nil}. @code{buffer-file-name} is +already set up. + +This is not a normal hook because the values of the functions are +used, and in many cases only some of the functions are called. +@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 +which are sometimes useful in user Lisp code: @code{create-file-buffer} +and @code{after-find-file}. This section explains how to use them. + +@defun create-file-buffer filename +This function creates a suitably named buffer for visiting +@var{filename}, and returns it. It uses @var{filename} (sans directory) +as the name if that name is free; otherwise, it appends a string such as +@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. + +@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 +(create-file-buffer "foo") + @result{} #<buffer foo> +@end group +@group +(create-file-buffer "foo") + @result{} #<buffer foo<2>> +@end group +@group +(create-file-buffer "foo") + @result{} #<buffer foo<3>> +@end group +@end example + +This function is used by @code{find-file-noselect}. +It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). +@end defun + +@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes +This function sets the buffer major mode, and parses local variables +(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} +and by the default revert function (@pxref{Reverting}). + +@cindex new file message +@cindex file open error +If reading the file got an error because the file does not exist, but +its directory does exist, the caller should pass a non-@code{nil} value +for @var{error}. In that case, @code{after-find-file} issues a warning: +@samp{(New file)}. For more serious errors, the caller should usually not +call @code{after-find-file}. + +If @var{warn} is non-@code{nil}, then this function issues a warning +if an auto-save file exists and is more recent than the visited file. + +If @var{noauto} is non-@code{nil}, that says not to enable or disable +Auto-Save mode. The mode remains enabled if it was enabled before. + +If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that +means this call was from @code{revert-buffer}. This has no direct +effect, but some mode functions and hook functions check the value +of this variable. + +If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's +major mode, don't process local variables specifications in the file, +and don't run @code{find-file-hook}. This feature is used by +@code{revert-buffer} in some cases. + +The last thing @code{after-find-file} does is call all the functions +in the list @code{find-file-hook}. +@end defun + +@node Saving Buffers +@section Saving Buffers +@cindex saving buffers + + When you edit a file in Emacs, you are actually working on a buffer +that is visiting that file---that is, the contents of the file are +copied into the buffer and the copy is what you edit. Changes to the +buffer do not change the file until you @dfn{save} the buffer, which +means copying the contents of the buffer into the file. + +@deffn Command save-buffer &optional backup-option +This function saves the contents of the current buffer in its visited +file if the buffer has been modified since it was last visited or saved. +Otherwise it does nothing. + +@code{save-buffer} is responsible for making backup files. Normally, +@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup +file only if this is the first save since visiting the file. Other +values for @var{backup-option} request the making of backup files in +other circumstances: + +@itemize @bullet +@item +With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the +@code{save-buffer} function marks this version of the file to be +backed up when the buffer is next saved. + +@item +With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the +@code{save-buffer} function unconditionally backs up the previous +version of the file before saving it. + +@item +With an argument of 0, unconditionally do @emph{not} make any backup file. +@end itemize +@end deffn + +@deffn Command save-some-buffers &optional save-silently-p pred +@anchor{Definition of save-some-buffers} +This command saves some modified file-visiting buffers. Normally it +asks the user about each buffer. But if @var{save-silently-p} is +non-@code{nil}, it saves all the file-visiting buffers without querying +the user. + +The optional @var{pred} argument controls which buffers to ask about +(or to save silently if @var{save-silently-p} is non-@code{nil}). +If it is @code{nil}, that means to ask only about file-visiting buffers. +If it is @code{t}, that means also offer to save certain other non-file +buffers---those that have a non-@code{nil} buffer-local value of +@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says +@samp{yes} to saving a non-file buffer is asked to specify the file +name to use. The @code{save-buffers-kill-emacs} function passes the +value @code{t} for @var{pred}. + +If @var{pred} is neither @code{t} nor @code{nil}, then it should be +a function of no arguments. It will be called in each buffer to decide +whether to offer to save that buffer. If it returns a non-@code{nil} +value in a certain buffer, that means do offer to save that buffer. +@end deffn + +@deffn Command write-file filename &optional confirm +@anchor{Definition of write-file} +This function writes the current buffer into file @var{filename}, makes +the buffer visit that file, and marks it not modified. Then it renames +the buffer based on @var{filename}, appending a string like @samp{<2>} +if necessary to make a unique buffer name. It does most of this work by +calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and +@code{save-buffer}. + +If @var{confirm} is non-@code{nil}, that means to ask for confirmation +before overwriting an existing file. Interactively, confirmation is +required, unless the user supplies a prefix argument. + +If @var{filename} is an existing directory, or a symbolic link to one, +@code{write-file} uses the name of the visited file, in directory +@var{filename}. If the buffer is not visiting a file, it uses the +buffer name instead. +@end deffn + + Saving a buffer runs several hooks. It also performs format +conversion (@pxref{Format Conversion}). + +@defvar write-file-functions +The value of this variable is a list of functions to be called before +writing out a buffer to its visited file. If one of them returns +non-@code{nil}, the file is considered already written and the rest of +the functions are not called, nor is the usual code for writing the file +executed. + +If a function in @code{write-file-functions} returns non-@code{nil}, it +is responsible for making a backup file (if that is appropriate). +To do so, execute the following code: + +@example +(or buffer-backed-up (backup-buffer)) +@end example + +You might wish to save the file modes value returned by +@code{backup-buffer} and use that (if non-@code{nil}) to set the mode +bits of the file that you write. This is what @code{save-buffer} +normally does. @xref{Making Backups,, Making Backup Files}. + +The hook functions in @code{write-file-functions} are also responsible +for encoding the data (if desired): they must choose a suitable coding +system and end-of-line conversion (@pxref{Lisp and Coding Systems}), +perform the encoding (@pxref{Explicit Encoding}), and set +@code{last-coding-system-used} to the coding system that was used +(@pxref{Encoding and I/O}). + +If you set this hook locally in a buffer, it is assumed to be +associated with the file or the way the contents of the buffer were +obtained. Thus the variable is marked as a permanent local, so that +changing the major mode does not alter a buffer-local value. On the +other hand, calling @code{set-visited-file-name} will reset it. +If this is not what you want, you might like to use +@code{write-contents-functions} instead. + +Even though this is not a normal hook, you can use @code{add-hook} and +@code{remove-hook} to manipulate the list. @xref{Hooks}. +@end defvar + +@c Emacs 19 feature +@defvar write-contents-functions +This works just like @code{write-file-functions}, but it is intended +for hooks that pertain to the buffer's contents, not to the particular +visited file or its location. 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, but calling +@code{set-visited-file-name} does not. + +If any of the functions in this hook returns non-@code{nil}, the file +is considered already written and the rest are not called and neither +are the functions in @code{write-file-functions}. +@end defvar + +@defopt before-save-hook +This normal hook runs before a buffer is saved in its visited file, +regardless of whether that is done normally or by one of the hooks +described above. For instance, the @file{copyright.el} program uses +this hook to make sure the file you are saving has the current year in +its copyright notice. +@end defopt + +@c Emacs 19 feature +@defopt after-save-hook +This normal hook runs after a buffer has been saved in its visited file. +One use of this hook is in Fast Lock mode; it uses this hook to save the +highlighting information in a cache file. +@end defopt + +@defopt file-precious-flag +If this variable is non-@code{nil}, then @code{save-buffer} protects +against I/O errors while saving by writing the new file to a temporary +name instead of the name it is supposed to have, and then renaming it to +the intended name after it is clear there are no errors. This procedure +prevents problems such as a lack of disk space from resulting in an +invalid file. + +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 give this variable a non-@code{nil} buffer-local value +in particular buffers. +@end defopt + +@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. + +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 +major modes set it to @code{t} in particular buffers. +@end defopt + + See also the function @code{set-visited-file-name} (@pxref{Buffer File +Name}). + +@node Reading from Files +@comment node-name, next, previous, up +@section Reading from Files +@cindex reading from files + + You can copy a file from the disk and insert it into a buffer +using the @code{insert-file-contents} function. Don't use the user-level +command @code{insert-file} in a Lisp program, as that sets the mark. + +@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 +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. + +The function @code{insert-file-contents} checks the file contents +against the defined file formats, and converts the file contents if +appropriate and also calls the functions in +the list @code{after-insert-file-functions}. @xref{Format Conversion}. +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. + +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 +is visiting the file @var{filename}: these include the buffer's visited +file name and its last save file modtime. This feature is used by +@code{find-file-noselect} and you probably should not use it yourself. + +If @var{beg} and @var{end} are non-@code{nil}, they should be integers +specifying the portion of the file to insert. In this case, @var{visit} +must be @code{nil}. For example, + +@example +(insert-file-contents filename nil 0 500) +@end example + +@noindent +inserts the first 500 characters of a file. + +If the argument @var{replace} is non-@code{nil}, it means to replace the +contents of the buffer (actually, just the accessible portion) with the +contents of the file. This is better than simply deleting the buffer +contents and inserting the whole file, because (1) it preserves some +marker positions and (2) it puts less data in the undo list. + +It is possible to read a special file (such as a FIFO or an I/O device) +with @code{insert-file-contents}, as long as @var{replace} and +@var{visit} are @code{nil}. +@end defun + +@defun insert-file-contents-literally filename &optional visit beg end replace +This function works like @code{insert-file-contents} except that it does +not do format decoding (@pxref{Format Conversion}), does not do +character code conversion (@pxref{Coding Systems}), does not run +@code{find-file-hook}, does not perform automatic uncompression, and so +on. +@end defun + +If you want to pass a file name to another process so that another +program can read the file, use the function @code{file-local-copy}; see +@ref{Magic File Names}. + +@node Writing to Files +@comment node-name, next, previous, up +@section Writing to Files +@cindex writing to files + + You can write the contents of a buffer, or part of a buffer, directly +to a file on disk using the @code{append-to-file} and +@code{write-region} functions. Don't use these functions to write to +files that are being visited; that could cause confusion in the +mechanisms for visiting. + +@deffn Command append-to-file start end filename +This function appends the contents of the region delimited by +@var{start} and @var{end} in the current buffer to the end of file +@var{filename}. If that file does not exist, it is created. This +function returns @code{nil}. + +An error is signaled if @var{filename} specifies a nonwritable file, +or a nonexistent file in a directory where files cannot be created. + +When called from Lisp, this function is completely equivalent to: + +@example +(write-region start end filename t) +@end example +@end deffn + +@deffn Command write-region start end filename &optional append visit lockname mustbenew +This function writes the region delimited by @var{start} and @var{end} +in the current buffer into the file specified by @var{filename}. + +If @var{start} is @code{nil}, then the command writes the entire buffer +contents (@emph{not} just the accessible portion) to the file and +ignores @var{end}. + +@c Emacs 19 feature +If @var{start} is a string, then @code{write-region} writes or appends +that string, rather than text from the buffer. @var{end} is ignored in +this case. + +If @var{append} is non-@code{nil}, then the specified text is appended +to the existing file contents (if any). If @var{append} is an +integer, @code{write-region} seeks to that byte offset from the start +of the file and writes the data from there. + +If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks +for confirmation if @var{filename} names an existing file. If +@var{mustbenew} is the symbol @code{excl}, then @code{write-region} +does not ask for confirmation, but instead it signals an error +@code{file-already-exists} if the file already exists. + +The test for an existing file, when @var{mustbenew} is @code{excl}, uses +a special system feature. At least for files on a local disk, there is +no chance that some other program could create a file of the same name +before Emacs does, without Emacs's noticing. + +If @var{visit} is @code{t}, then Emacs establishes an association +between the buffer and the file: the buffer is then visiting that file. +It also sets the last file modification time for the current buffer to +@var{filename}'s modtime, and marks the buffer as not modified. This +feature is used by @code{save-buffer}, but you probably should not use +it yourself. + +@c Emacs 19 feature +If @var{visit} is a string, it specifies the file name to visit. This +way, you can write the data to one file (@var{filename}) while recording +the buffer as visiting another file (@var{visit}). The argument +@var{visit} is used in the echo area message and also for file locking; +@var{visit} is stored in @code{buffer-file-name}. This feature is used +to implement @code{file-precious-flag}; don't use it yourself unless you +really know what you're doing. + +The optional argument @var{lockname}, if non-@code{nil}, specifies the +file name to use for purposes of locking and unlocking, overriding +@var{filename} and @var{visit} for that purpose. + +The function @code{write-region} converts the data which it writes to +the appropriate file formats specified by @code{buffer-file-format} +and also calls the functions in the list +@code{write-region-annotate-functions}. +@xref{Format Conversion}. + +Normally, @code{write-region} displays the message @samp{Wrote +@var{filename}} in the echo area. If @var{visit} is neither @code{t} +nor @code{nil} nor a string, then this message is inhibited. This +feature is useful for programs that use files for internal purposes, +files that the user does not need to know about. +@end deffn + +@defmac with-temp-file file body@dots{} +@anchor{Definition of with-temp-file} +The @code{with-temp-file} macro evaluates the @var{body} forms with a +temporary buffer as the current buffer; then, at the end, it writes the +buffer contents into file @var{file}. It kills the temporary buffer +when finished, restoring the buffer that was current before the +@code{with-temp-file} form. Then it returns the value of the last form +in @var{body}. + +The current buffer is restored even in case of an abnormal exit via +@code{throw} or error (@pxref{Nonlocal Exits}). + +See also @code{with-temp-buffer} in @ref{Definition of +with-temp-buffer,, The Current Buffer}. +@end defmac + +@node File Locks +@section File Locks +@cindex file locks +@cindex lock file + + When two users edit the same file at the same time, they are likely +to interfere with each other. Emacs tries to prevent this situation +from arising by recording a @dfn{file lock} when a file is being +modified. (File locks are not implemented on Microsoft systems.) +Emacs can then detect the first attempt to modify a buffer visiting a +file that is locked by another Emacs job, and ask the user what to do. +The file lock is really a file, a symbolic link with a special name, +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.'' +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 +on disk catches some cases of simultaneous editing; see +@ref{Modification Time}. + +@defun file-locked-p filename +This function returns @code{nil} if the file @var{filename} is not +locked. It returns @code{t} if it is locked by this Emacs process, and +it returns the name of the user who has locked it if it is locked by +some other job. + +@example +@group +(file-locked-p "foo") + @result{} nil +@end group +@end example +@end defun + +@defun lock-buffer &optional filename +This function locks the file @var{filename}, if the current buffer is +modified. The argument @var{filename} defaults to the current buffer's +visited file. Nothing is done if the current buffer is not visiting a +file, or is not modified, or if the system does not support locking. +@end defun + +@defun unlock-buffer +This function unlocks the file being visited in the current buffer, +if the buffer is modified. If the buffer is not modified, then +the file should not be locked, so this function does nothing. It also +does nothing if the current buffer is not visiting a file, or if the +system does not support locking. +@end defun + + 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}. + +@defun ask-user-about-lock file other-user +This function is called when the user tries to modify @var{file}, but it +is locked by another user named @var{other-user}. The default +definition of this function asks the user to say what to do. The value +this function returns determines what Emacs does next: + +@itemize @bullet +@item +A value of @code{t} says to grab the lock on the file. Then +this user may edit the file and @var{other-user} loses the lock. + +@item +A value of @code{nil} says to ignore the lock and let this +user edit the file anyway. + +@item +@kindex file-locked +This function may instead signal a @code{file-locked} error, in which +case the change that the user was about to make does not take place. + +The error message for this error looks like this: + +@example +@error{} File is locked: @var{file} @var{other-user} +@end example + +@noindent +where @code{file} is the name of the file and @var{other-user} is the +name of the user who has locked the file. +@end itemize + +If you wish, you can replace the @code{ask-user-about-lock} function +with your own version that makes the decision in another way. The code +for its usual definition is in @file{userlock.el}. +@end defun + +@node Information about Files +@section Information about Files +@cindex file, information about + + The functions described in this section all operate on strings that +designate file names. With a few exceptions, all the functions have +names that begin with the word @samp{file}. These functions all +return information about actual files or directories, so their +arguments must all exist as actual files or directories unless +otherwise noted. + +@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. +* File Attributes:: How large is it? Any other names? Etc. +* Locating Files:: How to find a file in standard places. +@end menu + +@node Testing Accessibility +@comment node-name, next, previous, up +@subsection Testing Accessibility +@cindex accessibility of a file +@cindex file accessibility + + These functions test for permission to access a file in specific +ways. Unless explicitly stated otherwise, they recursively follow +symbolic links for their file name arguments, at all levels (at the +level of the file itself and at all levels of parent directories). + +@defun file-exists-p filename +This function returns @code{t} if a file named @var{filename} appears +to exist. This does not mean you can necessarily read the file, only +that you can find out its attributes. (On Unix and GNU/Linux, this is +true if the file exists and you have execute permission on the +containing directories, regardless of the protection of the file +itself.) + +If the file does not exist, or if fascist access control policies +prevent you from finding the attributes of the file, this function +returns @code{nil}. + +Directories are files, so @code{file-exists-p} returns @code{t} when +given a directory name. However, symbolic links are treated +specially; @code{file-exists-p} returns @code{t} for a symbolic link +name only if the target file exists. +@end defun + +@defun file-readable-p filename +This function returns @code{t} if a file named @var{filename} exists +and you can read it. It returns @code{nil} otherwise. + +@example +@group +(file-readable-p "files.texi") + @result{} t +@end group +@group +(file-exists-p "/usr/spool/mqueue") + @result{} t +@end group +@group +(file-readable-p "/usr/spool/mqueue") + @result{} nil +@end group +@end example +@end defun + +@c Emacs 19 feature +@defun file-executable-p filename +This function returns @code{t} if a file named @var{filename} exists and +you can execute it. It returns @code{nil} otherwise. On Unix and +GNU/Linux, if the file is a directory, execute permission means you can +check the existence and attributes of files inside the directory, and +open those files if their modes permit. +@end defun + +@defun file-writable-p filename +This function returns @code{t} if the file @var{filename} can be written +or created by you, and @code{nil} otherwise. A file is writable if the +file exists and you can write it. It is creatable if it does not exist, +but the specified directory does exist and you can write in that +directory. + +In the third example below, @file{foo} is not writable because the +parent directory does not exist, even though the user could create such +a directory. + +@example +@group +(file-writable-p "~/foo") + @result{} t +@end group +@group +(file-writable-p "/foo") + @result{} nil +@end group +@group +(file-writable-p "~/no-such-dir/foo") + @result{} nil +@end group +@end example +@end defun + +@c Emacs 19 feature +@defun file-accessible-directory-p dirname +This function returns @code{t} if you have permission to open existing +files in the directory whose name as a file is @var{dirname}; +otherwise (or if there is no such directory), it returns @code{nil}. +The value of @var{dirname} may be either a directory name (such as +@file{/foo/}) or the file name of a file which is a directory +(such as @file{/foo}, without the final slash). + +Example: after the following, + +@example +(file-accessible-directory-p "/foo") + @result{} nil +@end example + +@noindent +we can deduce that any attempt to read a file in @file{/foo/} will +give an error. +@end defun + +@defun access-file filename string +This function opens file @var{filename} for reading, then closes it and +returns @code{nil}. However, if the open fails, it signals an error +using @var{string} as the error message text. +@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. It also +returns @code{t} for nonexistent files. + +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 +follow symbolic links at all levels of parent directories. +@end defun + +@defun file-newer-than-file-p filename1 filename2 +@cindex file age +@cindex file modification time +This function returns @code{t} if the file @var{filename1} is +newer than file @var{filename2}. If @var{filename1} does not +exist, it returns @code{nil}. If @var{filename1} does exist, but +@var{filename2} does not, it returns @code{t}. + +In the following example, assume that the file @file{aug-19} was written +on the 19th, @file{aug-20} was written on the 20th, and the file +@file{no-file} doesn't exist at all. + +@example +@group +(file-newer-than-file-p "aug-19" "aug-20") + @result{} nil +@end group +@group +(file-newer-than-file-p "aug-20" "aug-19") + @result{} t +@end group +@group +(file-newer-than-file-p "aug-19" "no-file") + @result{} t +@end group +@group +(file-newer-than-file-p "no-file" "aug-19") + @result{} nil +@end group +@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}. +@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 +as directories, symbolic links, and ordinary files. + +@defun file-symlink-p filename +@cindex file symbolic links +If the file @var{filename} is a symbolic link, the +@code{file-symlink-p} function returns the (non-recursive) link target +as a string. (Determining the file name that the link points to from +the target is nontrivial.) First, this function recursively follows +symbolic links at all levels of parent directories. + +If the file @var{filename} is not a symbolic link (or there is no such file), +@code{file-symlink-p} returns @code{nil}. + +@example +@group +(file-symlink-p "foo") + @result{} nil +@end group +@group +(file-symlink-p "sym-link") + @result{} "foo" +@end group +@group +(file-symlink-p "sym-link2") + @result{} "sym-link" +@end group +@group +(file-symlink-p "/bin") + @result{} "/pub/bin" +@end group +@end example + +@c !!! file-symlink-p: should show output of ls -l for comparison +@end defun + +The next two functions recursively follow symbolic links at +all levels for @var{filename}. + +@defun file-directory-p filename +This function returns @code{t} if @var{filename} is the name of an +existing directory, @code{nil} otherwise. + +@example +@group +(file-directory-p "~rms") + @result{} t +@end group +@group +(file-directory-p "~rms/lewis/files.texi") + @result{} nil +@end group +@group +(file-directory-p "~rms/lewis/no-such-file") + @result{} nil +@end group +@group +(file-directory-p "$HOME") + @result{} nil +@end group +@group +(file-directory-p + (substitute-in-file-name "$HOME")) + @result{} t +@end group +@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, named pipe, terminal, or +other I/O device). +@end defun + +@node Truenames +@subsection Truenames +@cindex truename (of file) + +@c Emacs 19 features + The @dfn{truename} of a file is the name that you get by following +symbolic links at all levels until none remain, then simplifying away +@samp{.}@: and @samp{..}@: appearing as name components. This results +in a sort of canonical name for the file. A file does not always have a +unique truename; the number of distinct truenames a file has is equal to +the number of hard links to the file. However, truenames are useful +because they eliminate symbolic links as a cause of name variation. + +@defun file-truename filename +The function @code{file-truename} returns the truename of the file +@var{filename}. The argument must be an absolute file name. + +This function does not expand environment variables. Only +@code{substitute-in-file-name} does that. @xref{Definition of +substitute-in-file-name}. + +If you may need to follow symbolic links preceding @samp{..}@: +appearing as a name component, you should make sure to call +@code{file-truename} without prior direct or indirect calls to +@code{expand-file-name}, as otherwise the file name component +immediately preceding @samp{..} will be ``simplified away'' before +@code{file-truename} is called. To eliminate the need for a call to +@code{expand-file-name}, @code{file-truename} handles @samp{~} in the +same way that @code{expand-file-name} does. @xref{File Name +Expansion,, Functions that Expand Filenames}. +@end defun + +@defun file-chase-links filename &optional limit +This function follows symbolic links, starting with @var{filename}, +until it finds a file name which is not the name of a symbolic link. +Then it returns that file name. This function does @emph{not} follow +symbolic links at the level of parent directories. + +If you specify a number for @var{limit}, then after chasing through +that many links, the function just returns what it has even if that is +still a symbolic link. +@end defun + + To illustrate the difference between @code{file-chase-links} and +@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to +the directory @file{/home/foo}, and @file{/home/foo/hello} is an +ordinary file (or at least, not a symbolic link) or nonexistent. Then +we would have: + +@example +(file-chase-links "/usr/foo/hello") + ;; @r{This does not follow the links in the parent directories.} + @result{} "/usr/foo/hello" +(file-truename "/usr/foo/hello") + ;; @r{Assuming that @file{/home} is not a symbolic link.} + @result{} "/home/foo/hello" +@end example + + @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 information +about a file, other than its contents. This information includes the +mode bits that control access permission, the owner and group numbers, +the number of names, the inode number, the size, and the times of access +and modification. + +@defun file-modes filename +@cindex permission +@cindex file attributes +This function returns the mode bits of @var{filename}, as an integer. +The mode bits are also called the file permissions, and they specify +access control in the usual Unix fashion. If the low-order bit is 1, +then the file is executable by all users, if the second-lowest-order bit +is 1, then the file is writable by all users, etc. + +The highest value returnable is 4095 (7777 octal), meaning that +everyone has read, write, and execute permission, that the @acronym{SUID} bit +is set for both others and group, and that the sticky bit is set. + +If @var{filename} does not exist, @code{file-modes} returns @code{nil}. + +This function recursively follows symbolic links at all levels. + +@example +@group +(file-modes "~/junk/diffs") + @result{} 492 ; @r{Decimal integer.} +@end group +@group +(format "%o" 492) + @result{} "754" ; @r{Convert to octal.} +@end group + +@group +(set-file-modes "~/junk/diffs" 438) + @result{} nil +@end group + +@group +(format "%o" 438) + @result{} "666" ; @r{Convert to octal.} +@end group + +@group +% ls -l diffs + -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs +@end group +@end example +@end defun + +If the @var{filename} argument to the next two functions is a symbolic +link, then these function do @emph{not} replace it with its target. +However, they both recursively follow symbolic links at all levels of +parent directories. + +@defun file-nlinks filename +This functions returns the number of names (i.e., hard links) that +file @var{filename} has. If the file does not exist, then this function +returns @code{nil}. Note that symbolic links have no effect on this +function, because they are not considered to be names of the files they +link to. + +@example +@group +% ls -l foo* +-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo +-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 +@end group + +@group +(file-nlinks "foo") + @result{} 2 +@end group +@group +(file-nlinks "doesnt-exist") + @result{} nil +@end group +@end example +@end defun + +@defun file-attributes filename &optional id-format +@anchor{Definition of file-attributes} +This function returns a list of attributes of file @var{filename}. If +the specified file cannot be opened, it returns @code{nil}. +The optional parameter @var{id-format} specifies the preferred format +of attributes @acronym{UID} and @acronym{GID} (see below)---the +valid values are @code{'string} and @code{'integer}. The latter is +the default, but we plan to change that, so you should specify a +non-@code{nil} value for @var{id-format} if you use the returned +@acronym{UID} or @acronym{GID}. + +The elements of the list, in order, are: + +@enumerate 0 +@item +@code{t} for a directory, a string for a symbolic link (the name +linked to), or @code{nil} for a text file. + +@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 +@item +The number of names the file has. Alternate names, also known as hard +links, can be created by using the @code{add-name-to-file} function +(@pxref{Changing Files}). + +@item +The file's @acronym{UID}, normally as a string. However, if it does +not correspond to a named user, the value is an integer or a floating +point number. + +@item +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 +value of @code{current-time}; see @ref{Time of Day}.) + +@item +The time of last modification as a list of two integers (as above). +@cindex modification time of file + +@item +The time of last status change as a list of two integers (as above). + +@item +The size of the file in bytes. If the size is too large to fit in a +Lisp integer, this is a floating point number. + +@item +The file's modes, as a string of ten letters or dashes, +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. + +@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. + +@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. +@end enumerate + +For example, here are the file attributes for @file{files.texi}: + +@example +@group +(file-attributes "files.texi" 'string) + @result{} (nil 1 "lh" "users" + (8489 20284) + (8489 20284) + (8489 20285) + 14906 "-rw-rw-rw-" + nil 129500 -32252) +@end group +@end example + +@noindent +and here is how the result is interpreted: + +@table @code +@item nil +is neither a directory nor a symbolic link. + +@item 1 +has only one name (the name @file{files.texi} in the current default +directory). + +@item "lh" +is owned by the user with name "lh". + +@item "users" +is in the group with name "users". + +@item (8489 20284) +was last accessed on Aug 19 00:09. + +@item (8489 20284) +was last modified on Aug 19 00:09. + +@item (8489 20285) +last had its inode changed on Aug 19 00:09. + +@item 14906 +is 14906 bytes long. (It may not contain 14906 characters, though, +if some of the bytes belong to multibyte sequences.) + +@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. +@end table +@end defun + +@node Locating Files +@subsection How to Locate Files in Standard Places +@cindex locate file in path +@cindex find file in path + + This section explains how to search for a file in a list of +directories (a @dfn{path}). One example is when you need to look for +a program's executable file, e.g., to find out whether a given program +is installed on the user's system. Another example is the search for +Lisp libraries (@pxref{Library Search}). Such searches generally need +to try various possible file name extensions, in addition to various +possible directories. Emacs provides a function for such a +generalized search for a file. + +@defun locate-file filename path &optional suffixes predicate +This function searches for a file whose name is @var{filename} in a +list of directories given by @var{path}, trying the suffixes in +@var{suffixes}. If it finds such a file, it returns the full +@dfn{absolute file name} of the file (@pxref{Relative File Names}); +otherwise it returns @code{nil}. + +The optional argument @var{suffixes} gives the list of file-name +suffixes to append to @var{filename} when searching. +@code{locate-file} tries each possible directory with each of these +suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there +are no suffixes, and @var{filename} is used only as-is. Typical +values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess +Creation, exec-suffixes}), @code{load-suffixes}, +@code{load-file-rep-suffixes} and the return value of the function +@code{get-load-suffixes} (@pxref{Load Suffixes}). + +Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess +Creation, exec-path}) when looking for executable programs or +@code{load-path} (@pxref{Library Search, load-path}) when looking for +Lisp files. If @var{filename} is absolute, @var{path} has no effect, +but the suffixes in @var{suffixes} are still tried. + +The optional argument @var{predicate}, if non-@code{nil}, specifies +the predicate function to use for testing whether a candidate file is +suitable. The predicate function is passed the candidate file name as +its single argument. If @var{predicate} is @code{nil} or unspecified, +@code{locate-file} uses @code{file-readable-p} as the default +predicate. Useful non-default predicates include +@code{file-executable-p}, @code{file-directory-p}, and other +predicates described in @ref{Kinds of Files}. + +For compatibility, @var{predicate} can also be one of the symbols +@code{executable}, @code{readable}, @code{writable}, @code{exists}, or +a list of one or more of these symbols. +@end defun + +@defun executable-find program +This function searches for the executable file of the named +@var{program} and returns the full absolute name of the executable, +including its file-name extensions, if any. It returns @code{nil} if +the file is not found. The functions searches in all the directories +in @code{exec-path} and tries all the file-name extensions in +@code{exec-suffixes}. +@end defun + +@node Changing Files +@section Changing File Names and Attributes +@c @cindex renaming files Duplicates rename-file +@cindex copying files +@cindex deleting files +@cindex linking files +@cindex setting modes of files + + The functions in this section rename, copy, delete, link, and set the +modes of files. + + In the functions that have an argument @var{newname}, if a file by the +name of @var{newname} already exists, the actions taken depend on the +value of the argument @var{ok-if-already-exists}: + +@itemize @bullet +@item +Signal a @code{file-already-exists} error if +@var{ok-if-already-exists} is @code{nil}. + +@item +Request confirmation if @var{ok-if-already-exists} is a number. + +@item +Replace the old file without confirmation if @var{ok-if-already-exists} +is any other value. +@end itemize + +The next four commands all recursively follow symbolic links at all +levels of parent directories for their first argument, but, if that +argument is itself a symbolic link, then only @code{copy-file} +replaces it with its (recursive) target. + +@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists +@cindex file with multiple names +@cindex file hard link +This function gives the file named @var{oldname} the additional name +@var{newname}. This means that @var{newname} becomes a new ``hard +link'' to @var{oldname}. + +In the first part of the following example, we list two files, +@file{foo} and @file{foo3}. + +@example +@group +% ls -li fo* +81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo +84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 +@end group +@end example + +Now we create a hard link, by calling @code{add-name-to-file}, then list +the files again. This shows two names for one file, @file{foo} and +@file{foo2}. + +@example +@group +(add-name-to-file "foo" "foo2") + @result{} nil +@end group + +@group +% ls -li fo* +81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo +81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 +84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 +@end group +@end example + +Finally, we evaluate the following: + +@example +(add-name-to-file "foo" "foo3" t) +@end example + +@noindent +and list the files again. Now there are three names +for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old +contents of @file{foo3} are lost. + +@example +@group +(add-name-to-file "foo1" "foo3") + @result{} nil +@end group + +@group +% ls -li fo* +81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo +81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 +81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 +@end group +@end example + +This function is meaningless on operating systems where multiple names +for one file are not allowed. Some systems implement multiple names +by copying the file instead. + +See also @code{file-nlinks} in @ref{File Attributes}. +@end deffn + +@deffn Command rename-file filename newname &optional ok-if-already-exists +This command renames the file @var{filename} as @var{newname}. + +If @var{filename} has additional names aside from @var{filename}, it +continues to have those names. In fact, adding the name @var{newname} +with @code{add-name-to-file} and then deleting @var{filename} has the +same effect as renaming, aside from momentary intermediate states. +@end deffn + +@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid +This command copies the file @var{oldname} to @var{newname}. An +error is signaled if @var{oldname} does not exist. If @var{newname} +names a directory, it copies @var{oldname} into that directory, +preserving its final name component. + +If @var{time} is non-@code{nil}, then this function gives the new file +the same last-modified time that the old one has. (This works on only +some operating systems.) If setting the time gets an error, +@code{copy-file} signals a @code{file-date-error} error. In an +interactive call, a prefix argument specifies a non-@code{nil} value +for @var{time}. + +This function copies the file modes, too. + +If argument @var{preserve-uid-gid} is @code{nil}, we let the operating +system decide the user and group ownership of the new file (this is +usually set to the user running Emacs). If @var{preserve-uid-gid} is +non-@code{nil}, we attempt to copy the user and group ownership of the +file. This works only on some operating systems, and only if you have +the correct permissions to do so. +@end deffn + +@deffn Command make-symbolic-link filename newname &optional ok-if-exists +@pindex ln +@kindex file-already-exists +This command makes a symbolic link to @var{filename}, named +@var{newname}. This is like the shell command @samp{ln -s +@var{filename} @var{newname}}. + +This function is not available on systems that don't support symbolic +links. +@end deffn + +@deffn Command delete-file filename +@pindex rm +This command deletes the file @var{filename}, like the shell command +@samp{rm @var{filename}}. If the file has multiple names, it continues +to exist under the other names. + +A suitable kind of @code{file-error} error is signaled if the file does +not exist, or is not deletable. (On Unix and GNU/Linux, a file is +deletable if its directory is writable.) + +If @var{filename} is a symbolic link, @code{delete-file} does not +replace it with its target, but it does follow symbolic links at all +levels of parent directories. + +See also @code{delete-directory} in @ref{Create/Delete Dirs}. +@end deffn + +@defun define-logical-name varname string +This function defines the logical name @var{varname} to have the value +@var{string}. It is available only on VMS. +@end defun + +@defun set-file-modes filename mode +This function sets mode bits of @var{filename} to @var{mode} (which +must be an integer). Only the low 12 bits of @var{mode} are used. +This function recursively follows symbolic links at all levels for +@var{filename}. +@end defun + +@c Emacs 19 feature +@defun set-default-file-modes mode +@cindex umask +This function sets the default file protection for new files created by +Emacs and its subprocesses. Every file created with Emacs initially has +this protection, or a subset of it (@code{write-region} will not give a +file execute permission even if the default file protection allows +execute permission). On Unix and GNU/Linux, the default protection is +the bitwise complement of the ``umask'' value. + +The argument @var{mode} must be an integer. On most systems, only the +low 9 bits of @var{mode} are meaningful. You can use the Lisp construct +for octal character codes to enter @var{mode}; for example, + +@example +(set-default-file-modes ?\644) +@end example + +Saving a modified version of an existing file does not count as creating +the file; it preserves the existing file's mode, whatever that is. So +the default file protection has no effect. +@end defun + +@defun default-file-modes +This function returns the current default protection value. +@end defun + +@defun set-file-times filename &optional time +This function sets the access and modification times of @var{filename} +to @var{time}. The return value is @code{t} if the times are successfully +set, otherwise it is @code{nil}. @var{time} defaults to the current +time and must be in the format returned by @code{current-time} +(@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 + + Files are generally referred to by their names, in Emacs as elsewhere. +File names in Emacs are represented as strings. The functions that +operate on a file all expect a file name argument. + + In addition to operating on files themselves, Emacs Lisp programs +often need to operate on file names; i.e., to take them apart and to use +part of a name to construct related file names. This section describes +how to manipulate file names. + + The functions in this section do not actually access files, so they +can operate on file names that do not refer to an existing file or +directory. + + 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. On VMS, these functions (and the ones +that operate on files) understand both VMS file-name syntax and Unix +syntax. This enables Lisp programs to specify file names in Unix syntax +and work properly on all systems without change. + +@menu +* File Name Components:: The directory part of a file name, and the rest. +* Relative File Names:: Some file names are relative to a current directory. +* Directory Names:: A directory's name as a directory + is different from its name as a file. +* File Name Expansion:: Converting relative file names to absolute ones. +* Unique File Names:: Generating names for temporary files. +* File Name Completion:: Finding the completions for a given file name. +* Standard File Names:: If your package uses a fixed file name, + how to handle various operating systems simply. +@end menu + +@node File Name Components +@subsection File Name Components +@cindex directory part (of file name) +@cindex nondirectory part (of file name) +@cindex version number (in file name) + + The operating system groups files into directories. To specify a +file, you must specify the directory and the file's name within that +directory. Therefore, Emacs considers a file name as having two main +parts: the @dfn{directory name} part, and the @dfn{nondirectory} part +(or @dfn{file name within the directory}). Either part may be empty. +Concatenating these two parts reproduces the original file name. + + On most systems, the directory part is everything up to and including +the last slash (backslash is also allowed in input on MS-DOS or +MS-Windows); the nondirectory part is the rest. The rules in VMS syntax +are complicated. + + For some purposes, the nondirectory part is further subdivided into +the name proper and the @dfn{version number}. On most systems, only +backup files have version numbers in their names. On VMS, every file +has a version number, but most of the time the file name actually used +in Emacs omits the version number, so that version numbers in Emacs are +found mostly in directory lists. + +@defun file-name-directory filename +This function returns the directory part of @var{filename}, as a +directory name (@pxref{Directory Names}), or @code{nil} if +@var{filename} does not include a directory part. + +On GNU and Unix systems, a string returned by this function always +ends in a slash. On MS-DOS it can also end in a colon. On VMS, it +returns a string ending in one of the three characters @samp{:}, +@samp{]}, or @samp{>}. + +@example +@group +(file-name-directory "lewis/foo") ; @r{Unix example} + @result{} "lewis/" +@end group +@group +(file-name-directory "foo") ; @r{Unix example} + @result{} nil +@end group +@group +(file-name-directory "[X]FOO.TMP") ; @r{VMS example} + @result{} "[X]" +@end group +@end example +@end defun + +@defun file-name-nondirectory filename +This function returns the nondirectory part of @var{filename}. + +@example +@group +(file-name-nondirectory "lewis/foo") + @result{} "foo" +@end group +@group +(file-name-nondirectory "foo") + @result{} "foo" +@end group +@group +(file-name-nondirectory "lewis/") + @result{} "" +@end group +@group +;; @r{The following example is accurate only on VMS.} +(file-name-nondirectory "[X]FOO.TMP") + @result{} "FOO.TMP" +@end group +@end example +@end defun + +@defun file-name-sans-versions filename &optional keep-backup-version +This function returns @var{filename} with any file version numbers, +backup version numbers, or trailing tildes discarded. + +If @var{keep-backup-version} is non-@code{nil}, then true file version +numbers understood as such by the file system are discarded from the +return value, but backup version numbers are kept. + +@example +@group +(file-name-sans-versions "~rms/foo.~1~") + @result{} "~rms/foo" +@end group +@group +(file-name-sans-versions "~rms/foo~") + @result{} "~rms/foo" +@end group +@group +(file-name-sans-versions "~rms/foo") + @result{} "~rms/foo" +@end group +@group +;; @r{The following example applies to VMS only.} +(file-name-sans-versions "foo;23") + @result{} "foo" +@end group +@end example +@end defun + +@defun file-name-extension filename &optional period +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 +starts with the last @samp{.} in the last name component (minus +any version/backup part). + +This function returns @code{nil} for extensionless file names such as +@file{foo}. It returns @code{""} for null extensions, as in +@file{foo.}. If the last component of a file name begins with a +@samp{.}, that @samp{.} doesn't count as the beginning of an +extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not +@samp{.emacs}. + +If @var{period} is non-@code{nil}, then the returned value includes +the period that delimits the extension, and if @var{filename} has no +extension, the value is @code{""}. +@end defun + +@defun file-name-sans-extension filename +This function returns @var{filename} minus its extension, if any. The +version/backup part, if present, is only removed if the file has an +extension. For example, + +@example +(file-name-sans-extension "foo.lose.c") + @result{} "foo.lose" +(file-name-sans-extension "big.hack/foo") + @result{} "big.hack/foo" +(file-name-sans-extension "/my/home/.emacs") + @result{} "/my/home/.emacs" +(file-name-sans-extension "/my/home/.emacs.el") + @result{} "/my/home/.emacs" +(file-name-sans-extension "~/foo.el.~3~") + @result{} "~/foo" +(file-name-sans-extension "~/foo.~3~") + @result{} "~/foo.~3~" +@end example + +Note that the @samp{.~3~} in the two last examples is the backup part, +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 +@cindex absolute file name +@cindex relative file name + + All the directories in the file system form a tree starting at the +root directory. A file name can specify all the directory names +starting from the root of the tree; then it is called an @dfn{absolute} +file name. Or it can specify the position of the file in the tree +relative to a default directory; then it is called a @dfn{relative} file +name. On Unix and GNU/Linux, an absolute file name starts with a slash +or a tilde (@samp{~}), and a relative one does not. On MS-DOS and +MS-Windows, an absolute file name starts with a slash or a backslash, or +with a drive specification @samp{@var{x}:/}, where @var{x} is the +@dfn{drive letter}. The rules on VMS are complicated. + +@defun file-name-absolute-p filename +This function returns @code{t} if file @var{filename} is an absolute +file name, @code{nil} otherwise. On VMS, this function understands both +Unix syntax and VMS syntax. + +@example +@group +(file-name-absolute-p "~rms/foo") + @result{} t +@end group +@group +(file-name-absolute-p "rms/foo") + @result{} nil +@end group +@group +(file-name-absolute-p "/user/rms/foo") + @result{} t +@end group +@end example +@end defun + + Given a possibly relative file name, you can convert it to an +absolute name using @code{expand-file-name} (@pxref{File Name +Expansion}). This function converts absolute file names to relative +names: + +@defun file-relative-name filename &optional directory +This function tries to return a relative name that is equivalent to +@var{filename}, assuming the result will be interpreted relative to +@var{directory} (an absolute directory name or directory file name). +If @var{directory} is omitted or @code{nil}, it defaults to the +current buffer's default directory. + +On some operating systems, an absolute file name begins with a device +name. On such systems, @var{filename} has no relative equivalent based +on @var{directory} if they start with two different device names. In +this case, @code{file-relative-name} returns @var{filename} in absolute +form. + +@example +(file-relative-name "/foo/bar" "/foo/") + @result{} "bar" +(file-relative-name "/foo/bar" "/hack/") + @result{} "../foo/bar" +@end example +@end defun + +@node Directory Names +@comment node-name, next, previous, up +@subsection Directory Names +@cindex directory name +@cindex file name of directory + + A @dfn{directory name} is the name of a directory. A directory is +actually a kind of file, so it has a file name, which is related to +the directory name but not identical to it. (This is not quite the +same as the usual Unix terminology.) These two different names for +the same entity are related by a syntactic transformation. On GNU and +Unix systems, this is simple: a directory name ends in a slash, +whereas the directory's name as a file lacks that slash. On MS-DOS and +VMS, the relationship is more complicated. + + The difference between a directory name and its name as a file is +subtle but crucial. When an Emacs variable or function argument is +described as being a directory name, a file name of a directory is not +acceptable. When @code{file-name-directory} returns a string, that is +always a directory name. + + The following two functions convert between directory names and file +names. They do nothing special with environment variable substitutions +such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. + +@defun file-name-as-directory filename +This function returns a string representing @var{filename} in a form +that the operating system will interpret as the name of a directory. On +most systems, this means appending a slash to the string (if it does not +already end in one). On VMS, the function converts a string of the form +@file{[X]Y.DIR.1} to the form @file{[X.Y]}. + +@example +@group +(file-name-as-directory "~rms/lewis") + @result{} "~rms/lewis/" +@end group +@end example +@end defun + +@defun directory-file-name dirname +This function returns a string representing @var{dirname} in a form that +the operating system will interpret as the name of a file. On most +systems, this means removing the final slash (or backslash) from the +string. On VMS, the function converts a string of the form @file{[X.Y]} +to @file{[X]Y.DIR.1}. + +@example +@group +(directory-file-name "~lewis/") + @result{} "~lewis" +@end group +@end example +@end defun + + Given a directory name, you can combine it with a relative file name +using @code{concat}: + +@example +(concat @var{dirname} @var{relfile}) +@end example + +@noindent +Be sure to verify that the file name is relative before doing that. +If you use an absolute file name, the results could be syntactically +invalid or refer to the wrong file. + + If you want to use a directory file name in making such a +combination, you must first convert it to a directory name using +@code{file-name-as-directory}: + +@example +(concat (file-name-as-directory @var{dirfile}) @var{relfile}) +@end example + +@noindent +Don't try concatenating a slash by hand, as in + +@example +;;; @r{Wrong!} +(concat @var{dirfile} "/" @var{relfile}) +@end example + +@noindent +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, +because it recognizes abbreviations even as part of the name. +@end defun + +@node File Name Expansion +@subsection Functions that Expand Filenames +@cindex expansion of file names + + @dfn{Expansion} of a file name means converting a relative file name +to an absolute one. Since this is done relative to a default directory, +you must specify the default directory name as well as the file name to +be expanded. Expansion also simplifies file names by eliminating +redundancies such as @file{./} and @file{@var{name}/../}. + +@defun expand-file-name filename &optional directory +This function converts @var{filename} to an absolute file name. If +@var{directory} is supplied, it is the default directory to start with +if @var{filename} is relative. (The value of @var{directory} should +itself be an absolute directory name or directory file name; it may +start with @samp{~}.) Otherwise, the current buffer's value of +@code{default-directory} is used. For example: + +@example +@group +(expand-file-name "foo") + @result{} "/xcssun/users/rms/lewis/foo" +@end group +@group +(expand-file-name "../foo") + @result{} "/xcssun/users/rms/foo" +@end group +@group +(expand-file-name "foo" "/usr/spool/") + @result{} "/usr/spool/foo" +@end group +@group +(expand-file-name "$HOME/foo") + @result{} "/xcssun/users/rms/lewis/$HOME/foo" +@end group +@end example + +If the part of the combined file name before the first slash is +@samp{~}, it expands to the value of the @env{HOME} environment +variable (usually your home directory). If the part before the first +slash is @samp{~@var{user}} and if @var{user} is a valid login name, +it expands to @var{user}'s home directory. + +Filenames containing @samp{.} or @samp{..} are simplified to their +canonical form: + +@example +@group +(expand-file-name "bar/../foo") + @result{} "/xcssun/users/rms/lewis/foo" +@end group +@end example + +In some cases, a leading @samp{..} component can remain in the output: + +@example +@group +(expand-file-name "../home" "/") + @result{} "/../home" +@end group +@end example + +@noindent +This is for the sake of filesystems that have the concept of a +``superroot'' above the root directory @file{/}. On other filesystems, +@file{/../} is interpreted exactly the same as @file{/}. + +Note that @code{expand-file-name} does @emph{not} expand environment +variables; only @code{substitute-in-file-name} does that. + +Note also that @code{expand-file-name} does not follow symbolic links +at any level. This results in a difference between the way +@code{file-truename} and @code{expand-file-name} treat @samp{..}. +Assuming that @samp{/tmp/bar} is a symbolic link to the directory +@samp{/tmp/foo/bar} we get: + +@example +@group +(file-truename "/tmp/bar/../myfile") + @result{} "/tmp/foo/myfile" +@end group +@group +(expand-file-name "/tmp/bar/../myfile") + @result{} "/tmp/myfile" +@end group +@end example + +If you may need to follow symbolic links preceding @samp{..}, you +should make sure to call @code{file-truename} without prior direct or +indirect calls to @code{expand-file-name}. @xref{Truenames}. +@end defun + +@defvar default-directory +The value of this buffer-local variable is the default directory for the +current buffer. It should be an absolute directory name; it may start +with @samp{~}. This variable is buffer-local in every buffer. + +@code{expand-file-name} uses the default directory when its second +argument is @code{nil}. + +Aside from VMS, the value is always a string ending with a slash. + +@example +@group +default-directory + @result{} "/user/lewis/manual/" +@end group +@end example +@end defvar + +@defun substitute-in-file-name filename +@anchor{Definition of substitute-in-file-name} +This function replaces environment variable references in +@var{filename} with the environment variable values. Following +standard Unix shell syntax, @samp{$} is the prefix to substitute an +environment variable value. If the input contains @samp{$$}, that is +converted to @samp{$}; this gives the user a way to ``quote'' a +@samp{$}. + +The environment variable name is the series of alphanumeric characters +(including underscores) that follow the @samp{$}. If the character following +the @samp{$} is a @samp{@{}, then the variable name is everything up to the +matching @samp{@}}. + +Calling @code{substitute-in-file-name} on output produced by +@code{substitute-in-file-name} tends to give incorrect results. For +instance, use of @samp{$$} to quote a single @samp{$} won't work +properly, and @samp{$} in an environment variable's value could lead +to repeated substitution. Therefore, programs that call this function +and put the output where it will be passed to this function need to +double all @samp{$} characters to prevent subsequent incorrect +results. + +@c Wordy to avoid overfull hbox. --rjc 15mar92 +Here we assume that the environment variable @code{HOME}, which holds +the user's home directory name, has value @samp{/xcssun/users/rms}. + +@example +@group +(substitute-in-file-name "$HOME/foo") + @result{} "/xcssun/users/rms/foo" +@end group +@end example + +After substitution, if a @samp{~} or a @samp{/} appears immediately +after another @samp{/}, the function discards everything before it (up +through the immediately preceding @samp{/}). + +@example +@group +(substitute-in-file-name "bar/~/foo") + @result{} "~/foo" +@end group +@group +(substitute-in-file-name "/usr/local/$HOME/foo") + @result{} "/xcssun/users/rms/foo" + ;; @r{@file{/usr/local/} has been discarded.} +@end group +@end example + +On VMS, @samp{$} substitution is not done, so this function does nothing +on VMS except discard superfluous initial components as shown above. +@end defun + +@node Unique File Names +@subsection Generating Unique File Names + + Some programs need to write temporary files. Here is the usual way to +construct a name for such a file: + +@example +(make-temp-file @var{name-of-application}) +@end example + +@noindent +The job of @code{make-temp-file} is to prevent two different users or +two different jobs from trying to use the exact same file name. + +@defun make-temp-file prefix &optional dir-flag suffix +This function creates a temporary file and returns its name. Emacs +creates the temporary file's name by adding to @var{prefix} some +random characters that are different in each Emacs job. The result is +guaranteed to be a newly created empty file. On MS-DOS, this function +can truncate the @var{string} prefix to fit into the 8+3 file-name +limits. If @var{prefix} is a relative file name, it is expanded +against @code{temporary-file-directory}. + +@example +@group +(make-temp-file "foo") + @result{} "/tmp/foo232J6v" +@end group +@end example + +When @code{make-temp-file} returns, the file has been created and is +empty. At that point, you should write the intended contents into the +file. + +If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an +empty directory instead of an empty file. It returns the file name, +not the directory name, of that directory. @xref{Directory Names}. + +If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at +the end of the file name. + +To prevent conflicts among different libraries running in the same +Emacs, each Lisp program that uses @code{make-temp-file} should have its +own @var{prefix}. The number added to the end of @var{prefix} +distinguishes between the same application running in different Emacs +jobs. Additional added characters permit a large number of distinct +names even in one Emacs job. +@end defun + + The default directory for temporary files is controlled by the +variable @code{temporary-file-directory}. This variable gives the user +a uniform way to specify the directory for all temporary files. Some +programs use @code{small-temporary-file-directory} instead, if that is +non-@code{nil}. To use it, you should expand the prefix against +the proper directory before calling @code{make-temp-file}. + + In older Emacs versions where @code{make-temp-file} does not exist, +you should use @code{make-temp-name} instead: + +@example +(make-temp-name + (expand-file-name @var{name-of-application} + temporary-file-directory)) +@end example + +@defun make-temp-name string +This function generates a string that can be used as a unique file +name. The name starts with @var{string}, and has several random +characters appended to it, which are different in each Emacs job. It +is like @code{make-temp-file} except that it just constructs a name, +and does not create a file. Another difference is that @var{string} +should be an absolute file name. On MS-DOS, this function can +truncate the @var{string} prefix to fit into the 8+3 file-name limits. +@end defun + +@defvar temporary-file-directory +@cindex @code{TMPDIR} environment variable +@cindex @code{TMP} environment variable +@cindex @code{TEMP} environment variable +This variable specifies the directory name for creating temporary files. +Its value should be a directory name (@pxref{Directory Names}), but it +is good for Lisp programs to cope if the value is a directory's file +name instead. Using the value as the second argument to +@code{expand-file-name} is a good way to achieve that. + +The default value is determined in a reasonable way for your operating +system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} +environment variables, with a fall-back to a system-dependent name if +none of these variables is defined. + +Even if you do not use @code{make-temp-file} to create the temporary +file, you should still use this variable to decide which directory to +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 + +@defvar small-temporary-file-directory +This variable specifies the directory name for +creating certain temporary files, which are likely to be small. + +If you want to write a temporary file which is likely to be small, you +should compute the directory like this: + +@example +(make-temp-file + (expand-file-name @var{prefix} + (or small-temporary-file-directory + temporary-file-directory))) +@end example +@end defvar + +@node File Name Completion +@subsection File Name Completion +@cindex file name completion subroutines +@cindex completion, file name + + This section describes low-level subroutines for completing a file +name. For higher level functions, see @ref{Reading File Names}. + +@defun file-name-all-completions partial-filename directory +This function returns a list of all possible completions for a file +whose name starts with @var{partial-filename} in directory +@var{directory}. The order of the completions is the order of the files +in the directory, which is unpredictable and conveys no useful +information. + +The argument @var{partial-filename} must be a file name containing no +directory part and no slash (or backslash on some systems). The current +buffer's default directory is prepended to @var{directory}, if +@var{directory} is not absolute. + +In the following example, suppose that @file{~rms/lewis} is the current +default directory, and has five files whose names begin with @samp{f}: +@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and +@file{file.c.~2~}.@refill + +@example +@group +(file-name-all-completions "f" "") + @result{} ("foo" "file~" "file.c.~2~" + "file.c.~1~" "file.c") +@end group + +@group +(file-name-all-completions "fo" "") + @result{} ("foo") +@end group +@end example +@end defun + +@defun file-name-completion filename directory &optional predicate +This function completes the file name @var{filename} in directory +@var{directory}. It returns the longest prefix common to all file names +in directory @var{directory} that start with @var{filename}. If +@var{predicate} is non-@code{nil} then it ignores possible completions +that don't satisfy @var{predicate}, after calling that function +with one argument, the expanded absolute file name. + +If only one match exists and @var{filename} matches it exactly, the +function returns @code{t}. The function returns @code{nil} if directory +@var{directory} contains no name starting with @var{filename}. + +In the following example, suppose that the current default directory +has five files whose names begin with @samp{f}: @file{foo}, +@file{file~}, @file{file.c}, @file{file.c.~1~}, and +@file{file.c.~2~}.@refill + +@example +@group +(file-name-completion "fi" "") + @result{} "file" +@end group + +@group +(file-name-completion "file.c.~1" "") + @result{} "file.c.~1~" +@end group + +@group +(file-name-completion "file.c.~1~" "") + @result{} t +@end group + +@group +(file-name-completion "file.c.~3" "") + @result{} nil +@end group +@end example +@end defun + +@defopt completion-ignored-extensions +@code{file-name-completion} usually ignores file names that end in any +string in this list. It does not ignore them when all the possible +completions end in one of these suffixes. This variable has no effect +on @code{file-name-all-completions}.@refill + +A typical value might look like this: + +@example +@group +completion-ignored-extensions + @result{} (".o" ".elc" "~" ".dvi") +@end group +@end example + +If an element of @code{completion-ignored-extensions} ends in a slash +@samp{/}, it signals a directory. The elements which do @emph{not} end +in a slash will never match a directory; thus, the above value will not +filter out a directory named @file{foo.elc}. +@end defopt + +@node Standard File Names +@subsection Standard File Names + + Most of the file names used in Lisp programs are entered by the user. +But occasionally a Lisp program needs to specify a standard file name +for a particular use---typically, to hold customization information +about each user. For example, abbrev definitions are stored (by +default) in the file @file{~/.abbrev_defs}; the @code{completion} +package stores completions in the file @file{~/.completions}. These are +two of the many standard file names used by parts of Emacs for certain +purposes. + + Various operating systems have their own conventions for valid file +names and for which file names to use for user profile data. A Lisp +program which reads a file using a standard file name ought to use, on +each type of system, a file name suitable for that system. The function +@code{convert-standard-filename} makes this easy to do. + +@defun convert-standard-filename filename +This function alters the file name @var{filename} to fit the conventions +of the operating system in use, and returns the result as a new string. +@end defun + + The recommended way to specify a standard file name in a Lisp program +is to choose a name which fits the conventions of GNU and Unix systems, +usually with a nondirectory part that starts with a period, and pass it +to @code{convert-standard-filename} instead of using it directly. Here +is an example from the @code{completion} package: + +@example +(defvar save-completions-file-name + (convert-standard-filename "~/.completions") + "*The file name to save completions to.") +@end example + + On GNU and Unix systems, and on some other systems as well, +@code{convert-standard-filename} returns its argument unchanged. On +some other systems, it alters the name to fit the system's conventions. + + For example, on MS-DOS the alterations made by this function include +converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the +middle of the name to @samp{.} if there is no other @samp{.}, inserting +a @samp{.} after eight characters if there is none, and truncating to +three characters after the @samp{.}. (It makes other changes as well.) +Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and +@file{.completions} becomes @file{_complet.ion}. + +@node Contents of Directories +@section Contents of Directories +@cindex directory-oriented functions +@cindex file names in directory + + A directory is a kind of file that contains other files entered under +various names. Directories are a feature of the file system. + + Emacs can list the names of the files in a directory as a Lisp list, +or display the names in a buffer using the @code{ls} shell command. In +the latter case, it can optionally display information about each file, +depending on the options passed to the @code{ls} command. + +@defun directory-files directory &optional full-name match-regexp nosort +This function returns a list of the names of the files in the directory +@var{directory}. By default, the list is in alphabetical order. + +If @var{full-name} is non-@code{nil}, the function returns the files' +absolute file names. Otherwise, it returns the names relative to +the specified directory. + +If @var{match-regexp} is non-@code{nil}, this function returns only +those file names that contain a match for that regular expression---the +other file names are excluded from the list. On case-insensitive +filesystems, the regular expression matching is case-insensitive. + +@c Emacs 19 feature +If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort +the list, so you get the file names in no particular order. Use this if +you want the utmost possible speed and don't care what order the files +are processed in. If the order of processing is visible to the user, +then the user will probably be happier if you do sort the names. + +@example +@group +(directory-files "~lewis") + @result{} ("#foo#" "#foo.el#" "." ".." + "dired-mods.el" "files.texi" + "files.texi.~1~") +@end group +@end example + +An error is signaled if @var{directory} is not the name of a directory +that can be read. +@end defun + +@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format +This is similar to @code{directory-files} in deciding which files +to report on and how to report their names. However, instead +of returning a list of file names, it returns for each file a +list @code{(@var{filename} . @var{attributes})}, where @var{attributes} +is what @code{file-attributes} would return for that file. +The optional argument @var{id-format} has the same meaning as the +corresponding argument to @code{file-attributes} (@pxref{Definition +of file-attributes}). +@end defun + +@defun file-name-all-versions file dirname +This function returns a list of all versions of the file named +@var{file} in directory @var{dirname}. It is only available on VMS. +@end defun + +@defun file-expand-wildcards pattern &optional full +This function expands the wildcard pattern @var{pattern}, returning +a list of file names that match it. + +If @var{pattern} is written as an absolute file name, +the values are absolute also. + +If @var{pattern} is written as a relative file name, it is interpreted +relative to the current default directory. The file names returned are +normally also relative to the current default directory. However, if +@var{full} is non-@code{nil}, they are absolute. +@end defun + +@defun insert-directory file switches &optional wildcard full-directory-p +This function inserts (in the current buffer) a directory listing for +directory @var{file}, formatted with @code{ls} according to +@var{switches}. It leaves point after the inserted text. +@var{switches} may be a string of options, or a list of strings +representing individual options. + +The argument @var{file} may be either a directory name or a file +specification including wildcard characters. If @var{wildcard} is +non-@code{nil}, that means treat @var{file} as a file specification with +wildcards. + +If @var{full-directory-p} is non-@code{nil}, that means the directory +listing is expected to show the full contents of a directory. You +should specify @code{t} when @var{file} is a directory and switches do +not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to +describe a directory itself as a file, rather than showing its +contents.) + +On most systems, this function works by running a directory listing +program whose name is in the variable @code{insert-directory-program}. +If @var{wildcard} is non-@code{nil}, it also runs the shell specified by +@code{shell-file-name}, to expand the wildcards. + +MS-DOS and MS-Windows systems usually lack the standard Unix program +@code{ls}, so this function emulates the standard Unix program @code{ls} +with Lisp code. + +As a technical detail, when @var{switches} contains the long +@samp{--dired} option, @code{insert-directory} treats it specially, +for the sake of dired. However, the normally equivalent short +@samp{-D} option is just passed on to @code{insert-directory-program}, +as any other option. +@end defun + +@defvar insert-directory-program +This variable's value is the program to run to generate a directory listing +for the function @code{insert-directory}. It is ignored on systems +which generate the listing with Lisp code. +@end defvar + +@node Create/Delete Dirs +@section Creating and Deleting Directories +@cindex creating and deleting directories +@c Emacs 19 features + + Most Emacs Lisp file-manipulation functions get errors when used on +files that are directories. For example, you cannot delete a directory +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 +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{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. + +This function only follows symbolic links at the level of parent +directories. +@end defun + +@node Magic File Names +@section Making Certain File Names ``Magic'' +@cindex magic file names + +@c Emacs 19 feature + You can implement special handling for certain file names. This is +called making those names @dfn{magic}. The principal use for this +feature is in implementing remote file names (@pxref{Remote Files,, +Remote Files, emacs, The GNU Emacs Manual}). + + To define a kind of magic file name, you must supply a regular +expression to define the class of names (all those that match the +regular expression), plus a handler that implements all the primitive +Emacs file operations for file names that do match. + + 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: + +@example +(@var{regexp} . @var{handler}) +@end example + +@noindent +All the Emacs primitives for file access and file name transformation +check the given file name against @code{file-name-handler-alist}. If +the file name matches @var{regexp}, the primitives handle that file by +calling @var{handler}. + + The first argument given to @var{handler} is the name of the +primitive, as a symbol; the remaining arguments are the arguments that +were passed to that primitive. (The first of these arguments is most +often the file name itself.) For example, if you do this: + +@example +(file-exists-p @var{filename}) +@end example + +@noindent +and @var{filename} has handler @var{handler}, then @var{handler} is +called like this: + +@example +(funcall @var{handler} 'file-exists-p @var{filename}) +@end example + + When a function takes two or more arguments that must be file names, +it checks each of those names for a handler. For example, if you do +this: + +@example +(expand-file-name @var{filename} @var{dirname}) +@end example + +@noindent +then it checks for a handler for @var{filename} and then for a handler +for @var{dirname}. In either case, the @var{handler} is called like +this: + +@example +(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) +@end example + +@noindent +The @var{handler} then needs to figure out whether to handle +@var{filename} or @var{dirname}. + + If the specified file name matches more than one handler, the one +whose match starts last in the file name gets precedence. This rule +is chosen so that handlers for jobs such as uncompression are handled +first, before handlers for jobs such as remote file access. + + Here are the operations that a magic file name handler gets to handle: + +@ifnottex +@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{diff-latest-backup-file}, +@code{directory-file-name}, +@code{directory-files}, +@code{directory-files-and-attributes}, +@code{dired-compress-file}, @code{dired-uncache},@* +@code{expand-file-name}, +@code{file-accessible-directory-p}, +@code{file-attributes}, +@code{file-directory-p}, +@code{file-executable-p}, @code{file-exists-p}, +@code{file-local-copy}, @code{file-remote-p}, +@code{file-modes}, @code{file-name-all-completions}, +@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-ownership-preserved-p}, +@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, +@code{file-truename}, @code{file-writable-p}, +@code{find-backup-file-name}, +@code{find-file-noselect},@* +@code{get-file-buffer}, +@code{insert-directory}, +@code{insert-file-contents},@* +@code{load}, +@code{make-auto-save-file-name}, +@code{make-directory}, +@code{make-directory-internal}, +@code{make-symbolic-link},@* +@code{process-file}, +@code{rename-file}, @code{set-file-modes}, @code{set-file-times}, +@code{set-visited-file-modtime}, @code{shell-command}, +@code{start-file-process}, +@code{substitute-in-file-name},@* +@code{unhandled-file-name-directory}, +@code{vc-registered}, +@code{verify-visited-file-modtime},@* +@code{write-region}. +@end ifnottex +@iftex +@noindent +@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{diff-latest-backup-file}, +@code{directory-file-name}, +@code{directory-files}, +@code{directory-files-and-at@discretionary{}{}{}tributes}, +@code{dired-compress-file}, @code{dired-uncache}, +@code{expand-file-name}, +@code{file-accessible-direc@discretionary{}{}{}tory-p}, +@code{file-attributes}, +@code{file-direct@discretionary{}{}{}ory-p}, +@code{file-executable-p}, @code{file-exists-p}, +@code{file-local-copy}, @code{file-remote-p}, +@code{file-modes}, @code{file-name-all-completions}, +@code{file-name-as-directory}, +@code{file-name-completion}, +@code{file-name-directory}, +@code{file-name-nondirec@discretionary{}{}{}tory}, +@code{file-name-sans-versions}, @code{file-newer-than-file-p}, +@code{file-ownership-pre@discretionary{}{}{}served-p}, +@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, +@code{file-truename}, @code{file-writable-p}, +@code{find-backup-file-name}, +@code{find-file-noselect}, +@code{get-file-buffer}, +@code{insert-directory}, +@code{insert-file-contents}, +@code{load}, @code{make-direc@discretionary{}{}{}tory}, +@code{make-direc@discretionary{}{}{}tory-internal}, +@code{make-symbolic-link}, +@code{process-file}, +@code{rename-file}, @code{set-file-modes}, +@code{set-visited-file-modtime}, @code{shell-command}, +@code{start-file-process}, +@code{substitute-in-file-name}, +@code{unhandled-file-name-directory}, +@code{vc-regis@discretionary{}{}{}tered}, +@code{verify-visited-file-modtime}, +@code{write-region}. +@end flushleft +@end iftex + + Handlers for @code{insert-file-contents} typically need to clear the +buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the +@var{visit} argument is non-@code{nil}. This also has the effect of +unlocking the buffer if it is locked. + + The handler function must handle all of the above operations, and +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 +for an operation it does not recognize. Here's one way to do this: + +@smallexample +(defun my-file-handler (operation &rest args) + ;; @r{First check for the specific operations} + ;; @r{that we have special handling for.} + (cond ((eq operation 'insert-file-contents) @dots{}) + ((eq operation 'write-region) @dots{}) + @dots{} + ;; @r{Handle any operation we don't know about.} + (t (let ((inhibit-file-name-handlers + (cons 'my-file-handler + (and (eq inhibit-file-name-operation operation) + inhibit-file-name-handlers))) + (inhibit-file-name-operation operation)) + (apply operation args))))) +@end smallexample + + When a handler function decides to call the ordinary Emacs primitive for +the operation at hand, it needs to prevent the primitive from calling +the same handler once again, thus leading to an infinite recursion. The +example above shows how to do this, with the variables +@code{inhibit-file-name-handlers} and +@code{inhibit-file-name-operation}. Be careful to use them exactly as +shown above; the details are crucial for proper behavior in the case of +multiple handlers, and for operations that have two file names that may +each have handlers. + +@kindex safe-magic (@r{property}) + Handlers that don't really do anything special for actual access to the +file---such as the ones that implement completion of host names for +remote file names---should have a non-@code{nil} @code{safe-magic} +property. For instance, Emacs normally ``protects'' directory names +it finds in @code{PATH} from becoming magic, if they look like magic +file names, by prefixing them with @samp{/:}. But if the handler that +would be used for them has a non-@code{nil} @code{safe-magic} +property, the @samp{/:} is not added. + +@kindex operations (@r{property}) + A file name handler can have an @code{operations} property to +declare which operations it handles in a nontrivial way. If this +property has a non-@code{nil} value, it should be a list of +operations; then only those operations will call the handler. This +avoids inefficiency, but its main purpose is for autoloaded handler +functions, so that they won't be loaded except when they have real +work to do. + + Simply deferring all operations to the usual primitives does not +work. For instance, if the file name handler applies to +@code{file-exists-p}, then it must handle @code{load} itself, because +the usual @code{load} code won't work properly in that case. However, +if the handler uses the @code{operations} property to say it doesn't +handle @code{file-exists-p}, then it need not handle @code{load} +nontrivially. + +@defvar inhibit-file-name-handlers +This variable holds a list of handlers whose use is presently inhibited +for a certain operation. +@end defvar + +@defvar inhibit-file-name-operation +The operation for which certain handlers are presently inhibited. +@end defvar + +@defun find-file-name-handler file operation +This function returns the handler function for file name @var{file}, +or @code{nil} if there is none. The argument @var{operation} should +be the operation to be performed on the file---the value you will pass +to the handler as its first argument when you call it. If +@var{operation} equals @code{inhibit-file-name-operation}, or if it is +not found in the @code{operations} property of the handler, this +function returns @code{nil}. +@end defun + +@defun file-local-copy filename +This function copies file @var{filename} to an ordinary non-magic file +on the local machine, if it isn't on the local machine already. Magic +file names should handle the @code{file-local-copy} operation if they +refer to files on other machines. A magic file name that is used for +other purposes than remote file access should not handle +@code{file-local-copy}; then this function will treat the file as +local. + +If @var{filename} is local, whether magic or not, this function does +nothing and returns @code{nil}. Otherwise it returns the file name +of the local copy file. +@end defun + +@defun file-remote-p filename &optional identification connected +This function tests whether @var{filename} is a remote file. If +@var{filename} is local (not remote), the return value is @code{nil}. +If @var{filename} is indeed remote, the return value is a string that +identifies the remote system. + +This identifier string can include a host name and a user name, as +well as characters designating the method used to access the remote +system. For example, the remote identifier string for the filename +@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. + +If @code{file-remote-p} returns the same identifier for two different +filenames, that means they are stored on the same file system and can +be accessed locally with respect to each other. This means, for +example, that it is possible to start a remote process accessing both +files at the same time. Implementors of file handlers need to ensure +this principle is valid. + +@var{identification} specifies which part of the identifier shall be +returned as string. @var{identification} can be the symbol +@code{method}, @code{user} or @code{host}; any other value is handled +like @code{nil} and means to return the complete identifier string. +In the example above, the remote @code{user} identifier string would +be @code{root}. + +If @var{connected} is non-@code{nil}, this function returns @code{nil} +even if @var{filename} is remote, if Emacs has no network connection +to its host. This is useful when you want to avoid the delay of +making connections when they don't exist. +@end defun + +@defun unhandled-file-name-directory filename +This function returns the name of a directory that is not magic. It +uses the directory part of @var{filename} if that is not magic. For a +magic file name, it invokes the file name handler, which therefore +decides what value to return. + +This is useful for running a subprocess; every subprocess must have a +non-magic directory to serve as its current directory, and this function +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 +@cindex text properties in files +@cindex saving text properties + Emacs performs several steps to convert the data in a buffer (text, +text properties, and possibly other information) to and from a +representation suitable for storing into a file. This section describes +the fundamental functions that perform this @dfn{format conversion}, +namely @code{insert-file-contents} for reading a file into a buffer, +and @code{write-region} for writing a buffer into a file. + +@menu +* 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 + +@node Format Conversion Overview +@subsection Overview +@noindent +The function @code{insert-file-contents}: + +@itemize +@item initially, inserts bytes from the file into the buffer; +@item decodes bytes to characters as appropriate; +@item processes formats as defined by entries in @code{format-alist}; and +@item calls functions in @code{after-insert-file-functions}. +@end itemize + +@noindent +The function @code{write-region}: + +@itemize +@item initially, calls functions in @code{write-region-annotate-functions}; +@item processes formats as defined by entries in @code{format-alist}; +@item encodes characters to bytes as appropriate; and +@item modifies the file with the bytes. +@end itemize + + This shows the symmetry of the lowest-level operations; reading and +writing handle things in opposite order. The rest of this section +describes the two facilities surrounding the three variables named +above, as well as some related functions. @ref{Coding Systems}, for +details on character encoding and decoding. + +@node Format Conversion Round-Trip +@subsection Round-Trip Specification + + The most general of the two facilities is controlled by the variable +@code{format-alist}, a list of @dfn{file format} specifications, which +describe textual representations used in files for the data in an Emacs +buffer. The descriptions for reading and writing are paired, which is +why we call this ``round-trip'' specification +(@pxref{Format Conversion Piecemeal}, for non-paired specification). + +@defvar format-alist +This list contains one format definition for each defined file format. +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 +@end defvar + +@cindex format definition +@noindent +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 shell command or function to decode data in this format (to convert +file data into the usual Emacs data representation). + +A shell command is represented as a string; Emacs runs the command as a +filter to perform the conversion. + +If @var{from-fn} is a function, it is called with two arguments, @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 shell command or function to encode data in this format---that is, to +convert the usual Emacs data representation into this format. + +If @var{to-fn} is a string, it is a shell command; Emacs runs the +command as a filter to perform the conversion. + +If @var{to-fn} is a function, it is called with three arguments: +@var{begin} and @var{end}, which specify the part of the buffer it +should convert, and @var{buffer}, which specifies which buffer. 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-fn +A minor-mode function to call after visiting a file converted from this +format. The function is called with one argument, the integer 1; +that tells a minor-mode function to enable the mode. +@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 buffer-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. + +@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. 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}. +@end deffn + +@deffn Command 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 deffn + +@deffn Command 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 deffn + +@defvar buffer-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}; however, it is used instead of +@code{buffer-file-format} for writing auto-save files. If the value +is @code{t}, the default, auto-saving uses the same format as a +regular save in the same buffer. This variable is always buffer-local +in all buffers. +@end defvar + +@node Format Conversion Piecemeal +@subsection Piecemeal Specification + + In contrast to the round-trip specification described in the previous +subsection (@pxref{Format Conversion Round-Trip}), you can use the variables +@code{after-insert-file-functions} and @code{write-region-annotate-functions} +to separately control the respective reading and writing conversions. + + Conversion starts with one representation and produces another +representation. When there is only one conversion to do, there is no +conflict about what to start with. However, when there are multiple +conversions involved, conflict may arise when two conversions need to +start with the same data. + + This situation is best understood in the context of converting text +properties during @code{write-region}. For example, the character at +position 42 in a buffer is @samp{X} with a text property @code{foo}. If +the conversion for @code{foo} is done by inserting into the buffer, say, +@samp{FOO:}, then that changes the character at position 42 from +@samp{X} to @samp{F}. The next conversion will start with the wrong +data straight away. + + To avoid conflict, cooperative conversions do not modify the buffer, +but instead specify @dfn{annotations}, a list of elements of the form +@code{(@var{position} . @var{string})}, sorted in order of increasing +@var{position}. + + If there is more than one conversion, @code{write-region} merges their +annotations destructively into one sorted list. Later, when the text +from the buffer is actually written to the file, it intermixes the +specified annotations at the corresponding positions. All this takes +place without modifying the buffer. + +@c ??? What about ``overriding'' conversions like those allowed +@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 +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. + +@defvar write-region-annotate-functions +A list of functions for @code{write-region} to call. Each function in +the list is called with two arguments: the start and end of the region +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. +@end defvar + +@defvar after-insert-file-functions +Each function in this list is called by @code{insert-file-contents} +with one argument, the number of characters inserted, and with point +at the beginning of the inserted text. Each function should leave +point unchanged, and return the new character count describing the +inserted text as modified by the function. +@c ??? The docstring mentions a handler from `file-name-handler-alist' +@c "intercepting" `insert-file-contents'. Hmmm. --ttn +@end defvar + + We invite users to write Lisp programs to store and retrieve text +properties in files, using these hooks, and thus to experiment with +various data formats and find good ones. Eventually we hope users +will produce good, general extensions we can install in Emacs. + + We suggest not trying to handle arbitrary Lisp objects as text property +names or values---because a program that general is probably difficult +to write, and slow. Instead, choose a set of possible data types that +are reasonably flexible, and not too hard to encode. + +@ignore + arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c +@end ignore