Regenerate.
[emacs.git] / lispref / files.texi
blob2719eae66134ceb939fdf1eb27a2252eb718e80a
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c   2002, 2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/files
7 @node Files, Backups and Auto-Saving, Documentation, Top
8 @comment  node-name,  next,  previous,  up
9 @chapter Files
11   In Emacs, you can find, create, view, save, and otherwise work with
12 files and file directories.  This chapter describes most of the
13 file-related functions of Emacs Lisp, but a few others are described in
14 @ref{Buffers}, and those related to backups and auto-saving are
15 described in @ref{Backups and Auto-Saving}.
17   Many of the file functions take one or more arguments that are file
18 names.  A file name is actually a string.  Most of these functions
19 expand file name arguments by calling @code{expand-file-name}, so that
20 @file{~} is handled correctly, as are relative file names (including
21 @samp{../}).  These functions don't recognize environment variable
22 substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
24   When file I/O functions signal Lisp errors, they usually use the
25 condition @code{file-error} (@pxref{Handling Errors}).  The error
26 message is in most cases obtained from the operating system, according
27 to locale @code{system-message-locale}, and decoded using coding system
28 @code{locale-coding-system} (@pxref{Locales}).
30 @menu
31 * Visiting Files::           Reading files into Emacs buffers for editing.
32 * Saving Buffers::           Writing changed buffers back into files.
33 * Reading from Files::       Reading files into buffers without visiting.
34 * Writing to Files::         Writing new files from parts of buffers.
35 * File Locks::               Locking and unlocking files, to prevent
36                                simultaneous editing by two people.
37 * Information about Files::  Testing existence, accessibility, size of files.
38 * Changing Files::           Renaming files, changing protection, etc.
39 * File Names::               Decomposing and expanding file names.
40 * Contents of Directories::  Getting a list of the files in a directory.
41 * Create/Delete Dirs::       Creating and Deleting Directories.
42 * Magic File Names::         Defining "magic" special handling
43                                for certain file names.
44 * Format Conversion::        Conversion to and from various file formats.
45 @end menu
47 @node Visiting Files
48 @section Visiting Files
49 @cindex finding files
50 @cindex visiting files
52   Visiting a file means reading a file into a buffer.  Once this is
53 done, we say that the buffer is @dfn{visiting} that file, and call the
54 file ``the visited file'' of the buffer.
56   A file and a buffer are two different things.  A file is information
57 recorded permanently in the computer (unless you delete it).  A buffer,
58 on the other hand, is information inside of Emacs that will vanish at
59 the end of the editing session (or when you kill the buffer).  Usually,
60 a buffer contains information that you have copied from a file; then we
61 say the buffer is visiting that file.  The copy in the buffer is what
62 you modify with editing commands.  Such changes to the buffer do not
63 change the file; therefore, to make the changes permanent, you must
64 @dfn{save} the buffer, which means copying the altered buffer contents
65 back into the file.
67   In spite of the distinction between files and buffers, people often
68 refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
70 will soon save as a file of the same name.''  Humans do not usually need
71 to make the distinction explicit.  When dealing with a computer program,
72 however, it is good to keep the distinction in mind.
74 @menu
75 * Visiting Functions::         The usual interface functions for visiting.
76 * Subroutines of Visiting::    Lower-level subroutines that they use.
77 @end menu
79 @node Visiting Functions
80 @subsection Functions for Visiting Files
82   This section describes the functions normally used to visit files.
83 For historical reasons, these functions have names starting with
84 @samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
85 functions and variables that access the visited file name of a buffer or
86 that find an existing buffer by its visited file name.
88   In a Lisp program, if you want to look at the contents of a file but
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
90 temporary buffer.  Visiting the file is not necessary and takes longer.
91 @xref{Reading from Files}.
93 @deffn Command find-file filename &optional wildcards
94 This command selects a buffer visiting the file @var{filename},
95 using an existing buffer if there is one, and otherwise creating a
96 new buffer and reading the file into it.  It also returns that buffer.
98 Aside from some technical details, the body of the @code{find-file}
99 function is basically equivalent to:
101 @smallexample
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
103 @end smallexample
105 @noindent
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
108 If @var{wildcards} is non-@code{nil}, which is always true in an
109 interactive call, then @code{find-file} expands wildcard characters in
110 @var{filename} and visits all the matching files.
112 When @code{find-file} is called interactively, it prompts for
113 @var{filename} in the minibuffer.
114 @end deffn
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
117 This function is the guts of all the file-visiting functions.  It
118 returns a buffer visiting the file @var{filename}.  You may make the
119 buffer current or display it in a window if you wish, but this
120 function does not do so.
122 The function returns an existing buffer if there is one; otherwise it
123 creates a new buffer and reads the file into it.  When
124 @code{find-file-noselect} uses an existing buffer, it first verifies
125 that the file has not changed since it was last visited or saved in
126 that buffer.  If the file has changed, this function asks the user
127 whether to reread the changed file.  If the user says @samp{yes}, any
128 edits previously made in the buffer are lost.
130 Reading the file involves decoding the file's contents (@pxref{Coding
131 Systems}), including end-of-line conversion, and format conversion
132 (@pxref{Format Conversion}).  If @var{wildcards} is non-@code{nil},
133 then @code{find-file-noselect} expands wildcard characters in
134 @var{filename} and visits all the matching files.
136 This function displays warning or advisory messages in various peculiar
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
138 example, if it needs to create a buffer, and there is no file named
139 @var{filename}, it displays the message @samp{(New file)} in the echo
140 area, and leaves the buffer empty.
142 The @code{find-file-noselect} function normally calls
143 @code{after-find-file} after reading the file (@pxref{Subroutines of
144 Visiting}).  That function sets the buffer major mode, parses local
145 variables, warns the user if there exists an auto-save file more recent
146 than the file just visited, and finishes by running the functions in
147 @code{find-file-hook}.
149 If the optional argument @var{rawfile} is non-@code{nil}, then
150 @code{after-find-file} is not called, and the
151 @code{find-file-not-found-functions} are not run in case of failure.
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
153 system conversion and format conversion.
155 The @code{find-file-noselect} function usually returns the buffer that
156 is visiting the file @var{filename}.  But, if wildcards are actually
157 used and expanded, it returns a list of buffers that are visiting the
158 various files.
160 @example
161 @group
162 (find-file-noselect "/etc/fstab")
163      @result{} #<buffer fstab>
164 @end group
165 @end example
166 @end defun
168 @deffn Command find-file-other-window filename &optional wildcards
169 This command selects a buffer visiting the file @var{filename}, but
170 does so in a window other than the selected window.  It may use another
171 existing window or split a window; see @ref{Displaying Buffers}.
173 When this command is called interactively, it prompts for
174 @var{filename}.
175 @end deffn
177 @deffn Command find-file-read-only filename &optional wildcards
178 This command selects a buffer visiting the file @var{filename}, like
179 @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
180 Buffers}, for related functions and variables.
182 When this command is called interactively, it prompts for
183 @var{filename}.
184 @end deffn
186 @deffn Command view-file filename
187 This command visits @var{filename} using View mode, returning to the
188 previous buffer when you exit View mode.  View mode is a minor mode that
189 provides commands to skim rapidly through the file, but does not let you
190 modify the text.  Entering View mode runs the normal hook
191 @code{view-mode-hook}.  @xref{Hooks}.
193 When @code{view-file} is called interactively, it prompts for
194 @var{filename}.
195 @end deffn
197 @defopt find-file-wildcards
198 If this variable is non-@code{nil}, then the various @code{find-file}
199 commands check for wildcard characters and visit all the files that
200 match them (when invoked interactively or when their @var{wildcards}
201 argument is non-@code{nil}).  If this option is @code{nil}, then
202 the @code{find-file} commands ignore their @var{wildcards} argument
203 and never treat wildcard characters specially.
204 @end defopt
206 @defvar find-file-hook
207 The value of this variable is a list of functions to be called after a
208 file is visited.  The file's local-variables specification (if any) will
209 have been processed before the hooks are run.  The buffer visiting the
210 file is current when the hook functions are run.
212 This variable is a normal hook.  @xref{Hooks}.
213 @end defvar
215 @defvar find-file-not-found-functions
216 The value of this variable is a list of functions to be called when
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
218 file name.  @code{find-file-noselect} calls these functions as soon as
219 it detects a nonexistent file.  It calls them in the order of the list,
220 until one of them returns non-@code{nil}.  @code{buffer-file-name} is
221 already set up.
223 This is not a normal hook because the values of the functions are
224 used, and in many cases only some of the functions are called.
225 @end defvar
227 @node Subroutines of Visiting
228 @comment  node-name,  next,  previous,  up
229 @subsection Subroutines of Visiting
231   The @code{find-file-noselect} function uses two important subroutines
232 which are sometimes useful in user Lisp code: @code{create-file-buffer}
233 and @code{after-find-file}.  This section explains how to use them.
235 @defun create-file-buffer filename
236 This function creates a suitably named buffer for visiting
237 @var{filename}, and returns it.  It uses @var{filename} (sans directory)
238 as the name if that name is free; otherwise, it appends a string such as
239 @samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
241 @strong{Please note:} @code{create-file-buffer} does @emph{not}
242 associate the new buffer with a file and does not select the buffer.
243 It also does not use the default major mode.
245 @example
246 @group
247 (create-file-buffer "foo")
248      @result{} #<buffer foo>
249 @end group
250 @group
251 (create-file-buffer "foo")
252      @result{} #<buffer foo<2>>
253 @end group
254 @group
255 (create-file-buffer "foo")
256      @result{} #<buffer foo<3>>
257 @end group
258 @end example
260 This function is used by @code{find-file-noselect}.
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
262 @end defun
264 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
265 This function sets the buffer major mode, and parses local variables
266 (@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
267 and by the default revert function (@pxref{Reverting}).
269 @cindex new file message
270 @cindex file open error
271 If reading the file got an error because the file does not exist, but
272 its directory does exist, the caller should pass a non-@code{nil} value
273 for @var{error}.  In that case, @code{after-find-file} issues a warning:
274 @samp{(New file)}.  For more serious errors, the caller should usually not
275 call @code{after-find-file}.
277 If @var{warn} is non-@code{nil}, then this function issues a warning
278 if an auto-save file exists and is more recent than the visited file.
280 If @var{noauto} is non-@code{nil}, that says not to enable or disable
281 Auto-Save mode.  The mode remains enabled if it was enabled before.
283 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
284 means this call was from @code{revert-buffer}.  This has no direct
285 effect, but some mode functions and hook functions check the value
286 of this variable.
288 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
289 major mode, don't process local variables specifications in the file,
290 and don't run @code{find-file-hook}.  This feature is used by
291 @code{revert-buffer} in some cases.
293 The last thing @code{after-find-file} does is call all the functions
294 in the list @code{find-file-hook}.
295 @end defun
297 @node Saving Buffers
298 @section Saving Buffers
299 @cindex saving buffers
301   When you edit a file in Emacs, you are actually working on a buffer
302 that is visiting that file---that is, the contents of the file are
303 copied into the buffer and the copy is what you edit.  Changes to the
304 buffer do not change the file until you @dfn{save} the buffer, which
305 means copying the contents of the buffer into the file.
307 @deffn Command save-buffer &optional backup-option
308 This function saves the contents of the current buffer in its visited
309 file if the buffer has been modified since it was last visited or saved.
310 Otherwise it does nothing.
312 @code{save-buffer} is responsible for making backup files.  Normally,
313 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
314 file only if this is the first save since visiting the file.  Other
315 values for @var{backup-option} request the making of backup files in
316 other circumstances:
318 @itemize @bullet
319 @item
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
321 @code{save-buffer} function marks this version of the file to be
322 backed up when the buffer is next saved.
324 @item
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
326 @code{save-buffer} function unconditionally backs up the previous
327 version of the file before saving it.
329 @item
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
331 @end itemize
332 @end deffn
334 @deffn Command save-some-buffers &optional save-silently-p pred
335 @anchor{Definition of save-some-buffers}
336 This command saves some modified file-visiting buffers.  Normally it
337 asks the user about each buffer.  But if @var{save-silently-p} is
338 non-@code{nil}, it saves all the file-visiting buffers without querying
339 the user.
341 The optional @var{pred} argument controls which buffers to ask about
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
343 If it is @code{nil}, that means to ask only about file-visiting buffers.
344 If it is @code{t}, that means also offer to save certain other non-file
345 buffers---those that have a non-@code{nil} buffer-local value of
346 @code{buffer-offer-save} (@pxref{Killing Buffers}).  A user who says
347 @samp{yes} to saving a non-file buffer is asked to specify the file
348 name to use.  The @code{save-buffers-kill-emacs} function passes the
349 value @code{t} for @var{pred}.
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
352 a function of no arguments.  It will be called in each buffer to decide
353 whether to offer to save that buffer.  If it returns a non-@code{nil}
354 value in a certain buffer, that means do offer to save that buffer.
355 @end deffn
357 @deffn Command write-file filename &optional confirm
358 @anchor{Definition of write-file}
359 This function writes the current buffer into file @var{filename}, makes
360 the buffer visit that file, and marks it not modified.  Then it renames
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
362 if necessary to make a unique buffer name.  It does most of this work by
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
364 @code{save-buffer}.
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
367 before overwriting an existing file.  Interactively, confirmation is
368 required, unless the user supplies a prefix argument.
370 If @var{filename} is an existing directory, or a symbolic link to one,
371 @code{write-file} uses the name of the visited file, in directory
372 @var{filename}.  If the buffer is not visiting a file, it uses the
373 buffer name instead.
374 @end deffn
376   Saving a buffer runs several hooks.  It also performs format
377 conversion (@pxref{Format Conversion}), and may save text properties in
378 ``annotations'' (@pxref{Saving Properties}).
380 @defvar write-file-functions
381 The value of this variable is a list of functions to be called before
382 writing out a buffer to its visited file.  If one of them returns
383 non-@code{nil}, the file is considered already written and the rest of
384 the functions are not called, nor is the usual code for writing the file
385 executed.
387 If a function in @code{write-file-functions} returns non-@code{nil}, it
388 is responsible for making a backup file (if that is appropriate).
389 To do so, execute the following code:
391 @example
392 (or buffer-backed-up (backup-buffer))
393 @end example
395 You might wish to save the file modes value returned by
396 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
397 bits of the file that you write.  This is what @code{save-buffer}
398 normally does. @xref{Making Backups,, Making Backup Files}.
400 The hook functions in @code{write-file-functions} are also responsible
401 for encoding the data (if desired): they must choose a suitable coding
402 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
403 perform the encoding (@pxref{Explicit Encoding}), and set
404 @code{last-coding-system-used} to the coding system that was used
405 (@pxref{Encoding and I/O}).
407 If you set this hook locally in a buffer, it is assumed to be
408 associated with the file or the way the contents of the buffer were
409 obtained.  Thus the variable is marked as a permanent local, so that
410 changing the major mode does not alter a buffer-local value.  On the
411 other hand, calling @code{set-visited-file-name} will reset it.
412 If this is not what you want, you might like to use
413 @code{write-contents-functions} instead.
415 Even though this is not a normal hook, you can use @code{add-hook} and
416 @code{remove-hook} to manipulate the list.  @xref{Hooks}.
417 @end defvar
419 @c Emacs 19 feature
420 @defvar write-contents-functions
421 This works just like @code{write-file-functions}, but it is intended
422 for hooks that pertain to the buffer's contents, not to the particular
423 visited file or its location.  Such hooks are usually set up by major
424 modes, as buffer-local bindings for this variable.  This variable
425 automatically becomes buffer-local whenever it is set; switching to a
426 new major mode always resets this variable, but calling
427 @code{set-visited-file-name} does not.
429 If any of the functions in this hook returns non-@code{nil}, the file
430 is considered already written and the rest are not called and neither
431 are the functions in @code{write-file-functions}.
432 @end defvar
434 @defopt before-save-hook
435 This normal hook runs before a buffer is saved in its visited file,
436 regardless of whether that is done normally or by one of the hooks
437 described above.  For instance, the @file{copyright.el} program uses
438 this hook to make sure the file you are saving has the current year in
439 its copyright notice.
440 @end defopt
442 @c Emacs 19 feature
443 @defopt after-save-hook
444 This normal hook runs after a buffer has been saved in its visited file.
445 One use of this hook is in Fast Lock mode; it uses this hook to save the
446 highlighting information in a cache file.
447 @end defopt
449 @defopt file-precious-flag
450 If this variable is non-@code{nil}, then @code{save-buffer} protects
451 against I/O errors while saving by writing the new file to a temporary
452 name instead of the name it is supposed to have, and then renaming it to
453 the intended name after it is clear there are no errors.  This procedure
454 prevents problems such as a lack of disk space from resulting in an
455 invalid file.
457 As a side effect, backups are necessarily made by copying.  @xref{Rename
458 or Copy}.  Yet, at the same time, saving a precious file always breaks
459 all hard links between the file you save and other file names.
461 Some modes give this variable a non-@code{nil} buffer-local value
462 in particular buffers.
463 @end defopt
465 @defopt require-final-newline
466 This variable determines whether files may be written out that do
467 @emph{not} end with a newline.  If the value of the variable is
468 @code{t}, then @code{save-buffer} silently adds a newline at the end of
469 the file whenever the buffer being saved does not already end in one.
470 If the value of the variable is non-@code{nil}, but not @code{t}, then
471 @code{save-buffer} asks the user whether to add a newline each time the
472 case arises.
474 If the value of the variable is @code{nil}, then @code{save-buffer}
475 doesn't add newlines at all.  @code{nil} is the default value, but a few
476 major modes set it to @code{t} in particular buffers.
477 @end defopt
479   See also the function @code{set-visited-file-name} (@pxref{Buffer File
480 Name}).
482 @node Reading from Files
483 @comment  node-name,  next,  previous,  up
484 @section Reading from Files
485 @cindex reading from files
487   You can copy a file from the disk and insert it into a buffer
488 using the @code{insert-file-contents} function.  Don't use the user-level
489 command @code{insert-file} in a Lisp program, as that sets the mark.
491 @defun insert-file-contents filename &optional visit beg end replace
492 This function inserts the contents of file @var{filename} into the
493 current buffer after point.  It returns a list of the absolute file name
494 and the length of the data inserted.  An error is signaled if
495 @var{filename} is not the name of a file that can be read.
497 The function @code{insert-file-contents} checks the file contents
498 against the defined file formats, and converts the file contents if
499 appropriate.  @xref{Format Conversion}.  It also calls the functions in
500 the list @code{after-insert-file-functions}; see @ref{Saving
501 Properties}.  Normally, one of the functions in the
502 @code{after-insert-file-functions} list determines the coding system
503 (@pxref{Coding Systems}) used for decoding the file's contents,
504 including end-of-line conversion.
506 If @var{visit} is non-@code{nil}, this function additionally marks the
507 buffer as unmodified and sets up various fields in the buffer so that it
508 is visiting the file @var{filename}: these include the buffer's visited
509 file name and its last save file modtime.  This feature is used by
510 @code{find-file-noselect} and you probably should not use it yourself.
512 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
513 specifying the portion of the file to insert.  In this case, @var{visit}
514 must be @code{nil}.  For example,
516 @example
517 (insert-file-contents filename nil 0 500)
518 @end example
520 @noindent
521 inserts the first 500 characters of a file.
523 If the argument @var{replace} is non-@code{nil}, it means to replace the
524 contents of the buffer (actually, just the accessible portion) with the
525 contents of the file.  This is better than simply deleting the buffer
526 contents and inserting the whole file, because (1) it preserves some
527 marker positions and (2) it puts less data in the undo list.
529 It is possible to read a special file (such as a FIFO or an I/O device)
530 with @code{insert-file-contents}, as long as @var{replace} and
531 @var{visit} are @code{nil}.
532 @end defun
534 @defun insert-file-contents-literally filename &optional visit beg end replace
535 This function works like @code{insert-file-contents} except that it does
536 not do format decoding (@pxref{Format Conversion}), does not do
537 character code conversion (@pxref{Coding Systems}), does not run
538 @code{find-file-hook}, does not perform automatic uncompression, and so
540 @end defun
542 If you want to pass a file name to another process so that another
543 program can read the file, use the function @code{file-local-copy}; see
544 @ref{Magic File Names}.
546 @node Writing to Files
547 @comment  node-name,  next,  previous,  up
548 @section Writing to Files
549 @cindex writing to files
551   You can write the contents of a buffer, or part of a buffer, directly
552 to a file on disk using the @code{append-to-file} and
553 @code{write-region} functions.  Don't use these functions to write to
554 files that are being visited; that could cause confusion in the
555 mechanisms for visiting.
557 @deffn Command append-to-file start end filename
558 This function appends the contents of the region delimited by
559 @var{start} and @var{end} in the current buffer to the end of file
560 @var{filename}.  If that file does not exist, it is created.  This
561 function returns @code{nil}.
563 An error is signaled if @var{filename} specifies a nonwritable file,
564 or a nonexistent file in a directory where files cannot be created.
566 When called from Lisp, this function is completely equivalent to:
568 @example
569 (write-region start end filename t)
570 @end example
571 @end deffn
573 @deffn Command write-region start end filename &optional append visit lockname mustbenew
574 This function writes the region delimited by @var{start} and @var{end}
575 in the current buffer into the file specified by @var{filename}.
577 If @var{start} is @code{nil}, then the command writes the entire buffer
578 contents (@emph{not} just the accessible portion) to the file and
579 ignores @var{end}.
581 @c Emacs 19 feature
582 If @var{start} is a string, then @code{write-region} writes or appends
583 that string, rather than text from the buffer.  @var{end} is ignored in
584 this case.
586 If @var{append} is non-@code{nil}, then the specified text is appended
587 to the existing file contents (if any).  If @var{append} is an
588 integer, @code{write-region} seeks to that byte offset from the start
589 of the file and writes the data from there.
591 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
592 for confirmation if @var{filename} names an existing file.  If
593 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
594 does not ask for confirmation, but instead it signals an error
595 @code{file-already-exists} if the file already exists.
597 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
598 a special system feature.  At least for files on a local disk, there is
599 no chance that some other program could create a file of the same name
600 before Emacs does, without Emacs's noticing.
602 If @var{visit} is @code{t}, then Emacs establishes an association
603 between the buffer and the file: the buffer is then visiting that file.
604 It also sets the last file modification time for the current buffer to
605 @var{filename}'s modtime, and marks the buffer as not modified.  This
606 feature is used by @code{save-buffer}, but you probably should not use
607 it yourself.
609 @c Emacs 19 feature
610 If @var{visit} is a string, it specifies the file name to visit.  This
611 way, you can write the data to one file (@var{filename}) while recording
612 the buffer as visiting another file (@var{visit}).  The argument
613 @var{visit} is used in the echo area message and also for file locking;
614 @var{visit} is stored in @code{buffer-file-name}.  This feature is used
615 to implement @code{file-precious-flag}; don't use it yourself unless you
616 really know what you're doing.
618 The optional argument @var{lockname}, if non-@code{nil}, specifies the
619 file name to use for purposes of locking and unlocking, overriding
620 @var{filename} and @var{visit} for that purpose.
622 The function @code{write-region} converts the data which it writes to
623 the appropriate file formats specified by @code{buffer-file-format}.
624 @xref{Format Conversion}.  It also calls the functions in the list
625 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
627 Normally, @code{write-region} displays the message @samp{Wrote
628 @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
629 nor @code{nil} nor a string, then this message is inhibited.  This
630 feature is useful for programs that use files for internal purposes,
631 files that the user does not need to know about.
632 @end deffn
634 @defmac with-temp-file file body@dots{}
635 @anchor{Definition of with-temp-file}
636 The @code{with-temp-file} macro evaluates the @var{body} forms with a
637 temporary buffer as the current buffer; then, at the end, it writes the
638 buffer contents into file @var{file}.  It kills the temporary buffer
639 when finished, restoring the buffer that was current before the
640 @code{with-temp-file} form.  Then it returns the value of the last form
641 in @var{body}.
643 The current buffer is restored even in case of an abnormal exit via
644 @code{throw} or error (@pxref{Nonlocal Exits}).
646 See also @code{with-temp-buffer} in @ref{Definition of
647 with-temp-buffer,, The Current Buffer}.
648 @end defmac
650 @node File Locks
651 @section File Locks
652 @cindex file locks
653 @cindex lock file
655   When two users edit the same file at the same time, they are likely
656 to interfere with each other.  Emacs tries to prevent this situation
657 from arising by recording a @dfn{file lock} when a file is being
658 modified.  (File locks are not implemented on Microsoft systems.)
659 Emacs can then detect the first attempt to modify a buffer visiting a
660 file that is locked by another Emacs job, and ask the user what to do.
661 The file lock is really a file, a symbolic link with a special name,
662 stored in the same directory as the file you are editing.
664   When you access files using NFS, there may be a small probability that
665 you and another user will both lock the same file ``simultaneously.''
666 If this happens, it is possible for the two users to make changes
667 simultaneously, but Emacs will still warn the user who saves second.
668 Also, the detection of modification of a buffer visiting a file changed
669 on disk catches some cases of simultaneous editing; see
670 @ref{Modification Time}.
672 @defun file-locked-p filename
673 This function returns @code{nil} if the file @var{filename} is not
674 locked.  It returns @code{t} if it is locked by this Emacs process, and
675 it returns the name of the user who has locked it if it is locked by
676 some other job.
678 @example
679 @group
680 (file-locked-p "foo")
681      @result{} nil
682 @end group
683 @end example
684 @end defun
686 @defun lock-buffer &optional filename
687 This function locks the file @var{filename}, if the current buffer is
688 modified.  The argument @var{filename} defaults to the current buffer's
689 visited file.  Nothing is done if the current buffer is not visiting a
690 file, or is not modified, or if the system does not support locking.
691 @end defun
693 @defun unlock-buffer
694 This function unlocks the file being visited in the current buffer,
695 if the buffer is modified.  If the buffer is not modified, then
696 the file should not be locked, so this function does nothing.  It also
697 does nothing if the current buffer is not visiting a file, or if the
698 system does not support locking.
699 @end defun
701   File locking is not supported on some systems.  On systems that do not
702 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
703 @code{file-locked-p} do nothing and return @code{nil}.
705 @defun ask-user-about-lock file other-user
706 This function is called when the user tries to modify @var{file}, but it
707 is locked by another user named @var{other-user}.  The default
708 definition of this function asks the user to say what to do.  The value
709 this function returns determines what Emacs does next:
711 @itemize @bullet
712 @item
713 A value of @code{t} says to grab the lock on the file.  Then
714 this user may edit the file and @var{other-user} loses the lock.
716 @item
717 A value of @code{nil} says to ignore the lock and let this
718 user edit the file anyway.
720 @item
721 @kindex file-locked
722 This function may instead signal a @code{file-locked} error, in which
723 case the change that the user was about to make does not take place.
725 The error message for this error looks like this:
727 @example
728 @error{} File is locked: @var{file} @var{other-user}
729 @end example
731 @noindent
732 where @code{file} is the name of the file and @var{other-user} is the
733 name of the user who has locked the file.
734 @end itemize
736 If you wish, you can replace the @code{ask-user-about-lock} function
737 with your own version that makes the decision in another way.  The code
738 for its usual definition is in @file{userlock.el}.
739 @end defun
741 @node Information about Files
742 @section Information about Files
743 @cindex file, information about
745   The functions described in this section all operate on strings that
746 designate file names.  With a few exceptions, all the functions have
747 names that begin with the word @samp{file}.  These functions all
748 return information about actual files or directories, so their
749 arguments must all exist as actual files or directories unless
750 otherwise noted.
752 @menu
753 * Testing Accessibility::   Is a given file readable?  Writable?
754 * Kinds of Files::          Is it a directory?  A symbolic link?
755 * Truenames::               Eliminating symbolic links from a file name.
756 * File Attributes::         How large is it?  Any other names?  Etc.
757 * Locating Files::          How to find a file in standard places.
758 @end menu
760 @node Testing Accessibility
761 @comment  node-name,  next,  previous,  up
762 @subsection Testing Accessibility
763 @cindex accessibility of a file
764 @cindex file accessibility
766   These functions test for permission to access a file in specific
767 ways.  Unless explicitly stated otherwise, they recursively follow
768 symbolic links for their file name arguments, at all levels (at the
769 level of the file itself and at all levels of parent directories).
771 @defun file-exists-p filename
772 This function returns @code{t} if a file named @var{filename} appears
773 to exist.  This does not mean you can necessarily read the file, only
774 that you can find out its attributes.  (On Unix and GNU/Linux, this is
775 true if the file exists and you have execute permission on the
776 containing directories, regardless of the protection of the file
777 itself.)
779 If the file does not exist, or if fascist access control policies
780 prevent you from finding the attributes of the file, this function
781 returns @code{nil}.
783 Directories are files, so @code{file-exists-p} returns @code{t} when
784 given a directory name.  However, symbolic links are treated
785 specially; @code{file-exists-p} returns @code{t} for a symbolic link
786 name only if the target file exists.
787 @end defun
789 @defun file-readable-p filename
790 This function returns @code{t} if a file named @var{filename} exists
791 and you can read it.  It returns @code{nil} otherwise.
793 @example
794 @group
795 (file-readable-p "files.texi")
796      @result{} t
797 @end group
798 @group
799 (file-exists-p "/usr/spool/mqueue")
800      @result{} t
801 @end group
802 @group
803 (file-readable-p "/usr/spool/mqueue")
804      @result{} nil
805 @end group
806 @end example
807 @end defun
809 @c Emacs 19 feature
810 @defun file-executable-p filename
811 This function returns @code{t} if a file named @var{filename} exists and
812 you can execute it.  It returns @code{nil} otherwise.  On Unix and
813 GNU/Linux, if the file is a directory, execute permission means you can
814 check the existence and attributes of files inside the directory, and
815 open those files if their modes permit.
816 @end defun
818 @defun file-writable-p filename
819 This function returns @code{t} if the file @var{filename} can be written
820 or created by you, and @code{nil} otherwise.  A file is writable if the
821 file exists and you can write it.  It is creatable if it does not exist,
822 but the specified directory does exist and you can write in that
823 directory.
825 In the third example below, @file{foo} is not writable because the
826 parent directory does not exist, even though the user could create such
827 a directory.
829 @example
830 @group
831 (file-writable-p "~/foo")
832      @result{} t
833 @end group
834 @group
835 (file-writable-p "/foo")
836      @result{} nil
837 @end group
838 @group
839 (file-writable-p "~/no-such-dir/foo")
840      @result{} nil
841 @end group
842 @end example
843 @end defun
845 @c Emacs 19 feature
846 @defun file-accessible-directory-p dirname
847 This function returns @code{t} if you have permission to open existing
848 files in the directory whose name as a file is @var{dirname};
849 otherwise (or if there is no such directory), it returns @code{nil}.
850 The value of @var{dirname} may be either a directory name (such as
851 @file{/foo/}) or the file name of a file which is a directory
852 (such as @file{/foo}, without the final slash).
854 Example: after the following,
856 @example
857 (file-accessible-directory-p "/foo")
858      @result{} nil
859 @end example
861 @noindent
862 we can deduce that any attempt to read a file in @file{/foo/} will
863 give an error.
864 @end defun
866 @defun access-file filename string
867 This function opens file @var{filename} for reading, then closes it and
868 returns @code{nil}.  However, if the open fails, it signals an error
869 using @var{string} as the error message text.
870 @end defun
872 @defun file-ownership-preserved-p filename
873 This function returns @code{t} if deleting the file @var{filename} and
874 then creating it anew would keep the file's owner unchanged.  It also
875 returns @code{t} for nonexistent files.
877 If @var{filename} is a symbolic link, then, unlike the other functions
878 discussed here, @code{file-ownership-preserved-p} does @emph{not}
879 replace @var{filename} with its target.  However, it does recursively
880 follow symbolic links at all levels of parent directories.
881 @end defun
883 @defun file-newer-than-file-p filename1 filename2
884 @cindex file age
885 @cindex file modification time
886 This function returns @code{t} if the file @var{filename1} is
887 newer than file @var{filename2}.  If @var{filename1} does not
888 exist, it returns @code{nil}.  If @var{filename1} does exist, but
889 @var{filename2} does not, it returns @code{t}.
891 In the following example, assume that the file @file{aug-19} was written
892 on the 19th, @file{aug-20} was written on the 20th, and the file
893 @file{no-file} doesn't exist at all.
895 @example
896 @group
897 (file-newer-than-file-p "aug-19" "aug-20")
898      @result{} nil
899 @end group
900 @group
901 (file-newer-than-file-p "aug-20" "aug-19")
902      @result{} t
903 @end group
904 @group
905 (file-newer-than-file-p "aug-19" "no-file")
906      @result{} t
907 @end group
908 @group
909 (file-newer-than-file-p "no-file" "aug-19")
910      @result{} nil
911 @end group
912 @end example
914 You can use @code{file-attributes} to get a file's last modification
915 time as a list of two numbers.  @xref{File Attributes}.
916 @end defun
918 @node Kinds of Files
919 @comment  node-name,  next,  previous,  up
920 @subsection Distinguishing Kinds of Files
922   This section describes how to distinguish various kinds of files, such
923 as directories, symbolic links, and ordinary files.
925 @defun file-symlink-p filename
926 @cindex file symbolic links
927 If the file @var{filename} is a symbolic link, the
928 @code{file-symlink-p} function returns the (non-recursive) link target
929 as a string.  (Determining the file name that the link points to from
930 the target is nontrivial.)  First, this function recursively follows
931 symbolic links at all levels of parent directories.
933 If the file @var{filename} is not a symbolic link (or there is no such file),
934 @code{file-symlink-p} returns @code{nil}.
936 @example
937 @group
938 (file-symlink-p "foo")
939      @result{} nil
940 @end group
941 @group
942 (file-symlink-p "sym-link")
943      @result{} "foo"
944 @end group
945 @group
946 (file-symlink-p "sym-link2")
947      @result{} "sym-link"
948 @end group
949 @group
950 (file-symlink-p "/bin")
951      @result{} "/pub/bin"
952 @end group
953 @end example
955 @c !!! file-symlink-p: should show output of ls -l for comparison
956 @end defun
958 The next two functions recursively follow symbolic links at
959 all levels for @var{filename}.
961 @defun file-directory-p filename
962 This function returns @code{t} if @var{filename} is the name of an
963 existing directory, @code{nil} otherwise.
965 @example
966 @group
967 (file-directory-p "~rms")
968      @result{} t
969 @end group
970 @group
971 (file-directory-p "~rms/lewis/files.texi")
972      @result{} nil
973 @end group
974 @group
975 (file-directory-p "~rms/lewis/no-such-file")
976      @result{} nil
977 @end group
978 @group
979 (file-directory-p "$HOME")
980      @result{} nil
981 @end group
982 @group
983 (file-directory-p
984  (substitute-in-file-name "$HOME"))
985      @result{} t
986 @end group
987 @end example
988 @end defun
990 @defun file-regular-p filename
991 This function returns @code{t} if the file @var{filename} exists and is
992 a regular file (not a directory, named pipe, terminal, or
993 other I/O device).
994 @end defun
996 @node Truenames
997 @subsection Truenames
998 @cindex truename (of file)
1000 @c Emacs 19 features
1001   The @dfn{truename} of a file is the name that you get by following
1002 symbolic links at all levels until none remain, then simplifying away
1003 @samp{.}@: and @samp{..}@: appearing as name components.  This results
1004 in a sort of canonical name for the file.  A file does not always have a
1005 unique truename; the number of distinct truenames a file has is equal to
1006 the number of hard links to the file.  However, truenames are useful
1007 because they eliminate symbolic links as a cause of name variation.
1009 @defun file-truename filename
1010 The function @code{file-truename} returns the truename of the file
1011 @var{filename}.  The argument must be an absolute file name.
1013 This function does not expand environment variables.  Only
1014 @code{substitute-in-file-name} does that.  @xref{Definition of
1015 substitute-in-file-name}.
1017 If you may need to follow symbolic links preceding @samp{..}@:
1018 appearing as a name component, you should make sure to call
1019 @code{file-truename} without prior direct or indirect calls to
1020 @code{expand-file-name}, as otherwise the file name component
1021 immediately preceding @samp{..} will be ``simplified away'' before
1022 @code{file-truename} is called.  To eliminate the need for a call to
1023 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1024 same way that @code{expand-file-name} does.  @xref{File Name
1025 Expansion,, Functions that Expand Filenames}.
1026 @end defun
1028 @defun file-chase-links filename &optional limit
1029 This function follows symbolic links, starting with @var{filename},
1030 until it finds a file name which is not the name of a symbolic link.
1031 Then it returns that file name.  This function does @emph{not} follow
1032 symbolic links at the level of parent directories.
1034 If you specify a number for @var{limit}, then after chasing through
1035 that many links, the function just returns what it has even if that is
1036 still a symbolic link.
1037 @end defun
1039   To illustrate the difference between @code{file-chase-links} and
1040 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1041 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1042 ordinary file (or at least, not a symbolic link) or nonexistent.  Then
1043 we would have:
1045 @example
1046 (file-chase-links "/usr/foo/hello")
1047      ;; @r{This does not follow the links in the parent directories.}
1048      @result{} "/usr/foo/hello"
1049 (file-truename "/usr/foo/hello")
1050      ;; @r{Assuming that @file{/home} is not a symbolic link.}
1051      @result{} "/home/foo/hello"
1052 @end example
1054   @xref{Buffer File Name}, for related information.
1056 @node File Attributes
1057 @comment  node-name,  next,  previous,  up
1058 @subsection Other Information about Files
1060   This section describes the functions for getting detailed information
1061 about a file, other than its contents.  This information includes the
1062 mode bits that control access permission, the owner and group numbers,
1063 the number of names, the inode number, the size, and the times of access
1064 and modification.
1066 @defun file-modes filename
1067 @cindex permission
1068 @cindex file attributes
1069 This function returns the mode bits of @var{filename}, as an integer.
1070 The mode bits are also called the file permissions, and they specify
1071 access control in the usual Unix fashion.  If the low-order bit is 1,
1072 then the file is executable by all users, if the second-lowest-order bit
1073 is 1, then the file is writable by all users, etc.
1075 The highest value returnable is 4095 (7777 octal), meaning that
1076 everyone has read, write, and execute permission, that the @acronym{SUID} bit
1077 is set for both others and group, and that the sticky bit is set.
1079 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
1081 This function recursively follows symbolic links at all levels.
1083 @example
1084 @group
1085 (file-modes "~/junk/diffs")
1086      @result{} 492               ; @r{Decimal integer.}
1087 @end group
1088 @group
1089 (format "%o" 492)
1090      @result{} "754"             ; @r{Convert to octal.}
1091 @end group
1093 @group
1094 (set-file-modes "~/junk/diffs" 438)
1095      @result{} nil
1096 @end group
1098 @group
1099 (format "%o" 438)
1100      @result{} "666"             ; @r{Convert to octal.}
1101 @end group
1103 @group
1104 % ls -l diffs
1105   -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
1106 @end group
1107 @end example
1108 @end defun
1110 If the @var{filename} argument to the next two functions is a symbolic
1111 link, then these function do @emph{not} replace it with its target.
1112 However, they both recursively follow symbolic links at all levels of
1113 parent directories.
1115 @defun file-nlinks filename
1116 This functions returns the number of names (i.e., hard links) that
1117 file @var{filename} has.  If the file does not exist, then this function
1118 returns @code{nil}.  Note that symbolic links have no effect on this
1119 function, because they are not considered to be names of the files they
1120 link to.
1122 @example
1123 @group
1124 % ls -l foo*
1125 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
1126 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
1127 @end group
1129 @group
1130 (file-nlinks "foo")
1131      @result{} 2
1132 @end group
1133 @group
1134 (file-nlinks "doesnt-exist")
1135      @result{} nil
1136 @end group
1137 @end example
1138 @end defun
1140 @defun file-attributes filename &optional id-format
1141 @anchor{Definition of file-attributes}
1142 This function returns a list of attributes of file @var{filename}.  If
1143 the specified file cannot be opened, it returns @code{nil}.
1144 The optional parameter @var{id-format} specifies the preferred format
1145 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1146 valid values are @code{'string} and @code{'integer}.  The latter is
1147 the default, but we plan to change that, so you should specify a
1148 non-@code{nil} value for @var{id-format} if you use the returned
1149 @acronym{UID} or @acronym{GID}.
1151 The elements of the list, in order, are:
1153 @enumerate 0
1154 @item
1155 @code{t} for a directory, a string for a symbolic link (the name
1156 linked to), or @code{nil} for a text file.
1158 @c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
1159 @item
1160 The number of names the file has.  Alternate names, also known as hard
1161 links, can be created by using the @code{add-name-to-file} function
1162 (@pxref{Changing Files}).
1164 @item
1165 The file's @acronym{UID}, normally as a string.  However, if it does
1166 not correspond to a named user, the value is an integer or a floating
1167 point number.
1169 @item
1170 The file's @acronym{GID}, likewise.
1172 @item
1173 The time of last access, as a list of two integers.
1174 The first integer has the high-order 16 bits of time,
1175 the second has the low 16 bits.  (This is similar to the
1176 value of @code{current-time}; see @ref{Time of Day}.)
1178 @item
1179 The time of last modification as a list of two integers (as above).
1180 @cindex modification time of file
1182 @item
1183 The time of last status change as a list of two integers (as above).
1185 @item
1186 The size of the file in bytes.  If the size is too large to fit in a
1187 Lisp integer, this is a floating point number.
1189 @item
1190 The file's modes, as a string of ten letters or dashes,
1191 as in @samp{ls -l}.
1193 @item
1194 @code{t} if the file's @acronym{GID} would change if file were
1195 deleted and recreated; @code{nil} otherwise.
1197 @item
1198 The file's inode number.  If possible, this is an integer.  If the inode
1199 number is too large to be represented as an integer in Emacs Lisp, then
1200 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
1201 holds the low 16 bits.
1203 @item
1204 The file system number of the file system that the file is in.
1205 Depending on the magnitude of the value, this can be either an integer
1206 or a cons cell, in the same manner as the inode number.  This element
1207 and the file's inode number together give enough information to
1208 distinguish any two files on the system---no two files can have the same
1209 values for both of these numbers.
1210 @end enumerate
1212 For example, here are the file attributes for @file{files.texi}:
1214 @example
1215 @group
1216 (file-attributes "files.texi" 'string)
1217      @result{}  (nil 1 "lh" "users"
1218           (8489 20284)
1219           (8489 20284)
1220           (8489 20285)
1221           14906 "-rw-rw-rw-"
1222           nil 129500 -32252)
1223 @end group
1224 @end example
1226 @noindent
1227 and here is how the result is interpreted:
1229 @table @code
1230 @item nil
1231 is neither a directory nor a symbolic link.
1233 @item 1
1234 has only one name (the name @file{files.texi} in the current default
1235 directory).
1237 @item "lh"
1238 is owned by the user with name "lh".
1240 @item "users"
1241 is in the group with name "users".
1243 @item (8489 20284)
1244 was last accessed on Aug 19 00:09.
1246 @item (8489 20284)
1247 was last modified on Aug 19 00:09.
1249 @item (8489 20285)
1250 last had its inode changed on Aug 19 00:09.
1252 @item 14906
1253 is 14906 bytes long.  (It may not contain 14906 characters, though,
1254 if some of the bytes belong to multibyte sequences.)
1256 @item "-rw-rw-rw-"
1257 has a mode of read and write access for the owner, group, and world.
1259 @item nil
1260 would retain the same @acronym{GID} if it were recreated.
1262 @item 129500
1263 has an inode number of 129500.
1264 @item -32252
1265 is on file system number -32252.
1266 @end table
1267 @end defun
1269 @node Locating Files
1270 @subsection How to Locate Files in Standard Places
1271 @cindex locate file in path
1272 @cindex find file in path
1274   This section explains how to search for a file in a list of
1275 directories (a @dfn{path}).  One example is when you need to look for
1276 a program's executable file, e.g., to find out whether a given program
1277 is installed on the user's system.  Another example is the search for
1278 Lisp libraries (@pxref{Library Search}).  Such searches generally need
1279 to try various possible file name extensions, in addition to various
1280 possible directories.  Emacs provides a function for such a
1281 generalized search for a file.
1283 @defun locate-file filename path &optional suffixes predicate
1284 This function searches for a file whose name is @var{filename} in a
1285 list of directories given by @var{path}, trying the suffixes in
1286 @var{suffixes}.  If it finds such a file, it returns the full
1287 @dfn{absolute file name} of the file (@pxref{Relative File Names});
1288 otherwise it returns @code{nil}.
1290 The optional argument @var{suffixes} gives the list of file-name
1291 suffixes to append to @var{filename} when searching.
1292 @code{locate-file} tries each possible directory with each of these
1293 suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
1294 are no suffixes, and @var{filename} is used only as-is.  Typical
1295 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1296 Creation, exec-suffixes}), @code{load-suffixes},
1297 @code{load-file-rep-suffixes} and the return value of the function
1298 @code{get-load-suffixes} (@pxref{Load Suffixes}).
1300 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1301 Creation, exec-path}) when looking for executable programs or
1302 @code{load-path} (@pxref{Library Search, load-path}) when looking for
1303 Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
1304 but the suffixes in @var{suffixes} are still tried.
1306 The optional argument @var{predicate}, if non-@code{nil}, specifies
1307 the predicate function to use for testing whether a candidate file is
1308 suitable.  The predicate function is passed the candidate file name as
1309 its single argument.  If @var{predicate} is @code{nil} or unspecified,
1310 @code{locate-file} uses @code{file-readable-p} as the default
1311 predicate.  Useful non-default predicates include
1312 @code{file-executable-p}, @code{file-directory-p}, and other
1313 predicates described in @ref{Kinds of Files}.
1315 For compatibility, @var{predicate} can also be one of the symbols
1316 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1317 a list of one or more of these symbols.
1318 @end defun
1320 @defun executable-find program
1321 This function searches for the executable file of the named
1322 @var{program} and returns the full absolute name of the executable,
1323 including its file-name extensions, if any.  It returns @code{nil} if
1324 the file is not found.  The functions searches in all the directories
1325 in @code{exec-path} and tries all the file-name extensions in
1326 @code{exec-suffixes}.
1327 @end defun
1329 @node Changing Files
1330 @section Changing File Names and Attributes
1331 @c @cindex renaming files  Duplicates rename-file
1332 @cindex copying files
1333 @cindex deleting files
1334 @cindex linking files
1335 @cindex setting modes of files
1337   The functions in this section rename, copy, delete, link, and set the
1338 modes of files.
1340   In the functions that have an argument @var{newname}, if a file by the
1341 name of @var{newname} already exists, the actions taken depend on the
1342 value of the argument @var{ok-if-already-exists}:
1344 @itemize @bullet
1345 @item
1346 Signal a @code{file-already-exists} error if
1347 @var{ok-if-already-exists} is @code{nil}.
1349 @item
1350 Request confirmation if @var{ok-if-already-exists} is a number.
1352 @item
1353 Replace the old file without confirmation if @var{ok-if-already-exists}
1354 is any other value.
1355 @end itemize
1357 The next four commands all recursively follow symbolic links at all
1358 levels of parent directories for their first argument, but, if that
1359 argument is itself a symbolic link, then only @code{copy-file}
1360 replaces it with its (recursive) target.
1362 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1363 @cindex file with multiple names
1364 @cindex file hard link
1365 This function gives the file named @var{oldname} the additional name
1366 @var{newname}.  This means that @var{newname} becomes a new ``hard
1367 link'' to @var{oldname}.
1369 In the first part of the following example, we list two files,
1370 @file{foo} and @file{foo3}.
1372 @example
1373 @group
1374 % ls -li fo*
1375 81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
1376 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1377 @end group
1378 @end example
1380 Now we create a hard link, by calling @code{add-name-to-file}, then list
1381 the files again.  This shows two names for one file, @file{foo} and
1382 @file{foo2}.
1384 @example
1385 @group
1386 (add-name-to-file "foo" "foo2")
1387      @result{} nil
1388 @end group
1390 @group
1391 % ls -li fo*
1392 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
1393 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
1394 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1395 @end group
1396 @end example
1398 Finally, we evaluate the following:
1400 @example
1401 (add-name-to-file "foo" "foo3" t)
1402 @end example
1404 @noindent
1405 and list the files again.  Now there are three names
1406 for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
1407 contents of @file{foo3} are lost.
1409 @example
1410 @group
1411 (add-name-to-file "foo1" "foo3")
1412      @result{} nil
1413 @end group
1415 @group
1416 % ls -li fo*
1417 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
1418 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
1419 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
1420 @end group
1421 @end example
1423 This function is meaningless on operating systems where multiple names
1424 for one file are not allowed.  Some systems implement multiple names
1425 by copying the file instead.
1427 See also @code{file-nlinks} in @ref{File Attributes}.
1428 @end deffn
1430 @deffn Command rename-file filename newname &optional ok-if-already-exists
1431 This command renames the file @var{filename} as @var{newname}.
1433 If @var{filename} has additional names aside from @var{filename}, it
1434 continues to have those names.  In fact, adding the name @var{newname}
1435 with @code{add-name-to-file} and then deleting @var{filename} has the
1436 same effect as renaming, aside from momentary intermediate states.
1437 @end deffn
1439 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
1440 This command copies the file @var{oldname} to @var{newname}.  An
1441 error is signaled if @var{oldname} does not exist.  If @var{newname}
1442 names a directory, it copies @var{oldname} into that directory,
1443 preserving its final name component.
1445 If @var{time} is non-@code{nil}, then this function gives the new file
1446 the same last-modified time that the old one has.  (This works on only
1447 some operating systems.)  If setting the time gets an error,
1448 @code{copy-file} signals a @code{file-date-error} error.  In an
1449 interactive call, a prefix argument specifies a non-@code{nil} value
1450 for @var{time}.
1452 This function copies the file modes, too.
1454 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
1455 system decide the user and group ownership of the new file (this is
1456 usually set to the user running Emacs).  If @var{preserve-uid-gid} is
1457 non-@code{nil}, we attempt to copy the user and group ownership of the
1458 file.  This works only on some operating systems, and only if you have
1459 the correct permissions to do so.
1460 @end deffn
1462 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
1463 @pindex ln
1464 @kindex file-already-exists
1465 This command makes a symbolic link to @var{filename}, named
1466 @var{newname}.  This is like the shell command @samp{ln -s
1467 @var{filename} @var{newname}}.
1469 This function is not available on systems that don't support symbolic
1470 links.
1471 @end deffn
1473 @deffn Command delete-file filename
1474 @pindex rm
1475 This command deletes the file @var{filename}, like the shell command
1476 @samp{rm @var{filename}}.  If the file has multiple names, it continues
1477 to exist under the other names.
1479 A suitable kind of @code{file-error} error is signaled if the file does
1480 not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
1481 deletable if its directory is writable.)
1483 If @var{filename} is a symbolic link, @code{delete-file} does not
1484 replace it with its target, but it does follow symbolic links at all
1485 levels of parent directories.
1487 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1488 @end deffn
1490 @defun define-logical-name varname string
1491 This function defines the logical name @var{varname} to have the value
1492 @var{string}.  It is available only on VMS.
1493 @end defun
1495 @defun set-file-modes filename mode
1496 This function sets mode bits of @var{filename} to @var{mode} (which
1497 must be an integer).  Only the low 12 bits of @var{mode} are used.
1498 This function recursively follows symbolic links at all levels for
1499 @var{filename}.
1500 @end defun
1502 @c Emacs 19 feature
1503 @defun set-default-file-modes mode
1504 @cindex umask
1505 This function sets the default file protection for new files created by
1506 Emacs and its subprocesses.  Every file created with Emacs initially has
1507 this protection, or a subset of it (@code{write-region} will not give a
1508 file execute permission even if the default file protection allows
1509 execute permission).  On Unix and GNU/Linux, the default protection is
1510 the bitwise complement of the ``umask'' value.
1512 The argument @var{mode} must be an integer.  On most systems, only the
1513 low 9 bits of @var{mode} are meaningful.  You can use the Lisp construct
1514 for octal character codes to enter @var{mode}; for example,
1516 @example
1517 (set-default-file-modes ?\644)
1518 @end example
1520 Saving a modified version of an existing file does not count as creating
1521 the file; it preserves the existing file's mode, whatever that is.  So
1522 the default file protection has no effect.
1523 @end defun
1525 @defun default-file-modes
1526 This function returns the current default protection value.
1527 @end defun
1529 @defun set-file-times filename &optional time
1530 This function sets the access and modification times of @var{filename}
1531 to @var{time}.  The return value is @code{t} if the times are successfully
1532 set, otherwise it is @code{nil}.  @var{time} defaults to the current
1533 time and must be in the format returned by @code{current-time}
1534 (@pxref{Time of Day}).
1535 @end defun
1537 @cindex MS-DOS and file modes
1538 @cindex file modes and MS-DOS
1539   On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1540 So Emacs considers a file executable if its name ends in one of the
1541 standard executable extensions, such as @file{.com}, @file{.bat},
1542 @file{.exe}, and some others.  Files that begin with the Unix-standard
1543 @samp{#!} signature, such as shell and Perl scripts, are also considered
1544 as executable files.  This is reflected in the values returned by
1545 @code{file-modes} and @code{file-attributes}.  Directories are also
1546 reported with executable bit set, for compatibility with Unix.
1548 @node File Names
1549 @section File Names
1550 @cindex file names
1552   Files are generally referred to by their names, in Emacs as elsewhere.
1553 File names in Emacs are represented as strings.  The functions that
1554 operate on a file all expect a file name argument.
1556   In addition to operating on files themselves, Emacs Lisp programs
1557 often need to operate on file names; i.e., to take them apart and to use
1558 part of a name to construct related file names.  This section describes
1559 how to manipulate file names.
1561   The functions in this section do not actually access files, so they
1562 can operate on file names that do not refer to an existing file or
1563 directory.
1565   On MS-DOS and MS-Windows, these functions (like the function that
1566 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1567 where backslashes separate the components, as well as Unix syntax; but
1568 they always return Unix syntax.  On VMS, these functions (and the ones
1569 that operate on files) understand both VMS file-name syntax and Unix
1570 syntax.  This enables Lisp programs to specify file names in Unix syntax
1571 and work properly on all systems without change.
1573 @menu
1574 * File Name Components::  The directory part of a file name, and the rest.
1575 * Relative File Names::   Some file names are relative to a current directory.
1576 * Directory Names::       A directory's name as a directory
1577                             is different from its name as a file.
1578 * File Name Expansion::   Converting relative file names to absolute ones.
1579 * Unique File Names::     Generating names for temporary files.
1580 * File Name Completion::  Finding the completions for a given file name.
1581 * Standard File Names::   If your package uses a fixed file name,
1582                             how to handle various operating systems simply.
1583 @end menu
1585 @node File Name Components
1586 @subsection File Name Components
1587 @cindex directory part (of file name)
1588 @cindex nondirectory part (of file name)
1589 @cindex version number (in file name)
1591   The operating system groups files into directories.  To specify a
1592 file, you must specify the directory and the file's name within that
1593 directory.  Therefore, Emacs considers a file name as having two main
1594 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1595 (or @dfn{file name within the directory}).  Either part may be empty.
1596 Concatenating these two parts reproduces the original file name.
1598   On most systems, the directory part is everything up to and including
1599 the last slash (backslash is also allowed in input on MS-DOS or
1600 MS-Windows); the nondirectory part is the rest.  The rules in VMS syntax
1601 are complicated.
1603   For some purposes, the nondirectory part is further subdivided into
1604 the name proper and the @dfn{version number}.  On most systems, only
1605 backup files have version numbers in their names.  On VMS, every file
1606 has a version number, but most of the time the file name actually used
1607 in Emacs omits the version number, so that version numbers in Emacs are
1608 found mostly in directory lists.
1610 @defun file-name-directory filename
1611 This function returns the directory part of @var{filename}, as a
1612 directory name (@pxref{Directory Names}), or @code{nil} if
1613 @var{filename} does not include a directory part.
1615 On GNU and Unix systems, a string returned by this function always
1616 ends in a slash.  On MS-DOS it can also end in a colon.  On VMS, it
1617 returns a string ending in one of the three characters @samp{:},
1618 @samp{]}, or @samp{>}.
1620 @example
1621 @group
1622 (file-name-directory "lewis/foo")  ; @r{Unix example}
1623      @result{} "lewis/"
1624 @end group
1625 @group
1626 (file-name-directory "foo")        ; @r{Unix example}
1627      @result{} nil
1628 @end group
1629 @group
1630 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
1631      @result{} "[X]"
1632 @end group
1633 @end example
1634 @end defun
1636 @defun file-name-nondirectory filename
1637 This function returns the nondirectory part of @var{filename}.
1639 @example
1640 @group
1641 (file-name-nondirectory "lewis/foo")
1642      @result{} "foo"
1643 @end group
1644 @group
1645 (file-name-nondirectory "foo")
1646      @result{} "foo"
1647 @end group
1648 @group
1649 (file-name-nondirectory "lewis/")
1650      @result{} ""
1651 @end group
1652 @group
1653 ;; @r{The following example is accurate only on VMS.}
1654 (file-name-nondirectory "[X]FOO.TMP")
1655      @result{} "FOO.TMP"
1656 @end group
1657 @end example
1658 @end defun
1660 @defun file-name-sans-versions filename &optional keep-backup-version
1661 This function returns @var{filename} with any file version numbers,
1662 backup version numbers, or trailing tildes discarded.
1664 If @var{keep-backup-version} is non-@code{nil}, then true file version
1665 numbers understood as such by the file system are discarded from the
1666 return value, but backup version numbers are kept.
1668 @example
1669 @group
1670 (file-name-sans-versions "~rms/foo.~1~")
1671      @result{} "~rms/foo"
1672 @end group
1673 @group
1674 (file-name-sans-versions "~rms/foo~")
1675      @result{} "~rms/foo"
1676 @end group
1677 @group
1678 (file-name-sans-versions "~rms/foo")
1679      @result{} "~rms/foo"
1680 @end group
1681 @group
1682 ;; @r{The following example applies to VMS only.}
1683 (file-name-sans-versions "foo;23")
1684      @result{} "foo"
1685 @end group
1686 @end example
1687 @end defun
1689 @defun file-name-extension filename &optional period
1690 This function returns @var{filename}'s final ``extension,'' if any,
1691 after applying @code{file-name-sans-versions} to remove any
1692 version/backup part.  The extension, in a file name, is the part that
1693 starts with the last @samp{.} in the last name component (minus
1694 any version/backup part).
1696 This function returns @code{nil} for extensionless file names such as
1697 @file{foo}.  It returns @code{""} for null extensions, as in
1698 @file{foo.}.  If the last component of a file name begins with a
1699 @samp{.}, that @samp{.}  doesn't count as the beginning of an
1700 extension.  Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1701 @samp{.emacs}.
1703 If @var{period} is non-@code{nil}, then the returned value includes
1704 the period that delimits the extension, and if @var{filename} has no
1705 extension, the value is @code{""}.
1706 @end defun
1708 @defun file-name-sans-extension filename
1709 This function returns @var{filename} minus its extension, if any.  The
1710 version/backup part, if present, is only removed if the file has an
1711 extension.  For example,
1713 @example
1714 (file-name-sans-extension "foo.lose.c")
1715      @result{} "foo.lose"
1716 (file-name-sans-extension "big.hack/foo")
1717      @result{} "big.hack/foo"
1718 (file-name-sans-extension "/my/home/.emacs")
1719      @result{} "/my/home/.emacs"
1720 (file-name-sans-extension "/my/home/.emacs.el")
1721      @result{} "/my/home/.emacs"
1722 (file-name-sans-extension "~/foo.el.~3~")
1723      @result{} "~/foo"
1724 (file-name-sans-extension "~/foo.~3~")
1725      @result{} "~/foo.~3~"
1726 @end example
1728 Note that the @samp{.~3~} in the two last examples is the backup part,
1729 not an extension.
1730 @end defun
1732 @ignore
1733 Andrew Innes says that this
1735 @c @defvar directory-sep-char
1736 This variable holds the character that Emacs normally uses to separate
1737 file name components.  The default value is @code{?/}, but on MS-Windows
1738 you can set it to @code{?\\}; then the functions that transform file names
1739 use backslashes in their output.
1741 File names using backslashes work as input to Lisp primitives even on
1742 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
1743 value of @code{?/}.
1744 @end defvar
1745 @end ignore
1747 @node Relative File Names
1748 @subsection Absolute and Relative File Names
1749 @cindex absolute file name
1750 @cindex relative file name
1752   All the directories in the file system form a tree starting at the
1753 root directory.  A file name can specify all the directory names
1754 starting from the root of the tree; then it is called an @dfn{absolute}
1755 file name.  Or it can specify the position of the file in the tree
1756 relative to a default directory; then it is called a @dfn{relative} file
1757 name.  On Unix and GNU/Linux, an absolute file name starts with a slash
1758 or a tilde (@samp{~}), and a relative one does not.  On MS-DOS and
1759 MS-Windows, an absolute file name starts with a slash or a backslash, or
1760 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1761 @dfn{drive letter}.  The rules on VMS are complicated.
1763 @defun file-name-absolute-p filename
1764 This function returns @code{t} if file @var{filename} is an absolute
1765 file name, @code{nil} otherwise.  On VMS, this function understands both
1766 Unix syntax and VMS syntax.
1768 @example
1769 @group
1770 (file-name-absolute-p "~rms/foo")
1771      @result{} t
1772 @end group
1773 @group
1774 (file-name-absolute-p "rms/foo")
1775      @result{} nil
1776 @end group
1777 @group
1778 (file-name-absolute-p "/user/rms/foo")
1779      @result{} t
1780 @end group
1781 @end example
1782 @end defun
1784   Given a possibly relative file name, you can convert it to an
1785 absolute name using @code{expand-file-name} (@pxref{File Name
1786 Expansion}).  This function converts absolute file names to relative
1787 names:
1789 @defun file-relative-name filename &optional directory
1790 This function tries to return a relative name that is equivalent to
1791 @var{filename}, assuming the result will be interpreted relative to
1792 @var{directory} (an absolute directory name or directory file name).
1793 If @var{directory} is omitted or @code{nil}, it defaults to the
1794 current buffer's default directory.
1796 On some operating systems, an absolute file name begins with a device
1797 name.  On such systems, @var{filename} has no relative equivalent based
1798 on @var{directory} if they start with two different device names.  In
1799 this case, @code{file-relative-name} returns @var{filename} in absolute
1800 form.
1802 @example
1803 (file-relative-name "/foo/bar" "/foo/")
1804      @result{} "bar"
1805 (file-relative-name "/foo/bar" "/hack/")
1806      @result{} "../foo/bar"
1807 @end example
1808 @end defun
1810 @node Directory Names
1811 @comment  node-name,  next,  previous,  up
1812 @subsection Directory Names
1813 @cindex directory name
1814 @cindex file name of directory
1816   A @dfn{directory name} is the name of a directory.  A directory is
1817 actually a kind of file, so it has a file name, which is related to
1818 the directory name but not identical to it.  (This is not quite the
1819 same as the usual Unix terminology.)  These two different names for
1820 the same entity are related by a syntactic transformation.  On GNU and
1821 Unix systems, this is simple: a directory name ends in a slash,
1822 whereas the directory's name as a file lacks that slash.  On MS-DOS and
1823 VMS, the relationship is more complicated.
1825   The difference between a directory name and its name as a file is
1826 subtle but crucial.  When an Emacs variable or function argument is
1827 described as being a directory name, a file name of a directory is not
1828 acceptable.  When @code{file-name-directory} returns a string, that is
1829 always a directory name.
1831   The following two functions convert between directory names and file
1832 names.  They do nothing special with environment variable substitutions
1833 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1835 @defun file-name-as-directory filename
1836 This function returns a string representing @var{filename} in a form
1837 that the operating system will interpret as the name of a directory.  On
1838 most systems, this means appending a slash to the string (if it does not
1839 already end in one).  On VMS, the function converts a string of the form
1840 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
1842 @example
1843 @group
1844 (file-name-as-directory "~rms/lewis")
1845      @result{} "~rms/lewis/"
1846 @end group
1847 @end example
1848 @end defun
1850 @defun directory-file-name dirname
1851 This function returns a string representing @var{dirname} in a form that
1852 the operating system will interpret as the name of a file.  On most
1853 systems, this means removing the final slash (or backslash) from the
1854 string.  On VMS, the function converts a string of the form @file{[X.Y]}
1855 to @file{[X]Y.DIR.1}.
1857 @example
1858 @group
1859 (directory-file-name "~lewis/")
1860      @result{} "~lewis"
1861 @end group
1862 @end example
1863 @end defun
1865   Given a directory name, you can combine it with a relative file name
1866 using @code{concat}:
1868 @example
1869 (concat @var{dirname} @var{relfile})
1870 @end example
1872 @noindent
1873 Be sure to verify that the file name is relative before doing that.
1874 If you use an absolute file name, the results could be syntactically
1875 invalid or refer to the wrong file.
1877   If you want to use a directory file name in making such a
1878 combination, you must first convert it to a directory name using
1879 @code{file-name-as-directory}:
1881 @example
1882 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1883 @end example
1885 @noindent
1886 Don't try concatenating a slash by hand, as in
1888 @example
1889 ;;; @r{Wrong!}
1890 (concat @var{dirfile} "/" @var{relfile})
1891 @end example
1893 @noindent
1894 because this is not portable.  Always use
1895 @code{file-name-as-directory}.
1897 @cindex directory name abbreviation
1898   Directory name abbreviations are useful for directories that are
1899 normally accessed through symbolic links.  Sometimes the users recognize
1900 primarily the link's name as ``the name'' of the directory, and find it
1901 annoying to see the directory's ``real'' name.  If you define the link
1902 name as an abbreviation for the ``real'' name, Emacs shows users the
1903 abbreviation instead.
1905 @defvar directory-abbrev-alist
1906 The variable @code{directory-abbrev-alist} contains an alist of
1907 abbreviations to use for file directories.  Each element has the form
1908 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1909 @var{to} when it appears in a directory name.  The @var{from} string is
1910 actually a regular expression; it should always start with @samp{^}.
1911 The @var{to} string should be an ordinary absolute directory name.  Do
1912 not use @samp{~} to stand for a home directory in that string.  The
1913 function @code{abbreviate-file-name} performs these substitutions.
1915 You can set this variable in @file{site-init.el} to describe the
1916 abbreviations appropriate for your site.
1918 Here's an example, from a system on which file system @file{/home/fsf}
1919 and so on are normally accessed through symbolic links named @file{/fsf}
1920 and so on.
1922 @example
1923 (("^/home/fsf" . "/fsf")
1924  ("^/home/gp" . "/gp")
1925  ("^/home/gd" . "/gd"))
1926 @end example
1927 @end defvar
1929   To convert a directory name to its abbreviation, use this
1930 function:
1932 @defun abbreviate-file-name filename
1933 @anchor{Definition of abbreviate-file-name}
1934 This function applies abbreviations from @code{directory-abbrev-alist}
1935 to its argument, and substitutes @samp{~} for the user's home
1936 directory.  You can use it for directory names and for file names,
1937 because it recognizes abbreviations even as part of the name.
1938 @end defun
1940 @node File Name Expansion
1941 @subsection Functions that Expand Filenames
1942 @cindex expansion of file names
1944   @dfn{Expansion} of a file name means converting a relative file name
1945 to an absolute one.  Since this is done relative to a default directory,
1946 you must specify the default directory name as well as the file name to
1947 be expanded.  Expansion also simplifies file names by eliminating
1948 redundancies such as @file{./} and @file{@var{name}/../}.
1950 @defun expand-file-name filename &optional directory
1951 This function converts @var{filename} to an absolute file name.  If
1952 @var{directory} is supplied, it is the default directory to start with
1953 if @var{filename} is relative.  (The value of @var{directory} should
1954 itself be an absolute directory name or directory file name; it may
1955 start with @samp{~}.)  Otherwise, the current buffer's value of
1956 @code{default-directory} is used.  For example:
1958 @example
1959 @group
1960 (expand-file-name "foo")
1961      @result{} "/xcssun/users/rms/lewis/foo"
1962 @end group
1963 @group
1964 (expand-file-name "../foo")
1965      @result{} "/xcssun/users/rms/foo"
1966 @end group
1967 @group
1968 (expand-file-name "foo" "/usr/spool/")
1969      @result{} "/usr/spool/foo"
1970 @end group
1971 @group
1972 (expand-file-name "$HOME/foo")
1973      @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1974 @end group
1975 @end example
1977 If the part of the combined file name before the first slash is
1978 @samp{~}, it expands to the value of the @env{HOME} environment
1979 variable (usually your home directory).  If the part before the first
1980 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
1981 it expands to @var{user}'s home directory.
1983 Filenames containing @samp{.} or @samp{..} are simplified to their
1984 canonical form:
1986 @example
1987 @group
1988 (expand-file-name "bar/../foo")
1989      @result{} "/xcssun/users/rms/lewis/foo"
1990 @end group
1991 @end example
1993 In some cases, a leading @samp{..} component can remain in the output:
1995 @example
1996 @group
1997 (expand-file-name "../home" "/")
1998      @result{} "/../home"
1999 @end group
2000 @end example
2002 @noindent
2003 This is for the sake of filesystems that have the concept of a
2004 ``superroot'' above the root directory @file{/}.  On other filesystems,
2005 @file{/../} is interpreted exactly the same as @file{/}.
2007 Note that @code{expand-file-name} does @emph{not} expand environment
2008 variables; only @code{substitute-in-file-name} does that.
2010 Note also that @code{expand-file-name} does not follow symbolic links
2011 at any level.  This results in a difference between the way
2012 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
2013 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
2014 @samp{/tmp/foo/bar} we get:
2016 @example
2017 @group
2018 (file-truename "/tmp/bar/../myfile")
2019      @result{} "/tmp/foo/myfile"
2020 @end group
2021 @group
2022 (expand-file-name "/tmp/bar/../myfile")
2023      @result{} "/tmp/myfile"
2024 @end group
2025 @end example
2027 If you may need to follow symbolic links preceding @samp{..}, you
2028 should make sure to call @code{file-truename} without prior direct or
2029 indirect calls to @code{expand-file-name}.  @xref{Truenames}.
2030 @end defun
2032 @defvar default-directory
2033 The value of this buffer-local variable is the default directory for the
2034 current buffer.  It should be an absolute directory name; it may start
2035 with @samp{~}.  This variable is buffer-local in every buffer.
2037 @code{expand-file-name} uses the default directory when its second
2038 argument is @code{nil}.
2040 Aside from VMS, the value is always a string ending with a slash.
2042 @example
2043 @group
2044 default-directory
2045      @result{} "/user/lewis/manual/"
2046 @end group
2047 @end example
2048 @end defvar
2050 @defun substitute-in-file-name filename
2051 @anchor{Definition of substitute-in-file-name}
2052 This function replaces environment variable references in
2053 @var{filename} with the environment variable values.  Following
2054 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2055 environment variable value.  If the input contains @samp{$$}, that is
2056 converted to @samp{$}; this gives the user a way to ``quote'' a
2057 @samp{$}.
2059 The environment variable name is the series of alphanumeric characters
2060 (including underscores) that follow the @samp{$}.  If the character following
2061 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2062 matching @samp{@}}.
2064 Calling @code{substitute-in-file-name} on output produced by
2065 @code{substitute-in-file-name} tends to give incorrect results.  For
2066 instance, use of @samp{$$} to quote a single @samp{$} won't work
2067 properly, and @samp{$} in an environment variable's value could lead
2068 to repeated substitution.  Therefore, programs that call this function
2069 and put the output where it will be passed to this function need to
2070 double all @samp{$} characters to prevent subsequent incorrect
2071 results.
2073 @c Wordy to avoid overfull hbox.  --rjc 15mar92
2074 Here we assume that the environment variable @code{HOME}, which holds
2075 the user's home directory name, has value @samp{/xcssun/users/rms}.
2077 @example
2078 @group
2079 (substitute-in-file-name "$HOME/foo")
2080      @result{} "/xcssun/users/rms/foo"
2081 @end group
2082 @end example
2084 After substitution, if a @samp{~} or a @samp{/} appears immediately
2085 after another @samp{/}, the function discards everything before it (up
2086 through the immediately preceding @samp{/}).
2088 @example
2089 @group
2090 (substitute-in-file-name "bar/~/foo")
2091      @result{} "~/foo"
2092 @end group
2093 @group
2094 (substitute-in-file-name "/usr/local/$HOME/foo")
2095      @result{} "/xcssun/users/rms/foo"
2096      ;; @r{@file{/usr/local/} has been discarded.}
2097 @end group
2098 @end example
2100 On VMS, @samp{$} substitution is not done, so this function does nothing
2101 on VMS except discard superfluous initial components as shown above.
2102 @end defun
2104 @node Unique File Names
2105 @subsection Generating Unique File Names
2107   Some programs need to write temporary files.  Here is the usual way to
2108 construct a name for such a file:
2110 @example
2111 (make-temp-file @var{name-of-application})
2112 @end example
2114 @noindent
2115 The job of @code{make-temp-file} is to prevent two different users or
2116 two different jobs from trying to use the exact same file name.
2118 @defun make-temp-file prefix &optional dir-flag suffix
2119 This function creates a temporary file and returns its name.  Emacs
2120 creates the temporary file's name by adding to @var{prefix} some
2121 random characters that are different in each Emacs job.  The result is
2122 guaranteed to be a newly created empty file.  On MS-DOS, this function
2123 can truncate the @var{string} prefix to fit into the 8+3 file-name
2124 limits.  If @var{prefix} is a relative file name, it is expanded
2125 against @code{temporary-file-directory}.
2127 @example
2128 @group
2129 (make-temp-file "foo")
2130      @result{} "/tmp/foo232J6v"
2131 @end group
2132 @end example
2134 When @code{make-temp-file} returns, the file has been created and is
2135 empty.  At that point, you should write the intended contents into the
2136 file.
2138 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2139 empty directory instead of an empty file.  It returns the file name,
2140 not the directory name, of that directory.  @xref{Directory Names}.
2142 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2143 the end of the file name.
2145 To prevent conflicts among different libraries running in the same
2146 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2147 own @var{prefix}.  The number added to the end of @var{prefix}
2148 distinguishes between the same application running in different Emacs
2149 jobs.  Additional added characters permit a large number of distinct
2150 names even in one Emacs job.
2151 @end defun
2153   The default directory for temporary files is controlled by the
2154 variable @code{temporary-file-directory}.  This variable gives the user
2155 a uniform way to specify the directory for all temporary files.  Some
2156 programs use @code{small-temporary-file-directory} instead, if that is
2157 non-@code{nil}.  To use it, you should expand the prefix against
2158 the proper directory before calling @code{make-temp-file}.
2160   In older Emacs versions where @code{make-temp-file} does not exist,
2161 you should use @code{make-temp-name} instead:
2163 @example
2164 (make-temp-name
2165  (expand-file-name @var{name-of-application}
2166                    temporary-file-directory))
2167 @end example
2169 @defun make-temp-name string
2170 This function generates a string that can be used as a unique file
2171 name.  The name starts with @var{string}, and has several random
2172 characters appended to it, which are different in each Emacs job.  It
2173 is like @code{make-temp-file} except that it just constructs a name,
2174 and does not create a file.  Another difference is that @var{string}
2175 should be an absolute file name.  On MS-DOS, this function can
2176 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
2177 @end defun
2179 @defvar temporary-file-directory
2180 @cindex @code{TMPDIR} environment variable
2181 @cindex @code{TMP} environment variable
2182 @cindex @code{TEMP} environment variable
2183 This variable specifies the directory name for creating temporary files.
2184 Its value should be a directory name (@pxref{Directory Names}), but it
2185 is good for Lisp programs to cope if the value is a directory's file
2186 name instead.  Using the value as the second argument to
2187 @code{expand-file-name} is a good way to achieve that.
2189 The default value is determined in a reasonable way for your operating
2190 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2191 environment variables, with a fall-back to a system-dependent name if
2192 none of these variables is defined.
2194 Even if you do not use @code{make-temp-file} to create the temporary
2195 file, you should still use this variable to decide which directory to
2196 put the file in.  However, if you expect the file to be small, you
2197 should use @code{small-temporary-file-directory} first if that is
2198 non-@code{nil}.
2199 @end defvar
2201 @defvar small-temporary-file-directory
2202 This variable specifies the directory name for
2203 creating certain temporary files, which are likely to be small.
2205 If you want to write a temporary file which is likely to be small, you
2206 should compute the directory like this:
2208 @example
2209 (make-temp-file
2210   (expand-file-name @var{prefix}
2211                     (or small-temporary-file-directory
2212                         temporary-file-directory)))
2213 @end example
2214 @end defvar
2216 @node File Name Completion
2217 @subsection File Name Completion
2218 @cindex file name completion subroutines
2219 @cindex completion, file name
2221   This section describes low-level subroutines for completing a file
2222 name.  For higher level functions, see @ref{Reading File Names}.
2224 @defun file-name-all-completions partial-filename directory
2225 This function returns a list of all possible completions for a file
2226 whose name starts with @var{partial-filename} in directory
2227 @var{directory}.  The order of the completions is the order of the files
2228 in the directory, which is unpredictable and conveys no useful
2229 information.
2231 The argument @var{partial-filename} must be a file name containing no
2232 directory part and no slash (or backslash on some systems).  The current
2233 buffer's default directory is prepended to @var{directory}, if
2234 @var{directory} is not absolute.
2236 In the following example, suppose that @file{~rms/lewis} is the current
2237 default directory, and has five files whose names begin with @samp{f}:
2238 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2239 @file{file.c.~2~}.@refill
2241 @example
2242 @group
2243 (file-name-all-completions "f" "")
2244      @result{} ("foo" "file~" "file.c.~2~"
2245                 "file.c.~1~" "file.c")
2246 @end group
2248 @group
2249 (file-name-all-completions "fo" "")
2250      @result{} ("foo")
2251 @end group
2252 @end example
2253 @end defun
2255 @defun file-name-completion filename directory &optional predicate
2256 This function completes the file name @var{filename} in directory
2257 @var{directory}.  It returns the longest prefix common to all file names
2258 in directory @var{directory} that start with @var{filename}.  If
2259 @var{predicate} is non-@code{nil} then it ignores possible completions
2260 that don't satisfy @var{predicate}, after calling that function
2261 with one argument, the expanded absolute file name.
2263 If only one match exists and @var{filename} matches it exactly, the
2264 function returns @code{t}.  The function returns @code{nil} if directory
2265 @var{directory} contains no name starting with @var{filename}.
2267 In the following example, suppose that the current default directory
2268 has five files whose names begin with @samp{f}: @file{foo},
2269 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2270 @file{file.c.~2~}.@refill
2272 @example
2273 @group
2274 (file-name-completion "fi" "")
2275      @result{} "file"
2276 @end group
2278 @group
2279 (file-name-completion "file.c.~1" "")
2280      @result{} "file.c.~1~"
2281 @end group
2283 @group
2284 (file-name-completion "file.c.~1~" "")
2285      @result{} t
2286 @end group
2288 @group
2289 (file-name-completion "file.c.~3" "")
2290      @result{} nil
2291 @end group
2292 @end example
2293 @end defun
2295 @defopt completion-ignored-extensions
2296 @code{file-name-completion} usually ignores file names that end in any
2297 string in this list.  It does not ignore them when all the possible
2298 completions end in one of these suffixes.  This variable has no effect
2299 on @code{file-name-all-completions}.@refill
2301 A typical value might look like this:
2303 @example
2304 @group
2305 completion-ignored-extensions
2306      @result{} (".o" ".elc" "~" ".dvi")
2307 @end group
2308 @end example
2310 If an element of @code{completion-ignored-extensions} ends in a slash
2311 @samp{/}, it signals a directory.  The elements which do @emph{not} end
2312 in a slash will never match a directory; thus, the above value will not
2313 filter out a directory named @file{foo.elc}.
2314 @end defopt
2316 @node Standard File Names
2317 @subsection Standard File Names
2319   Most of the file names used in Lisp programs are entered by the user.
2320 But occasionally a Lisp program needs to specify a standard file name
2321 for a particular use---typically, to hold customization information
2322 about each user.  For example, abbrev definitions are stored (by
2323 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2324 package stores completions in the file @file{~/.completions}.  These are
2325 two of the many standard file names used by parts of Emacs for certain
2326 purposes.
2328   Various operating systems have their own conventions for valid file
2329 names and for which file names to use for user profile data.  A Lisp
2330 program which reads a file using a standard file name ought to use, on
2331 each type of system, a file name suitable for that system.  The function
2332 @code{convert-standard-filename} makes this easy to do.
2334 @defun convert-standard-filename filename
2335 This function alters the file name @var{filename} to fit the conventions
2336 of the operating system in use, and returns the result as a new string.
2337 @end defun
2339   The recommended way to specify a standard file name in a Lisp program
2340 is to choose a name which fits the conventions of GNU and Unix systems,
2341 usually with a nondirectory part that starts with a period, and pass it
2342 to @code{convert-standard-filename} instead of using it directly.  Here
2343 is an example from the @code{completion} package:
2345 @example
2346 (defvar save-completions-file-name
2347         (convert-standard-filename "~/.completions")
2348   "*The file name to save completions to.")
2349 @end example
2351   On GNU and Unix systems, and on some other systems as well,
2352 @code{convert-standard-filename} returns its argument unchanged.  On
2353 some other systems, it alters the name to fit the system's conventions.
2355   For example, on MS-DOS the alterations made by this function include
2356 converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
2357 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2358 a @samp{.} after eight characters if there is none, and truncating to
2359 three characters after the @samp{.}.  (It makes other changes as well.)
2360 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2361 @file{.completions} becomes @file{_complet.ion}.
2363 @node Contents of Directories
2364 @section Contents of Directories
2365 @cindex directory-oriented functions
2366 @cindex file names in directory
2368   A directory is a kind of file that contains other files entered under
2369 various names.  Directories are a feature of the file system.
2371   Emacs can list the names of the files in a directory as a Lisp list,
2372 or display the names in a buffer using the @code{ls} shell command.  In
2373 the latter case, it can optionally display information about each file,
2374 depending on the options passed to the @code{ls} command.
2376 @defun directory-files directory &optional full-name match-regexp nosort
2377 This function returns a list of the names of the files in the directory
2378 @var{directory}.  By default, the list is in alphabetical order.
2380 If @var{full-name} is non-@code{nil}, the function returns the files'
2381 absolute file names.  Otherwise, it returns the names relative to
2382 the specified directory.
2384 If @var{match-regexp} is non-@code{nil}, this function returns only
2385 those file names that contain a match for that regular expression---the
2386 other file names are excluded from the list.  On case-insensitive
2387 filesystems, the regular expression matching is case-insensitive.
2389 @c Emacs 19 feature
2390 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2391 the list, so you get the file names in no particular order.  Use this if
2392 you want the utmost possible speed and don't care what order the files
2393 are processed in.  If the order of processing is visible to the user,
2394 then the user will probably be happier if you do sort the names.
2396 @example
2397 @group
2398 (directory-files "~lewis")
2399      @result{} ("#foo#" "#foo.el#" "." ".."
2400          "dired-mods.el" "files.texi"
2401          "files.texi.~1~")
2402 @end group
2403 @end example
2405 An error is signaled if @var{directory} is not the name of a directory
2406 that can be read.
2407 @end defun
2409 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2410 This is similar to @code{directory-files} in deciding which files
2411 to report on and how to report their names.  However, instead
2412 of returning a list of file names, it returns for each file a
2413 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2414 is what @code{file-attributes} would return for that file.
2415 The optional argument @var{id-format} has the same meaning as the
2416 corresponding argument to @code{file-attributes} (@pxref{Definition
2417 of file-attributes}).
2418 @end defun
2420 @defun file-name-all-versions file dirname
2421 This function returns a list of all versions of the file named
2422 @var{file} in directory @var{dirname}.  It is only available on VMS.
2423 @end defun
2425 @defun file-expand-wildcards pattern &optional full
2426 This function expands the wildcard pattern @var{pattern}, returning
2427 a list of file names that match it.
2429 If @var{pattern} is written as an absolute file name,
2430 the values are absolute also.
2432 If @var{pattern} is written as a relative file name, it is interpreted
2433 relative to the current default directory.  The file names returned are
2434 normally also relative to the current default directory.  However, if
2435 @var{full} is non-@code{nil}, they are absolute.
2436 @end defun
2438 @defun insert-directory file switches &optional wildcard full-directory-p
2439 This function inserts (in the current buffer) a directory listing for
2440 directory @var{file}, formatted with @code{ls} according to
2441 @var{switches}.  It leaves point after the inserted text.
2442 @var{switches} may be a string of options, or a list of strings
2443 representing individual options.
2445 The argument @var{file} may be either a directory name or a file
2446 specification including wildcard characters.  If @var{wildcard} is
2447 non-@code{nil}, that means treat @var{file} as a file specification with
2448 wildcards.
2450 If @var{full-directory-p} is non-@code{nil}, that means the directory
2451 listing is expected to show the full contents of a directory.  You
2452 should specify @code{t} when @var{file} is a directory and switches do
2453 not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
2454 describe a directory itself as a file, rather than showing its
2455 contents.)
2457 On most systems, this function works by running a directory listing
2458 program whose name is in the variable @code{insert-directory-program}.
2459 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2460 @code{shell-file-name}, to expand the wildcards.
2462 MS-DOS and MS-Windows systems usually lack the standard Unix program
2463 @code{ls}, so this function emulates the standard Unix program @code{ls}
2464 with Lisp code.
2466 As a technical detail, when @var{switches} contains the long
2467 @samp{--dired} option, @code{insert-directory} treats it specially,
2468 for the sake of dired.  However, the normally equivalent short
2469 @samp{-D} option is just passed on to @code{insert-directory-program},
2470 as any other option.
2471 @end defun
2473 @defvar insert-directory-program
2474 This variable's value is the program to run to generate a directory listing
2475 for the function @code{insert-directory}.  It is ignored on systems
2476 which generate the listing with Lisp code.
2477 @end defvar
2479 @node Create/Delete Dirs
2480 @section Creating and Deleting Directories
2481 @cindex creating and deleting directories
2482 @c Emacs 19 features
2484   Most Emacs Lisp file-manipulation functions get errors when used on
2485 files that are directories.  For example, you cannot delete a directory
2486 with @code{delete-file}.  These special functions exist to create and
2487 delete directories.
2489 @defun make-directory dirname &optional parents
2490 This function creates a directory named @var{dirname}.
2491 If @var{parents} is non-@code{nil}, as is always the case in an
2492 interactive call, that means to create the parent directories first,
2493 if they don't already exist.
2494 @end defun
2496 @defun delete-directory dirname
2497 This function deletes the directory named @var{dirname}.  The function
2498 @code{delete-file} does not work for files that are directories; you
2499 must use @code{delete-directory} for them.  If the directory contains
2500 any files, @code{delete-directory} signals an error.
2502 This function only follows symbolic links at the level of parent
2503 directories.
2504 @end defun
2506 @node Magic File Names
2507 @section Making Certain File Names ``Magic''
2508 @cindex magic file names
2510 @c Emacs 19 feature
2511   You can implement special handling for certain file names.  This is
2512 called making those names @dfn{magic}.  The principal use for this
2513 feature is in implementing remote file names (@pxref{Remote Files,,
2514 Remote Files, emacs, The GNU Emacs Manual}).
2516   To define a kind of magic file name, you must supply a regular
2517 expression to define the class of names (all those that match the
2518 regular expression), plus a handler that implements all the primitive
2519 Emacs file operations for file names that do match.
2521   The variable @code{file-name-handler-alist} holds a list of handlers,
2522 together with regular expressions that determine when to apply each
2523 handler.  Each element has this form:
2525 @example
2526 (@var{regexp} . @var{handler})
2527 @end example
2529 @noindent
2530 All the Emacs primitives for file access and file name transformation
2531 check the given file name against @code{file-name-handler-alist}.  If
2532 the file name matches @var{regexp}, the primitives handle that file by
2533 calling @var{handler}.
2535   The first argument given to @var{handler} is the name of the
2536 primitive, as a symbol; the remaining arguments are the arguments that
2537 were passed to that primitive.  (The first of these arguments is most
2538 often the file name itself.)  For example, if you do this:
2540 @example
2541 (file-exists-p @var{filename})
2542 @end example
2544 @noindent
2545 and @var{filename} has handler @var{handler}, then @var{handler} is
2546 called like this:
2548 @example
2549 (funcall @var{handler} 'file-exists-p @var{filename})
2550 @end example
2552   When a function takes two or more arguments that must be file names,
2553 it checks each of those names for a handler.  For example, if you do
2554 this:
2556 @example
2557 (expand-file-name @var{filename} @var{dirname})
2558 @end example
2560 @noindent
2561 then it checks for a handler for @var{filename} and then for a handler
2562 for @var{dirname}.  In either case, the @var{handler} is called like
2563 this:
2565 @example
2566 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2567 @end example
2569 @noindent
2570 The @var{handler} then needs to figure out whether to handle
2571 @var{filename} or @var{dirname}.
2573   If the specified file name matches more than one handler, the one
2574 whose match starts last in the file name gets precedence.  This rule
2575 is chosen so that handlers for jobs such as uncompression are handled
2576 first, before handlers for jobs such as remote file access.
2578   Here are the operations that a magic file name handler gets to handle:
2580 @ifnottex
2581 @noindent
2582 @code{access-file}, @code{add-name-to-file},
2583 @code{byte-compiler-base-file-name},@*
2584 @code{copy-file}, @code{delete-directory},
2585 @code{delete-file},
2586 @code{diff-latest-backup-file},
2587 @code{directory-file-name},
2588 @code{directory-files},
2589 @code{directory-files-and-attributes},
2590 @code{dired-call-process},
2591 @code{dired-compress-file}, @code{dired-uncache},@*
2592 @code{expand-file-name},
2593 @code{file-accessible-directory-p},
2594 @code{file-attributes},
2595 @code{file-directory-p},
2596 @code{file-executable-p}, @code{file-exists-p},
2597 @code{file-local-copy}, @code{file-remote-p},
2598 @code{file-modes}, @code{file-name-all-completions},
2599 @code{file-name-as-directory},
2600 @code{file-name-completion},
2601 @code{file-name-directory},
2602 @code{file-name-nondirectory},
2603 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2604 @code{file-ownership-preserved-p},
2605 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2606 @code{file-truename}, @code{file-writable-p},
2607 @code{find-backup-file-name},
2608 @code{find-file-noselect},@*
2609 @code{get-file-buffer},
2610 @code{insert-directory},
2611 @code{insert-file-contents},@*
2612 @code{load},
2613 @code{make-auto-save-file-name},
2614 @code{make-directory},
2615 @code{make-directory-internal},
2616 @code{make-symbolic-link},@*
2617 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2618 @code{set-visited-file-modtime}, @code{shell-command},
2619 @code{substitute-in-file-name},@*
2620 @code{unhandled-file-name-directory},
2621 @code{vc-registered},
2622 @code{verify-visited-file-modtime},@*
2623 @code{write-region}.
2624 @end ifnottex
2625 @iftex
2626 @noindent
2627 @flushleft
2628 @code{access-file}, @code{add-name-to-file},
2629 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2630 @code{copy-file}, @code{delete-directory},
2631 @code{delete-file},
2632 @code{diff-latest-backup-file},
2633 @code{directory-file-name},
2634 @code{directory-files},
2635 @code{directory-files-and-at@discretionary{}{}{}tributes},
2636 @code{dired-call-process},
2637 @code{dired-compress-file}, @code{dired-uncache},
2638 @code{expand-file-name},
2639 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2640 @code{file-attributes},
2641 @code{file-direct@discretionary{}{}{}ory-p},
2642 @code{file-executable-p}, @code{file-exists-p},
2643 @code{file-local-copy}, @code{file-remote-p},
2644 @code{file-modes}, @code{file-name-all-completions},
2645 @code{file-name-as-directory},
2646 @code{file-name-completion},
2647 @code{file-name-directory},
2648 @code{file-name-nondirec@discretionary{}{}{}tory},
2649 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2650 @code{file-ownership-pre@discretionary{}{}{}served-p},
2651 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2652 @code{file-truename}, @code{file-writable-p},
2653 @code{find-backup-file-name},
2654 @code{find-file-noselect},
2655 @code{get-file-buffer},
2656 @code{insert-directory},
2657 @code{insert-file-contents},
2658 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2659 @code{make-direc@discretionary{}{}{}tory-internal},
2660 @code{make-symbolic-link},
2661 @code{rename-file}, @code{set-file-modes},
2662 @code{set-visited-file-modtime}, @code{shell-command},
2663 @code{substitute-in-file-name},
2664 @code{unhandled-file-name-directory},
2665 @code{vc-regis@discretionary{}{}{}tered},
2666 @code{verify-visited-file-modtime},
2667 @code{write-region}.
2668 @end flushleft
2669 @end iftex
2671   Handlers for @code{insert-file-contents} typically need to clear the
2672 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2673 @var{visit} argument is non-@code{nil}.  This also has the effect of
2674 unlocking the buffer if it is locked.
2676   The handler function must handle all of the above operations, and
2677 possibly others to be added in the future.  It need not implement all
2678 these operations itself---when it has nothing special to do for a
2679 certain operation, it can reinvoke the primitive, to handle the
2680 operation ``in the usual way.''  It should always reinvoke the primitive
2681 for an operation it does not recognize.  Here's one way to do this:
2683 @smallexample
2684 (defun my-file-handler (operation &rest args)
2685   ;; @r{First check for the specific operations}
2686   ;; @r{that we have special handling for.}
2687   (cond ((eq operation 'insert-file-contents) @dots{})
2688         ((eq operation 'write-region) @dots{})
2689         @dots{}
2690         ;; @r{Handle any operation we don't know about.}
2691         (t (let ((inhibit-file-name-handlers
2692                   (cons 'my-file-handler
2693                         (and (eq inhibit-file-name-operation operation)
2694                              inhibit-file-name-handlers)))
2695                  (inhibit-file-name-operation operation))
2696              (apply operation args)))))
2697 @end smallexample
2699   When a handler function decides to call the ordinary Emacs primitive for
2700 the operation at hand, it needs to prevent the primitive from calling
2701 the same handler once again, thus leading to an infinite recursion.  The
2702 example above shows how to do this, with the variables
2703 @code{inhibit-file-name-handlers} and
2704 @code{inhibit-file-name-operation}.  Be careful to use them exactly as
2705 shown above; the details are crucial for proper behavior in the case of
2706 multiple handlers, and for operations that have two file names that may
2707 each have handlers.
2709 @kindex safe-magic (@r{property})
2710   Handlers that don't really do anything special for actual access to the
2711 file---such as the ones that implement completion of host names for
2712 remote file names---should have a non-@code{nil} @code{safe-magic}
2713 property.  For instance, Emacs normally ``protects'' directory names
2714 it finds in @code{PATH} from becoming magic, if they look like magic
2715 file names, by prefixing them with @samp{/:}.  But if the handler that
2716 would be used for them has a non-@code{nil} @code{safe-magic}
2717 property, the @samp{/:} is not added.
2719 @kindex operations (@r{property})
2720   A file name handler can have an @code{operations} property to
2721 declare which operations it handles in a nontrivial way.  If this
2722 property has a non-@code{nil} value, it should be a list of
2723 operations; then only those operations will call the handler.  This
2724 avoids inefficiency, but its main purpose is for autoloaded handler
2725 functions, so that they won't be loaded except when they have real
2726 work to do.
2728   Simply deferring all operations to the usual primitives does not
2729 work.  For instance, if the file name handler applies to
2730 @code{file-exists-p}, then it must handle @code{load} itself, because
2731 the usual @code{load} code won't work properly in that case.  However,
2732 if the handler uses the @code{operations} property to say it doesn't
2733 handle @code{file-exists-p}, then it need not handle @code{load}
2734 nontrivially.
2736 @defvar inhibit-file-name-handlers
2737 This variable holds a list of handlers whose use is presently inhibited
2738 for a certain operation.
2739 @end defvar
2741 @defvar inhibit-file-name-operation
2742 The operation for which certain handlers are presently inhibited.
2743 @end defvar
2745 @defun find-file-name-handler file operation
2746 This function returns the handler function for file name @var{file},
2747 or @code{nil} if there is none.  The argument @var{operation} should
2748 be the operation to be performed on the file---the value you will pass
2749 to the handler as its first argument when you call it.  If
2750 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2751 not found in the @code{operations} property of the handler, this
2752 function returns @code{nil}.
2753 @end defun
2755 @defun file-local-copy filename
2756 This function copies file @var{filename} to an ordinary non-magic file
2757 on the local machine, if it isn't on the local machine already.  Magic
2758 file names should handle the @code{file-local-copy} operation if they
2759 refer to files on other machines.  A magic file name that is used for
2760 other purposes than remote file access should not handle
2761 @code{file-local-copy}; then this function will treat the file as
2762 local.
2764 If @var{filename} is local, whether magic or not, this function does
2765 nothing and returns @code{nil}.  Otherwise it returns the file name
2766 of the local copy file.
2767 @end defun
2769 @defun file-remote-p filename
2770 This function tests whether @var{filename} is a remote file.  If
2771 @var{filename} is local (not remote), the return value is @code{nil}.
2772 If @var{filename} is indeed remote, the return value is a string that
2773 identifies the remote system.
2775 This identifier string can include a host name and a user name, as
2776 well as characters designating the method used to access the remote
2777 system.  For example, the remote identifier string for the filename
2778 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
2780 If @code{file-remote-p} returns the same identifier for two different
2781 filenames, that means they are stored on the same file system and can
2782 be accessed locally with respect to each other.  This means, for
2783 example, that it is possible to start a remote process accessing both
2784 files at the same time.  Implementors of file handlers need to ensure
2785 this principle is valid.
2786 @end defun
2788 @defun unhandled-file-name-directory filename
2789 This function returns the name of a directory that is not magic.  It
2790 uses the directory part of @var{filename} if that is not magic.  For a
2791 magic file name, it invokes the file name handler, which therefore
2792 decides what value to return.
2794 This is useful for running a subprocess; every subprocess must have a
2795 non-magic directory to serve as its current directory, and this function
2796 is a good way to come up with one.
2797 @end defun
2799 @node Format Conversion
2800 @section File Format Conversion
2802 @cindex file format conversion
2803 @cindex encoding file formats
2804 @cindex decoding file formats
2805   The variable @code{format-alist} defines a list of @dfn{file formats},
2806 which describe textual representations used in files for the data (text,
2807 text-properties, and possibly other information) in an Emacs buffer.
2808 Emacs performs format conversion if appropriate when reading and writing
2809 files.
2811 @defvar format-alist
2812 This list contains one format definition for each defined file format.
2813 @end defvar
2815 @cindex format definition
2816 Each format definition is a list of this form:
2818 @example
2819 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2820 @end example
2822 Here is what the elements in a format definition mean:
2824 @table @var
2825 @item name
2826 The name of this format.
2828 @item doc-string
2829 A documentation string for the format.
2831 @item regexp
2832 A regular expression which is used to recognize files represented in
2833 this format.
2835 @item from-fn
2836 A shell command or function to decode data in this format (to convert
2837 file data into the usual Emacs data representation).
2839 A shell command is represented as a string; Emacs runs the command as a
2840 filter to perform the conversion.
2842 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2843 and @var{end}, which specify the part of the buffer it should convert.
2844 It should convert the text by editing it in place.  Since this can
2845 change the length of the text, @var{from-fn} should return the modified
2846 end position.
2848 One responsibility of @var{from-fn} is to make sure that the beginning
2849 of the file no longer matches @var{regexp}.  Otherwise it is likely to
2850 get called again.
2852 @item to-fn
2853 A shell command or function to encode data in this format---that is, to
2854 convert the usual Emacs data representation into this format.
2856 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2857 command as a filter to perform the conversion.
2859 If @var{to-fn} is a function, it is called with three arguments:
2860 @var{begin} and @var{end}, which specify the part of the buffer it
2861 should convert, and @var{buffer}, which specifies which buffer.  There
2862 are two ways it can do the conversion:
2864 @itemize @bullet
2865 @item
2866 By editing the buffer in place.  In this case, @var{to-fn} should
2867 return the end-position of the range of text, as modified.
2869 @item
2870 By returning a list of annotations.  This is a list of elements of the
2871 form @code{(@var{position} . @var{string})}, where @var{position} is an
2872 integer specifying the relative position in the text to be written, and
2873 @var{string} is the annotation to add there.  The list must be sorted in
2874 order of position when @var{to-fn} returns it.
2876 When @code{write-region} actually writes the text from the buffer to the
2877 file, it intermixes the specified annotations at the corresponding
2878 positions.  All this takes place without modifying the buffer.
2879 @end itemize
2881 @item modify
2882 A flag, @code{t} if the encoding function modifies the buffer, and
2883 @code{nil} if it works by returning a list of annotations.
2885 @item mode-fn
2886 A minor-mode function to call after visiting a file converted from this
2887 format.  The function is called with one argument, the integer 1;
2888 that tells a minor-mode function to enable the mode.
2889 @end table
2891 The function @code{insert-file-contents} automatically recognizes file
2892 formats when it reads the specified file.  It checks the text of the
2893 beginning of the file against the regular expressions of the format
2894 definitions, and if it finds a match, it calls the decoding function for
2895 that format.  Then it checks all the known formats over again.
2896 It keeps checking them until none of them is applicable.
2898 Visiting a file, with @code{find-file-noselect} or the commands that use
2899 it, performs conversion likewise (because it calls
2900 @code{insert-file-contents}); it also calls the mode function for each
2901 format that it decodes.  It stores a list of the format names in the
2902 buffer-local variable @code{buffer-file-format}.
2904 @defvar buffer-file-format
2905 This variable states the format of the visited file.  More precisely,
2906 this is a list of the file format names that were decoded in the course
2907 of visiting the current buffer's file.  It is always buffer-local in all
2908 buffers.
2909 @end defvar
2911 When @code{write-region} writes data into a file, it first calls the
2912 encoding functions for the formats listed in @code{buffer-file-format},
2913 in the order of appearance in the list.
2915 @deffn Command format-write-file file format &optional confirm
2916 This command writes the current buffer contents into the file
2917 @var{file} in format @var{format}, and makes that format the default
2918 for future saves of the buffer.  The argument @var{format} is a list
2919 of format names.  Except for the @var{format} argument, this command
2920 is similar to @code{write-file}.  In particular, @var{confirm} has the
2921 same meaning and interactive treatment as the corresponding argument
2922 to @code{write-file}.  @xref{Definition of write-file}.
2923 @end deffn
2925 @deffn Command format-find-file file format
2926 This command finds the file @var{file}, converting it according to
2927 format @var{format}.  It also makes @var{format} the default if the
2928 buffer is saved later.
2930 The argument @var{format} is a list of format names.  If @var{format} is
2931 @code{nil}, no conversion takes place.  Interactively, typing just
2932 @key{RET} for @var{format} specifies @code{nil}.
2933 @end deffn
2935 @deffn Command format-insert-file file format &optional beg end
2936 This command inserts the contents of file @var{file}, converting it
2937 according to format @var{format}.  If @var{beg} and @var{end} are
2938 non-@code{nil}, they specify which part of the file to read, as in
2939 @code{insert-file-contents} (@pxref{Reading from Files}).
2941 The return value is like what @code{insert-file-contents} returns: a
2942 list of the absolute file name and the length of the data inserted
2943 (after conversion).
2945 The argument @var{format} is a list of format names.  If @var{format} is
2946 @code{nil}, no conversion takes place.  Interactively, typing just
2947 @key{RET} for @var{format} specifies @code{nil}.
2948 @end deffn
2950 @defvar buffer-auto-save-file-format
2951 This variable specifies the format to use for auto-saving.  Its value is
2952 a list of format names, just like the value of
2953 @code{buffer-file-format}; however, it is used instead of
2954 @code{buffer-file-format} for writing auto-save files.  If the value
2955 is @code{t}, the default, auto-saving uses the same format as a
2956 regular save in the same buffer.  This variable is always buffer-local
2957 in all buffers.
2958 @end defvar
2960 @ignore
2961    arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
2962 @end ignore