2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005, 2006 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
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}).
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.
48 @section Visiting 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
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.
75 * Visiting Functions:: The usual interface functions for visiting.
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
79 @node Visiting Functions
80 @subsection Functions for Visiting Files
82 This section describes the functions normally used to visit files.
83 For historical reasons, these functions have names starting with
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
85 functions and variables that access the visited file name of a buffer or
86 that find an existing buffer by its visited file name.
88 In a Lisp program, if you want to look at the contents of a file but
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
90 temporary buffer. Visiting the file is not necessary and takes longer.
91 @xref{Reading from Files}.
93 @deffn Command find-file filename &optional wildcards
94 This command selects a buffer visiting the file @var{filename},
95 using an existing buffer if there is one, and otherwise creating a
96 new buffer and reading the file into it. It also returns that buffer.
98 Aside from some technical details, the body of the @code{find-file}
99 function is basically equivalent to:
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
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.
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-hook}.
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-functions} 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
153 The @code{find-file-noselect} function usually returns the buffer that
154 is visiting the file @var{filename}. But, if wildcards are actually
155 used and expanded, it returns a list of buffers that are visiting the
160 (find-file-noselect "/etc/fstab")
161 @result{} #<buffer fstab>
166 @deffn Command find-file-other-window filename &optional wildcards
167 This command selects a buffer visiting the file @var{filename}, but
168 does so in a window other than the selected window. It may use another
169 existing window or split a window; see @ref{Displaying Buffers}.
171 When this command is called interactively, it prompts for
175 @deffn Command find-file-read-only filename &optional wildcards
176 This command selects a buffer visiting the file @var{filename}, like
177 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
178 Buffers}, for related functions and variables.
180 When this command is called interactively, it prompts for
184 @deffn Command view-file filename
185 This command visits @var{filename} using View mode, returning to the
186 previous buffer when you exit View mode. View mode is a minor mode that
187 provides commands to skim rapidly through the file, but does not let you
188 modify the text. Entering View mode runs the normal hook
189 @code{view-mode-hook}. @xref{Hooks}.
191 When @code{view-file} is called interactively, it prompts for
195 @tindex find-file-wildcards
196 @defopt find-file-wildcards
197 If this variable is non-@code{nil}, then the various @code{find-file}
198 commands check for wildcard characters and visit all the files that
199 match them (when invoked interactively or when their @var{wildcards}
200 argument is non-@code{nil}). If this option is @code{nil}, then
201 the @code{find-file} commands ignore their @var{wildcards} argument
202 and never treat wildcard characters specially.
205 @defvar find-file-hook
206 The value of this variable is a list of functions to be called after a
207 file is visited. The file's local-variables specification (if any) will
208 have been processed before the hooks are run. The buffer visiting the
209 file is current when the hook functions are run.
211 This variable is a normal hook. @xref{Hooks}.
214 @defvar find-file-not-found-functions
215 The value of this variable is a list of functions to be called when
216 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
217 file name. @code{find-file-noselect} calls these functions as soon as
218 it detects a nonexistent file. It calls them in the order of the list,
219 until one of them returns non-@code{nil}. @code{buffer-file-name} is
222 This is not a normal hook because the values of the functions are
223 used, and in many cases only some of the functions are called.
226 @node Subroutines of Visiting
227 @comment node-name, next, previous, up
228 @subsection Subroutines of Visiting
230 The @code{find-file-noselect} function uses two important subroutines
231 which are sometimes useful in user Lisp code: @code{create-file-buffer}
232 and @code{after-find-file}. This section explains how to use them.
234 @defun create-file-buffer filename
235 This function creates a suitably named buffer for visiting
236 @var{filename}, and returns it. It uses @var{filename} (sans directory)
237 as the name if that name is free; otherwise, it appends a string such as
238 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
240 @strong{Please note:} @code{create-file-buffer} does @emph{not}
241 associate the new buffer with a file and does not select the buffer.
242 It also does not use the default major mode.
246 (create-file-buffer "foo")
247 @result{} #<buffer foo>
250 (create-file-buffer "foo")
251 @result{} #<buffer foo<2>>
254 (create-file-buffer "foo")
255 @result{} #<buffer foo<3>>
259 This function is used by @code{find-file-noselect}.
260 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
263 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
264 This function sets the buffer major mode, and parses local variables
265 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
266 and by the default revert function (@pxref{Reverting}).
268 @cindex new file message
269 @cindex file open error
270 If reading the file got an error because the file does not exist, but
271 its directory does exist, the caller should pass a non-@code{nil} value
272 for @var{error}. In that case, @code{after-find-file} issues a warning:
273 @samp{(New file)}. For more serious errors, the caller should usually not
274 call @code{after-find-file}.
276 If @var{warn} is non-@code{nil}, then this function issues a warning
277 if an auto-save file exists and is more recent than the visited file.
279 If @var{noauto} is non-@code{nil}, that says not to enable or disable
280 Auto-Save mode. The mode remains enabled if it was enabled before.
282 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
283 means this call was from @code{revert-buffer}. This has no direct
284 effect, but some mode functions and hook functions check the value
287 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
288 major mode, don't process local variables specifications in the file,
289 and don't run @code{find-file-hook}. This feature is used by
290 @code{revert-buffer} in some cases.
292 The last thing @code{after-find-file} does is call all the functions
293 in the list @code{find-file-hook}.
297 @section Saving Buffers
299 When you edit a file in Emacs, you are actually working on a buffer
300 that is visiting that file---that is, the contents of the file are
301 copied into the buffer and the copy is what you edit. Changes to the
302 buffer do not change the file until you @dfn{save} the buffer, which
303 means copying the contents of the buffer into the file.
305 @deffn Command save-buffer &optional backup-option
306 This function saves the contents of the current buffer in its visited
307 file if the buffer has been modified since it was last visited or saved.
308 Otherwise it does nothing.
310 @code{save-buffer} is responsible for making backup files. Normally,
311 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
312 file only if this is the first save since visiting the file. Other
313 values for @var{backup-option} request the making of backup files in
318 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
319 @code{save-buffer} function marks this version of the file to be
320 backed up when the buffer is next saved.
323 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
324 @code{save-buffer} function unconditionally backs up the previous
325 version of the file before saving it.
328 With an argument of 0, unconditionally do @emph{not} make any backup file.
332 @deffn Command save-some-buffers &optional save-silently-p pred
333 @anchor{Definition of save-some-buffers}
334 This command saves some modified file-visiting buffers. Normally it
335 asks the user about each buffer. But if @var{save-silently-p} is
336 non-@code{nil}, it saves all the file-visiting buffers without querying
339 The optional @var{pred} argument controls which buffers to ask about
340 (or to save silently if @var{save-silently-p} is non-@code{nil}).
341 If it is @code{nil}, that means to ask only about file-visiting buffers.
342 If it is @code{t}, that means also offer to save certain other non-file
343 buffers---those that have a non-@code{nil} buffer-local value of
344 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
345 @samp{yes} to saving a non-file buffer is asked to specify the file
346 name to use. The @code{save-buffers-kill-emacs} function passes the
347 value @code{t} for @var{pred}.
349 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
350 a function of no arguments. It will be called in each buffer to decide
351 whether to offer to save that buffer. If it returns a non-@code{nil}
352 value in a certain buffer, that means do offer to save that buffer.
355 @deffn Command write-file filename &optional confirm
356 @anchor{Definition of write-file}
357 This function writes the current buffer into file @var{filename}, makes
358 the buffer visit that file, and marks it not modified. Then it renames
359 the buffer based on @var{filename}, appending a string like @samp{<2>}
360 if necessary to make a unique buffer name. It does most of this work by
361 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
364 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
365 before overwriting an existing file. Interactively, confirmation is
366 required, unless the user supplies a prefix argument.
368 If @var{filename} is an existing directory, or a symbolic link to one,
369 @code{write-file} uses the name of the visited file, in directory
370 @var{filename}. If the buffer is not visiting a file, it uses the
374 Saving a buffer runs several hooks. It also performs format
375 conversion (@pxref{Format Conversion}), and may save text properties in
376 ``annotations'' (@pxref{Saving Properties}).
378 @defvar write-file-functions
379 The value of this variable is a list of functions to be called before
380 writing out a buffer to its visited file. If one of them returns
381 non-@code{nil}, the file is considered already written and the rest of
382 the functions are not called, nor is the usual code for writing the file
385 If a function in @code{write-file-functions} returns non-@code{nil}, it
386 is responsible for making a backup file (if that is appropriate).
387 To do so, execute the following code:
390 (or buffer-backed-up (backup-buffer))
393 You might wish to save the file modes value returned by
394 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
395 bits of the file that you write. This is what @code{save-buffer}
396 normally does. @xref{Making Backups,, Making Backup Files}.
398 The hook functions in @code{write-file-functions} are also responsible for
399 encoding the data (if desired): they must choose a suitable coding
400 system (@pxref{Lisp and Coding Systems}), perform the encoding
401 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
402 the coding system that was used (@pxref{Encoding and I/O}).
404 If you set this hook locally in a buffer, it is assumed to be
405 associated with the file or the way the contents of the buffer were
406 obtained. Thus the variable is marked as a permanent local, so that
407 changing the major mode does not alter a buffer-local value. On the
408 other hand, calling @code{set-visited-file-name} will reset it.
409 If this is not what you want, you might like to use
410 @code{write-contents-functions} instead.
412 Even though this is not a normal hook, you can use @code{add-hook} and
413 @code{remove-hook} to manipulate the list. @xref{Hooks}.
417 @defvar write-contents-functions
418 This works just like @code{write-file-functions}, but it is intended
419 for hooks that pertain to the buffer's contents, not to the particular
420 visited file or its location. Such hooks are usually set up by major
421 modes, as buffer-local bindings for this variable. This variable
422 automatically becomes buffer-local whenever it is set; switching to a
423 new major mode always resets this variable, but calling
424 @code{set-visited-file-name} does not.
426 If any of the functions in this hook returns non-@code{nil}, the file
427 is considered already written and the rest are not called and neither
428 are the functions in @code{write-file-functions}.
431 @defopt before-save-hook
432 This normal hook runs before a buffer is saved in its visited file,
433 regardless of whether that is done normally or by one of the hooks
434 described above. For instance, the @file{copyright.el} program uses
435 this hook to make sure the file you are saving has the current year in
436 its copyright notice.
440 @defopt after-save-hook
441 This normal hook runs after a buffer has been saved in its visited file.
442 One use of this hook is in Fast Lock mode; it uses this hook to save the
443 highlighting information in a cache file.
446 @defopt file-precious-flag
447 If this variable is non-@code{nil}, then @code{save-buffer} protects
448 against I/O errors while saving by writing the new file to a temporary
449 name instead of the name it is supposed to have, and then renaming it to
450 the intended name after it is clear there are no errors. This procedure
451 prevents problems such as a lack of disk space from resulting in an
454 As a side effect, backups are necessarily made by copying. @xref{Rename
455 or Copy}. Yet, at the same time, saving a precious file always breaks
456 all hard links between the file you save and other file names.
458 Some modes give this variable a non-@code{nil} buffer-local value
459 in particular buffers.
462 @defopt require-final-newline
463 This variable determines whether files may be written out that do
464 @emph{not} end with a newline. If the value of the variable is
465 @code{t}, then @code{save-buffer} silently adds a newline at the end of
466 the file whenever the buffer being saved does not already end in one.
467 If the value of the variable is non-@code{nil}, but not @code{t}, then
468 @code{save-buffer} asks the user whether to add a newline each time the
471 If the value of the variable is @code{nil}, then @code{save-buffer}
472 doesn't add newlines at all. @code{nil} is the default value, but a few
473 major modes set it to @code{t} in particular buffers.
476 See also the function @code{set-visited-file-name} (@pxref{Buffer File
479 @node Reading from Files
480 @comment node-name, next, previous, up
481 @section Reading from Files
483 You can copy a file from the disk and insert it into a buffer
484 using the @code{insert-file-contents} function. Don't use the user-level
485 command @code{insert-file} in a Lisp program, as that sets the mark.
487 @defun insert-file-contents filename &optional visit beg end replace
488 This function inserts the contents of file @var{filename} into the
489 current buffer after point. It returns a list of the absolute file name
490 and the length of the data inserted. An error is signaled if
491 @var{filename} is not the name of a file that can be read.
493 The function @code{insert-file-contents} checks the file contents
494 against the defined file formats, and converts the file contents if
495 appropriate. @xref{Format Conversion}. It also calls the functions in
496 the list @code{after-insert-file-functions}; see @ref{Saving
497 Properties}. Normally, one of the functions in the
498 @code{after-insert-file-functions} list determines the coding system
499 (@pxref{Coding Systems}) used for decoding the file's contents.
501 If @var{visit} is non-@code{nil}, this function additionally marks the
502 buffer as unmodified and sets up various fields in the buffer so that it
503 is visiting the file @var{filename}: these include the buffer's visited
504 file name and its last save file modtime. This feature is used by
505 @code{find-file-noselect} and you probably should not use it yourself.
507 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
508 specifying the portion of the file to insert. In this case, @var{visit}
509 must be @code{nil}. For example,
512 (insert-file-contents filename nil 0 500)
516 inserts the first 500 characters of a file.
518 If the argument @var{replace} is non-@code{nil}, it means to replace the
519 contents of the buffer (actually, just the accessible portion) with the
520 contents of the file. This is better than simply deleting the buffer
521 contents and inserting the whole file, because (1) it preserves some
522 marker positions and (2) it puts less data in the undo list.
524 It is possible to read a special file (such as a FIFO or an I/O device)
525 with @code{insert-file-contents}, as long as @var{replace} and
526 @var{visit} are @code{nil}.
529 @defun insert-file-contents-literally filename &optional visit beg end replace
530 This function works like @code{insert-file-contents} except that it does
531 not do format decoding (@pxref{Format Conversion}), does not do
532 character code conversion (@pxref{Coding Systems}), does not run
533 @code{find-file-hook}, does not perform automatic uncompression, and so
537 If you want to pass a file name to another process so that another
538 program can read the file, use the function @code{file-local-copy}; see
539 @ref{Magic File Names}.
541 @node Writing to Files
542 @comment node-name, next, previous, up
543 @section Writing to Files
545 You can write the contents of a buffer, or part of a buffer, directly
546 to a file on disk using the @code{append-to-file} and
547 @code{write-region} functions. Don't use these functions to write to
548 files that are being visited; that could cause confusion in the
549 mechanisms for visiting.
551 @deffn Command append-to-file start end filename
552 This function appends the contents of the region delimited by
553 @var{start} and @var{end} in the current buffer to the end of file
554 @var{filename}. If that file does not exist, it is created. This
555 function returns @code{nil}.
557 An error is signaled if @var{filename} specifies a nonwritable file,
558 or a nonexistent file in a directory where files cannot be created.
560 When called from Lisp, this function is completely equivalent to:
563 (write-region start end filename t)
567 @deffn Command write-region start end filename &optional append visit lockname mustbenew
568 This function writes the region delimited by @var{start} and @var{end}
569 in the current buffer into the file specified by @var{filename}.
571 If @var{start} is @code{nil}, then the command writes the entire buffer
572 contents (@emph{not} just the accessible portion) to the file and
576 If @var{start} is a string, then @code{write-region} writes or appends
577 that string, rather than text from the buffer. @var{end} is ignored in
580 If @var{append} is non-@code{nil}, then the specified text is appended
581 to the existing file contents (if any). If @var{append} is an
582 integer, @code{write-region} seeks to that byte offset from the start
583 of the file and writes the data from there.
585 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
586 for confirmation if @var{filename} names an existing file. If
587 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
588 does not ask for confirmation, but instead it signals an error
589 @code{file-already-exists} if the file already exists.
591 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
592 a special system feature. At least for files on a local disk, there is
593 no chance that some other program could create a file of the same name
594 before Emacs does, without Emacs's noticing.
596 If @var{visit} is @code{t}, then Emacs establishes an association
597 between the buffer and the file: the buffer is then visiting that file.
598 It also sets the last file modification time for the current buffer to
599 @var{filename}'s modtime, and marks the buffer as not modified. This
600 feature is used by @code{save-buffer}, but you probably should not use
604 If @var{visit} is a string, it specifies the file name to visit. This
605 way, you can write the data to one file (@var{filename}) while recording
606 the buffer as visiting another file (@var{visit}). The argument
607 @var{visit} is used in the echo area message and also for file locking;
608 @var{visit} is stored in @code{buffer-file-name}. This feature is used
609 to implement @code{file-precious-flag}; don't use it yourself unless you
610 really know what you're doing.
612 The optional argument @var{lockname}, if non-@code{nil}, specifies the
613 file name to use for purposes of locking and unlocking, overriding
614 @var{filename} and @var{visit} for that purpose.
616 The function @code{write-region} converts the data which it writes to
617 the appropriate file formats specified by @code{buffer-file-format}.
618 @xref{Format Conversion}. It also calls the functions in the list
619 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
621 Normally, @code{write-region} displays the message @samp{Wrote
622 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
623 nor @code{nil} nor a string, then this message is inhibited. This
624 feature is useful for programs that use files for internal purposes,
625 files that the user does not need to know about.
628 @defmac with-temp-file file body@dots{}
629 @anchor{Definition of with-temp-file}
630 The @code{with-temp-file} macro evaluates the @var{body} forms with a
631 temporary buffer as the current buffer; then, at the end, it writes the
632 buffer contents into file @var{file}. It kills the temporary buffer
633 when finished, restoring the buffer that was current before the
634 @code{with-temp-file} form. Then it returns the value of the last form
637 The current buffer is restored even in case of an abnormal exit via
638 @code{throw} or error (@pxref{Nonlocal Exits}).
640 See also @code{with-temp-buffer} in @ref{Definition of
641 with-temp-buffer,, The Current Buffer}.
648 When two users edit the same file at the same time, they are likely
649 to interfere with each other. Emacs tries to prevent this situation
650 from arising by recording a @dfn{file lock} when a file is being
651 modified. (File locks are not implemented on Microsoft systems.)
652 Emacs can then detect the first attempt to modify a buffer visiting a
653 file that is locked by another Emacs job, and ask the user what to do.
654 The file lock is really a file, a symbolic link with a special name,
655 stored in the same directory as the file you are editing.
657 When you access files using NFS, there may be a small probability that
658 you and another user will both lock the same file ``simultaneously''.
659 If this happens, it is possible for the two users to make changes
660 simultaneously, but Emacs will still warn the user who saves second.
661 Also, the detection of modification of a buffer visiting a file changed
662 on disk catches some cases of simultaneous editing; see
663 @ref{Modification Time}.
665 @defun file-locked-p filename
666 This function returns @code{nil} if the file @var{filename} is not
667 locked. It returns @code{t} if it is locked by this Emacs process, and
668 it returns the name of the user who has locked it if it is locked by
673 (file-locked-p "foo")
679 @defun lock-buffer &optional filename
680 This function locks the file @var{filename}, if the current buffer is
681 modified. The argument @var{filename} defaults to the current buffer's
682 visited file. Nothing is done if the current buffer is not visiting a
683 file, or is not modified, or if the system does not support locking.
687 This function unlocks the file being visited in the current buffer,
688 if the buffer is modified. If the buffer is not modified, then
689 the file should not be locked, so this function does nothing. It also
690 does nothing if the current buffer is not visiting a file, or if the
691 system does not support locking.
694 File locking is not supported on some systems. On systems that do not
695 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
696 @code{file-locked-p} do nothing and return @code{nil}.
698 @defun ask-user-about-lock file other-user
699 This function is called when the user tries to modify @var{file}, but it
700 is locked by another user named @var{other-user}. The default
701 definition of this function asks the user to say what to do. The value
702 this function returns determines what Emacs does next:
706 A value of @code{t} says to grab the lock on the file. Then
707 this user may edit the file and @var{other-user} loses the lock.
710 A value of @code{nil} says to ignore the lock and let this
711 user edit the file anyway.
715 This function may instead signal a @code{file-locked} error, in which
716 case the change that the user was about to make does not take place.
718 The error message for this error looks like this:
721 @error{} File is locked: @var{file} @var{other-user}
725 where @code{file} is the name of the file and @var{other-user} is the
726 name of the user who has locked the file.
729 If you wish, you can replace the @code{ask-user-about-lock} function
730 with your own version that makes the decision in another way. The code
731 for its usual definition is in @file{userlock.el}.
734 @node Information about Files
735 @section Information about Files
737 The functions described in this section all operate on strings that
738 designate file names. With a few exceptions, all the functions have
739 names that begin with the word @samp{file}. These functions all
740 return information about actual files or directories, so their
741 arguments must all exist as actual files or directories unless
745 * Testing Accessibility:: Is a given file readable? Writable?
746 * Kinds of Files:: Is it a directory? A symbolic link?
747 * Truenames:: Eliminating symbolic links from a file name.
748 * File Attributes:: How large is it? Any other names? Etc.
749 * Locating Files:: How to find a file in standard places.
752 @node Testing Accessibility
753 @comment node-name, next, previous, up
754 @subsection Testing Accessibility
755 @cindex accessibility of a file
756 @cindex file accessibility
758 These functions test for permission to access a file in specific
759 ways. Unless explicitly stated otherwise, they recursively follow
760 symbolic links for their file name arguments, at all levels (at the
761 level of the file itself and at all levels of parent directories).
763 @defun file-exists-p filename
764 This function returns @code{t} if a file named @var{filename} appears
765 to exist. This does not mean you can necessarily read the file, only
766 that you can find out its attributes. (On Unix and GNU/Linux, this is
767 true if the file exists and you have execute permission on the
768 containing directories, regardless of the protection of the file
771 If the file does not exist, or if fascist access control policies
772 prevent you from finding the attributes of the file, this function
775 Directories are files, so @code{file-exists-p} returns @code{t} when
776 given a directory name. However, symbolic links are treated
777 specially; @code{file-exists-p} returns @code{t} for a symbolic link
778 name only if the target file exists.
781 @defun file-readable-p filename
782 This function returns @code{t} if a file named @var{filename} exists
783 and you can read it. It returns @code{nil} otherwise.
787 (file-readable-p "files.texi")
791 (file-exists-p "/usr/spool/mqueue")
795 (file-readable-p "/usr/spool/mqueue")
802 @defun file-executable-p filename
803 This function returns @code{t} if a file named @var{filename} exists and
804 you can execute it. It returns @code{nil} otherwise. On Unix and
805 GNU/Linux, if the file is a directory, execute permission means you can
806 check the existence and attributes of files inside the directory, and
807 open those files if their modes permit.
810 @defun file-writable-p filename
811 This function returns @code{t} if the file @var{filename} can be written
812 or created by you, and @code{nil} otherwise. A file is writable if the
813 file exists and you can write it. It is creatable if it does not exist,
814 but the specified directory does exist and you can write in that
817 In the third example below, @file{foo} is not writable because the
818 parent directory does not exist, even though the user could create such
823 (file-writable-p "~/foo")
827 (file-writable-p "/foo")
831 (file-writable-p "~/no-such-dir/foo")
838 @defun file-accessible-directory-p dirname
839 This function returns @code{t} if you have permission to open existing
840 files in the directory whose name as a file is @var{dirname};
841 otherwise (or if there is no such directory), it returns @code{nil}.
842 The value of @var{dirname} may be either a directory name (such as
843 @file{/foo/}) or the file name of a file which is a directory
844 (such as @file{/foo}, without the final slash).
846 Example: after the following,
849 (file-accessible-directory-p "/foo")
854 we can deduce that any attempt to read a file in @file{/foo/} will
858 @defun access-file filename string
859 This function opens file @var{filename} for reading, then closes it and
860 returns @code{nil}. However, if the open fails, it signals an error
861 using @var{string} as the error message text.
864 @defun file-ownership-preserved-p filename
865 This function returns @code{t} if deleting the file @var{filename} and
866 then creating it anew would keep the file's owner unchanged. It also
867 returns @code{t} for nonexistent files.
869 If @var{filename} is a symbolic link, then, unlike the other functions
870 discussed here, @code{file-ownership-preserved-p} does @emph{not}
871 replace @var{filename} with its target. However, it does recursively
872 follow symbolic links at all levels of parent directories.
875 @defun file-newer-than-file-p filename1 filename2
877 @cindex file modification time
878 This function returns @code{t} if the file @var{filename1} is
879 newer than file @var{filename2}. If @var{filename1} does not
880 exist, it returns @code{nil}. If @var{filename1} does exist, but
881 @var{filename2} does not, it returns @code{t}.
883 In the following example, assume that the file @file{aug-19} was written
884 on the 19th, @file{aug-20} was written on the 20th, and the file
885 @file{no-file} doesn't exist at all.
889 (file-newer-than-file-p "aug-19" "aug-20")
893 (file-newer-than-file-p "aug-20" "aug-19")
897 (file-newer-than-file-p "aug-19" "no-file")
901 (file-newer-than-file-p "no-file" "aug-19")
906 You can use @code{file-attributes} to get a file's last modification
907 time as a list of two numbers. @xref{File Attributes}.
911 @comment node-name, next, previous, up
912 @subsection Distinguishing Kinds of Files
914 This section describes how to distinguish various kinds of files, such
915 as directories, symbolic links, and ordinary files.
917 @defun file-symlink-p filename
918 @cindex file symbolic links
919 If the file @var{filename} is a symbolic link, the
920 @code{file-symlink-p} function returns the (non-recursive) link target
921 as a string. (Determining the file name that the link points to from
922 the target is nontrivial.) First, this function recursively follows
923 symbolic links at all levels of parent directories.
925 If the file @var{filename} is not a symbolic link (or there is no such file),
926 @code{file-symlink-p} returns @code{nil}.
930 (file-symlink-p "foo")
934 (file-symlink-p "sym-link")
938 (file-symlink-p "sym-link2")
942 (file-symlink-p "/bin")
947 @c !!! file-symlink-p: should show output of ls -l for comparison
950 The next two functions recursively follow symbolic links at
951 all levels for @var{filename}.
953 @defun file-directory-p filename
954 This function returns @code{t} if @var{filename} is the name of an
955 existing directory, @code{nil} otherwise.
959 (file-directory-p "~rms")
963 (file-directory-p "~rms/lewis/files.texi")
967 (file-directory-p "~rms/lewis/no-such-file")
971 (file-directory-p "$HOME")
976 (substitute-in-file-name "$HOME"))
982 @defun file-regular-p filename
983 This function returns @code{t} if the file @var{filename} exists and is
984 a regular file (not a directory, named pipe, terminal, or
989 @subsection Truenames
990 @cindex truename (of file)
993 The @dfn{truename} of a file is the name that you get by following
994 symbolic links at all levels until none remain, then simplifying away
995 @samp{.}@: and @samp{..}@: appearing as name components. This results
996 in a sort of canonical name for the file. A file does not always have a
997 unique truename; the number of distinct truenames a file has is equal to
998 the number of hard links to the file. However, truenames are useful
999 because they eliminate symbolic links as a cause of name variation.
1001 @defun file-truename filename
1002 The function @code{file-truename} returns the truename of the file
1003 @var{filename}. The argument must be an absolute file name.
1005 This function does not expand environment variables. Only
1006 @code{substitute-in-file-name} does that. @xref{Definition of
1007 substitute-in-file-name}.
1009 If you may need to follow symbolic links preceding @samp{..}@:
1010 appearing as a name component, you should make sure to call
1011 @code{file-truename} without prior direct or indirect calls to
1012 @code{expand-file-name}, as otherwise the file name component
1013 immediately preceding @samp{..} will be ``simplified away'' before
1014 @code{file-truename} is called. To eliminate the need for a call to
1015 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1016 same way that @code{expand-file-name} does. @xref{File Name
1017 Expansion,, Functions that Expand Filenames}.
1020 @defun file-chase-links filename &optional limit
1021 This function follows symbolic links, starting with @var{filename},
1022 until it finds a file name which is not the name of a symbolic link.
1023 Then it returns that file name. This function does @emph{not} follow
1024 symbolic links at the level of parent directories.
1026 If you specify a number for @var{limit}, then after chasing through
1027 that many links, the function just returns what it has even if that is
1028 still a symbolic link.
1031 To illustrate the difference between @code{file-chase-links} and
1032 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1033 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1034 ordinary file (or at least, not a symbolic link) or nonexistent. Then
1038 (file-chase-links "/usr/foo/hello")
1039 ;; @r{This does not follow the links in the parent directories.}
1040 @result{} "/usr/foo/hello"
1041 (file-truename "/usr/foo/hello")
1042 ;; @r{Assuming that @file{/home} is not a symbolic link.}
1043 @result{} "/home/foo/hello"
1046 @xref{Buffer File Name}, for related information.
1048 @node File Attributes
1049 @comment node-name, next, previous, up
1050 @subsection Other Information about Files
1052 This section describes the functions for getting detailed information
1053 about a file, other than its contents. This information includes the
1054 mode bits that control access permission, the owner and group numbers,
1055 the number of names, the inode number, the size, and the times of access
1058 @defun file-modes filename
1060 @cindex file attributes
1061 This function returns the mode bits of @var{filename}, as an integer.
1062 The mode bits are also called the file permissions, and they specify
1063 access control in the usual Unix fashion. If the low-order bit is 1,
1064 then the file is executable by all users, if the second-lowest-order bit
1065 is 1, then the file is writable by all users, etc.
1067 The highest value returnable is 4095 (7777 octal), meaning that
1068 everyone has read, write, and execute permission, that the @acronym{SUID} bit
1069 is set for both others and group, and that the sticky bit is set.
1071 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
1073 This function recursively follows symbolic links at all levels.
1077 (file-modes "~/junk/diffs")
1078 @result{} 492 ; @r{Decimal integer.}
1082 @result{} "754" ; @r{Convert to octal.}
1086 (set-file-modes "~/junk/diffs" 438)
1092 @result{} "666" ; @r{Convert to octal.}
1097 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1102 If the @var{filename} argument to the next two functions is a symbolic
1103 link, then these function do @emph{not} replace it with its target.
1104 However, they both recursively follow symbolic links at all levels of
1107 @defun file-nlinks filename
1108 This functions returns the number of names (i.e., hard links) that
1109 file @var{filename} has. If the file does not exist, then this function
1110 returns @code{nil}. Note that symbolic links have no effect on this
1111 function, because they are not considered to be names of the files they
1117 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1118 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1126 (file-nlinks "doesnt-exist")
1132 @defun file-attributes filename &optional id-format
1133 @anchor{Definition of file-attributes}
1134 This function returns a list of attributes of file @var{filename}. If
1135 the specified file cannot be opened, it returns @code{nil}.
1136 The optional parameter @var{id-format} specifies the preferred format
1137 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1138 valid values are @code{'string} and @code{'integer}. The latter is
1139 the default, but we plan to change that, so you should specify a
1140 non-@code{nil} value for @var{id-format} if you use the returned
1141 @acronym{UID} or @acronym{GID}.
1143 The elements of the list, in order, are:
1147 @code{t} for a directory, a string for a symbolic link (the name
1148 linked to), or @code{nil} for a text file.
1150 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
1152 The number of names the file has. Alternate names, also known as hard
1153 links, can be created by using the @code{add-name-to-file} function
1154 (@pxref{Changing Files}).
1157 The file's @acronym{UID} as a string or an integer. If a string
1158 value cannot be looked up, the integer value is returned.
1161 The file's @acronym{GID} likewise.
1164 The time of last access, as a list of two integers.
1165 The first integer has the high-order 16 bits of time,
1166 the second has the low 16 bits. (This is similar to the
1167 value of @code{current-time}; see @ref{Time of Day}.)
1170 The time of last modification as a list of two integers (as above).
1173 The time of last status change as a list of two integers (as above).
1176 The size of the file in bytes. If the size is too large to fit in a
1177 Lisp integer, this is a floating point number.
1180 The file's modes, as a string of ten letters or dashes,
1184 @code{t} if the file's @acronym{GID} would change if file were
1185 deleted and recreated; @code{nil} otherwise.
1188 The file's inode number. If possible, this is an integer. If the inode
1189 number is too large to be represented as an integer in Emacs Lisp, then
1190 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
1191 holds the low 16 bits.
1194 The file system number of the file system that the file is in.
1195 Depending on the magnitude of the value, this can be either an integer
1196 or a cons cell, in the same manner as the inode number. This element
1197 and the file's inode number together give enough information to
1198 distinguish any two files on the system---no two files can have the same
1199 values for both of these numbers.
1202 For example, here are the file attributes for @file{files.texi}:
1206 (file-attributes "files.texi" 'string)
1207 @result{} (nil 1 "lh" "users"
1217 and here is how the result is interpreted:
1221 is neither a directory nor a symbolic link.
1224 has only one name (the name @file{files.texi} in the current default
1228 is owned by the user with name "lh".
1231 is in the group with name "users".
1234 was last accessed on Aug 19 00:09.
1237 was last modified on Aug 19 00:09.
1240 last had its inode changed on Aug 19 00:09.
1243 is 14906 bytes long. (It may not contain 14906 characters, though,
1244 if some of the bytes belong to multibyte sequences.)
1247 has a mode of read and write access for the owner, group, and world.
1250 would retain the same @acronym{GID} if it were recreated.
1253 has an inode number of 129500.
1255 is on file system number -32252.
1259 @node Locating Files
1260 @subsection How to Locate Files in Standard Places
1261 @cindex locate files
1264 This section explains how to search for a file in a list of
1265 directories. One example is when you need to look for a program's
1266 executable file, e.g., to find out whether a given program is
1267 installed on the user's system. Another example is the search for
1268 Lisp libraries (@pxref{Library Search}). Such searches generally need
1269 to try various possible file name extensions, in addition to various
1270 possible directories. Emacs provides a function for such a
1271 generalized search for a file.
1273 @defun locate-file filename path &optional suffixes predicate
1274 This function searches for a file whose name is @var{filename} in a
1275 list of directories given by @var{path}, trying the suffixes in
1276 @var{suffixes}. If it finds such a file, it returns the full
1277 @dfn{absolute file name} of the file (@pxref{Relative File Names});
1278 otherwise it returns @code{nil}.
1280 The optional argument @var{suffixes} gives the list of file-name
1281 suffixes to append to @var{filename} when searching.
1282 @code{locate-file} tries each possible directory with each of these
1283 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
1284 are no suffixes, and @var{filename} is used only as-is. Typical
1285 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1286 Creation, exec-suffixes}) and @code{load-suffixes} (@pxref{Library
1287 Search, load-suffixes}).
1289 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1290 Creation, exec-path}) when looking for executable programs or
1291 @code{load-path} (@pxref{Library Search, load-path}) when looking for
1292 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
1293 but the suffixes in @var{suffixes} are still tried.
1295 The optional argument @var{predicate}, if non-@code{nil}, specifies
1296 the predicate function to use for testing whether a candidate file is
1297 suitable. The predicate function is passed the candidate file name as
1298 its single argument. If @var{predicate} is @code{nil} or unspecified,
1299 @code{locate-file} uses @code{file-readable-p} as the default
1300 predicate. Useful non-default predicates include
1301 @code{file-executable-p}, @code{file-directory-p}, and other
1302 predicates described in @ref{Kinds of Files}.
1304 For compatibility, @var{predicate} can also be one of the symbols
1305 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1306 a list of one or more of these symbols.
1309 @cindex find executable program
1310 @defun executable-find program
1311 This function searches for the executable file of the named
1312 @var{program} and returns the full absolute name of the executable,
1313 including its file-name extensions, if any. It returns @code{nil} if
1314 the file is not found. The functions searches in all the directories
1315 in @code{exec-path} and tries all the file-name extensions in
1316 @code{exec-suffixes}.
1319 @node Changing Files
1320 @section Changing File Names and Attributes
1321 @cindex renaming files
1322 @cindex copying files
1323 @cindex deleting files
1324 @cindex linking files
1325 @cindex setting modes of files
1327 The functions in this section rename, copy, delete, link, and set the
1330 In the functions that have an argument @var{newname}, if a file by the
1331 name of @var{newname} already exists, the actions taken depend on the
1332 value of the argument @var{ok-if-already-exists}:
1336 Signal a @code{file-already-exists} error if
1337 @var{ok-if-already-exists} is @code{nil}.
1340 Request confirmation if @var{ok-if-already-exists} is a number.
1343 Replace the old file without confirmation if @var{ok-if-already-exists}
1347 The next four commands all recursively follow symbolic links at all
1348 levels of parent directories for their first argument, but, if that
1349 argument is itself a symbolic link, then only @code{copy-file}
1350 replaces it with its (recursive) target.
1352 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1353 @cindex file with multiple names
1354 @cindex file hard link
1355 This function gives the file named @var{oldname} the additional name
1356 @var{newname}. This means that @var{newname} becomes a new ``hard
1357 link'' to @var{oldname}.
1359 In the first part of the following example, we list two files,
1360 @file{foo} and @file{foo3}.
1365 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1366 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1370 Now we create a hard link, by calling @code{add-name-to-file}, then list
1371 the files again. This shows two names for one file, @file{foo} and
1376 (add-name-to-file "foo" "foo2")
1382 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1383 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1384 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1388 Finally, we evaluate the following:
1391 (add-name-to-file "foo" "foo3" t)
1395 and list the files again. Now there are three names
1396 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1397 contents of @file{foo3} are lost.
1401 (add-name-to-file "foo1" "foo3")
1407 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1408 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1409 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1413 This function is meaningless on operating systems where multiple names
1414 for one file are not allowed. Some systems implement multiple names
1415 by copying the file instead.
1417 See also @code{file-nlinks} in @ref{File Attributes}.
1420 @deffn Command rename-file filename newname &optional ok-if-already-exists
1421 This command renames the file @var{filename} as @var{newname}.
1423 If @var{filename} has additional names aside from @var{filename}, it
1424 continues to have those names. In fact, adding the name @var{newname}
1425 with @code{add-name-to-file} and then deleting @var{filename} has the
1426 same effect as renaming, aside from momentary intermediate states.
1429 @deffn Command copy-file oldname newname &optional ok-if-exists time mustbenew
1430 This command copies the file @var{oldname} to @var{newname}. An
1431 error is signaled if @var{oldname} does not exist. If @var{newname}
1432 names a directory, it copies @var{oldname} into that directory,
1433 preserving its final name component.
1435 If @var{time} is non-@code{nil}, then this function gives the new file
1436 the same last-modified time that the old one has. (This works on only
1437 some operating systems.) If setting the time gets an error,
1438 @code{copy-file} signals a @code{file-date-error} error.
1440 This function copies the file modes, too.
1442 In an interactive call, a prefix argument specifies a non-@code{nil}
1443 value for @var{time}.
1445 The argument @var{mustbenew} controls whether an existing file can be
1446 overwritten. It works like the similarly-named argument of
1447 @code{write-region} (@pxref{Writing to Files, mustbenew}).
1450 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
1452 @kindex file-already-exists
1453 This command makes a symbolic link to @var{filename}, named
1454 @var{newname}. This is like the shell command @samp{ln -s
1455 @var{filename} @var{newname}}.
1457 This function is not available on systems that don't support symbolic
1461 @deffn Command delete-file filename
1463 This command deletes the file @var{filename}, like the shell command
1464 @samp{rm @var{filename}}. If the file has multiple names, it continues
1465 to exist under the other names.
1467 A suitable kind of @code{file-error} error is signaled if the file does
1468 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
1469 deletable if its directory is writable.)
1471 If @var{filename} is a symbolic link, @code{delete-file} does not
1472 replace it with its target, but it does follow symbolic links at all
1473 levels of parent directories.
1475 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1478 @defun define-logical-name varname string
1479 This function defines the logical name @var{varname} to have the value
1480 @var{string}. It is available only on VMS.
1483 @defun set-file-modes filename mode
1484 This function sets mode bits of @var{filename} to @var{mode} (which
1485 must be an integer). Only the low 12 bits of @var{mode} are used.
1486 This function recursively follows symbolic links at all levels for
1491 @defun set-default-file-modes mode
1493 This function sets the default file protection for new files created by
1494 Emacs and its subprocesses. Every file created with Emacs initially has
1495 this protection, or a subset of it (@code{write-region} will not give a
1496 file execute permission even if the default file protection allows
1497 execute permission). On Unix and GNU/Linux, the default protection is
1498 the bitwise complement of the ``umask'' value.
1500 The argument @var{mode} must be an integer. On most systems, only the
1501 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
1502 for octal character codes to enter @var{mode}; for example,
1505 (set-default-file-modes ?\644)
1508 Saving a modified version of an existing file does not count as creating
1509 the file; it preserves the existing file's mode, whatever that is. So
1510 the default file protection has no effect.
1513 @defun default-file-modes
1514 This function returns the current default protection value.
1517 @defun set-file-times filename &optional time
1518 This function sets the access and modification times of @var{filename}
1519 to @var{time}. The return value is @code{t} if the times are successfully
1520 set, otherwise it is @code{nil}. @var{time} defaults to the current
1521 time and must be in the format returned by @code{current-time}
1522 (@pxref{Time of Day}).
1525 @cindex MS-DOS and file modes
1526 @cindex file modes and MS-DOS
1527 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1528 So Emacs considers a file executable if its name ends in one of the
1529 standard executable extensions, such as @file{.com}, @file{.bat},
1530 @file{.exe}, and some others. Files that begin with the Unix-standard
1531 @samp{#!} signature, such as shell and Perl scripts, are also considered
1532 as executable files. This is reflected in the values returned by
1533 @code{file-modes} and @code{file-attributes}. Directories are also
1534 reported with executable bit set, for compatibility with Unix.
1540 Files are generally referred to by their names, in Emacs as elsewhere.
1541 File names in Emacs are represented as strings. The functions that
1542 operate on a file all expect a file name argument.
1544 In addition to operating on files themselves, Emacs Lisp programs
1545 often need to operate on file names; i.e., to take them apart and to use
1546 part of a name to construct related file names. This section describes
1547 how to manipulate file names.
1549 The functions in this section do not actually access files, so they
1550 can operate on file names that do not refer to an existing file or
1553 On MS-DOS and MS-Windows, these functions (like the function that
1554 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1555 where backslashes separate the components, as well as Unix syntax; but
1556 they always return Unix syntax. On VMS, these functions (and the ones
1557 that operate on files) understand both VMS file-name syntax and Unix
1558 syntax. This enables Lisp programs to specify file names in Unix syntax
1559 and work properly on all systems without change.
1562 * File Name Components:: The directory part of a file name, and the rest.
1563 * Relative File Names:: Some file names are relative to a current directory.
1564 * Directory Names:: A directory's name as a directory
1565 is different from its name as a file.
1566 * File Name Expansion:: Converting relative file names to absolute ones.
1567 * Unique File Names:: Generating names for temporary files.
1568 * File Name Completion:: Finding the completions for a given file name.
1569 * Standard File Names:: If your package uses a fixed file name,
1570 how to handle various operating systems simply.
1573 @node File Name Components
1574 @subsection File Name Components
1575 @cindex directory part (of file name)
1576 @cindex nondirectory part (of file name)
1577 @cindex version number (in file name)
1579 The operating system groups files into directories. To specify a
1580 file, you must specify the directory and the file's name within that
1581 directory. Therefore, Emacs considers a file name as having two main
1582 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1583 (or @dfn{file name within the directory}). Either part may be empty.
1584 Concatenating these two parts reproduces the original file name.
1586 On most systems, the directory part is everything up to and including
1587 the last slash (backslash is also allowed in input on MS-DOS or
1588 MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
1591 For some purposes, the nondirectory part is further subdivided into
1592 the name proper and the @dfn{version number}. On most systems, only
1593 backup files have version numbers in their names. On VMS, every file
1594 has a version number, but most of the time the file name actually used
1595 in Emacs omits the version number, so that version numbers in Emacs are
1596 found mostly in directory lists.
1598 @defun file-name-directory filename
1599 This function returns the directory part of @var{filename}, as a
1600 directory name (@pxref{Directory Names}), or @code{nil} if
1601 @var{filename} does not include a directory part.
1603 On GNU and Unix systems, a string returned by this function always
1604 ends in a slash. On MSDOS it can also end in a colon. On VMS, it
1605 returns a string ending in one of the three characters @samp{:},
1606 @samp{]}, or @samp{>}.
1610 (file-name-directory "lewis/foo") ; @r{Unix example}
1614 (file-name-directory "foo") ; @r{Unix example}
1618 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
1624 @defun file-name-nondirectory filename
1625 This function returns the nondirectory part of @var{filename}.
1629 (file-name-nondirectory "lewis/foo")
1633 (file-name-nondirectory "foo")
1637 (file-name-nondirectory "lewis/")
1641 ;; @r{The following example is accurate only on VMS.}
1642 (file-name-nondirectory "[X]FOO.TMP")
1648 @defun file-name-sans-versions filename &optional keep-backup-version
1649 This function returns @var{filename} with any file version numbers,
1650 backup version numbers, or trailing tildes discarded.
1652 If @var{keep-backup-version} is non-@code{nil}, then true file version
1653 numbers understood as such by the file system are discarded from the
1654 return value, but backup version numbers are kept.
1658 (file-name-sans-versions "~rms/foo.~1~")
1659 @result{} "~rms/foo"
1662 (file-name-sans-versions "~rms/foo~")
1663 @result{} "~rms/foo"
1666 (file-name-sans-versions "~rms/foo")
1667 @result{} "~rms/foo"
1670 ;; @r{The following example applies to VMS only.}
1671 (file-name-sans-versions "foo;23")
1677 @defun file-name-extension filename &optional period
1678 This function returns @var{filename}'s final ``extension'', if any,
1679 after applying @code{file-name-sans-versions} to remove any
1680 version/backup part. The extension, in a file name, is the part that
1681 starts with the last @samp{.} in the last name component (minus
1682 any version/backup part).
1684 This function returns @code{nil} for extensionless file names such as
1685 @file{foo}. It returns @code{""} for null extensions, as in
1686 @file{foo.}. If the last component of a file name begins with a
1687 @samp{.}, that @samp{.} doesn't count as the beginning of an
1688 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1691 If @var{period} is non-@code{nil}, then the returned value includes
1692 the period that delimits the extension, and if @var{filename} has no
1693 extension, the value is @code{""}.
1696 @defun file-name-sans-extension filename
1697 This function returns @var{filename} minus its extension, if any. The
1698 version/backup part, if present, is only removed if the file has an
1699 extension. For example,
1702 (file-name-sans-extension "foo.lose.c")
1703 @result{} "foo.lose"
1704 (file-name-sans-extension "big.hack/foo")
1705 @result{} "big.hack/foo"
1706 (file-name-sans-extension "/my/home/.emacs")
1707 @result{} "/my/home/.emacs"
1708 (file-name-sans-extension "/my/home/.emacs.el")
1709 @result{} "/my/home/.emacs"
1710 (file-name-sans-extension "~/foo.el.~3~")
1712 (file-name-sans-extension "~/foo.~3~")
1713 @result{} "~/foo.~3~"
1716 Note that the @samp{.~3~} in the two last examples is the backup part,
1721 Andrew Innes says that this
1723 @c @defvar directory-sep-char
1724 @c @tindex directory-sep-char
1725 This variable holds the character that Emacs normally uses to separate
1726 file name components. The default value is @code{?/}, but on MS-Windows
1727 you can set it to @code{?\\}; then the functions that transform file names
1728 use backslashes in their output.
1730 File names using backslashes work as input to Lisp primitives even on
1731 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
1736 @node Relative File Names
1737 @subsection Absolute and Relative File Names
1738 @cindex absolute file name
1739 @cindex relative file name
1741 All the directories in the file system form a tree starting at the
1742 root directory. A file name can specify all the directory names
1743 starting from the root of the tree; then it is called an @dfn{absolute}
1744 file name. Or it can specify the position of the file in the tree
1745 relative to a default directory; then it is called a @dfn{relative} file
1746 name. On Unix and GNU/Linux, an absolute file name starts with a slash
1747 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
1748 MS-Windows, an absolute file name starts with a slash or a backslash, or
1749 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1750 @dfn{drive letter}. The rules on VMS are complicated.
1752 @defun file-name-absolute-p filename
1753 This function returns @code{t} if file @var{filename} is an absolute
1754 file name, @code{nil} otherwise. On VMS, this function understands both
1755 Unix syntax and VMS syntax.
1759 (file-name-absolute-p "~rms/foo")
1763 (file-name-absolute-p "rms/foo")
1767 (file-name-absolute-p "/user/rms/foo")
1773 @node Directory Names
1774 @comment node-name, next, previous, up
1775 @subsection Directory Names
1776 @cindex directory name
1777 @cindex file name of directory
1779 A @dfn{directory name} is the name of a directory. A directory is
1780 actually a kind of file, so it has a file name, which is related to
1781 the directory name but not identical to it. (This is not quite the
1782 same as the usual Unix terminology.) These two different names for
1783 the same entity are related by a syntactic transformation. On GNU and
1784 Unix systems, this is simple: a directory name ends in a slash,
1785 whereas the directory's name as a file lacks that slash. On MSDOS and
1786 VMS, the relationship is more complicated.
1788 The difference between a directory name and its name as a file is
1789 subtle but crucial. When an Emacs variable or function argument is
1790 described as being a directory name, a file name of a directory is not
1791 acceptable. When @code{file-name-directory} returns a string, that is
1792 always a directory name.
1794 The following two functions convert between directory names and file
1795 names. They do nothing special with environment variable substitutions
1796 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1798 @defun file-name-as-directory filename
1799 This function returns a string representing @var{filename} in a form
1800 that the operating system will interpret as the name of a directory. On
1801 most systems, this means appending a slash to the string (if it does not
1802 already end in one). On VMS, the function converts a string of the form
1803 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
1807 (file-name-as-directory "~rms/lewis")
1808 @result{} "~rms/lewis/"
1813 @defun directory-file-name dirname
1814 This function returns a string representing @var{dirname} in a form that
1815 the operating system will interpret as the name of a file. On most
1816 systems, this means removing the final slash (or backslash) from the
1817 string. On VMS, the function converts a string of the form @file{[X.Y]}
1818 to @file{[X]Y.DIR.1}.
1822 (directory-file-name "~lewis/")
1828 Given a directory name, you can combine it with a relative file name
1829 using @code{concat}:
1832 (concat @var{dirname} @var{relfile})
1836 Be sure to verify that the file name is relative before doing that.
1837 If you use an absolute file name, the results could be syntactically
1838 invalid or refer to the wrong file.
1840 If you want to use a directory file name in making such a
1841 combination, you must first convert it to a directory name using
1842 @code{file-name-as-directory}:
1845 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1849 Don't try concatenating a slash by hand, as in
1853 (concat @var{dirfile} "/" @var{relfile})
1857 because this is not portable. Always use
1858 @code{file-name-as-directory}.
1860 @cindex directory name abbreviation
1861 Directory name abbreviations are useful for directories that are
1862 normally accessed through symbolic links. Sometimes the users recognize
1863 primarily the link's name as ``the name'' of the directory, and find it
1864 annoying to see the directory's ``real'' name. If you define the link
1865 name as an abbreviation for the ``real'' name, Emacs shows users the
1866 abbreviation instead.
1868 @defvar directory-abbrev-alist
1869 The variable @code{directory-abbrev-alist} contains an alist of
1870 abbreviations to use for file directories. Each element has the form
1871 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1872 @var{to} when it appears in a directory name. The @var{from} string is
1873 actually a regular expression; it should always start with @samp{^}.
1874 The @var{to} string should be an ordinary absolute directory name. Do
1875 not use @samp{~} to stand for a home directory in that string. The
1876 function @code{abbreviate-file-name} performs these substitutions.
1878 You can set this variable in @file{site-init.el} to describe the
1879 abbreviations appropriate for your site.
1881 Here's an example, from a system on which file system @file{/home/fsf}
1882 and so on are normally accessed through symbolic links named @file{/fsf}
1886 (("^/home/fsf" . "/fsf")
1887 ("^/home/gp" . "/gp")
1888 ("^/home/gd" . "/gd"))
1892 To convert a directory name to its abbreviation, use this
1895 @defun abbreviate-file-name filename
1896 @anchor{Definition of abbreviate-file-name}
1897 This function applies abbreviations from @code{directory-abbrev-alist}
1898 to its argument, and substitutes @samp{~} for the user's home
1899 directory. You can use it for directory names and for file names,
1900 because it recognizes abbreviations even as part of the name.
1903 @node File Name Expansion
1904 @subsection Functions that Expand Filenames
1905 @cindex expansion of file names
1907 @dfn{Expansion} of a file name means converting a relative file name
1908 to an absolute one. Since this is done relative to a default directory,
1909 you must specify the default directory name as well as the file name to
1910 be expanded. Expansion also simplifies file names by eliminating
1911 redundancies such as @file{./} and @file{@var{name}/../}.
1913 In the next two functions, the @var{directory} argument can be either
1914 a directory name or a directory file name. @xref{Directory Names}.
1916 @defun expand-file-name filename &optional directory
1917 This function converts @var{filename} to an absolute file name. If
1918 @var{directory} is supplied, it is the default directory to start with
1919 if @var{filename} is relative. (The value of @var{directory} should
1920 itself be an absolute directory name; it may start with @samp{~}.)
1921 Otherwise, the current buffer's value of @code{default-directory} is
1926 (expand-file-name "foo")
1927 @result{} "/xcssun/users/rms/lewis/foo"
1930 (expand-file-name "../foo")
1931 @result{} "/xcssun/users/rms/foo"
1934 (expand-file-name "foo" "/usr/spool/")
1935 @result{} "/usr/spool/foo"
1938 (expand-file-name "$HOME/foo")
1939 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1943 If the part of the combined file name before the first slash is
1944 @samp{~}, it expands to the value of the @env{HOME} environment
1945 variable (usually your home directory). If the part before the first
1946 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
1947 it expands to @var{user}'s home directory.
1949 Filenames containing @samp{.} or @samp{..} are simplified to their
1954 (expand-file-name "bar/../foo")
1955 @result{} "/xcssun/users/rms/lewis/foo"
1959 Note that @code{expand-file-name} does @emph{not} expand environment
1960 variables; only @code{substitute-in-file-name} does that.
1962 Note also that @code{expand-file-name} does not follow symbolic links
1963 at any level. This results in a difference between the way
1964 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
1965 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
1966 @samp{/tmp/foo/bar} we get:
1970 (file-truename "/tmp/bar/../myfile")
1971 @result{} "/tmp/foo/myfile"
1974 (expand-file-name "/tmp/bar/../myfile")
1975 @result{} "/tmp/myfile"
1979 If you may need to follow symbolic links preceding @samp{..}, you
1980 should make sure to call @code{file-truename} without prior direct or
1981 indirect calls to @code{expand-file-name}. @xref{Truenames}.
1985 @defun file-relative-name filename &optional directory
1986 This function does the inverse of expansion---it tries to return a
1987 relative name that is equivalent to @var{filename} when interpreted
1988 relative to @var{directory}. If @var{directory} is omitted or
1989 @code{nil}, it defaults to the current buffer's default directory.
1991 On some operating systems, an absolute file name begins with a device
1992 name. On such systems, @var{filename} has no relative equivalent based
1993 on @var{directory} if they start with two different device names. In
1994 this case, @code{file-relative-name} returns @var{filename} in absolute
1998 (file-relative-name "/foo/bar" "/foo/")
2000 (file-relative-name "/foo/bar" "/hack/")
2001 @result{} "../foo/bar"
2005 @defvar default-directory
2006 The value of this buffer-local variable is the default directory for the
2007 current buffer. It should be an absolute directory name; it may start
2008 with @samp{~}. This variable is buffer-local in every buffer.
2010 @code{expand-file-name} uses the default directory when its second
2011 argument is @code{nil}.
2013 Aside from VMS, the value is always a string ending with a slash.
2018 @result{} "/user/lewis/manual/"
2023 @defun substitute-in-file-name filename
2024 @anchor{Definition of substitute-in-file-name}
2025 This function replaces environment variable references in
2026 @var{filename} with the environment variable values. Following
2027 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2028 environment variable value. If the input contains @samp{$$}, that is
2029 converted to @samp{$}; this gives the user a way to ``quote'' a
2032 The environment variable name is the series of alphanumeric characters
2033 (including underscores) that follow the @samp{$}. If the character following
2034 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2037 Calling @code{substitute-in-file-name} on output produced by
2038 @code{substitute-in-file-name} tends to give incorrect results. For
2039 instance, use of @samp{$$} to quote a single @samp{$} won't work
2040 properly, and @samp{$} in an environment variable's value could lead
2041 to repeated substitution. Therefore, programs that call this function
2042 and put the output where it will be passed to this function need to
2043 double all @samp{$} characters to prevent subsequent incorrect
2046 @c Wordy to avoid overfull hbox. --rjc 15mar92
2047 Here we assume that the environment variable @code{HOME}, which holds
2048 the user's home directory name, has value @samp{/xcssun/users/rms}.
2052 (substitute-in-file-name "$HOME/foo")
2053 @result{} "/xcssun/users/rms/foo"
2057 After substitution, if a @samp{~} or a @samp{/} appears immediately
2058 after another @samp{/}, the function discards everything before it (up
2059 through the immediately preceding @samp{/}).
2063 (substitute-in-file-name "bar/~/foo")
2067 (substitute-in-file-name "/usr/local/$HOME/foo")
2068 @result{} "/xcssun/users/rms/foo"
2069 ;; @r{@file{/usr/local/} has been discarded.}
2073 On VMS, @samp{$} substitution is not done, so this function does nothing
2074 on VMS except discard superfluous initial components as shown above.
2077 @node Unique File Names
2078 @subsection Generating Unique File Names
2080 Some programs need to write temporary files. Here is the usual way to
2081 construct a name for such a file:
2084 (make-temp-file @var{name-of-application})
2088 The job of @code{make-temp-file} is to prevent two different users or
2089 two different jobs from trying to use the exact same file name.
2091 @defun make-temp-file prefix &optional dir-flag suffix
2092 @tindex make-temp-file
2093 This function creates a temporary file and returns its name. Emacs
2094 creates the temporary file's name by adding to @var{prefix} some
2095 random characters that are different in each Emacs job. The result is
2096 guaranteed to be a newly created empty file. On MS-DOS, this function
2097 can truncate the @var{string} prefix to fit into the 8+3 file-name
2098 limits. If @var{prefix} is a relative file name, it is expanded
2099 against @code{temporary-file-directory}.
2103 (make-temp-file "foo")
2104 @result{} "/tmp/foo232J6v"
2108 When @code{make-temp-file} returns, the file has been created and is
2109 empty. At that point, you should write the intended contents into the
2112 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2113 empty directory instead of an empty file. It returns the file name,
2114 not the directory name, of that directory. @xref{Directory Names}.
2116 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2117 the end of the file name.
2119 To prevent conflicts among different libraries running in the same
2120 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2121 own @var{prefix}. The number added to the end of @var{prefix}
2122 distinguishes between the same application running in different Emacs
2123 jobs. Additional added characters permit a large number of distinct
2124 names even in one Emacs job.
2127 The default directory for temporary files is controlled by the
2128 variable @code{temporary-file-directory}. This variable gives the user
2129 a uniform way to specify the directory for all temporary files. Some
2130 programs use @code{small-temporary-file-directory} instead, if that is
2131 non-@code{nil}. To use it, you should expand the prefix against
2132 the proper directory before calling @code{make-temp-file}.
2134 In older Emacs versions where @code{make-temp-file} does not exist,
2135 you should use @code{make-temp-name} instead:
2139 (expand-file-name @var{name-of-application}
2140 temporary-file-directory))
2143 @defun make-temp-name string
2144 This function generates a string that can be used as a unique file
2145 name. The name starts with @var{string}, and has several random
2146 characters appended to it, which are different in each Emacs job. It
2147 is like @code{make-temp-file} except that it just constructs a name,
2148 and does not create a file. Another difference is that @var{string}
2149 should be an absolute file name. On MS-DOS, this function can
2150 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
2153 @defvar temporary-file-directory
2154 @cindex @code{TMPDIR} environment variable
2155 @cindex @code{TMP} environment variable
2156 @cindex @code{TEMP} environment variable
2157 This variable specifies the directory name for creating temporary files.
2158 Its value should be a directory name (@pxref{Directory Names}), but it
2159 is good for Lisp programs to cope if the value is a directory's file
2160 name instead. Using the value as the second argument to
2161 @code{expand-file-name} is a good way to achieve that.
2163 The default value is determined in a reasonable way for your operating
2164 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2165 environment variables, with a fall-back to a system-dependent name if
2166 none of these variables is defined.
2168 Even if you do not use @code{make-temp-file} to create the temporary
2169 file, you should still use this variable to decide which directory to
2170 put the file in. However, if you expect the file to be small, you
2171 should use @code{small-temporary-file-directory} first if that is
2175 @tindex small-temporary-file-directory
2176 @defvar small-temporary-file-directory
2177 This variable specifies the directory name for
2178 creating certain temporary files, which are likely to be small.
2180 If you want to write a temporary file which is likely to be small, you
2181 should compute the directory like this:
2185 (expand-file-name @var{prefix}
2186 (or small-temporary-file-directory
2187 temporary-file-directory)))
2191 @node File Name Completion
2192 @subsection File Name Completion
2193 @cindex file name completion subroutines
2194 @cindex completion, file name
2196 This section describes low-level subroutines for completing a file
2197 name. For other completion functions, see @ref{Completion}.
2199 @defun file-name-all-completions partial-filename directory
2200 This function returns a list of all possible completions for a file
2201 whose name starts with @var{partial-filename} in directory
2202 @var{directory}. The order of the completions is the order of the files
2203 in the directory, which is unpredictable and conveys no useful
2206 The argument @var{partial-filename} must be a file name containing no
2207 directory part and no slash (or backslash on some systems). The current
2208 buffer's default directory is prepended to @var{directory}, if
2209 @var{directory} is not absolute.
2211 In the following example, suppose that @file{~rms/lewis} is the current
2212 default directory, and has five files whose names begin with @samp{f}:
2213 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2214 @file{file.c.~2~}.@refill
2218 (file-name-all-completions "f" "")
2219 @result{} ("foo" "file~" "file.c.~2~"
2220 "file.c.~1~" "file.c")
2224 (file-name-all-completions "fo" "")
2230 @defun file-name-completion filename directory
2231 This function completes the file name @var{filename} in directory
2232 @var{directory}. It returns the longest prefix common to all file names
2233 in directory @var{directory} that start with @var{filename}.
2235 If only one match exists and @var{filename} matches it exactly, the
2236 function returns @code{t}. The function returns @code{nil} if directory
2237 @var{directory} contains no name starting with @var{filename}.
2239 In the following example, suppose that the current default directory
2240 has five files whose names begin with @samp{f}: @file{foo},
2241 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2242 @file{file.c.~2~}.@refill
2246 (file-name-completion "fi" "")
2251 (file-name-completion "file.c.~1" "")
2252 @result{} "file.c.~1~"
2256 (file-name-completion "file.c.~1~" "")
2261 (file-name-completion "file.c.~3" "")
2267 @defopt completion-ignored-extensions
2268 @code{file-name-completion} usually ignores file names that end in any
2269 string in this list. It does not ignore them when all the possible
2270 completions end in one of these suffixes. This variable has no effect
2271 on @code{file-name-all-completions}.@refill
2273 A typical value might look like this:
2277 completion-ignored-extensions
2278 @result{} (".o" ".elc" "~" ".dvi")
2282 If an element of @code{completion-ignored-extensions} ends in a slash
2283 @samp{/}, it signals a directory. The elements which do @emph{not} end
2284 in a slash will never match a directory; thus, the above value will not
2285 filter out a directory named @file{foo.elc}.
2288 @node Standard File Names
2289 @subsection Standard File Names
2291 Most of the file names used in Lisp programs are entered by the user.
2292 But occasionally a Lisp program needs to specify a standard file name
2293 for a particular use---typically, to hold customization information
2294 about each user. For example, abbrev definitions are stored (by
2295 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2296 package stores completions in the file @file{~/.completions}. These are
2297 two of the many standard file names used by parts of Emacs for certain
2300 Various operating systems have their own conventions for valid file
2301 names and for which file names to use for user profile data. A Lisp
2302 program which reads a file using a standard file name ought to use, on
2303 each type of system, a file name suitable for that system. The function
2304 @code{convert-standard-filename} makes this easy to do.
2306 @defun convert-standard-filename filename
2307 This function alters the file name @var{filename} to fit the conventions
2308 of the operating system in use, and returns the result as a new string.
2311 The recommended way to specify a standard file name in a Lisp program
2312 is to choose a name which fits the conventions of GNU and Unix systems,
2313 usually with a nondirectory part that starts with a period, and pass it
2314 to @code{convert-standard-filename} instead of using it directly. Here
2315 is an example from the @code{completion} package:
2318 (defvar save-completions-file-name
2319 (convert-standard-filename "~/.completions")
2320 "*The file name to save completions to.")
2323 On GNU and Unix systems, and on some other systems as well,
2324 @code{convert-standard-filename} returns its argument unchanged. On
2325 some other systems, it alters the name to fit the system's conventions.
2327 For example, on MS-DOS the alterations made by this function include
2328 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
2329 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2330 a @samp{.} after eight characters if there is none, and truncating to
2331 three characters after the @samp{.}. (It makes other changes as well.)
2332 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2333 @file{.completions} becomes @file{_complet.ion}.
2335 @node Contents of Directories
2336 @section Contents of Directories
2337 @cindex directory-oriented functions
2338 @cindex file names in directory
2340 A directory is a kind of file that contains other files entered under
2341 various names. Directories are a feature of the file system.
2343 Emacs can list the names of the files in a directory as a Lisp list,
2344 or display the names in a buffer using the @code{ls} shell command. In
2345 the latter case, it can optionally display information about each file,
2346 depending on the options passed to the @code{ls} command.
2348 @defun directory-files directory &optional full-name match-regexp nosort
2349 This function returns a list of the names of the files in the directory
2350 @var{directory}. By default, the list is in alphabetical order.
2352 If @var{full-name} is non-@code{nil}, the function returns the files'
2353 absolute file names. Otherwise, it returns the names relative to
2354 the specified directory.
2356 If @var{match-regexp} is non-@code{nil}, this function returns only
2357 those file names that contain a match for that regular expression---the
2358 other file names are excluded from the list.
2361 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2362 the list, so you get the file names in no particular order. Use this if
2363 you want the utmost possible speed and don't care what order the files
2364 are processed in. If the order of processing is visible to the user,
2365 then the user will probably be happier if you do sort the names.
2369 (directory-files "~lewis")
2370 @result{} ("#foo#" "#foo.el#" "." ".."
2371 "dired-mods.el" "files.texi"
2376 An error is signaled if @var{directory} is not the name of a directory
2380 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2381 This is similar to @code{directory-files} in deciding which files
2382 to report on and how to report their names. However, instead
2383 of returning a list of file names, it returns for each file a
2384 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2385 is what @code{file-attributes} would return for that file.
2386 The optional argument @var{id-format} has the same meaning as the
2387 corresponding argument to @code{file-attributes} (@pxref{Definition
2388 of file-attributes}).
2391 @defun file-name-all-versions file dirname
2392 This function returns a list of all versions of the file named
2393 @var{file} in directory @var{dirname}. It is only available on VMS.
2396 @tindex file-expand-wildcards
2397 @defun file-expand-wildcards pattern &optional full
2398 This function expands the wildcard pattern @var{pattern}, returning
2399 a list of file names that match it.
2401 If @var{pattern} is written as an absolute file name,
2402 the values are absolute also.
2404 If @var{pattern} is written as a relative file name, it is interpreted
2405 relative to the current default directory. The file names returned are
2406 normally also relative to the current default directory. However, if
2407 @var{full} is non-@code{nil}, they are absolute.
2410 @defun insert-directory file switches &optional wildcard full-directory-p
2411 This function inserts (in the current buffer) a directory listing for
2412 directory @var{file}, formatted with @code{ls} according to
2413 @var{switches}. It leaves point after the inserted text.
2414 @var{switches} may be a string of options, or a list of strings
2415 representing individual options.
2417 The argument @var{file} may be either a directory name or a file
2418 specification including wildcard characters. If @var{wildcard} is
2419 non-@code{nil}, that means treat @var{file} as a file specification with
2422 If @var{full-directory-p} is non-@code{nil}, that means the directory
2423 listing is expected to show the full contents of a directory. You
2424 should specify @code{t} when @var{file} is a directory and switches do
2425 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
2426 describe a directory itself as a file, rather than showing its
2429 On most systems, this function works by running a directory listing
2430 program whose name is in the variable @code{insert-directory-program}.
2431 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2432 @code{shell-file-name}, to expand the wildcards.
2434 MS-DOS and MS-Windows systems usually lack the standard Unix program
2435 @code{ls}, so this function emulates the standard Unix program @code{ls}
2438 As a technical detail, when @var{switches} contains the long
2439 @samp{--dired} option, @code{insert-directory} treats it specially,
2440 for the sake of dired. However, the normally equivalent short
2441 @samp{-D} option is just passed on to @code{insert-directory-program},
2442 as any other option.
2445 @defvar insert-directory-program
2446 This variable's value is the program to run to generate a directory listing
2447 for the function @code{insert-directory}. It is ignored on systems
2448 which generate the listing with Lisp code.
2451 @node Create/Delete Dirs
2452 @section Creating and Deleting Directories
2453 @c Emacs 19 features
2455 Most Emacs Lisp file-manipulation functions get errors when used on
2456 files that are directories. For example, you cannot delete a directory
2457 with @code{delete-file}. These special functions exist to create and
2460 @defun make-directory dirname &optional parents
2461 This function creates a directory named @var{dirname}.
2462 If @var{parents} is non-@code{nil}, as is always the case in an
2463 interactive call, that means to create the parent directories first,
2464 if they don't already exist.
2467 @defun delete-directory dirname
2468 This function deletes the directory named @var{dirname}. The function
2469 @code{delete-file} does not work for files that are directories; you
2470 must use @code{delete-directory} for them. If the directory contains
2471 any files, @code{delete-directory} signals an error.
2473 This function only follows symbolic links at the level of parent
2477 @node Magic File Names
2478 @section Making Certain File Names ``Magic''
2479 @cindex magic file names
2482 You can implement special handling for certain file names. This is
2483 called making those names @dfn{magic}. The principal use for this
2484 feature is in implementing remote file names (@pxref{Remote Files,,
2485 Remote Files, emacs, The GNU Emacs Manual}).
2487 To define a kind of magic file name, you must supply a regular
2488 expression to define the class of names (all those that match the
2489 regular expression), plus a handler that implements all the primitive
2490 Emacs file operations for file names that do match.
2492 The variable @code{file-name-handler-alist} holds a list of handlers,
2493 together with regular expressions that determine when to apply each
2494 handler. Each element has this form:
2497 (@var{regexp} . @var{handler})
2501 All the Emacs primitives for file access and file name transformation
2502 check the given file name against @code{file-name-handler-alist}. If
2503 the file name matches @var{regexp}, the primitives handle that file by
2504 calling @var{handler}.
2506 The first argument given to @var{handler} is the name of the
2507 primitive, as a symbol; the remaining arguments are the arguments that
2508 were passed to that primitive. (The first of these arguments is most
2509 often the file name itself.) For example, if you do this:
2512 (file-exists-p @var{filename})
2516 and @var{filename} has handler @var{handler}, then @var{handler} is
2520 (funcall @var{handler} 'file-exists-p @var{filename})
2523 When a function takes two or more arguments that must be file names,
2524 it checks each of those names for a handler. For example, if you do
2528 (expand-file-name @var{filename} @var{dirname})
2532 then it checks for a handler for @var{filename} and then for a handler
2533 for @var{dirname}. In either case, the @var{handler} is called like
2537 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2541 The @var{handler} then needs to figure out whether to handle
2542 @var{filename} or @var{dirname}.
2544 If the specified file name matches more than one handler, the one
2545 whose match starts last in the file name gets precedence. This rule
2546 is chosen so that handlers for jobs such as uncompression are handled
2547 first, before handlers for jobs such as remote file access.
2549 Here are the operations that a magic file name handler gets to handle:
2553 @code{access-file}, @code{add-name-to-file},
2554 @code{byte-compiler-base-file-name},@*
2555 @code{copy-file}, @code{delete-directory},
2557 @code{diff-latest-backup-file},
2558 @code{directory-file-name},
2559 @code{directory-files},
2560 @code{directory-files-and-attributes},
2561 @code{dired-call-process},
2562 @code{dired-compress-file}, @code{dired-uncache},@*
2563 @code{expand-file-name},
2564 @code{file-accessible-directory-p},
2565 @code{file-attributes},
2566 @code{file-directory-p},
2567 @code{file-executable-p}, @code{file-exists-p},
2568 @code{file-local-copy}, @code{file-remote-p},
2569 @code{file-modes}, @code{file-name-all-completions},
2570 @code{file-name-as-directory},
2571 @code{file-name-completion},
2572 @code{file-name-directory},
2573 @code{file-name-nondirectory},
2574 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2575 @code{file-ownership-preserved-p},
2576 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2577 @code{file-truename}, @code{file-writable-p},
2578 @code{find-backup-file-name},
2579 @code{find-file-noselect},@*
2580 @code{get-file-buffer},
2581 @code{insert-directory},
2582 @code{insert-file-contents},@*
2584 @code{make-auto-save-file-name},
2585 @code{make-directory},
2586 @code{make-directory-internal},
2587 @code{make-symbolic-link},@*
2588 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2589 @code{set-visited-file-modtime}, @code{shell-command},
2590 @code{substitute-in-file-name},@*
2591 @code{unhandled-file-name-directory},
2592 @code{vc-registered},
2593 @code{verify-visited-file-modtime},@*
2594 @code{write-region}.
2599 @code{access-file}, @code{add-name-to-file},
2600 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2601 @code{copy-file}, @code{delete-directory},
2603 @code{diff-latest-backup-file},
2604 @code{directory-file-name},
2605 @code{directory-files},
2606 @code{directory-files-and-at@discretionary{}{}{}tributes},
2607 @code{dired-call-process},
2608 @code{dired-compress-file}, @code{dired-uncache},
2609 @code{expand-file-name},
2610 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2611 @code{file-attributes},
2612 @code{file-direct@discretionary{}{}{}ory-p},
2613 @code{file-executable-p}, @code{file-exists-p},
2614 @code{file-local-copy}, @code{file-remote-p},
2615 @code{file-modes}, @code{file-name-all-completions},
2616 @code{file-name-as-directory},
2617 @code{file-name-completion},
2618 @code{file-name-directory},
2619 @code{file-name-nondirec@discretionary{}{}{}tory},
2620 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2621 @code{file-ownership-pre@discretionary{}{}{}served-p},
2622 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2623 @code{file-truename}, @code{file-writable-p},
2624 @code{find-backup-file-name},
2625 @code{find-file-noselect},
2626 @code{get-file-buffer},
2627 @code{insert-directory},
2628 @code{insert-file-contents},
2629 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2630 @code{make-direc@discretionary{}{}{}tory-internal},
2631 @code{make-symbolic-link},
2632 @code{rename-file}, @code{set-file-modes},
2633 @code{set-visited-file-modtime}, @code{shell-command},
2634 @code{substitute-in-file-name},
2635 @code{unhandled-file-name-directory},
2636 @code{vc-regis@discretionary{}{}{}tered},
2637 @code{verify-visited-file-modtime},
2638 @code{write-region}.
2642 Handlers for @code{insert-file-contents} typically need to clear the
2643 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2644 @var{visit} argument is non-@code{nil}. This also has the effect of
2645 unlocking the buffer if it is locked.
2647 The handler function must handle all of the above operations, and
2648 possibly others to be added in the future. It need not implement all
2649 these operations itself---when it has nothing special to do for a
2650 certain operation, it can reinvoke the primitive, to handle the
2651 operation ``in the usual way''. It should always reinvoke the primitive
2652 for an operation it does not recognize. Here's one way to do this:
2655 (defun my-file-handler (operation &rest args)
2656 ;; @r{First check for the specific operations}
2657 ;; @r{that we have special handling for.}
2658 (cond ((eq operation 'insert-file-contents) @dots{})
2659 ((eq operation 'write-region) @dots{})
2661 ;; @r{Handle any operation we don't know about.}
2662 (t (let ((inhibit-file-name-handlers
2663 (cons 'my-file-handler
2664 (and (eq inhibit-file-name-operation operation)
2665 inhibit-file-name-handlers)))
2666 (inhibit-file-name-operation operation))
2667 (apply operation args)))))
2670 When a handler function decides to call the ordinary Emacs primitive for
2671 the operation at hand, it needs to prevent the primitive from calling
2672 the same handler once again, thus leading to an infinite recursion. The
2673 example above shows how to do this, with the variables
2674 @code{inhibit-file-name-handlers} and
2675 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2676 shown above; the details are crucial for proper behavior in the case of
2677 multiple handlers, and for operations that have two file names that may
2680 @kindex safe-magic (@r{property})
2681 Handlers that don't really do anything special for actual access to the
2682 file---such as the ones that implement completion of host names for
2683 remote file names---should have a non-@code{nil} @code{safe-magic}
2684 property. For instance, Emacs normally ``protects'' directory names
2685 it finds in @code{PATH} from becoming magic, if they look like magic
2686 file names, by prefixing them with @samp{/:}. But if the handler that
2687 would be used for them has a non-@code{nil} @code{safe-magic}
2688 property, the @samp{/:} is not added.
2690 @kindex operations (@r{property})
2691 A file name handler can have an @code{operations} property to
2692 declare which operations it handles in a nontrivial way. If this
2693 property has a non-@code{nil} value, it should be a list of
2694 operations; then only those operations will call the handler. This
2695 avoids inefficiency, but its main purpose is for autoloaded handler
2696 functions, so that they won't be loaded except when they have real
2699 @defvar inhibit-file-name-handlers
2700 This variable holds a list of handlers whose use is presently inhibited
2701 for a certain operation.
2704 @defvar inhibit-file-name-operation
2705 The operation for which certain handlers are presently inhibited.
2708 @defun find-file-name-handler file operation
2709 This function returns the handler function for file name @var{file},
2710 or @code{nil} if there is none. The argument @var{operation} should
2711 be the operation to be performed on the file---the value you will pass
2712 to the handler as its first argument when you call it. If
2713 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2714 not found in the @code{operations} property of the handler, this
2715 function returns @code{nil}.
2718 @defun file-local-copy filename
2719 This function copies file @var{filename} to an ordinary non-magic file
2720 on the local machine, if it isn't on the local machine already. Magic
2721 file names should handle the @code{file-local-copy} operation if they
2722 refer to files on other machines. A magic file name that is used for
2723 other purposes than remote file access should not handle
2724 @code{file-local-copy}; then this function will treat the file as
2727 If @var{filename} is local, whether magic or not, this function does
2728 nothing and returns @code{nil}. Otherwise it returns the file name
2729 of the local copy file.
2732 @defun file-remote-p filename
2733 This function tests whether @var{filename} is a remote file. If
2734 @var{filename} is local (not remote), the return value is @code{nil}.
2735 If @var{filename} is indeed remote, the return value is a string that
2736 identifies the remote system.
2738 This identifier string can include a host name and a user name, as
2739 well as characters designating the method used to access the remote
2740 system. For example, the remote identifier string for the filename
2741 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
2743 If @code{file-remote-p} returns the same identifier for two different
2744 filenames, that means they are stored on the same file system and can
2745 be accessed locally with respect to each other. This means, for
2746 example, that it is possible to start a remote process accessing both
2747 files at the same time. Implementors of file handlers need to ensure
2748 this principle is valid.
2751 @defun unhandled-file-name-directory filename
2752 This function returns the name of a directory that is not magic. It
2753 uses the directory part of @var{filename} if that is not magic. For a
2754 magic file name, it invokes the file name handler, which therefore
2755 decides what value to return.
2757 This is useful for running a subprocess; every subprocess must have a
2758 non-magic directory to serve as its current directory, and this function
2759 is a good way to come up with one.
2762 @node Format Conversion
2763 @section File Format Conversion
2765 @cindex file format conversion
2766 @cindex encoding file formats
2767 @cindex decoding file formats
2768 The variable @code{format-alist} defines a list of @dfn{file formats},
2769 which describe textual representations used in files for the data (text,
2770 text-properties, and possibly other information) in an Emacs buffer.
2771 Emacs performs format conversion if appropriate when reading and writing
2774 @defvar format-alist
2775 This list contains one format definition for each defined file format.
2778 @cindex format definition
2779 Each format definition is a list of this form:
2782 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2785 Here is what the elements in a format definition mean:
2789 The name of this format.
2792 A documentation string for the format.
2795 A regular expression which is used to recognize files represented in
2799 A shell command or function to decode data in this format (to convert
2800 file data into the usual Emacs data representation).
2802 A shell command is represented as a string; Emacs runs the command as a
2803 filter to perform the conversion.
2805 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2806 and @var{end}, which specify the part of the buffer it should convert.
2807 It should convert the text by editing it in place. Since this can
2808 change the length of the text, @var{from-fn} should return the modified
2811 One responsibility of @var{from-fn} is to make sure that the beginning
2812 of the file no longer matches @var{regexp}. Otherwise it is likely to
2816 A shell command or function to encode data in this format---that is, to
2817 convert the usual Emacs data representation into this format.
2819 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2820 command as a filter to perform the conversion.
2822 If @var{to-fn} is a function, it is called with two arguments, @var{begin}
2823 and @var{end}, which specify the part of the buffer it should convert.
2824 There are two ways it can do the conversion:
2828 By editing the buffer in place. In this case, @var{to-fn} should
2829 return the end-position of the range of text, as modified.
2832 By returning a list of annotations. This is a list of elements of the
2833 form @code{(@var{position} . @var{string})}, where @var{position} is an
2834 integer specifying the relative position in the text to be written, and
2835 @var{string} is the annotation to add there. The list must be sorted in
2836 order of position when @var{to-fn} returns it.
2838 When @code{write-region} actually writes the text from the buffer to the
2839 file, it intermixes the specified annotations at the corresponding
2840 positions. All this takes place without modifying the buffer.
2844 A flag, @code{t} if the encoding function modifies the buffer, and
2845 @code{nil} if it works by returning a list of annotations.
2848 A minor-mode function to call after visiting a file converted from this
2849 format. The function is called with one argument, the integer 1;
2850 that tells a minor-mode function to enable the mode.
2853 The function @code{insert-file-contents} automatically recognizes file
2854 formats when it reads the specified file. It checks the text of the
2855 beginning of the file against the regular expressions of the format
2856 definitions, and if it finds a match, it calls the decoding function for
2857 that format. Then it checks all the known formats over again.
2858 It keeps checking them until none of them is applicable.
2860 Visiting a file, with @code{find-file-noselect} or the commands that use
2861 it, performs conversion likewise (because it calls
2862 @code{insert-file-contents}); it also calls the mode function for each
2863 format that it decodes. It stores a list of the format names in the
2864 buffer-local variable @code{buffer-file-format}.
2866 @defvar buffer-file-format
2867 This variable states the format of the visited file. More precisely,
2868 this is a list of the file format names that were decoded in the course
2869 of visiting the current buffer's file. It is always buffer-local in all
2873 When @code{write-region} writes data into a file, it first calls the
2874 encoding functions for the formats listed in @code{buffer-file-format},
2875 in the order of appearance in the list.
2877 @deffn Command format-write-file file format &optional confirm
2878 This command writes the current buffer contents into the file
2879 @var{file} in format @var{format}, and makes that format the default
2880 for future saves of the buffer. The argument @var{format} is a list
2881 of format names. Except for the @var{format} argument, this command
2882 is similar to @code{write-file}. In particular, @var{confirm} has the
2883 same meaning and interactive treatment as the corresponding argument
2884 to @code{write-file}. @xref{Definition of write-file}.
2887 @deffn Command format-find-file file format
2888 This command finds the file @var{file}, converting it according to
2889 format @var{format}. It also makes @var{format} the default if the
2890 buffer is saved later.
2892 The argument @var{format} is a list of format names. If @var{format} is
2893 @code{nil}, no conversion takes place. Interactively, typing just
2894 @key{RET} for @var{format} specifies @code{nil}.
2897 @deffn Command format-insert-file file format &optional beg end
2898 This command inserts the contents of file @var{file}, converting it
2899 according to format @var{format}. If @var{beg} and @var{end} are
2900 non-@code{nil}, they specify which part of the file to read, as in
2901 @code{insert-file-contents} (@pxref{Reading from Files}).
2903 The return value is like what @code{insert-file-contents} returns: a
2904 list of the absolute file name and the length of the data inserted
2907 The argument @var{format} is a list of format names. If @var{format} is
2908 @code{nil}, no conversion takes place. Interactively, typing just
2909 @key{RET} for @var{format} specifies @code{nil}.
2912 @defvar buffer-auto-save-file-format
2913 This variable specifies the format to use for auto-saving. Its value is
2914 a list of format names, just like the value of
2915 @code{buffer-file-format}; however, it is used instead of
2916 @code{buffer-file-format} for writing auto-save files. If the value
2917 is @code{t}, the default, auto-saving uses the same format as a
2918 regular save in the same buffer. This variable is always buffer-local
2923 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c