*** empty log message ***
[emacs.git] / lispref / files.texi
blob02c863421f97f8e4a064fc84a558dfec90c4ef1a
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
4 @c   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 The body of the @code{find-file} function is very simple and looks
99 like this:
101 @example
102 (switch-to-buffer (find-file-noselect filename))
103 @end example
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 finds
118 or creates a buffer visiting the file @var{filename}, and returns it.
119 It uses an existing buffer if there is one, and otherwise creates a new
120 buffer and reads the file into it.  You may make the buffer current or
121 display it in a window if you wish, but this function does not do so.
123 If @var{wildcards} is non-@code{nil},
124 then @code{find-file-noselect} expands wildcard
125 characters in @var{filename} and visits all the matching files.
127 When @code{find-file-noselect} uses an existing buffer, it first
128 verifies that the file has not changed since it was last visited or
129 saved in that buffer.  If the file has changed, then this function asks
130 the user whether to reread the changed file.  If the user says
131 @samp{yes}, any changes previously made in the buffer are lost.
133 This function displays warning or advisory messages in various peculiar
134 cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
135 example, if it needs to create a buffer, and there is no file named
136 @var{filename}, it displays the message @samp{(New file)} in the echo
137 area, and leaves the buffer empty.
139 The @code{find-file-noselect} function normally calls
140 @code{after-find-file} after reading the file (@pxref{Subroutines of
141 Visiting}).  That function sets the buffer major mode, parses local
142 variables, warns the user if there exists an auto-save file more recent
143 than the file just visited, and finishes by running the functions in
144 @code{find-file-hooks}.
146 If the optional argument @var{rawfile} is non-@code{nil}, then
147 @code{after-find-file} is not called, and the
148 @code{find-file-not-found-hooks} are not run in case of failure.  What's
149 more, a non-@code{nil} @var{rawfile} value suppresses coding system
150 conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
151 Conversion}).
153 The @code{find-file-noselect} function returns the buffer that is
154 visiting the file @var{filename}.
156 @example
157 @group
158 (find-file-noselect "/etc/fstab")
159      @result{} #<buffer fstab>
160 @end group
161 @end example
162 @end defun
164 @deffn Command find-file-other-window filename &optional wildcards
165 This command selects a buffer visiting the file @var{filename}, but
166 does so in a window other than the selected window.  It may use another
167 existing window or split a window; see @ref{Displaying Buffers}.
169 When this command is called interactively, it prompts for
170 @var{filename}.
171 @end deffn
173 @deffn Command find-file-read-only filename &optional wildcards
174 This command selects a buffer visiting the file @var{filename}, like
175 @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
176 Buffers}, for related functions and variables.
178 When this command is called interactively, it prompts for
179 @var{filename}.
180 @end deffn
182 @deffn Command view-file filename
183 This command visits @var{filename} using View mode, returning to the
184 previous buffer when you exit View mode.  View mode is a minor mode that
185 provides commands to skim rapidly through the file, but does not let you
186 modify the text.  Entering View mode runs the normal hook
187 @code{view-mode-hook}.  @xref{Hooks}.
189 When @code{view-file} is called interactively, it prompts for
190 @var{filename}.
191 @end deffn
193 @tindex find-file-wildcards
194 @defvar find-file-wildcards
195 If this variable is non-@code{nil}, then the various @code{find-file}
196 commands check for wildcard characters and visit all the files that
197 match them.  If this is @code{nil}, then wildcard characters are
198 not treated specially.
199 @end defvar
201 @defvar find-file-hooks
202 The value of this variable is a list of functions to be called after a
203 file is visited.  The file's local-variables specification (if any) will
204 have been processed before the hooks are run.  The buffer visiting the
205 file is current when the hook functions are run.
207 This variable works just like a normal hook, but we think that renaming
208 it would not be advisable.  @xref{Hooks}.
209 @end defvar
211 @defvar find-file-not-found-hooks
212 The value of this variable is a list of functions to be called when
213 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
214 file name.  @code{find-file-noselect} calls these functions as soon as
215 it detects a nonexistent file.  It calls them in the order of the list,
216 until one of them returns non-@code{nil}.  @code{buffer-file-name} is
217 already set up.
219 This is not a normal hook because the values of the functions are
220 used, and in many cases only some of the functions are called.
221 @end defvar
223 @node Subroutines of Visiting
224 @comment  node-name,  next,  previous,  up
225 @subsection Subroutines of Visiting
227   The @code{find-file-noselect} function uses two important subroutines
228 which are sometimes useful in user Lisp code: @code{create-file-buffer}
229 and @code{after-find-file}.  This section explains how to use them.
231 @defun create-file-buffer filename
232 This function creates a suitably named buffer for visiting
233 @var{filename}, and returns it.  It uses @var{filename} (sans directory)
234 as the name if that name is free; otherwise, it appends a string such as
235 @samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
237 @strong{Please note:} @code{create-file-buffer} does @emph{not}
238 associate the new buffer with a file and does not select the buffer.
239 It also does not use the default major mode.
241 @example
242 @group
243 (create-file-buffer "foo")
244      @result{} #<buffer foo>
245 @end group
246 @group
247 (create-file-buffer "foo")
248      @result{} #<buffer foo<2>>
249 @end group
250 @group
251 (create-file-buffer "foo")
252      @result{} #<buffer foo<3>>
253 @end group
254 @end example
256 This function is used by @code{find-file-noselect}.
257 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
258 @end defun
260 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
261 This function sets the buffer major mode, and parses local variables
262 (@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
263 and by the default revert function (@pxref{Reverting}).
265 @cindex new file message
266 @cindex file open error
267 If reading the file got an error because the file does not exist, but
268 its directory does exist, the caller should pass a non-@code{nil} value
269 for @var{error}.  In that case, @code{after-find-file} issues a warning:
270 @samp{(New file)}.  For more serious errors, the caller should usually not
271 call @code{after-find-file}.
273 If @var{warn} is non-@code{nil}, then this function issues a warning
274 if an auto-save file exists and is more recent than the visited file.
276 If @var{noauto} is non-@code{nil}, that says not to enable or disable
277 Auto-Save mode.  The mode remains enabled if it was enabled before.
279 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
280 means this call was from @code{revert-buffer}.  This has no direct
281 effect, but some mode functions and hook functions check the value
282 of this variable.
284 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
285 major mode, don't process local variables specifications in the file,
286 and don't run @code{find-file-hooks}.  This feature is used by
287 @code{revert-buffer} in some cases.
289 The last thing @code{after-find-file} does is call all the functions
290 in the list @code{find-file-hooks}.
291 @end defun
293 @node Saving Buffers
294 @section Saving Buffers
296   When you edit a file in Emacs, you are actually working on a buffer
297 that is visiting that file---that is, the contents of the file are
298 copied into the buffer and the copy is what you edit.  Changes to the
299 buffer do not change the file until you @dfn{save} the buffer, which
300 means copying the contents of the buffer into the file.
302 @deffn Command save-buffer &optional backup-option
303 This function saves the contents of the current buffer in its visited
304 file if the buffer has been modified since it was last visited or saved.
305 Otherwise it does nothing.
307 @code{save-buffer} is responsible for making backup files.  Normally,
308 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
309 file only if this is the first save since visiting the file.  Other
310 values for @var{backup-option} request the making of backup files in
311 other circumstances:
313 @itemize @bullet
314 @item
315 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
316 @code{save-buffer} function marks this version of the file to be
317 backed up when the buffer is next saved.
319 @item
320 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
321 @code{save-buffer} function unconditionally backs up the previous
322 version of the file before saving it.
323 @end itemize
324 @end deffn
326 @deffn Command save-some-buffers &optional save-silently-p pred
327 This command saves some modified file-visiting buffers.  Normally it
328 asks the user about each buffer.  But if @var{save-silently-p} is
329 non-@code{nil}, it saves all the file-visiting buffers without querying
330 the user.
332 The optional @var{pred} argument controls which buffers to ask about.
333 If it is @code{nil}, that means to ask only about file-visiting buffers.
334 If it is @code{t}, that means also offer to save certain other non-file
335 buffers---those that have a non-@code{nil} buffer-local value of
336 @code{buffer-offer-save}.  (A user who says @samp{yes} to saving a
337 non-file buffer is asked to specify the file name to use.)  The
338 @code{save-buffers-kill-emacs} function passes the value @code{t} for
339 @var{pred}.
341 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
342 a function of no arguments.  It will be called in each buffer to decide
343 whether to offer to save that buffer.  If it returns a non-@code{nil}
344 value in a certain buffer, that means do offer to save that buffer.
345 @end deffn
347 @deffn Command write-file filename &optional confirm
348 This function writes the current buffer into file @var{filename}, makes
349 the buffer visit that file, and marks it not modified.  Then it renames
350 the buffer based on @var{filename}, appending a string like @samp{<2>}
351 if necessary to make a unique buffer name.  It does most of this work by
352 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
353 @code{save-buffer}.
355 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
356 before overwriting an existing file.
357 @end deffn
359   Saving a buffer runs several hooks.  It also performs format
360 conversion (@pxref{Format Conversion}), and may save text properties in
361 ``annotations'' (@pxref{Saving Properties}).
363 @defvar write-file-hooks
364 The value of this variable is a list of functions to be called before
365 writing out a buffer to its visited file.  If one of them returns
366 non-@code{nil}, the file is considered already written and the rest of
367 the functions are not called, nor is the usual code for writing the file
368 executed.
370 If a function in @code{write-file-hooks} returns non-@code{nil}, it
371 is responsible for making a backup file (if that is appropriate).
372 To do so, execute the following code:
374 @example
375 (or buffer-backed-up (backup-buffer))
376 @end example
378 You might wish to save the file modes value returned by
379 @code{backup-buffer} and use that to set the mode bits of the file that
380 you write.  This is what @code{save-buffer} normally does.
382 The hook functions in @code{write-file-hooks} are also responsible for
383 encoding the data (if desired): they must choose a suitable coding
384 system (@pxref{Lisp and Coding Systems}), perform the encoding
385 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
386 the coding system that was used (@pxref{Encoding and I/O}).
388 Do not make this variable buffer-local.  To set up buffer-specific hook
389 functions, use @code{write-contents-hooks} instead.
391 Even though this is not a normal hook, you can use @code{add-hook} and
392 @code{remove-hook} to manipulate the list.  @xref{Hooks}.
393 @end defvar
395 @c Emacs 19 feature
396 @defvar local-write-file-hooks
397 This works just like @code{write-file-hooks}, but it is intended to be
398 made buffer-local in particular buffers, and used for hooks that pertain
399 to the file name or the way the buffer contents were obtained.
401 The variable is marked as a permanent local, so that changing the major
402 mode does not alter a buffer-local value.  This is convenient for
403 packages that read ``file'' contents in special ways, and set up hooks
404 to save the data in a corresponding way.
405 @end defvar
407 @c Emacs 19 feature
408 @defvar write-contents-hooks
409 This works just like @code{write-file-hooks}, but it is intended for
410 hooks that pertain to the contents of the file, as opposed to hooks that
411 pertain to where the file came from.  Such hooks are usually set up by
412 major modes, as buffer-local bindings for this variable.
414 This variable automatically becomes buffer-local whenever it is set;
415 switching to a new major mode always resets this variable.  When you use
416 @code{add-hooks} to add an element to this hook, you should @emph{not}
417 specify a non-@code{nil} @var{local} argument, since this variable is
418 used @emph{only} buffer-locally.
419 @end defvar
421 @c Emacs 19 feature
422 @defvar after-save-hook
423 This normal hook runs after a buffer has been saved in its visited file.
424 One use of this hook is in Fast Lock mode; it uses this hook to save the
425 highlighting information in a cache file.
426 @end defvar
428 @defvar file-precious-flag
429 If this variable is non-@code{nil}, then @code{save-buffer} protects
430 against I/O errors while saving by writing the new file to a temporary
431 name instead of the name it is supposed to have, and then renaming it to
432 the intended name after it is clear there are no errors.  This procedure
433 prevents problems such as a lack of disk space from resulting in an
434 invalid file.
436 As a side effect, backups are necessarily made by copying.  @xref{Rename
437 or Copy}.  Yet, at the same time, saving a precious file always breaks
438 all hard links between the file you save and other file names.
440 Some modes give this variable a non-@code{nil} buffer-local value
441 in particular buffers.
442 @end defvar
444 @defopt require-final-newline
445 This variable determines whether files may be written out that do
446 @emph{not} end with a newline.  If the value of the variable is
447 @code{t}, then @code{save-buffer} silently adds a newline at the end of
448 the file whenever the buffer being saved does not already end in one.
449 If the value of the variable is non-@code{nil}, but not @code{t}, then
450 @code{save-buffer} asks the user whether to add a newline each time the
451 case arises.
453 If the value of the variable is @code{nil}, then @code{save-buffer}
454 doesn't add newlines at all.  @code{nil} is the default value, but a few
455 major modes set it to @code{t} in particular buffers.
456 @end defopt
458   See also the function @code{set-visited-file-name} (@pxref{Buffer File
459 Name}).
461 @node Reading from Files
462 @comment  node-name,  next,  previous,  up
463 @section Reading from Files
465   You can copy a file from the disk and insert it into a buffer
466 using the @code{insert-file-contents} function.  Don't use the user-level
467 command @code{insert-file} in a Lisp program, as that sets the mark.
469 @defun insert-file-contents filename &optional visit beg end replace
470 This function inserts the contents of file @var{filename} into the
471 current buffer after point.  It returns a list of the absolute file name
472 and the length of the data inserted.  An error is signaled if
473 @var{filename} is not the name of a file that can be read.
475 The function @code{insert-file-contents} checks the file contents
476 against the defined file formats, and converts the file contents if
477 appropriate.  @xref{Format Conversion}.  It also calls the functions in
478 the list @code{after-insert-file-functions}; see @ref{Saving
479 Properties}.  Normally, one of the functions in the
480 @code{after-insert-file-functions} list determines the coding system
481 (@pxref{Coding Systems}) used for decoding the file's contents.
483 If @var{visit} is non-@code{nil}, this function additionally marks the
484 buffer as unmodified and sets up various fields in the buffer so that it
485 is visiting the file @var{filename}: these include the buffer's visited
486 file name and its last save file modtime.  This feature is used by
487 @code{find-file-noselect} and you probably should not use it yourself.
489 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
490 specifying the portion of the file to insert.  In this case, @var{visit}
491 must be @code{nil}.  For example,
493 @example
494 (insert-file-contents filename nil 0 500)
495 @end example
497 @noindent
498 inserts the first 500 characters of a file.
500 If the argument @var{replace} is non-@code{nil}, it means to replace the
501 contents of the buffer (actually, just the accessible portion) with the
502 contents of the file.  This is better than simply deleting the buffer
503 contents and inserting the whole file, because (1) it preserves some
504 marker positions and (2) it puts less data in the undo list.
506 It is possible to read a special file (such as a FIFO or an I/O device)
507 with @code{insert-file-contents}, as long as @var{replace} and
508 @var{visit} are @code{nil}.
509 @end defun
511 @defun insert-file-contents-literally filename &optional visit beg end replace
512 This function works like @code{insert-file-contents} except that it does
513 not do format decoding (@pxref{Format Conversion}), does not do
514 character code conversion (@pxref{Coding Systems}), does not run
515 @code{find-file-hooks}, does not perform automatic uncompression, and so
517 @end defun
519 If you want to pass a file name to another process so that another
520 program can read the file, use the function @code{file-local-copy}; see
521 @ref{Magic File Names}.
523 @node Writing to Files
524 @comment  node-name,  next,  previous,  up
525 @section Writing to Files
527   You can write the contents of a buffer, or part of a buffer, directly
528 to a file on disk using the @code{append-to-file} and
529 @code{write-region} functions.  Don't use these functions to write to
530 files that are being visited; that could cause confusion in the
531 mechanisms for visiting.
533 @deffn Command append-to-file start end filename
534 This function appends the contents of the region delimited by
535 @var{start} and @var{end} in the current buffer to the end of file
536 @var{filename}.  If that file does not exist, it is created.  This
537 function returns @code{nil}.
539 An error is signaled if @var{filename} specifies a nonwritable file,
540 or a nonexistent file in a directory where files cannot be created.
541 @end deffn
543 @deffn Command write-region start end filename &optional append visit lockname mustbenew
544 This function writes the region delimited by @var{start} and @var{end}
545 in the current buffer into the file specified by @var{filename}.
547 @c Emacs 19 feature
548 If @var{start} is a string, then @code{write-region} writes or appends
549 that string, rather than text from the buffer.  @var{end} is ignored in
550 this case.
552 If @var{append} is non-@code{nil}, then the specified text is appended
553 to the existing file contents (if any).  Starting in Emacs 21, if
554 @var{append} is an integer, then @code{write-region} seeks to that byte
555 offset from the start of the file and writes the data from there.
557 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
558 for confirmation if @var{filename} names an existing file.
559 Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl}, 
560 then @code{write-region} does not ask for confirmation, but instead
561 it signals an error @code{file-already-exists} if the file already
562 exists.
564 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
565 a special system feature.  At least for files on a local disk, there is
566 no chance that some other program could create a file of the same name
567 before Emacs does, without Emacs's noticing.
569 If @var{visit} is @code{t}, then Emacs establishes an association
570 between the buffer and the file: the buffer is then visiting that file.
571 It also sets the last file modification time for the current buffer to
572 @var{filename}'s modtime, and marks the buffer as not modified.  This
573 feature is used by @code{save-buffer}, but you probably should not use
574 it yourself.
576 @c Emacs 19 feature
577 If @var{visit} is a string, it specifies the file name to visit.  This
578 way, you can write the data to one file (@var{filename}) while recording
579 the buffer as visiting another file (@var{visit}).  The argument
580 @var{visit} is used in the echo area message and also for file locking;
581 @var{visit} is stored in @code{buffer-file-name}.  This feature is used
582 to implement @code{file-precious-flag}; don't use it yourself unless you
583 really know what you're doing.
585 The optional argument @var{lockname}, if non-@code{nil}, specifies the
586 file name to use for purposes of locking and unlocking, overriding
587 @var{filename} and @var{visit} for that purpose.
589 The function @code{write-region} converts the data which it writes to
590 the appropriate file formats specified by @code{buffer-file-format}.
591 @xref{Format Conversion}.  It also calls the functions in the list
592 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
594 Normally, @code{write-region} displays the message @samp{Wrote
595 @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
596 nor @code{nil} nor a string, then this message is inhibited.  This
597 feature is useful for programs that use files for internal purposes,
598 files that the user does not need to know about.
599 @end deffn
601 @defmac with-temp-file file body...
602 The @code{with-temp-file} macro evaluates the @var{body} forms with a
603 temporary buffer as the current buffer; then, at the end, it writes the
604 buffer contents into file @var{file}.  It kills the temporary buffer
605 when finished, restoring the buffer that was current before the
606 @code{with-temp-file} form.  Then it returns the value of the last form
607 in @var{body}.
609 The current buffer is restored even in case of an abnormal exit via
610 @code{throw} or error (@pxref{Nonlocal Exits}).
612 See also @code{with-temp-buffer} in @ref{Current Buffer}.
613 @end defmac
615 @node File Locks
616 @section File Locks
617 @cindex file locks
619   When two users edit the same file at the same time, they are likely to
620 interfere with each other.  Emacs tries to prevent this situation from
621 arising by recording a @dfn{file lock} when a file is being modified.
622 Emacs can then detect the first attempt to modify a buffer visiting a
623 file that is locked by another Emacs job, and ask the user what to do.
624 The file lock is really a file, a symbolic link with a special name,
625 stored in the same directory as the file you are editing.
627   When you access files using NFS, there may be a small probability that
628 you and another user will both lock the same file ``simultaneously''.
629 If this happens, it is possible for the two users to make changes
630 simultaneously, but Emacs will still warn the user who saves second.
631 Also, the detection of modification of a buffer visiting a file changed
632 on disk catches some cases of simultaneous editing; see
633 @ref{Modification Time}.
635 @defun file-locked-p filename
636 This function returns @code{nil} if the file @var{filename} is not
637 locked.  It returns @code{t} if it is locked by this Emacs process, and
638 it returns the name of the user who has locked it if it is locked by
639 some other job.
641 @example
642 @group
643 (file-locked-p "foo")
644      @result{} nil
645 @end group
646 @end example
647 @end defun
649 @defun lock-buffer &optional filename
650 This function locks the file @var{filename}, if the current buffer is
651 modified.  The argument @var{filename} defaults to the current buffer's
652 visited file.  Nothing is done if the current buffer is not visiting a
653 file, or is not modified.
654 @end defun
656 @defun unlock-buffer
657 This function unlocks the file being visited in the current buffer,
658 if the buffer is modified.  If the buffer is not modified, then
659 the file should not be locked, so this function does nothing.  It also
660 does nothing if the current buffer is not visiting a file.
661 @end defun
663   File locking is not supported on some systems.  On systems that do not
664 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
665 @code{file-locked-p} do nothing and return @code{nil}.
667 @defun ask-user-about-lock file other-user
668 This function is called when the user tries to modify @var{file}, but it
669 is locked by another user named @var{other-user}.  The default
670 definition of this function asks the user to say what to do.  The value
671 this function returns determines what Emacs does next:
673 @itemize @bullet
674 @item
675 A value of @code{t} says to grab the lock on the file.  Then
676 this user may edit the file and @var{other-user} loses the lock.
678 @item
679 A value of @code{nil} says to ignore the lock and let this
680 user edit the file anyway.
682 @item
683 @kindex file-locked
684 This function may instead signal a @code{file-locked} error, in which
685 case the change that the user was about to make does not take place.
687 The error message for this error looks like this:
689 @example
690 @error{} File is locked: @var{file} @var{other-user}
691 @end example
693 @noindent
694 where @code{file} is the name of the file and @var{other-user} is the
695 name of the user who has locked the file.
696 @end itemize
698 If you wish, you can replace the @code{ask-user-about-lock} function
699 with your own version that makes the decision in another way.  The code
700 for its usual definition is in @file{userlock.el}.
701 @end defun
703 @node Information about Files
704 @section Information about Files
706   The functions described in this section all operate on strings that
707 designate file names.  All the functions have names that begin with the
708 word @samp{file}.  These functions all return information about actual
709 files or directories, so their arguments must all exist as actual files
710 or directories unless otherwise noted.
712 @menu
713 * Testing Accessibility::   Is a given file readable?  Writable?
714 * Kinds of Files::          Is it a directory?  A symbolic link?
715 * Truenames::               Eliminating symbolic links from a file name.
716 * File Attributes::         How large is it?  Any other names?  Etc.
717 @end menu
719 @node Testing Accessibility
720 @comment  node-name,  next,  previous,  up
721 @subsection Testing Accessibility
722 @cindex accessibility of a file
723 @cindex file accessibility
725   These functions test for permission to access a file in specific ways.
727 @defun file-exists-p filename
728 This function returns @code{t} if a file named @var{filename} appears to
729 exist.  This does not mean you can necessarily read the file, only that
730 you can find out its attributes.  (On Unix and GNU/Linux, this is true
731 if the file exists and you have execute permission on the containing
732 directories, regardless of the protection of the file itself.)
734 If the file does not exist, or if fascist access control policies
735 prevent you from finding the attributes of the file, this function
736 returns @code{nil}.
737 @end defun
739 @defun file-readable-p filename
740 This function returns @code{t} if a file named @var{filename} exists
741 and you can read it.  It returns @code{nil} otherwise.
743 @example
744 @group
745 (file-readable-p "files.texi")
746      @result{} t
747 @end group
748 @group
749 (file-exists-p "/usr/spool/mqueue")
750      @result{} t
751 @end group
752 @group
753 (file-readable-p "/usr/spool/mqueue")
754      @result{} nil
755 @end group
756 @end example
757 @end defun
759 @c Emacs 19 feature
760 @defun file-executable-p filename
761 This function returns @code{t} if a file named @var{filename} exists and
762 you can execute it.  It returns @code{nil} otherwise.  On Unix and
763 GNU/Linux, if the file is a directory, execute permission means you can
764 check the existence and attributes of files inside the directory, and
765 open those files if their modes permit.
766 @end defun
768 @defun file-writable-p filename
769 This function returns @code{t} if the file @var{filename} can be written
770 or created by you, and @code{nil} otherwise.  A file is writable if the
771 file exists and you can write it.  It is creatable if it does not exist,
772 but the specified directory does exist and you can write in that
773 directory.
775 In the third example below, @file{foo} is not writable because the
776 parent directory does not exist, even though the user could create such
777 a directory.
779 @example
780 @group
781 (file-writable-p "~/foo")
782      @result{} t
783 @end group
784 @group
785 (file-writable-p "/foo")
786      @result{} nil
787 @end group
788 @group
789 (file-writable-p "~/no-such-dir/foo")
790      @result{} nil
791 @end group
792 @end example
793 @end defun
795 @c Emacs 19 feature
796 @defun file-accessible-directory-p dirname
797 This function returns @code{t} if you have permission to open existing
798 files in the directory whose name as a file is @var{dirname}; otherwise
799 (or if there is no such directory), it returns @code{nil}.  The value
800 of @var{dirname} may be either a directory name or the file name of a
801 file which is a directory.
803 Example: after the following,
805 @example
806 (file-accessible-directory-p "/foo")
807      @result{} nil
808 @end example
810 @noindent
811 we can deduce that any attempt to read a file in @file{/foo/} will
812 give an error.
813 @end defun
815 @defun access-file filename string
816 This function opens file @var{filename} for reading, then closes it and
817 returns @code{nil}.  However, if the open fails, it signals an error
818 using @var{string} as the error message text.
819 @end defun
821 @defun file-ownership-preserved-p filename
822 This function returns @code{t} if deleting the file @var{filename} and
823 then creating it anew would keep the file's owner unchanged.
824 @end defun
826 @defun file-newer-than-file-p filename1 filename2
827 @cindex file age
828 @cindex file modification time
829 This function returns @code{t} if the file @var{filename1} is
830 newer than file @var{filename2}.  If @var{filename1} does not
831 exist, it returns @code{nil}.  If @var{filename2} does not exist,
832 it returns @code{t}.
834 In the following example, assume that the file @file{aug-19} was written
835 on the 19th, @file{aug-20} was written on the 20th, and the file
836 @file{no-file} doesn't exist at all.
838 @example
839 @group
840 (file-newer-than-file-p "aug-19" "aug-20")
841      @result{} nil
842 @end group
843 @group
844 (file-newer-than-file-p "aug-20" "aug-19")
845      @result{} t
846 @end group
847 @group
848 (file-newer-than-file-p "aug-19" "no-file")
849      @result{} t
850 @end group
851 @group
852 (file-newer-than-file-p "no-file" "aug-19")
853      @result{} nil
854 @end group
855 @end example
857 You can use @code{file-attributes} to get a file's last modification
858 time as a list of two numbers.  @xref{File Attributes}.
859 @end defun
861 @node Kinds of Files
862 @comment  node-name,  next,  previous,  up
863 @subsection Distinguishing Kinds of Files
865   This section describes how to distinguish various kinds of files, such
866 as directories, symbolic links, and ordinary files.
868 @defun file-symlink-p filename
869 @cindex file symbolic links
870 If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
871 function returns the file name to which it is linked.  This may be the
872 name of a text file, a directory, or even another symbolic link, or it
873 may be a nonexistent file name.
875 If the file @var{filename} is not a symbolic link (or there is no such file),
876 @code{file-symlink-p} returns @code{nil}.  
878 @example
879 @group
880 (file-symlink-p "foo")
881      @result{} nil
882 @end group
883 @group
884 (file-symlink-p "sym-link")
885      @result{} "foo"
886 @end group
887 @group
888 (file-symlink-p "sym-link2")
889      @result{} "sym-link"
890 @end group
891 @group
892 (file-symlink-p "/bin")
893      @result{} "/pub/bin"
894 @end group
895 @end example
897 @c !!! file-symlink-p: should show output of ls -l for comparison
898 @end defun
900 @defun file-directory-p filename
901 This function returns @code{t} if @var{filename} is the name of an
902 existing directory, @code{nil} otherwise.
904 @example
905 @group
906 (file-directory-p "~rms")
907      @result{} t
908 @end group
909 @group
910 (file-directory-p "~rms/lewis/files.texi")
911      @result{} nil
912 @end group
913 @group
914 (file-directory-p "~rms/lewis/no-such-file")
915      @result{} nil
916 @end group
917 @group
918 (file-directory-p "$HOME")
919      @result{} nil
920 @end group
921 @group
922 (file-directory-p
923  (substitute-in-file-name "$HOME"))
924      @result{} t
925 @end group
926 @end example
927 @end defun
929 @defun file-regular-p filename
930 This function returns @code{t} if the file @var{filename} exists and is
931 a regular file (not a directory, named pipe, terminal, or
932 other I/O device).
933 @end defun
935 @node Truenames
936 @subsection Truenames
937 @cindex truename (of file)
939 @c Emacs 19 features
940   The @dfn{truename} of a file is the name that you get by following
941 symbolic links at all levels until none remain, then simplifying away
942 @samp{.}@: and @samp{..}@: appearing as name components.  This results
943 in a sort of canonical name for the file.  A file does not always have a
944 unique truename; the number of distinct truenames a file has is equal to
945 the number of hard links to the file.  However, truenames are useful
946 because they eliminate symbolic links as a cause of name variation.
948 @defun file-truename filename
949 The function @code{file-truename} returns the truename of the file
950 @var{filename}.  The argument must be an absolute file name.
951 @end defun
953 @defun file-chase-links filename
954 This function follows symbolic links, starting with @var{filename},
955 until it finds a file name which is not the name of a symbolic link.
956 Then it returns that file name.
957 @end defun
959   To illustrate the difference between @code{file-chase-links} and
960 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
961 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
962 ordinary file (or at least, not a symbolic link) or nonexistent.  Then
963 we would have:
965 @example
966 (file-chase-links "/usr/foo/hello")
967      ;; @r{This does not follow the links in the parent directories.}
968      @result{} "/usr/foo/hello"
969 (file-truename "/usr/foo/hello")
970      ;; @r{Assuming that @file{/home} is not a symbolic link.}
971      @result{} "/home/foo/hello"
972 @end example
974   @xref{Buffer File Name}, for related information.
976 @node File Attributes
977 @comment  node-name,  next,  previous,  up
978 @subsection Other Information about Files
980   This section describes the functions for getting detailed information
981 about a file, other than its contents.  This information includes the
982 mode bits that control access permission, the owner and group numbers,
983 the number of names, the inode number, the size, and the times of access
984 and modification.
986 @defun file-modes filename
987 @cindex permission
988 @cindex file attributes
989 This function returns the mode bits of @var{filename}, as an integer.
990 The mode bits are also called the file permissions, and they specify
991 access control in the usual Unix fashion.  If the low-order bit is 1,
992 then the file is executable by all users, if the second-lowest-order bit
993 is 1, then the file is writable by all users, etc.
995 The highest value returnable is 4095 (7777 octal), meaning that
996 everyone has read, write, and execute permission, that the @sc{suid} bit
997 is set for both others and group, and that the sticky bit is set.
999 @example
1000 @group
1001 (file-modes "~/junk/diffs")
1002      @result{} 492               ; @r{Decimal integer.}
1003 @end group
1004 @group
1005 (format "%o" 492)
1006      @result{} "754"             ; @r{Convert to octal.}
1007 @end group
1009 @group
1010 (set-file-modes "~/junk/diffs" 438)
1011      @result{} nil
1012 @end group
1014 @group
1015 (format "%o" 438)
1016      @result{} "666"             ; @r{Convert to octal.}
1017 @end group
1019 @group
1020 % ls -l diffs
1021   -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
1022 @end group
1023 @end example
1024 @end defun
1026 @defun file-nlinks filename
1027 This functions returns the number of names (i.e., hard links) that
1028 file @var{filename} has.  If the file does not exist, then this function
1029 returns @code{nil}.  Note that symbolic links have no effect on this
1030 function, because they are not considered to be names of the files they
1031 link to.
1033 @example
1034 @group
1035 % ls -l foo*
1036 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
1037 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
1038 @end group
1040 @group
1041 (file-nlinks "foo")
1042      @result{} 2
1043 @end group
1044 @group
1045 (file-nlinks "doesnt-exist")
1046      @result{} nil
1047 @end group
1048 @end example
1049 @end defun
1051 @defun file-attributes filename
1052 This function returns a list of attributes of file @var{filename}.  If
1053 the specified file cannot be opened, it returns @code{nil}.
1055 The elements of the list, in order, are:
1057 @enumerate 0
1058 @item
1059 @code{t} for a directory, a string for a symbolic link (the name
1060 linked to), or @code{nil} for a text file.
1062 @c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
1063 @item
1064 The number of names the file has.  Alternate names, also known as hard
1065 links, can be created by using the @code{add-name-to-file} function
1066 (@pxref{Changing Files}).
1068 @item
1069 The file's @sc{uid}.
1071 @item
1072 The file's @sc{gid}.
1074 @item
1075 The time of last access, as a list of two integers.
1076 The first integer has the high-order 16 bits of time,
1077 the second has the low 16 bits.  (This is similar to the
1078 value of @code{current-time}; see @ref{Time of Day}.)
1080 @item
1081 The time of last modification as a list of two integers (as above).
1083 @item
1084 The time of last status change as a list of two integers (as above).
1086 @item
1087 The size of the file in bytes.  If the size is too large to fit in a
1088 Lisp integer, this is a floating point number.
1090 @item
1091 The file's modes, as a string of ten letters or dashes,
1092 as in @samp{ls -l}.
1094 @item
1095 @code{t} if the file's @sc{gid} would change if file were
1096 deleted and recreated; @code{nil} otherwise.
1098 @item
1099 The file's inode number.  If possible, this is an integer.  If the inode
1100 number is too large to be represented as an integer in Emacs Lisp, then
1101 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
1102 holds the low 16 bits.
1104 @item
1105 The file system number of the file system that the file is in.  This
1106 element and the file's inode number together give enough information to
1107 distinguish any two files on the system---no two files can have the same
1108 values for both of these numbers.
1109 @end enumerate
1111 For example, here are the file attributes for @file{files.texi}:
1113 @example
1114 @group
1115 (file-attributes "files.texi")
1116      @result{}  (nil 1 2235 75 
1117           (8489 20284) 
1118           (8489 20284) 
1119           (8489 20285)
1120           14906 "-rw-rw-rw-" 
1121           nil 129500 -32252)
1122 @end group
1123 @end example
1125 @noindent
1126 and here is how the result is interpreted:
1128 @table @code
1129 @item nil
1130 is neither a directory nor a symbolic link.
1132 @item 1
1133 has only one name (the name @file{files.texi} in the current default
1134 directory).
1136 @item 2235
1137 is owned by the user with @sc{uid} 2235.
1139 @item 75
1140 is in the group with @sc{gid} 75.
1142 @item (8489 20284)
1143 was last accessed on Aug 19 00:09.
1145 @item (8489 20284)
1146 was last modified on Aug 19 00:09.
1148 @item (8489 20285)
1149 last had its inode changed on Aug 19 00:09.
1151 @item 14906
1152 is 14906 bytes long.  (It may not contain 14906 characters, though,
1153 if some of the bytes belong to multibyte sequences.)
1155 @item "-rw-rw-rw-"
1156 has a mode of read and write access for the owner, group, and world.
1158 @item nil
1159 would retain the same @sc{gid} if it were recreated.
1161 @item 129500
1162 has an inode number of 129500.
1163 @item -32252
1164 is on file system number -32252.
1165 @end table
1166 @end defun
1168 @node Changing Files
1169 @section Changing File Names and Attributes
1170 @cindex renaming files
1171 @cindex copying files
1172 @cindex deleting files
1173 @cindex linking files
1174 @cindex setting modes of files
1176   The functions in this section rename, copy, delete, link, and set the
1177 modes of files.
1179   In the functions that have an argument @var{newname}, if a file by the
1180 name of @var{newname} already exists, the actions taken depend on the
1181 value of the argument @var{ok-if-already-exists}:
1183 @itemize @bullet
1184 @item
1185 Signal a @code{file-already-exists} error if
1186 @var{ok-if-already-exists} is @code{nil}.
1188 @item
1189 Request confirmation if @var{ok-if-already-exists} is a number.
1191 @item
1192 Replace the old file without confirmation if @var{ok-if-already-exists}
1193 is any other value.
1194 @end itemize
1196 @defun add-name-to-file oldname newname &optional ok-if-already-exists
1197 @cindex file with multiple names
1198 @cindex file hard link
1199 This function gives the file named @var{oldname} the additional name
1200 @var{newname}.  This means that @var{newname} becomes a new ``hard
1201 link'' to @var{oldname}.
1203 In the first part of the following example, we list two files,
1204 @file{foo} and @file{foo3}.
1206 @example
1207 @group
1208 % ls -li fo*
1209 81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
1210 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1211 @end group
1212 @end example
1214 Now we create a hard link, by calling @code{add-name-to-file}, then list
1215 the files again.  This shows two names for one file, @file{foo} and
1216 @file{foo2}.
1218 @example
1219 @group
1220 (add-name-to-file "foo" "foo2")
1221      @result{} nil
1222 @end group
1224 @group
1225 % ls -li fo*
1226 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
1227 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
1228 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1229 @end group
1230 @end example
1232 Finally, we evaluate the following:
1234 @example
1235 (add-name-to-file "foo" "foo3" t)
1236 @end example
1238 @noindent
1239 and list the files again.  Now there are three names
1240 for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
1241 contents of @file{foo3} are lost.
1243 @example
1244 @group
1245 (add-name-to-file "foo1" "foo3")
1246      @result{} nil
1247 @end group
1249 @group
1250 % ls -li fo*
1251 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
1252 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
1253 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
1254 @end group
1255 @end example
1257 This function is meaningless on operating systems where multiple names
1258 for one file are not allowed.  Some systems implement multiple names
1259 by copying the file instead.
1261 See also @code{file-nlinks} in @ref{File Attributes}.
1262 @end defun
1264 @deffn Command rename-file filename newname &optional ok-if-already-exists
1265 This command renames the file @var{filename} as @var{newname}.
1267 If @var{filename} has additional names aside from @var{filename}, it
1268 continues to have those names.  In fact, adding the name @var{newname}
1269 with @code{add-name-to-file} and then deleting @var{filename} has the
1270 same effect as renaming, aside from momentary intermediate states.
1272 In an interactive call, this function prompts for @var{filename} and
1273 @var{newname} in the minibuffer; also, it requests confirmation if
1274 @var{newname} already exists.
1275 @end deffn
1277 @deffn Command copy-file oldname newname &optional ok-if-exists time
1278 This command copies the file @var{oldname} to @var{newname}.  An
1279 error is signaled if @var{oldname} does not exist.
1281 If @var{time} is non-@code{nil}, then this function gives the new file
1282 the same last-modified time that the old one has.  (This works on only
1283 some operating systems.)  If setting the time gets an error,
1284 @code{copy-file} signals a @code{file-date-error} error.
1286 In an interactive call, this function prompts for @var{filename} and
1287 @var{newname} in the minibuffer; also, it requests confirmation if
1288 @var{newname} already exists.
1289 @end deffn
1291 @deffn Command delete-file filename
1292 @pindex rm
1293 This command deletes the file @var{filename}, like the shell command
1294 @samp{rm @var{filename}}.  If the file has multiple names, it continues
1295 to exist under the other names.
1297 A suitable kind of @code{file-error} error is signaled if the file does
1298 not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
1299 deletable if its directory is writable.)
1301 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1302 @end deffn
1304 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
1305 @pindex ln
1306 @kindex file-already-exists
1307 This command makes a symbolic link to @var{filename}, named
1308 @var{newname}.  This is like the shell command @samp{ln -s
1309 @var{filename} @var{newname}}.
1311 In an interactive call, this function prompts for @var{filename} and
1312 @var{newname} in the minibuffer; also, it requests confirmation if
1313 @var{newname} already exists.
1315 This function is not available on systems that don't support symbolic
1316 links.
1317 @end deffn
1319 @defun define-logical-name varname string
1320 This function defines the logical name @var{name} to have the value
1321 @var{string}.  It is available only on VMS.
1322 @end defun
1324 @defun set-file-modes filename mode
1325 This function sets mode bits of @var{filename} to @var{mode} (which must
1326 be an integer).  Only the low 12 bits of @var{mode} are used.
1327 @end defun
1329 @c Emacs 19 feature
1330 @defun set-default-file-modes mode
1331 This function sets the default file protection for new files created by
1332 Emacs and its subprocesses.  Every file created with Emacs initially has
1333 this protection, or a subset of it (@code{write-region} will not give a
1334 file execute permission even if the default file protection allows
1335 execute permission).  On Unix and GNU/Linux, the default protection is
1336 the bitwise complement of the ``umask'' value.
1338 The argument @var{mode} must be an integer.  On most systems, only the
1339 low 9 bits of @var{mode} are meaningful.  You can use the Lisp construct
1340 for octal character codes to enter @var{mode}; for example,
1342 @example
1343 (set-default-file-modes ?\644)
1344 @end example
1346 Saving a modified version of an existing file does not count as creating
1347 the file; it preserves the existing file's mode, whatever that is.  So
1348 the default file protection has no effect.
1349 @end defun
1351 @defun default-file-modes
1352 This function returns the current default protection value.
1353 @end defun
1355 @cindex MS-DOS and file modes
1356 @cindex file modes and MS-DOS
1357   On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1358 So Emacs considers a file executable if its name ends in one of the
1359 standard executable extensions, such as @file{.com}, @file{.bat},
1360 @file{.exe}, and some others.  Files that begin with the Unix-standard
1361 @samp{#!} signature, such as shell and Perl scripts, are also considered
1362 as executable files.  This is reflected in the values returned by
1363 @code{file-modes} and @code{file-attributes}.  Directories are also
1364 reported with executable bit set, for compatibility with Unix.
1366 @node File Names
1367 @section File Names
1368 @cindex file names
1370   Files are generally referred to by their names, in Emacs as elsewhere.
1371 File names in Emacs are represented as strings.  The functions that
1372 operate on a file all expect a file name argument.
1374   In addition to operating on files themselves, Emacs Lisp programs
1375 often need to operate on file names; i.e., to take them apart and to use
1376 part of a name to construct related file names.  This section describes
1377 how to manipulate file names.
1379   The functions in this section do not actually access files, so they
1380 can operate on file names that do not refer to an existing file or
1381 directory.
1383   On MS-DOS and MS-Windows, these functions (like the function that
1384 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1385 where backslashes separate the components, as well as Unix syntax; but
1386 they always return Unix syntax.  On VMS, these functions (and the ones
1387 that operate on files) understand both VMS file-name syntax and Unix
1388 syntax.  This enables Lisp programs to specify file names in Unix syntax
1389 and work properly on all systems without change.
1391 @menu
1392 * File Name Components::  The directory part of a file name, and the rest.
1393 * Directory Names::       A directory's name as a directory
1394                             is different from its name as a file.
1395 * Relative File Names::   Some file names are relative to a current directory.
1396 * File Name Expansion::   Converting relative file names to absolute ones.
1397 * Unique File Names::     Generating names for temporary files.
1398 * File Name Completion::  Finding the completions for a given file name.
1399 * Standard File Names::   If your package uses a fixed file name,
1400                             how to handle various operating systems simply.
1401 @end menu
1403 @node File Name Components
1404 @subsection File Name Components
1405 @cindex directory part (of file name)
1406 @cindex nondirectory part (of file name)
1407 @cindex version number (in file name)
1409   The operating system groups files into directories.  To specify a
1410 file, you must specify the directory and the file's name within that
1411 directory.  Therefore, Emacs considers a file name as having two main
1412 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1413 (or @dfn{file name within the directory}).  Either part may be empty.
1414 Concatenating these two parts reproduces the original file name.
1416   On most systems, the directory part is everything up to and including
1417 the last slash (backslash is also allowed in input on MS-DOS or
1418 MS-Windows); the nondirectory part is the rest.  The rules in VMS syntax
1419 are complicated.
1421   For some purposes, the nondirectory part is further subdivided into
1422 the name proper and the @dfn{version number}.  On most systems, only
1423 backup files have version numbers in their names.  On VMS, every file
1424 has a version number, but most of the time the file name actually used
1425 in Emacs omits the version number, so that version numbers in Emacs are
1426 found mostly in directory lists.
1428 @defun file-name-directory filename
1429 This function returns the directory part of @var{filename} (or
1430 @code{nil} if @var{filename} does not include a directory part).  On
1431 most systems, the function returns a string ending in a slash.  On VMS,
1432 it returns a string ending in one of the three characters @samp{:},
1433 @samp{]}, or @samp{>}.
1435 @example
1436 @group
1437 (file-name-directory "lewis/foo")  ; @r{Unix example}
1438      @result{} "lewis/"
1439 @end group
1440 @group
1441 (file-name-directory "foo")        ; @r{Unix example}
1442      @result{} nil
1443 @end group
1444 @group
1445 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
1446      @result{} "[X]"
1447 @end group
1448 @end example
1449 @end defun
1451 @defun file-name-nondirectory filename
1452 This function returns the nondirectory part of @var{filename}.
1454 @example
1455 @group
1456 (file-name-nondirectory "lewis/foo")
1457      @result{} "foo"
1458 @end group
1459 @group
1460 (file-name-nondirectory "foo")
1461      @result{} "foo"
1462 @end group
1463 @group
1464 ;; @r{The following example is accurate only on VMS.}
1465 (file-name-nondirectory "[X]FOO.TMP")
1466      @result{} "FOO.TMP"
1467 @end group
1468 @end example
1469 @end defun
1471 @defun file-name-sans-versions filename &optional keep-backup-version
1472 This function returns @var{filename} with any file version numbers,
1473 backup version numbers, or trailing tildes discarded.
1475 If @var{keep-backup-version} is non-@code{nil}, then true file version
1476 numbers understood as such by the file system are discarded from the
1477 return value, but backup version numbers are kept.
1479 @example
1480 @group
1481 (file-name-sans-versions "~rms/foo.~1~")
1482      @result{} "~rms/foo"
1483 @end group
1484 @group
1485 (file-name-sans-versions "~rms/foo~")
1486      @result{} "~rms/foo"
1487 @end group
1488 @group
1489 (file-name-sans-versions "~rms/foo")
1490      @result{} "~rms/foo"
1491 @end group
1492 @group
1493 ;; @r{The following example applies to VMS only.}
1494 (file-name-sans-versions "foo;23")
1495      @result{} "foo"
1496 @end group
1497 @end example
1498 @end defun
1500 @defun file-name-sans-extension filename
1501 This function returns @var{filename} minus its ``extension,'' if any.
1502 The extension, in a file name, is the part that starts with the last
1503 @samp{.} in the last name component.  For example,
1505 @example
1506 (file-name-sans-extension "foo.lose.c")
1507      @result{} "foo.lose"
1508 (file-name-sans-extension "big.hack/foo")
1509      @result{} "big.hack/foo"
1510 @end example
1511 @end defun
1513 @ignore
1514 Andrew Innes says that this 
1516 @c @defvar directory-sep-char
1517 @c @tindex directory-sep-char
1518 This variable holds the character that Emacs normally uses to separate
1519 file name components.  The default value is @code{?/}, but on MS-Windows
1520 you can set it to @code{?\\}; then the functions that transform file names
1521 use backslashes in their output.
1523 File names using backslashes work as input to Lisp primitives even on
1524 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
1525 value of @code{?/}.
1526 @end defvar
1527 @end ignore
1529 @defun file-name-extension filename &optional period
1530 This function returns @var{filename}'s final ``extension,'' if any,
1531 after applying @code{file-name-sans-versions} to remove any
1532 version/backup part.  If @var{period} is non-nil, then the returned
1533 value includes the period that delimits the extension, and if
1534 @var{filename} has no extension, the value is @code{""}.
1535 @end defun
1537 @node Directory Names
1538 @comment  node-name,  next,  previous,  up
1539 @subsection Directory Names
1540 @cindex directory name
1541 @cindex file name of directory
1543   A @dfn{directory name} is the name of a directory.  A directory is a
1544 kind of file, and it has a file name, which is related to the directory
1545 name but not identical to it.  (This is not quite the same as the usual
1546 Unix terminology.)  These two different names for the same entity are
1547 related by a syntactic transformation.  On most systems, this is simple:
1548 a directory name ends in a slash (or backslash), whereas the directory's
1549 name as a file lacks that slash.  On VMS, the relationship is more
1550 complicated.
1552   The difference between a directory name and its name as a file is
1553 subtle but crucial.  When an Emacs variable or function argument is
1554 described as being a directory name, a file name of a directory is not
1555 acceptable.
1557   The following two functions convert between directory names and file
1558 names.  They do nothing special with environment variable substitutions
1559 such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
1561 @defun file-name-as-directory filename
1562 This function returns a string representing @var{filename} in a form
1563 that the operating system will interpret as the name of a directory.  On
1564 most systems, this means appending a slash to the string (if it does not
1565 already end in one).  On VMS, the function converts a string of the form
1566 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
1568 @example
1569 @group
1570 (file-name-as-directory "~rms/lewis")
1571      @result{} "~rms/lewis/"
1572 @end group
1573 @end example
1574 @end defun
1576 @defun directory-file-name dirname
1577 This function returns a string representing @var{dirname} in a form that
1578 the operating system will interpret as the name of a file.  On most
1579 systems, this means removing the final slash (or backslash) from the
1580 string.  On VMS, the function converts a string of the form @file{[X.Y]}
1581 to @file{[X]Y.DIR.1}.
1583 @example
1584 @group
1585 (directory-file-name "~lewis/")
1586      @result{} "~lewis"
1587 @end group
1588 @end example
1589 @end defun
1591 @cindex directory name abbreviation
1592   Directory name abbreviations are useful for directories that are
1593 normally accessed through symbolic links.  Sometimes the users recognize
1594 primarily the link's name as ``the name'' of the directory, and find it
1595 annoying to see the directory's ``real'' name.  If you define the link
1596 name as an abbreviation for the ``real'' name, Emacs shows users the
1597 abbreviation instead.
1599 @defvar directory-abbrev-alist
1600 The variable @code{directory-abbrev-alist} contains an alist of
1601 abbreviations to use for file directories.  Each element has the form
1602 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1603 @var{to} when it appears in a directory name.  The @var{from} string is
1604 actually a regular expression; it should always start with @samp{^}.
1605 The function @code{abbreviate-file-name} performs these substitutions.
1607 You can set this variable in @file{site-init.el} to describe the
1608 abbreviations appropriate for your site.
1610 Here's an example, from a system on which file system @file{/home/fsf}
1611 and so on are normally accessed through symbolic links named @file{/fsf}
1612 and so on.
1614 @example
1615 (("^/home/fsf" . "/fsf")
1616  ("^/home/gp" . "/gp")
1617  ("^/home/gd" . "/gd"))
1618 @end example
1619 @end defvar
1621   To convert a directory name to its abbreviation, use this
1622 function:
1624 @defun abbreviate-file-name dirname
1625 This function applies abbreviations from @code{directory-abbrev-alist}
1626 to its argument, and substitutes @samp{~} for the user's home
1627 directory.
1628 @end defun
1630 @node Relative File Names
1631 @subsection Absolute and Relative File Names
1632 @cindex absolute file name
1633 @cindex relative file name
1635   All the directories in the file system form a tree starting at the
1636 root directory.  A file name can specify all the directory names
1637 starting from the root of the tree; then it is called an @dfn{absolute}
1638 file name.  Or it can specify the position of the file in the tree
1639 relative to a default directory; then it is called a @dfn{relative} file
1640 name.  On Unix and GNU/Linux, an absolute file name starts with a slash
1641 or a tilde (@samp{~}), and a relative one does not.  On MS-DOS and
1642 MS-Windows, an absolute file name starts with a slash or a backslash, or
1643 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1644 @dfn{drive letter}.  The rules on VMS are complicated.
1646 @defun file-name-absolute-p filename
1647 This function returns @code{t} if file @var{filename} is an absolute
1648 file name, @code{nil} otherwise.  On VMS, this function understands both
1649 Unix syntax and VMS syntax.
1651 @example
1652 @group
1653 (file-name-absolute-p "~rms/foo")
1654      @result{} t
1655 @end group
1656 @group
1657 (file-name-absolute-p "rms/foo")
1658      @result{} nil
1659 @end group
1660 @group
1661 (file-name-absolute-p "/user/rms/foo")
1662      @result{} t
1663 @end group
1664 @end example
1665 @end defun
1667 @node File Name Expansion
1668 @subsection Functions that Expand Filenames
1669 @cindex expansion of file names
1671   @dfn{Expansion} of a file name means converting a relative file name
1672 to an absolute one.  Since this is done relative to a default directory,
1673 you must specify the default directory name as well as the file name to
1674 be expanded.  Expansion also simplifies file names by eliminating
1675 redundancies such as @file{./} and @file{@var{name}/../}.
1677 @defun expand-file-name filename &optional directory
1678 This function converts @var{filename} to an absolute file name.  If
1679 @var{directory} is supplied, it is the default directory to start with
1680 if @var{filename} is relative.  (The value of @var{directory} should
1681 itself be an absolute directory name; it may start with @samp{~}.)
1682 Otherwise, the current buffer's value of @code{default-directory} is
1683 used.  For example:
1685 @example
1686 @group
1687 (expand-file-name "foo")
1688      @result{} "/xcssun/users/rms/lewis/foo"
1689 @end group
1690 @group
1691 (expand-file-name "../foo")
1692      @result{} "/xcssun/users/rms/foo"
1693 @end group
1694 @group
1695 (expand-file-name "foo" "/usr/spool/")
1696      @result{} "/usr/spool/foo"
1697 @end group
1698 @group
1699 (expand-file-name "$HOME/foo")
1700      @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1701 @end group
1702 @end example
1704 Filenames containing @samp{.} or @samp{..} are simplified to their
1705 canonical form:
1707 @example
1708 @group
1709 (expand-file-name "bar/../foo")
1710      @result{} "/xcssun/users/rms/lewis/foo"
1711 @end group
1712 @end example
1714 Note that @code{expand-file-name} does @emph{not} expand environment
1715 variables; only @code{substitute-in-file-name} does that.
1716 @end defun
1718 @c Emacs 19 feature
1719 @defun file-relative-name filename &optional directory
1720 This function does the inverse of expansion---it tries to return a
1721 relative name that is equivalent to @var{filename} when interpreted
1722 relative to @var{directory}.  If @var{directory} is omitted or
1723 @code{nil}, it defaults to the current buffer's default directory.
1725 On some operating systems, an absolute file name begins with a device
1726 name.  On such systems, @var{filename} has no relative equivalent based
1727 on @var{directory} if they start with two different device names.  In
1728 this case, @code{file-relative-name} returns @var{filename} in absolute
1729 form.
1731 @example
1732 (file-relative-name "/foo/bar" "/foo/")
1733      @result{} "bar"
1734 (file-relative-name "/foo/bar" "/hack/")
1735      @result{} "../foo/bar"
1736 @end example
1737 @end defun
1739 @defvar default-directory
1740 The value of this buffer-local variable is the default directory for the
1741 current buffer.  It should be an absolute directory name; it may start
1742 with @samp{~}.  This variable is buffer-local in every buffer.
1744 @code{expand-file-name} uses the default directory when its second
1745 argument is @code{nil}.
1747 Aside from VMS, the value is always a string ending with a slash.
1749 @example
1750 @group
1751 default-directory
1752      @result{} "/user/lewis/manual/"
1753 @end group
1754 @end example
1755 @end defvar
1757 @defun substitute-in-file-name filename
1758 This function replaces environment variables references in
1759 @var{filename} with the environment variable values.  Following standard
1760 Unix shell syntax, @samp{$} is the prefix to substitute an environment
1761 variable value.
1763 The environment variable name is the series of alphanumeric characters
1764 (including underscores) that follow the @samp{$}.  If the character following
1765 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
1766 matching @samp{@}}.
1768 @c Wordy to avoid overfull hbox.  --rjc 15mar92
1769 Here we assume that the environment variable @code{HOME}, which holds
1770 the user's home directory name, has value @samp{/xcssun/users/rms}.
1772 @example
1773 @group
1774 (substitute-in-file-name "$HOME/foo")
1775      @result{} "/xcssun/users/rms/foo"
1776 @end group
1777 @end example
1779 After substitution, if a @samp{~} or a @samp{/} appears following a
1780 @samp{/}, everything before the following @samp{/} is discarded:
1782 @example
1783 @group
1784 (substitute-in-file-name "bar/~/foo")
1785      @result{} "~/foo"
1786 @end group
1787 @group
1788 (substitute-in-file-name "/usr/local/$HOME/foo")
1789      @result{} "/xcssun/users/rms/foo"
1790      ;; @r{@file{/usr/local/} has been discarded.}
1791 @end group
1792 @end example
1794 On VMS, @samp{$} substitution is not done, so this function does nothing
1795 on VMS except discard superfluous initial components as shown above.
1796 @end defun
1798 @node Unique File Names
1799 @subsection Generating Unique File Names
1801   Some programs need to write temporary files.  Here is the usual way to
1802 construct a name for such a file, starting in Emacs 21:
1804 @example
1805 (make-temp-file @var{name-of-application})
1806 @end example
1808 @noindent
1809 The job of @code{make-temp-file} is to prevent two different users or
1810 two different jobs from trying to use the exact same file name.
1812 @defun make-temp-file prefix &optional dir-flag
1813 @tindex make-temp-file
1814 This function creates a temporary file and returns its name.
1815 The name starts with @var{prefix}; it also contains a number that is
1816 different in each Emacs job.  If @var{prefix} is a relative file name,
1817 it is expanded against @code{temporary-file-directory}.
1819 @example
1820 @group
1821 (make-temp-file "foo")
1822      @result{} "/tmp/foo232J6v"
1823 @end group
1824 @end example
1826 When @code{make-temp-file} returns, the file has been created and is
1827 empty.  At that point, you should write the intended contents into the
1828 file.
1830 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
1831 an empty directory instead of an empty file.
1833 To prevent conflicts among different libraries running in the same
1834 Emacs, each Lisp program that uses @code{make-temp-file} should have its
1835 own @var{prefix}.  The number added to the end of @var{prefix}
1836 distinguishes between the same application running in different Emacs
1837 jobs.  Additional added characters permit a large number of distinct
1838 names even in one Emacs job.
1839 @end defun
1841   The default directory for temporary files is controlled by the
1842 variable @code{temporary-file-directory}.  This variable gives the user
1843 a uniform way to specify the directory for all temporary files.  Some
1844 programs use @code{small-temporary-file-directory} instead, if that is
1845 non-@code{nil}.  To use it, you should expand the prefix against
1846 the proper directory before calling @code{make-temp-file}.
1848   In older Emacs versions where @code{make-temp-file} does not exist,
1849 you should use @code{make-temp-name} instead:
1851 @example
1852 (make-temp-name
1853  (expand-file-name @var{name-of-application}
1854                    temporary-file-directory))
1855 @end example
1857 @defun make-temp-name string
1858 This function generates a string that can be used as a unique file name.
1859 The name starts with @var{string}, and contains a number that is
1860 different in each Emacs job.  It is like @code{make-temp-file} except
1861 that it just constructs a name, and does not create a file.  On MS-DOS,
1862 the @var{string} prefix can be truncated to fit into the 8+3 file-name
1863 limits.
1864 @end defun
1866 @defvar temporary-file-directory
1867 @cindex @code{TMPDIR} environment variable
1868 @cindex @code{TMP} environment variable
1869 @cindex @code{TEMP} environment variable
1870 This variable specifies the directory name for creating temporary files.
1871 Its value should be a directory name (@pxref{Directory Names}), but it
1872 is good for Lisp programs to cope if the value is a directory's file
1873 name instead.  Using the value as the second argument to
1874 @code{expand-file-name} is a good way to achieve that.
1876 The default value is determined in a reasonable way for your operating
1877 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
1878 environment variables, with a fall-back to a system-dependent name if
1879 none of these variables is defined.
1881 Even if you do not use @code{make-temp-name} to choose the temporary
1882 file's name, you should still use this variable to decide which
1883 directory to put the file in.  However, if you expect the file to be
1884 small, you should use @code{small-temporary-file-directory} first if
1885 that is non-@code{nil}.
1886 @end defvar
1888 @tindex small-temporary-file-directory
1889 @defvar small-temporary-file-directory
1890 This variable (new in Emacs 21) specifies the directory name for
1891 creating certain temporary files, which are likely to be small.
1893 If you want to write a temporary file which is likely to be small, you
1894 should compute the directory like this:
1896 @example
1897 (make-temp-file
1898   (expand-file-name @var{prefix}
1899                     (or small-temporary-file-directory
1900                         temporary-file-directory)))
1901 @end example
1902 @end defvar
1904 @node File Name Completion
1905 @subsection File Name Completion
1906 @cindex file name completion subroutines
1907 @cindex completion, file name
1909   This section describes low-level subroutines for completing a file
1910 name.  For other completion functions, see @ref{Completion}.
1912 @defun file-name-all-completions partial-filename directory
1913 This function returns a list of all possible completions for a file
1914 whose name starts with @var{partial-filename} in directory
1915 @var{directory}.  The order of the completions is the order of the files
1916 in the directory, which is unpredictable and conveys no useful
1917 information.
1919 The argument @var{partial-filename} must be a file name containing no
1920 directory part and no slash (or backslash on some systems).  The current
1921 buffer's default directory is prepended to @var{directory}, if
1922 @var{directory} is not absolute.
1924 In the following example, suppose that @file{~rms/lewis} is the current
1925 default directory, and has five files whose names begin with @samp{f}:
1926 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
1927 @file{file.c.~2~}.@refill
1929 @example
1930 @group
1931 (file-name-all-completions "f" "")
1932      @result{} ("foo" "file~" "file.c.~2~" 
1933                 "file.c.~1~" "file.c")
1934 @end group
1936 @group
1937 (file-name-all-completions "fo" "")  
1938      @result{} ("foo")
1939 @end group
1940 @end example
1941 @end defun
1943 @defun file-name-completion filename directory
1944 This function completes the file name @var{filename} in directory
1945 @var{directory}.  It returns the longest prefix common to all file names
1946 in directory @var{directory} that start with @var{filename}.
1948 If only one match exists and @var{filename} matches it exactly, the
1949 function returns @code{t}.  The function returns @code{nil} if directory
1950 @var{directory} contains no name starting with @var{filename}.
1952 In the following example, suppose that the current default directory
1953 has five files whose names begin with @samp{f}: @file{foo},
1954 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
1955 @file{file.c.~2~}.@refill
1957 @example
1958 @group
1959 (file-name-completion "fi" "")
1960      @result{} "file"
1961 @end group
1963 @group
1964 (file-name-completion "file.c.~1" "")
1965      @result{} "file.c.~1~"
1966 @end group
1968 @group
1969 (file-name-completion "file.c.~1~" "")
1970      @result{} t
1971 @end group
1973 @group
1974 (file-name-completion "file.c.~3" "")
1975      @result{} nil
1976 @end group
1977 @end example
1978 @end defun
1980 @defopt completion-ignored-extensions
1981 @code{file-name-completion} usually ignores file names that end in any
1982 string in this list.  It does not ignore them when all the possible
1983 completions end in one of these suffixes or when a buffer showing all
1984 possible completions is displayed.@refill
1986 A typical value might look like this:
1988 @example
1989 @group
1990 completion-ignored-extensions
1991      @result{} (".o" ".elc" "~" ".dvi")
1992 @end group
1993 @end example
1994 @end defopt
1996 @node Standard File Names
1997 @subsection Standard File Names
1999   Most of the file names used in Lisp programs are entered by the user.
2000 But occasionally a Lisp program needs to specify a standard file name
2001 for a particular use---typically, to hold customization information
2002 about each user.  For example, abbrev definitions are stored (by
2003 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2004 package stores completions in the file @file{~/.completions}.  These are
2005 two of the many standard file names used by parts of Emacs for certain
2006 purposes.
2008   Various operating systems have their own conventions for valid file
2009 names and for which file names to use for user profile data.  A Lisp
2010 program which reads a file using a standard file name ought to use, on
2011 each type of system, a file name suitable for that system.  The function
2012 @code{convert-standard-filename} makes this easy to do.
2014 @defun convert-standard-filename filename
2015 This function alters the file name @var{filename} to fit the conventions
2016 of the operating system in use, and returns the result as a new string.
2017 @end defun
2019   The recommended way to specify a standard file name in a Lisp program
2020 is to choose a name which fits the conventions of GNU and Unix systems,
2021 usually with a nondirectory part that starts with a period, and pass it
2022 to @code{convert-standard-filename} instead of using it directly.  Here
2023 is an example from the @code{completion} package:
2025 @example
2026 (defvar save-completions-file-name
2027         (convert-standard-filename "~/.completions")
2028   "*The file name to save completions to.")
2029 @end example
2031   On GNU and Unix systems, and on some other systems as well,
2032 @code{convert-standard-filename} returns its argument unchanged.  On
2033 some other systems, it alters the name to fit the system's conventions.
2035   For example, on MS-DOS the alterations made by this function include
2036 converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
2037 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2038 a @samp{.} after eight characters if there is none, and truncating to
2039 three characters after the @samp{.}.  (It makes other changes as well.)
2040 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2041 @file{.completions} becomes @file{_complet.ion}.
2043 @node Contents of Directories
2044 @section Contents of Directories
2045 @cindex directory-oriented functions
2046 @cindex file names in directory
2048   A directory is a kind of file that contains other files entered under
2049 various names.  Directories are a feature of the file system.
2051   Emacs can list the names of the files in a directory as a Lisp list,
2052 or display the names in a buffer using the @code{ls} shell command.  In
2053 the latter case, it can optionally display information about each file,
2054 depending on the options passed to the @code{ls} command.
2056 @defun directory-files directory &optional full-name match-regexp nosort
2057 This function returns a list of the names of the files in the directory
2058 @var{directory}.  By default, the list is in alphabetical order.
2060 If @var{full-name} is non-@code{nil}, the function returns the files'
2061 absolute file names.  Otherwise, it returns the names relative to
2062 the specified directory.
2064 If @var{match-regexp} is non-@code{nil}, this function returns only
2065 those file names that contain a match for that regular expression---the
2066 other file names are excluded from the list.
2068 @c Emacs 19 feature
2069 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2070 the list, so you get the file names in no particular order.  Use this if
2071 you want the utmost possible speed and don't care what order the files
2072 are processed in.  If the order of processing is visible to the user,
2073 then the user will probably be happier if you do sort the names.
2075 @example
2076 @group
2077 (directory-files "~lewis")
2078      @result{} ("#foo#" "#foo.el#" "." ".."
2079          "dired-mods.el" "files.texi" 
2080          "files.texi.~1~")
2081 @end group
2082 @end example
2084 An error is signaled if @var{directory} is not the name of a directory
2085 that can be read.
2086 @end defun
2088 @defun file-name-all-versions file dirname
2089 This function returns a list of all versions of the file named
2090 @var{file} in directory @var{dirname}.
2091 @end defun
2093 @tindex file-expand-wildcards
2094 @defun file-expand-wildcards pattern &optional full
2095 This function expands the wildcard pattern @var{pattern}, returning
2096 a list of file names that match it.
2098 If @var{pattern} is written as an absolute file name,
2099 the values are absolute also.
2101 If @var{pattern} is written as a relative file name, it is interpreted
2102 relative to the current default directory.  The file names returned are
2103 normally also relative to the current default directory.  However, if
2104 @var{full} is non-@code{nil}, they are absolute.
2105 @end defun
2107 @defun insert-directory file switches &optional wildcard full-directory-p
2108 This function inserts (in the current buffer) a directory listing for
2109 directory @var{file}, formatted with @code{ls} according to
2110 @var{switches}.  It leaves point after the inserted text.
2112 The argument @var{file} may be either a directory name or a file
2113 specification including wildcard characters.  If @var{wildcard} is
2114 non-@code{nil}, that means treat @var{file} as a file specification with
2115 wildcards.
2117 If @var{full-directory-p} is non-@code{nil}, that means the directory
2118 listing is expected to show the full contents of a directory.  You
2119 should specify @code{t} when @var{file} is a directory and switches do
2120 not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
2121 describe a directory itself as a file, rather than showing its
2122 contents.)
2124 On most systems, this function works by running a directory listing
2125 program whose name is in the variable @code{insert-directory-program}.
2126 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2127 @code{shell-file-name}, to expand the wildcards.
2129 MS-DOS and MS-Windows systems usually lack the standard Unix program
2130 @code{ls}, so this function emulates the standard Unix program @code{ls}
2131 with Lisp code.
2132 @end defun
2134 @defvar insert-directory-program
2135 This variable's value is the program to run to generate a directory listing
2136 for the function @code{insert-directory}.  It is ignored on systems
2137 which generate the listing with Lisp code.
2138 @end defvar
2140 @node Create/Delete Dirs
2141 @section Creating and Deleting Directories
2142 @c Emacs 19 features
2144   Most Emacs Lisp file-manipulation functions get errors when used on
2145 files that are directories.  For example, you cannot delete a directory
2146 with @code{delete-file}.  These special functions exist to create and
2147 delete directories.
2149 @defun make-directory dirname &optional parents
2150 This function creates a directory named @var{dirname}.
2151 If @var{parents} is non-@code{nil}, that means to create
2152 the parent directories first, if they don't already exist.
2153 @end defun
2155 @defun delete-directory dirname
2156 This function deletes the directory named @var{dirname}.  The function
2157 @code{delete-file} does not work for files that are directories; you
2158 must use @code{delete-directory} for them.  If the directory contains
2159 any files, @code{delete-directory} signals an error.
2160 @end defun
2162 @node Magic File Names
2163 @section Making Certain File Names ``Magic''
2164 @cindex magic file names
2166 @c Emacs 19 feature
2167   You can implement special handling for certain file names.  This is
2168 called making those names @dfn{magic}.  The principal use for this
2169 feature is in implementing remote file names (@pxref{Remote Files,,
2170 Remote Files, emacs, The GNU Emacs Manual}).
2172   To define a kind of magic file name, you must supply a regular
2173 expression to define the class of names (all those that match the
2174 regular expression), plus a handler that implements all the primitive
2175 Emacs file operations for file names that do match.
2177   The variable @code{file-name-handler-alist} holds a list of handlers,
2178 together with regular expressions that determine when to apply each
2179 handler.  Each element has this form:
2181 @example
2182 (@var{regexp} . @var{handler})
2183 @end example
2185 @noindent
2186 All the Emacs primitives for file access and file name transformation
2187 check the given file name against @code{file-name-handler-alist}.  If
2188 the file name matches @var{regexp}, the primitives handle that file by
2189 calling @var{handler}.
2191 The first argument given to @var{handler} is the name of the primitive;
2192 the remaining arguments are the arguments that were passed to that
2193 operation.  (The first of these arguments is typically the file name
2194 itself.)  For example, if you do this:
2196 @example
2197 (file-exists-p @var{filename})
2198 @end example
2200 @noindent
2201 and @var{filename} has handler @var{handler}, then @var{handler} is
2202 called like this:
2204 @example
2205 (funcall @var{handler} 'file-exists-p @var{filename})
2206 @end example
2208 Here are the operations that a magic file name handler gets to handle:
2210 @ifnottex
2211 @noindent
2212 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
2213 @code{delete-file},
2214 @code{diff-latest-backup-file},
2215 @code{directory-file-name},
2216 @code{directory-files},
2217 @code{dired-call-process},
2218 @code{dired-compress-file}, @code{dired-uncache},
2219 @code{expand-file-name},
2220 @code{file-accessible-directory-p},@*
2221 @code{file-attributes},
2222 @code{file-directory-p},
2223 @code{file-executable-p}, @code{file-exists-p},@*
2224 @code{file-local-copy},
2225 @code{file-modes}, @code{file-name-all-completions},@*
2226 @code{file-name-as-directory},
2227 @code{file-name-completion},
2228 @code{file-name-directory},
2229 @code{file-name-nondirectory},
2230 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2231 @code{file-ownership-preserved-p},
2232 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2233 @code{file-truename}, @code{file-writable-p},
2234 @code{find-backup-file-name},
2235 @code{get-file-buffer},@*
2236 @code{insert-directory},
2237 @code{insert-file-contents},
2238 @code{load}, @code{make-directory},
2239 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
2240 @code{set-visited-file-modtime}, @code{shell-command},@*
2241 @code{unhandled-file-name-directory},
2242 @code{vc-registered},
2243 @code{verify-visited-file-modtime},@*
2244 @code{write-region}.
2245 @end ifnottex
2246 @iftex
2247 @noindent
2248 @flushleft
2249 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
2250 @code{delete-file},
2251 @code{diff-latest-backup-file},
2252 @code{directory-file-name},
2253 @code{directory-files},
2254 @code{dired-call-process},
2255 @code{dired-compress-file}, @code{dired-uncache},
2256 @code{expand-file-name},
2257 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2258 @code{file-attributes},
2259 @code{file-direct@discretionary{}{}{}ory-p},
2260 @code{file-executable-p}, @code{file-exists-p},
2261 @code{file-local-copy},
2262 @code{file-modes}, @code{file-name-all-completions},
2263 @code{file-name-as-directory},
2264 @code{file-name-completion},
2265 @code{file-name-directory},
2266 @code{file-name-nondirec@discretionary{}{}{}tory},
2267 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2268 @code{file-ownership-pre@discretionary{}{}{}served-p},
2269 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2270 @code{file-truename}, @code{file-writable-p},
2271 @code{find-backup-file-name},
2272 @code{get-file-buffer},
2273 @code{insert-directory},
2274 @code{insert-file-contents},
2275 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2276 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
2277 @code{set-visited-file-modtime}, @code{shell-command},
2278 @code{unhandled-file-name-directory},
2279 @code{vc-regis@discretionary{}{}{}tered},
2280 @code{verify-visited-file-modtime},
2281 @code{write-region}.
2282 @end flushleft
2283 @end iftex
2285 Handlers for @code{insert-file-contents} typically need to clear the
2286 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2287 @var{visit} argument is non-@code{nil}.  This also has the effect of
2288 unlocking the buffer if it is locked.
2290 The handler function must handle all of the above operations, and
2291 possibly others to be added in the future.  It need not implement all
2292 these operations itself---when it has nothing special to do for a
2293 certain operation, it can reinvoke the primitive, to handle the
2294 operation ``in the usual way''.  It should always reinvoke the primitive
2295 for an operation it does not recognize.  Here's one way to do this:
2297 @smallexample
2298 (defun my-file-handler (operation &rest args)
2299   ;; @r{First check for the specific operations}
2300   ;; @r{that we have special handling for.}
2301   (cond ((eq operation 'insert-file-contents) @dots{})
2302         ((eq operation 'write-region) @dots{})
2303         @dots{}
2304         ;; @r{Handle any operation we don't know about.}
2305         (t (let ((inhibit-file-name-handlers
2306                   (cons 'my-file-handler 
2307                         (and (eq inhibit-file-name-operation operation)
2308                              inhibit-file-name-handlers)))
2309                  (inhibit-file-name-operation operation))
2310              (apply operation args)))))
2311 @end smallexample
2313 When a handler function decides to call the ordinary Emacs primitive for
2314 the operation at hand, it needs to prevent the primitive from calling
2315 the same handler once again, thus leading to an infinite recursion.  The
2316 example above shows how to do this, with the variables
2317 @code{inhibit-file-name-handlers} and
2318 @code{inhibit-file-name-operation}.  Be careful to use them exactly as
2319 shown above; the details are crucial for proper behavior in the case of
2320 multiple handlers, and for operations that have two file names that may
2321 each have handlers.
2323 @defvar inhibit-file-name-handlers
2324 This variable holds a list of handlers whose use is presently inhibited
2325 for a certain operation.
2326 @end defvar
2328 @defvar inhibit-file-name-operation
2329 The operation for which certain handlers are presently inhibited.
2330 @end defvar
2332 @defun find-file-name-handler file operation
2333 This function returns the handler function for file name @var{file}, or
2334 @code{nil} if there is none.  The argument @var{operation} should be the
2335 operation to be performed on the file---the value you will pass to the
2336 handler as its first argument when you call it.  The operation is needed
2337 for comparison with @code{inhibit-file-name-operation}.
2338 @end defun
2340 @defun file-local-copy filename
2341 This function copies file @var{filename} to an ordinary non-magic file,
2342 if it isn't one already.
2344 If @var{filename} specifies a magic file name, which programs
2345 outside Emacs cannot directly read or write, this copies the contents to
2346 an ordinary file and returns that file's name.
2348 If @var{filename} is an ordinary file name, not magic, then this function
2349 does nothing and returns @code{nil}.
2350 @end defun
2352 @defun unhandled-file-name-directory filename
2353 This function returns the name of a directory that is not magic.  It
2354 uses the directory part of @var{filename} if that is not magic.  For a
2355 magic file name, it invokes the file name handler, which therefore
2356 decides what value to return.
2358 This is useful for running a subprocess; every subprocess must have a
2359 non-magic directory to serve as its current directory, and this function
2360 is a good way to come up with one.
2361 @end defun
2363 @node Format Conversion
2364 @section File Format Conversion
2366 @cindex file format conversion
2367 @cindex encoding file formats
2368 @cindex decoding file formats
2369   The variable @code{format-alist} defines a list of @dfn{file formats},
2370 which describe textual representations used in files for the data (text,
2371 text-properties, and possibly other information) in an Emacs buffer.
2372 Emacs performs format conversion if appropriate when reading and writing
2373 files.
2375 @defvar format-alist
2376 This list contains one format definition for each defined file format.
2377 @end defvar
2379 @cindex format definition
2380 Each format definition is a list of this form:
2382 @example
2383 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2384 @end example
2386 Here is what the elements in a format definition mean:
2388 @table @var
2389 @item name
2390 The name of this format.
2392 @item doc-string
2393 A documentation string for the format.
2395 @item regexp
2396 A regular expression which is used to recognize files represented in
2397 this format.
2399 @item from-fn
2400 A shell command or function to decode data in this format (to convert
2401 file data into the usual Emacs data representation).
2403 A shell command is represented as a string; Emacs runs the command as a
2404 filter to perform the conversion.
2406 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2407 and @var{end}, which specify the part of the buffer it should convert.
2408 It should convert the text by editing it in place.  Since this can
2409 change the length of the text, @var{from-fn} should return the modified
2410 end position.
2412 One responsibility of @var{from-fn} is to make sure that the beginning
2413 of the file no longer matches @var{regexp}.  Otherwise it is likely to
2414 get called again.
2416 @item to-fn
2417 A shell command or function to encode data in this format---that is, to
2418 convert the usual Emacs data representation into this format.
2420 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2421 command as a filter to perform the conversion.
2423 If @var{to-fn} is a function, it is called with two arguments, @var{begin}
2424 and @var{end}, which specify the part of the buffer it should convert.
2425 There are two ways it can do the conversion:
2427 @itemize @bullet
2428 @item
2429 By editing the buffer in place.  In this case, @var{to-fn} should
2430 return the end-position of the range of text, as modified.
2432 @item
2433 By returning a list of annotations.  This is a list of elements of the
2434 form @code{(@var{position} . @var{string})}, where @var{position} is an
2435 integer specifying the relative position in the text to be written, and
2436 @var{string} is the annotation to add there.  The list must be sorted in
2437 order of position when @var{to-fn} returns it.
2439 When @code{write-region} actually writes the text from the buffer to the
2440 file, it intermixes the specified annotations at the corresponding
2441 positions.  All this takes place without modifying the buffer.
2442 @end itemize
2444 @item modify
2445 A flag, @code{t} if the encoding function modifies the buffer, and
2446 @code{nil} if it works by returning a list of annotations.
2448 @item mode-fn
2449 A minor-mode function to call after visiting a file converted from this
2450 format.  The function is called with one argument, the integer 1;
2451 that tells a minor-mode function to enable the mode.
2452 @end table
2454 The function @code{insert-file-contents} automatically recognizes file
2455 formats when it reads the specified file.  It checks the text of the
2456 beginning of the file against the regular expressions of the format
2457 definitions, and if it finds a match, it calls the decoding function for
2458 that format.  Then it checks all the known formats over again.
2459 It keeps checking them until none of them is applicable.
2461 Visiting a file, with @code{find-file-noselect} or the commands that use
2462 it, performs conversion likewise (because it calls
2463 @code{insert-file-contents}); it also calls the mode function for each
2464 format that it decodes.  It stores a list of the format names in the
2465 buffer-local variable @code{buffer-file-format}.
2467 @defvar buffer-file-format
2468 This variable states the format of the visited file.  More precisely,
2469 this is a list of the file format names that were decoded in the course
2470 of visiting the current buffer's file.  It is always buffer-local in all
2471 buffers.
2472 @end defvar
2474 When @code{write-region} writes data into a file, it first calls the
2475 encoding functions for the formats listed in @code{buffer-file-format},
2476 in the order of appearance in the list.
2478 @deffn Command format-write-file file format
2479 This command writes the current buffer contents into the file @var{file}
2480 in format @var{format}, and makes that format the default for future
2481 saves of the buffer.  The argument @var{format} is a list of format
2482 names.
2483 @end deffn
2485 @deffn Command format-find-file file format
2486 This command finds the file @var{file}, converting it according to
2487 format @var{format}.  It also makes @var{format} the default if the
2488 buffer is saved later.
2490 The argument @var{format} is a list of format names.  If @var{format} is
2491 @code{nil}, no conversion takes place.  Interactively, typing just
2492 @key{RET} for @var{format} specifies @code{nil}.
2493 @end deffn
2495 @deffn Command format-insert-file file format &optional beg end
2496 This command inserts the contents of file @var{file}, converting it
2497 according to format @var{format}.  If @var{beg} and @var{end} are
2498 non-@code{nil}, they specify which part of the file to read, as in
2499 @code{insert-file-contents} (@pxref{Reading from Files}).
2501 The return value is like what @code{insert-file-contents} returns: a
2502 list of the absolute file name and the length of the data inserted
2503 (after conversion).
2505 The argument @var{format} is a list of format names.  If @var{format} is
2506 @code{nil}, no conversion takes place.  Interactively, typing just
2507 @key{RET} for @var{format} specifies @code{nil}.
2508 @end deffn
2510 @defvar auto-save-file-format
2511 This variable specifies the format to use for auto-saving.  Its value is
2512 a list of format names, just like the value of
2513 @code{buffer-file-format}; however, it is used instead of
2514 @code{buffer-file-format} for writing auto-save files.  This variable is
2515 always buffer-local in all buffers.
2516 @end defvar