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
118 returns a buffer visiting the file @var{filename}. You may make the
119 buffer current or display it in a window if you wish, but this
120 function does not do so.
122 The function returns an existing buffer if there is one; otherwise it
123 creates a new buffer and reads the file into it. When
124 @code{find-file-noselect} uses an existing buffer, it first verifies
125 that the file has not changed since it was last visited or saved in
126 that buffer. If the file has changed, this function asks the user
127 whether to reread the changed file. If the user says @samp{yes}, any
128 edits previously made in the buffer are lost.
130 Reading the file involves decoding the file's contents (@pxref{Coding
131 Systems}), including end-of-line conversion, and format conversion
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
133 then @code{find-file-noselect} expands wildcard characters in
134 @var{filename} and visits all the matching files.
136 This function displays warning or advisory messages in various peculiar
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
138 example, if it needs to create a buffer, and there is no file named
139 @var{filename}, it displays the message @samp{(New file)} in the echo
140 area, and leaves the buffer empty.
142 The @code{find-file-noselect} function normally calls
143 @code{after-find-file} after reading the file (@pxref{Subroutines of
144 Visiting}). That function sets the buffer major mode, parses local
145 variables, warns the user if there exists an auto-save file more recent
146 than the file just visited, and finishes by running the functions in
147 @code{find-file-hook}.
149 If the optional argument @var{rawfile} is non-@code{nil}, then
150 @code{after-find-file} is not called, and the
151 @code{find-file-not-found-functions} are not run in case of failure.
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
153 system conversion and format conversion.
155 The @code{find-file-noselect} function usually returns the buffer that
156 is visiting the file @var{filename}. But, if wildcards are actually
157 used and expanded, it returns a list of buffers that are visiting the
162 (find-file-noselect "/etc/fstab")
163 @result{} #<buffer fstab>
168 @deffn Command find-file-other-window filename &optional wildcards
169 This command selects a buffer visiting the file @var{filename}, but
170 does so in a window other than the selected window. It may use another
171 existing window or split a window; see @ref{Displaying Buffers}.
173 When this command is called interactively, it prompts for
177 @deffn Command find-file-read-only filename &optional wildcards
178 This command selects a buffer visiting the file @var{filename}, like
179 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
180 Buffers}, for related functions and variables.
182 When this command is called interactively, it prompts for
186 @deffn Command view-file filename
187 This command visits @var{filename} using View mode, returning to the
188 previous buffer when you exit View mode. View mode is a minor mode that
189 provides commands to skim rapidly through the file, but does not let you
190 modify the text. Entering View mode runs the normal hook
191 @code{view-mode-hook}. @xref{Hooks}.
193 When @code{view-file} is called interactively, it prompts for
197 @tindex find-file-wildcards
198 @defopt find-file-wildcards
199 If this variable is non-@code{nil}, then the various @code{find-file}
200 commands check for wildcard characters and visit all the files that
201 match them (when invoked interactively or when their @var{wildcards}
202 argument is non-@code{nil}). If this option is @code{nil}, then
203 the @code{find-file} commands ignore their @var{wildcards} argument
204 and never treat wildcard characters specially.
207 @defvar find-file-hook
208 The value of this variable is a list of functions to be called after a
209 file is visited. The file's local-variables specification (if any) will
210 have been processed before the hooks are run. The buffer visiting the
211 file is current when the hook functions are run.
213 This variable is a normal hook. @xref{Hooks}.
216 @defvar find-file-not-found-functions
217 The value of this variable is a list of functions to be called when
218 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
219 file name. @code{find-file-noselect} calls these functions as soon as
220 it detects a nonexistent file. It calls them in the order of the list,
221 until one of them returns non-@code{nil}. @code{buffer-file-name} is
224 This is not a normal hook because the values of the functions are
225 used, and in many cases only some of the functions are called.
228 @node Subroutines of Visiting
229 @comment node-name, next, previous, up
230 @subsection Subroutines of Visiting
232 The @code{find-file-noselect} function uses two important subroutines
233 which are sometimes useful in user Lisp code: @code{create-file-buffer}
234 and @code{after-find-file}. This section explains how to use them.
236 @defun create-file-buffer filename
237 This function creates a suitably named buffer for visiting
238 @var{filename}, and returns it. It uses @var{filename} (sans directory)
239 as the name if that name is free; otherwise, it appends a string such as
240 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
242 @strong{Please note:} @code{create-file-buffer} does @emph{not}
243 associate the new buffer with a file and does not select the buffer.
244 It also does not use the default major mode.
248 (create-file-buffer "foo")
249 @result{} #<buffer foo>
252 (create-file-buffer "foo")
253 @result{} #<buffer foo<2>>
256 (create-file-buffer "foo")
257 @result{} #<buffer foo<3>>
261 This function is used by @code{find-file-noselect}.
262 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
265 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
266 This function sets the buffer major mode, and parses local variables
267 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
268 and by the default revert function (@pxref{Reverting}).
270 @cindex new file message
271 @cindex file open error
272 If reading the file got an error because the file does not exist, but
273 its directory does exist, the caller should pass a non-@code{nil} value
274 for @var{error}. In that case, @code{after-find-file} issues a warning:
275 @samp{(New file)}. For more serious errors, the caller should usually not
276 call @code{after-find-file}.
278 If @var{warn} is non-@code{nil}, then this function issues a warning
279 if an auto-save file exists and is more recent than the visited file.
281 If @var{noauto} is non-@code{nil}, that says not to enable or disable
282 Auto-Save mode. The mode remains enabled if it was enabled before.
284 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
285 means this call was from @code{revert-buffer}. This has no direct
286 effect, but some mode functions and hook functions check the value
289 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
290 major mode, don't process local variables specifications in the file,
291 and don't run @code{find-file-hook}. This feature is used by
292 @code{revert-buffer} in some cases.
294 The last thing @code{after-find-file} does is call all the functions
295 in the list @code{find-file-hook}.
299 @section Saving Buffers
301 When you edit a file in Emacs, you are actually working on a buffer
302 that is visiting that file---that is, the contents of the file are
303 copied into the buffer and the copy is what you edit. Changes to the
304 buffer do not change the file until you @dfn{save} the buffer, which
305 means copying the contents of the buffer into the file.
307 @deffn Command save-buffer &optional backup-option
308 This function saves the contents of the current buffer in its visited
309 file if the buffer has been modified since it was last visited or saved.
310 Otherwise it does nothing.
312 @code{save-buffer} is responsible for making backup files. Normally,
313 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
314 file only if this is the first save since visiting the file. Other
315 values for @var{backup-option} request the making of backup files in
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
321 @code{save-buffer} function marks this version of the file to be
322 backed up when the buffer is next saved.
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
326 @code{save-buffer} function unconditionally backs up the previous
327 version of the file before saving it.
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
334 @deffn Command save-some-buffers &optional save-silently-p pred
335 @anchor{Definition of save-some-buffers}
336 This command saves some modified file-visiting buffers. Normally it
337 asks the user about each buffer. But if @var{save-silently-p} is
338 non-@code{nil}, it saves all the file-visiting buffers without querying
341 The optional @var{pred} argument controls which buffers to ask about
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
343 If it is @code{nil}, that means to ask only about file-visiting buffers.
344 If it is @code{t}, that means also offer to save certain other non-file
345 buffers---those that have a non-@code{nil} buffer-local value of
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
347 @samp{yes} to saving a non-file buffer is asked to specify the file
348 name to use. The @code{save-buffers-kill-emacs} function passes the
349 value @code{t} for @var{pred}.
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
352 a function of no arguments. It will be called in each buffer to decide
353 whether to offer to save that buffer. If it returns a non-@code{nil}
354 value in a certain buffer, that means do offer to save that buffer.
357 @deffn Command write-file filename &optional confirm
358 @anchor{Definition of write-file}
359 This function writes the current buffer into file @var{filename}, makes
360 the buffer visit that file, and marks it not modified. Then it renames
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
362 if necessary to make a unique buffer name. It does most of this work by
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
367 before overwriting an existing file. Interactively, confirmation is
368 required, unless the user supplies a prefix argument.
370 If @var{filename} is an existing directory, or a symbolic link to one,
371 @code{write-file} uses the name of the visited file, in directory
372 @var{filename}. If the buffer is not visiting a file, it uses the
376 Saving a buffer runs several hooks. It also performs format
377 conversion (@pxref{Format Conversion}), and may save text properties in
378 ``annotations'' (@pxref{Saving Properties}).
380 @defvar write-file-functions
381 The value of this variable is a list of functions to be called before
382 writing out a buffer to its visited file. If one of them returns
383 non-@code{nil}, the file is considered already written and the rest of
384 the functions are not called, nor is the usual code for writing the file
387 If a function in @code{write-file-functions} returns non-@code{nil}, it
388 is responsible for making a backup file (if that is appropriate).
389 To do so, execute the following code:
392 (or buffer-backed-up (backup-buffer))
395 You might wish to save the file modes value returned by
396 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
397 bits of the file that you write. This is what @code{save-buffer}
398 normally does. @xref{Making Backups,, Making Backup Files}.
400 The hook functions in @code{write-file-functions} are also responsible
401 for encoding the data (if desired): they must choose a suitable coding
402 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
403 perform the encoding (@pxref{Explicit Encoding}), and set
404 @code{last-coding-system-used} to the coding system that was used
405 (@pxref{Encoding and I/O}).
407 If you set this hook locally in a buffer, it is assumed to be
408 associated with the file or the way the contents of the buffer were
409 obtained. Thus the variable is marked as a permanent local, so that
410 changing the major mode does not alter a buffer-local value. On the
411 other hand, calling @code{set-visited-file-name} will reset it.
412 If this is not what you want, you might like to use
413 @code{write-contents-functions} instead.
415 Even though this is not a normal hook, you can use @code{add-hook} and
416 @code{remove-hook} to manipulate the list. @xref{Hooks}.
420 @defvar write-contents-functions
421 This works just like @code{write-file-functions}, but it is intended
422 for hooks that pertain to the buffer's contents, not to the particular
423 visited file or its location. Such hooks are usually set up by major
424 modes, as buffer-local bindings for this variable. This variable
425 automatically becomes buffer-local whenever it is set; switching to a
426 new major mode always resets this variable, but calling
427 @code{set-visited-file-name} does not.
429 If any of the functions in this hook returns non-@code{nil}, the file
430 is considered already written and the rest are not called and neither
431 are the functions in @code{write-file-functions}.
434 @defopt before-save-hook
435 This normal hook runs before a buffer is saved in its visited file,
436 regardless of whether that is done normally or by one of the hooks
437 described above. For instance, the @file{copyright.el} program uses
438 this hook to make sure the file you are saving has the current year in
439 its copyright notice.
443 @defopt after-save-hook
444 This normal hook runs after a buffer has been saved in its visited file.
445 One use of this hook is in Fast Lock mode; it uses this hook to save the
446 highlighting information in a cache file.
449 @defopt file-precious-flag
450 If this variable is non-@code{nil}, then @code{save-buffer} protects
451 against I/O errors while saving by writing the new file to a temporary
452 name instead of the name it is supposed to have, and then renaming it to
453 the intended name after it is clear there are no errors. This procedure
454 prevents problems such as a lack of disk space from resulting in an
457 As a side effect, backups are necessarily made by copying. @xref{Rename
458 or Copy}. Yet, at the same time, saving a precious file always breaks
459 all hard links between the file you save and other file names.
461 Some modes give this variable a non-@code{nil} buffer-local value
462 in particular buffers.
465 @defopt require-final-newline
466 This variable determines whether files may be written out that do
467 @emph{not} end with a newline. If the value of the variable is
468 @code{t}, then @code{save-buffer} silently adds a newline at the end of
469 the file whenever the buffer being saved does not already end in one.
470 If the value of the variable is non-@code{nil}, but not @code{t}, then
471 @code{save-buffer} asks the user whether to add a newline each time the
474 If the value of the variable is @code{nil}, then @code{save-buffer}
475 doesn't add newlines at all. @code{nil} is the default value, but a few
476 major modes set it to @code{t} in particular buffers.
479 See also the function @code{set-visited-file-name} (@pxref{Buffer File
482 @node Reading from Files
483 @comment node-name, next, previous, up
484 @section Reading from Files
486 You can copy a file from the disk and insert it into a buffer
487 using the @code{insert-file-contents} function. Don't use the user-level
488 command @code{insert-file} in a Lisp program, as that sets the mark.
490 @defun insert-file-contents filename &optional visit beg end replace
491 This function inserts the contents of file @var{filename} into the
492 current buffer after point. It returns a list of the absolute file name
493 and the length of the data inserted. An error is signaled if
494 @var{filename} is not the name of a file that can be read.
496 The function @code{insert-file-contents} checks the file contents
497 against the defined file formats, and converts the file contents if
498 appropriate. @xref{Format Conversion}. It also calls the functions in
499 the list @code{after-insert-file-functions}; see @ref{Saving
500 Properties}. Normally, one of the functions in the
501 @code{after-insert-file-functions} list determines the coding system
502 (@pxref{Coding Systems}) used for decoding the file's contents,
503 including end-of-line conversion.
505 If @var{visit} is non-@code{nil}, this function additionally marks the
506 buffer as unmodified and sets up various fields in the buffer so that it
507 is visiting the file @var{filename}: these include the buffer's visited
508 file name and its last save file modtime. This feature is used by
509 @code{find-file-noselect} and you probably should not use it yourself.
511 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
512 specifying the portion of the file to insert. In this case, @var{visit}
513 must be @code{nil}. For example,
516 (insert-file-contents filename nil 0 500)
520 inserts the first 500 characters of a file.
522 If the argument @var{replace} is non-@code{nil}, it means to replace the
523 contents of the buffer (actually, just the accessible portion) with the
524 contents of the file. This is better than simply deleting the buffer
525 contents and inserting the whole file, because (1) it preserves some
526 marker positions and (2) it puts less data in the undo list.
528 It is possible to read a special file (such as a FIFO or an I/O device)
529 with @code{insert-file-contents}, as long as @var{replace} and
530 @var{visit} are @code{nil}.
533 @defun insert-file-contents-literally filename &optional visit beg end replace
534 This function works like @code{insert-file-contents} except that it does
535 not do format decoding (@pxref{Format Conversion}), does not do
536 character code conversion (@pxref{Coding Systems}), does not run
537 @code{find-file-hook}, does not perform automatic uncompression, and so
541 If you want to pass a file name to another process so that another
542 program can read the file, use the function @code{file-local-copy}; see
543 @ref{Magic File Names}.
545 @node Writing to Files
546 @comment node-name, next, previous, up
547 @section Writing to Files
549 You can write the contents of a buffer, or part of a buffer, directly
550 to a file on disk using the @code{append-to-file} and
551 @code{write-region} functions. Don't use these functions to write to
552 files that are being visited; that could cause confusion in the
553 mechanisms for visiting.
555 @deffn Command append-to-file start end filename
556 This function appends the contents of the region delimited by
557 @var{start} and @var{end} in the current buffer to the end of file
558 @var{filename}. If that file does not exist, it is created. This
559 function returns @code{nil}.
561 An error is signaled if @var{filename} specifies a nonwritable file,
562 or a nonexistent file in a directory where files cannot be created.
564 When called from Lisp, this function is completely equivalent to:
567 (write-region start end filename t)
571 @deffn Command write-region start end filename &optional append visit lockname mustbenew
572 This function writes the region delimited by @var{start} and @var{end}
573 in the current buffer into the file specified by @var{filename}.
575 If @var{start} is @code{nil}, then the command writes the entire buffer
576 contents (@emph{not} just the accessible portion) to the file and
580 If @var{start} is a string, then @code{write-region} writes or appends
581 that string, rather than text from the buffer. @var{end} is ignored in
584 If @var{append} is non-@code{nil}, then the specified text is appended
585 to the existing file contents (if any). If @var{append} is an
586 integer, @code{write-region} seeks to that byte offset from the start
587 of the file and writes the data from there.
589 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
590 for confirmation if @var{filename} names an existing file. If
591 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
592 does not ask for confirmation, but instead it signals an error
593 @code{file-already-exists} if the file already exists.
595 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
596 a special system feature. At least for files on a local disk, there is
597 no chance that some other program could create a file of the same name
598 before Emacs does, without Emacs's noticing.
600 If @var{visit} is @code{t}, then Emacs establishes an association
601 between the buffer and the file: the buffer is then visiting that file.
602 It also sets the last file modification time for the current buffer to
603 @var{filename}'s modtime, and marks the buffer as not modified. This
604 feature is used by @code{save-buffer}, but you probably should not use
608 If @var{visit} is a string, it specifies the file name to visit. This
609 way, you can write the data to one file (@var{filename}) while recording
610 the buffer as visiting another file (@var{visit}). The argument
611 @var{visit} is used in the echo area message and also for file locking;
612 @var{visit} is stored in @code{buffer-file-name}. This feature is used
613 to implement @code{file-precious-flag}; don't use it yourself unless you
614 really know what you're doing.
616 The optional argument @var{lockname}, if non-@code{nil}, specifies the
617 file name to use for purposes of locking and unlocking, overriding
618 @var{filename} and @var{visit} for that purpose.
620 The function @code{write-region} converts the data which it writes to
621 the appropriate file formats specified by @code{buffer-file-format}.
622 @xref{Format Conversion}. It also calls the functions in the list
623 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
625 Normally, @code{write-region} displays the message @samp{Wrote
626 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
627 nor @code{nil} nor a string, then this message is inhibited. This
628 feature is useful for programs that use files for internal purposes,
629 files that the user does not need to know about.
632 @defmac with-temp-file file body@dots{}
633 @anchor{Definition of with-temp-file}
634 The @code{with-temp-file} macro evaluates the @var{body} forms with a
635 temporary buffer as the current buffer; then, at the end, it writes the
636 buffer contents into file @var{file}. It kills the temporary buffer
637 when finished, restoring the buffer that was current before the
638 @code{with-temp-file} form. Then it returns the value of the last form
641 The current buffer is restored even in case of an abnormal exit via
642 @code{throw} or error (@pxref{Nonlocal Exits}).
644 See also @code{with-temp-buffer} in @ref{Definition of
645 with-temp-buffer,, The Current Buffer}.
652 When two users edit the same file at the same time, they are likely
653 to interfere with each other. Emacs tries to prevent this situation
654 from arising by recording a @dfn{file lock} when a file is being
655 modified. (File locks are not implemented on Microsoft systems.)
656 Emacs can then detect the first attempt to modify a buffer visiting a
657 file that is locked by another Emacs job, and ask the user what to do.
658 The file lock is really a file, a symbolic link with a special name,
659 stored in the same directory as the file you are editing.
661 When you access files using NFS, there may be a small probability that
662 you and another user will both lock the same file ``simultaneously''.
663 If this happens, it is possible for the two users to make changes
664 simultaneously, but Emacs will still warn the user who saves second.
665 Also, the detection of modification of a buffer visiting a file changed
666 on disk catches some cases of simultaneous editing; see
667 @ref{Modification Time}.
669 @defun file-locked-p filename
670 This function returns @code{nil} if the file @var{filename} is not
671 locked. It returns @code{t} if it is locked by this Emacs process, and
672 it returns the name of the user who has locked it if it is locked by
677 (file-locked-p "foo")
683 @defun lock-buffer &optional filename
684 This function locks the file @var{filename}, if the current buffer is
685 modified. The argument @var{filename} defaults to the current buffer's
686 visited file. Nothing is done if the current buffer is not visiting a
687 file, or is not modified, or if the system does not support locking.
691 This function unlocks the file being visited in the current buffer,
692 if the buffer is modified. If the buffer is not modified, then
693 the file should not be locked, so this function does nothing. It also
694 does nothing if the current buffer is not visiting a file, or if the
695 system does not support locking.
698 File locking is not supported on some systems. On systems that do not
699 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
700 @code{file-locked-p} do nothing and return @code{nil}.
702 @defun ask-user-about-lock file other-user
703 This function is called when the user tries to modify @var{file}, but it
704 is locked by another user named @var{other-user}. The default
705 definition of this function asks the user to say what to do. The value
706 this function returns determines what Emacs does next:
710 A value of @code{t} says to grab the lock on the file. Then
711 this user may edit the file and @var{other-user} loses the lock.
714 A value of @code{nil} says to ignore the lock and let this
715 user edit the file anyway.
719 This function may instead signal a @code{file-locked} error, in which
720 case the change that the user was about to make does not take place.
722 The error message for this error looks like this:
725 @error{} File is locked: @var{file} @var{other-user}
729 where @code{file} is the name of the file and @var{other-user} is the
730 name of the user who has locked the file.
733 If you wish, you can replace the @code{ask-user-about-lock} function
734 with your own version that makes the decision in another way. The code
735 for its usual definition is in @file{userlock.el}.
738 @node Information about Files
739 @section Information about Files
741 The functions described in this section all operate on strings that
742 designate file names. With a few exceptions, all the functions have
743 names that begin with the word @samp{file}. These functions all
744 return information about actual files or directories, so their
745 arguments must all exist as actual files or directories unless
749 * Testing Accessibility:: Is a given file readable? Writable?
750 * Kinds of Files:: Is it a directory? A symbolic link?
751 * Truenames:: Eliminating symbolic links from a file name.
752 * File Attributes:: How large is it? Any other names? Etc.
753 * Locating Files:: How to find a file in standard places.
756 @node Testing Accessibility
757 @comment node-name, next, previous, up
758 @subsection Testing Accessibility
759 @cindex accessibility of a file
760 @cindex file accessibility
762 These functions test for permission to access a file in specific
763 ways. Unless explicitly stated otherwise, they recursively follow
764 symbolic links for their file name arguments, at all levels (at the
765 level of the file itself and at all levels of parent directories).
767 @defun file-exists-p filename
768 This function returns @code{t} if a file named @var{filename} appears
769 to exist. This does not mean you can necessarily read the file, only
770 that you can find out its attributes. (On Unix and GNU/Linux, this is
771 true if the file exists and you have execute permission on the
772 containing directories, regardless of the protection of the file
775 If the file does not exist, or if fascist access control policies
776 prevent you from finding the attributes of the file, this function
779 Directories are files, so @code{file-exists-p} returns @code{t} when
780 given a directory name. However, symbolic links are treated
781 specially; @code{file-exists-p} returns @code{t} for a symbolic link
782 name only if the target file exists.
785 @defun file-readable-p filename
786 This function returns @code{t} if a file named @var{filename} exists
787 and you can read it. It returns @code{nil} otherwise.
791 (file-readable-p "files.texi")
795 (file-exists-p "/usr/spool/mqueue")
799 (file-readable-p "/usr/spool/mqueue")
806 @defun file-executable-p filename
807 This function returns @code{t} if a file named @var{filename} exists and
808 you can execute it. It returns @code{nil} otherwise. On Unix and
809 GNU/Linux, if the file is a directory, execute permission means you can
810 check the existence and attributes of files inside the directory, and
811 open those files if their modes permit.
814 @defun file-writable-p filename
815 This function returns @code{t} if the file @var{filename} can be written
816 or created by you, and @code{nil} otherwise. A file is writable if the
817 file exists and you can write it. It is creatable if it does not exist,
818 but the specified directory does exist and you can write in that
821 In the third example below, @file{foo} is not writable because the
822 parent directory does not exist, even though the user could create such
827 (file-writable-p "~/foo")
831 (file-writable-p "/foo")
835 (file-writable-p "~/no-such-dir/foo")
842 @defun file-accessible-directory-p dirname
843 This function returns @code{t} if you have permission to open existing
844 files in the directory whose name as a file is @var{dirname};
845 otherwise (or if there is no such directory), it returns @code{nil}.
846 The value of @var{dirname} may be either a directory name (such as
847 @file{/foo/}) or the file name of a file which is a directory
848 (such as @file{/foo}, without the final slash).
850 Example: after the following,
853 (file-accessible-directory-p "/foo")
858 we can deduce that any attempt to read a file in @file{/foo/} will
862 @defun access-file filename string
863 This function opens file @var{filename} for reading, then closes it and
864 returns @code{nil}. However, if the open fails, it signals an error
865 using @var{string} as the error message text.
868 @defun file-ownership-preserved-p filename
869 This function returns @code{t} if deleting the file @var{filename} and
870 then creating it anew would keep the file's owner unchanged. It also
871 returns @code{t} for nonexistent files.
873 If @var{filename} is a symbolic link, then, unlike the other functions
874 discussed here, @code{file-ownership-preserved-p} does @emph{not}
875 replace @var{filename} with its target. However, it does recursively
876 follow symbolic links at all levels of parent directories.
879 @defun file-newer-than-file-p filename1 filename2
881 @cindex file modification time
882 This function returns @code{t} if the file @var{filename1} is
883 newer than file @var{filename2}. If @var{filename1} does not
884 exist, it returns @code{nil}. If @var{filename1} does exist, but
885 @var{filename2} does not, it returns @code{t}.
887 In the following example, assume that the file @file{aug-19} was written
888 on the 19th, @file{aug-20} was written on the 20th, and the file
889 @file{no-file} doesn't exist at all.
893 (file-newer-than-file-p "aug-19" "aug-20")
897 (file-newer-than-file-p "aug-20" "aug-19")
901 (file-newer-than-file-p "aug-19" "no-file")
905 (file-newer-than-file-p "no-file" "aug-19")
910 You can use @code{file-attributes} to get a file's last modification
911 time as a list of two numbers. @xref{File Attributes}.
915 @comment node-name, next, previous, up
916 @subsection Distinguishing Kinds of Files
918 This section describes how to distinguish various kinds of files, such
919 as directories, symbolic links, and ordinary files.
921 @defun file-symlink-p filename
922 @cindex file symbolic links
923 If the file @var{filename} is a symbolic link, the
924 @code{file-symlink-p} function returns the (non-recursive) link target
925 as a string. (Determining the file name that the link points to from
926 the target is nontrivial.) First, this function recursively follows
927 symbolic links at all levels of parent directories.
929 If the file @var{filename} is not a symbolic link (or there is no such file),
930 @code{file-symlink-p} returns @code{nil}.
934 (file-symlink-p "foo")
938 (file-symlink-p "sym-link")
942 (file-symlink-p "sym-link2")
946 (file-symlink-p "/bin")
951 @c !!! file-symlink-p: should show output of ls -l for comparison
954 The next two functions recursively follow symbolic links at
955 all levels for @var{filename}.
957 @defun file-directory-p filename
958 This function returns @code{t} if @var{filename} is the name of an
959 existing directory, @code{nil} otherwise.
963 (file-directory-p "~rms")
967 (file-directory-p "~rms/lewis/files.texi")
971 (file-directory-p "~rms/lewis/no-such-file")
975 (file-directory-p "$HOME")
980 (substitute-in-file-name "$HOME"))
986 @defun file-regular-p filename
987 This function returns @code{t} if the file @var{filename} exists and is
988 a regular file (not a directory, named pipe, terminal, or
993 @subsection Truenames
994 @cindex truename (of file)
997 The @dfn{truename} of a file is the name that you get by following
998 symbolic links at all levels until none remain, then simplifying away
999 @samp{.}@: and @samp{..}@: appearing as name components. This results
1000 in a sort of canonical name for the file. A file does not always have a
1001 unique truename; the number of distinct truenames a file has is equal to
1002 the number of hard links to the file. However, truenames are useful
1003 because they eliminate symbolic links as a cause of name variation.
1005 @defun file-truename filename
1006 The function @code{file-truename} returns the truename of the file
1007 @var{filename}. The argument must be an absolute file name.
1009 This function does not expand environment variables. Only
1010 @code{substitute-in-file-name} does that. @xref{Definition of
1011 substitute-in-file-name}.
1013 If you may need to follow symbolic links preceding @samp{..}@:
1014 appearing as a name component, you should make sure to call
1015 @code{file-truename} without prior direct or indirect calls to
1016 @code{expand-file-name}, as otherwise the file name component
1017 immediately preceding @samp{..} will be ``simplified away'' before
1018 @code{file-truename} is called. To eliminate the need for a call to
1019 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1020 same way that @code{expand-file-name} does. @xref{File Name
1021 Expansion,, Functions that Expand Filenames}.
1024 @defun file-chase-links filename &optional limit
1025 This function follows symbolic links, starting with @var{filename},
1026 until it finds a file name which is not the name of a symbolic link.
1027 Then it returns that file name. This function does @emph{not} follow
1028 symbolic links at the level of parent directories.
1030 If you specify a number for @var{limit}, then after chasing through
1031 that many links, the function just returns what it has even if that is
1032 still a symbolic link.
1035 To illustrate the difference between @code{file-chase-links} and
1036 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1037 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1038 ordinary file (or at least, not a symbolic link) or nonexistent. Then
1042 (file-chase-links "/usr/foo/hello")
1043 ;; @r{This does not follow the links in the parent directories.}
1044 @result{} "/usr/foo/hello"
1045 (file-truename "/usr/foo/hello")
1046 ;; @r{Assuming that @file{/home} is not a symbolic link.}
1047 @result{} "/home/foo/hello"
1050 @xref{Buffer File Name}, for related information.
1052 @node File Attributes
1053 @comment node-name, next, previous, up
1054 @subsection Other Information about Files
1056 This section describes the functions for getting detailed information
1057 about a file, other than its contents. This information includes the
1058 mode bits that control access permission, the owner and group numbers,
1059 the number of names, the inode number, the size, and the times of access
1062 @defun file-modes filename
1064 @cindex file attributes
1065 This function returns the mode bits of @var{filename}, as an integer.
1066 The mode bits are also called the file permissions, and they specify
1067 access control in the usual Unix fashion. If the low-order bit is 1,
1068 then the file is executable by all users, if the second-lowest-order bit
1069 is 1, then the file is writable by all users, etc.
1071 The highest value returnable is 4095 (7777 octal), meaning that
1072 everyone has read, write, and execute permission, that the @acronym{SUID} bit
1073 is set for both others and group, and that the sticky bit is set.
1075 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
1077 This function recursively follows symbolic links at all levels.
1081 (file-modes "~/junk/diffs")
1082 @result{} 492 ; @r{Decimal integer.}
1086 @result{} "754" ; @r{Convert to octal.}
1090 (set-file-modes "~/junk/diffs" 438)
1096 @result{} "666" ; @r{Convert to octal.}
1101 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1106 If the @var{filename} argument to the next two functions is a symbolic
1107 link, then these function do @emph{not} replace it with its target.
1108 However, they both recursively follow symbolic links at all levels of
1111 @defun file-nlinks filename
1112 This functions returns the number of names (i.e., hard links) that
1113 file @var{filename} has. If the file does not exist, then this function
1114 returns @code{nil}. Note that symbolic links have no effect on this
1115 function, because they are not considered to be names of the files they
1121 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1122 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1130 (file-nlinks "doesnt-exist")
1136 @defun file-attributes filename &optional id-format
1137 @anchor{Definition of file-attributes}
1138 This function returns a list of attributes of file @var{filename}. If
1139 the specified file cannot be opened, it returns @code{nil}.
1140 The optional parameter @var{id-format} specifies the preferred format
1141 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1142 valid values are @code{'string} and @code{'integer}. The latter is
1143 the default, but we plan to change that, so you should specify a
1144 non-@code{nil} value for @var{id-format} if you use the returned
1145 @acronym{UID} or @acronym{GID}.
1147 The elements of the list, in order, are:
1151 @code{t} for a directory, a string for a symbolic link (the name
1152 linked to), or @code{nil} for a text file.
1154 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
1156 The number of names the file has. Alternate names, also known as hard
1157 links, can be created by using the @code{add-name-to-file} function
1158 (@pxref{Changing Files}).
1161 The file's @acronym{UID} as a string or an integer. If a string
1162 value cannot be looked up, the integer value is returned.
1165 The file's @acronym{GID} likewise.
1168 The time of last access, as a list of two integers.
1169 The first integer has the high-order 16 bits of time,
1170 the second has the low 16 bits. (This is similar to the
1171 value of @code{current-time}; see @ref{Time of Day}.)
1174 The time of last modification as a list of two integers (as above).
1177 The time of last status change as a list of two integers (as above).
1180 The size of the file in bytes. If the size is too large to fit in a
1181 Lisp integer, this is a floating point number.
1184 The file's modes, as a string of ten letters or dashes,
1188 @code{t} if the file's @acronym{GID} would change if file were
1189 deleted and recreated; @code{nil} otherwise.
1192 The file's inode number. If possible, this is an integer. If the inode
1193 number is too large to be represented as an integer in Emacs Lisp, then
1194 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
1195 holds the low 16 bits.
1198 The file system number of the file system that the file is in.
1199 Depending on the magnitude of the value, this can be either an integer
1200 or a cons cell, in the same manner as the inode number. This element
1201 and the file's inode number together give enough information to
1202 distinguish any two files on the system---no two files can have the same
1203 values for both of these numbers.
1206 For example, here are the file attributes for @file{files.texi}:
1210 (file-attributes "files.texi" 'string)
1211 @result{} (nil 1 "lh" "users"
1221 and here is how the result is interpreted:
1225 is neither a directory nor a symbolic link.
1228 has only one name (the name @file{files.texi} in the current default
1232 is owned by the user with name "lh".
1235 is in the group with name "users".
1238 was last accessed on Aug 19 00:09.
1241 was last modified on Aug 19 00:09.
1244 last had its inode changed on Aug 19 00:09.
1247 is 14906 bytes long. (It may not contain 14906 characters, though,
1248 if some of the bytes belong to multibyte sequences.)
1251 has a mode of read and write access for the owner, group, and world.
1254 would retain the same @acronym{GID} if it were recreated.
1257 has an inode number of 129500.
1259 is on file system number -32252.
1263 @node Locating Files
1264 @subsection How to Locate Files in Standard Places
1265 @cindex locate files
1268 This section explains how to search for a file in a list of
1269 directories. One example is when you need to look for a program's
1270 executable file, e.g., to find out whether a given program is
1271 installed on the user's system. Another example is the search for
1272 Lisp libraries (@pxref{Library Search}). Such searches generally need
1273 to try various possible file name extensions, in addition to various
1274 possible directories. Emacs provides a function for such a
1275 generalized search for a file.
1277 @defun locate-file filename path &optional suffixes predicate
1278 This function searches for a file whose name is @var{filename} in a
1279 list of directories given by @var{path}, trying the suffixes in
1280 @var{suffixes}. If it finds such a file, it returns the full
1281 @dfn{absolute file name} of the file (@pxref{Relative File Names});
1282 otherwise it returns @code{nil}.
1284 The optional argument @var{suffixes} gives the list of file-name
1285 suffixes to append to @var{filename} when searching.
1286 @code{locate-file} tries each possible directory with each of these
1287 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
1288 are no suffixes, and @var{filename} is used only as-is. Typical
1289 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1290 Creation, exec-suffixes}), @code{load-suffixes},
1291 @code{load-file-rep-suffixes} and the return value of the function
1292 @code{get-load-suffixes} (@pxref{Load Suffixes}).
1294 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1295 Creation, exec-path}) when looking for executable programs or
1296 @code{load-path} (@pxref{Library Search, load-path}) when looking for
1297 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
1298 but the suffixes in @var{suffixes} are still tried.
1300 The optional argument @var{predicate}, if non-@code{nil}, specifies
1301 the predicate function to use for testing whether a candidate file is
1302 suitable. The predicate function is passed the candidate file name as
1303 its single argument. If @var{predicate} is @code{nil} or unspecified,
1304 @code{locate-file} uses @code{file-readable-p} as the default
1305 predicate. Useful non-default predicates include
1306 @code{file-executable-p}, @code{file-directory-p}, and other
1307 predicates described in @ref{Kinds of Files}.
1309 For compatibility, @var{predicate} can also be one of the symbols
1310 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1311 a list of one or more of these symbols.
1314 @cindex find executable program
1315 @defun executable-find program
1316 This function searches for the executable file of the named
1317 @var{program} and returns the full absolute name of the executable,
1318 including its file-name extensions, if any. It returns @code{nil} if
1319 the file is not found. The functions searches in all the directories
1320 in @code{exec-path} and tries all the file-name extensions in
1321 @code{exec-suffixes}.
1324 @node Changing Files
1325 @section Changing File Names and Attributes
1326 @cindex renaming files
1327 @cindex copying files
1328 @cindex deleting files
1329 @cindex linking files
1330 @cindex setting modes of files
1332 The functions in this section rename, copy, delete, link, and set the
1335 In the functions that have an argument @var{newname}, if a file by the
1336 name of @var{newname} already exists, the actions taken depend on the
1337 value of the argument @var{ok-if-already-exists}:
1341 Signal a @code{file-already-exists} error if
1342 @var{ok-if-already-exists} is @code{nil}.
1345 Request confirmation if @var{ok-if-already-exists} is a number.
1348 Replace the old file without confirmation if @var{ok-if-already-exists}
1352 The next four commands all recursively follow symbolic links at all
1353 levels of parent directories for their first argument, but, if that
1354 argument is itself a symbolic link, then only @code{copy-file}
1355 replaces it with its (recursive) target.
1357 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1358 @cindex file with multiple names
1359 @cindex file hard link
1360 This function gives the file named @var{oldname} the additional name
1361 @var{newname}. This means that @var{newname} becomes a new ``hard
1362 link'' to @var{oldname}.
1364 In the first part of the following example, we list two files,
1365 @file{foo} and @file{foo3}.
1370 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1371 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1375 Now we create a hard link, by calling @code{add-name-to-file}, then list
1376 the files again. This shows two names for one file, @file{foo} and
1381 (add-name-to-file "foo" "foo2")
1387 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1388 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1389 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1393 Finally, we evaluate the following:
1396 (add-name-to-file "foo" "foo3" t)
1400 and list the files again. Now there are three names
1401 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1402 contents of @file{foo3} are lost.
1406 (add-name-to-file "foo1" "foo3")
1412 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1413 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1414 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1418 This function is meaningless on operating systems where multiple names
1419 for one file are not allowed. Some systems implement multiple names
1420 by copying the file instead.
1422 See also @code{file-nlinks} in @ref{File Attributes}.
1425 @deffn Command rename-file filename newname &optional ok-if-already-exists
1426 This command renames the file @var{filename} as @var{newname}.
1428 If @var{filename} has additional names aside from @var{filename}, it
1429 continues to have those names. In fact, adding the name @var{newname}
1430 with @code{add-name-to-file} and then deleting @var{filename} has the
1431 same effect as renaming, aside from momentary intermediate states.
1434 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
1435 This command copies the file @var{oldname} to @var{newname}. An
1436 error is signaled if @var{oldname} does not exist. If @var{newname}
1437 names a directory, it copies @var{oldname} into that directory,
1438 preserving its final name component.
1440 If @var{time} is non-@code{nil}, then this function gives the new file
1441 the same last-modified time that the old one has. (This works on only
1442 some operating systems.) If setting the time gets an error,
1443 @code{copy-file} signals a @code{file-date-error} error. In an
1444 interactive call, a prefix argument specifies a non-@code{nil} value
1447 This function copies the file modes, too.
1449 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
1450 system decide the user and group ownership of the new file (this is
1451 usually set to the user running Emacs). If @var{preserve-uid-gid} is
1452 non-@code{nil}, we attempt to copy the user and group ownership of the
1453 file. This works only on some operating systems, and only if you have
1454 the correct permissions to do so.
1457 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
1459 @kindex file-already-exists
1460 This command makes a symbolic link to @var{filename}, named
1461 @var{newname}. This is like the shell command @samp{ln -s
1462 @var{filename} @var{newname}}.
1464 This function is not available on systems that don't support symbolic
1468 @deffn Command delete-file filename
1470 This command deletes the file @var{filename}, like the shell command
1471 @samp{rm @var{filename}}. If the file has multiple names, it continues
1472 to exist under the other names.
1474 A suitable kind of @code{file-error} error is signaled if the file does
1475 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
1476 deletable if its directory is writable.)
1478 If @var{filename} is a symbolic link, @code{delete-file} does not
1479 replace it with its target, but it does follow symbolic links at all
1480 levels of parent directories.
1482 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1485 @defun define-logical-name varname string
1486 This function defines the logical name @var{varname} to have the value
1487 @var{string}. It is available only on VMS.
1490 @defun set-file-modes filename mode
1491 This function sets mode bits of @var{filename} to @var{mode} (which
1492 must be an integer). Only the low 12 bits of @var{mode} are used.
1493 This function recursively follows symbolic links at all levels for
1498 @defun set-default-file-modes mode
1500 This function sets the default file protection for new files created by
1501 Emacs and its subprocesses. Every file created with Emacs initially has
1502 this protection, or a subset of it (@code{write-region} will not give a
1503 file execute permission even if the default file protection allows
1504 execute permission). On Unix and GNU/Linux, the default protection is
1505 the bitwise complement of the ``umask'' value.
1507 The argument @var{mode} must be an integer. On most systems, only the
1508 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
1509 for octal character codes to enter @var{mode}; for example,
1512 (set-default-file-modes ?\644)
1515 Saving a modified version of an existing file does not count as creating
1516 the file; it preserves the existing file's mode, whatever that is. So
1517 the default file protection has no effect.
1520 @defun default-file-modes
1521 This function returns the current default protection value.
1524 @defun set-file-times filename &optional time
1525 This function sets the access and modification times of @var{filename}
1526 to @var{time}. The return value is @code{t} if the times are successfully
1527 set, otherwise it is @code{nil}. @var{time} defaults to the current
1528 time and must be in the format returned by @code{current-time}
1529 (@pxref{Time of Day}).
1532 @cindex MS-DOS and file modes
1533 @cindex file modes and MS-DOS
1534 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1535 So Emacs considers a file executable if its name ends in one of the
1536 standard executable extensions, such as @file{.com}, @file{.bat},
1537 @file{.exe}, and some others. Files that begin with the Unix-standard
1538 @samp{#!} signature, such as shell and Perl scripts, are also considered
1539 as executable files. This is reflected in the values returned by
1540 @code{file-modes} and @code{file-attributes}. Directories are also
1541 reported with executable bit set, for compatibility with Unix.
1547 Files are generally referred to by their names, in Emacs as elsewhere.
1548 File names in Emacs are represented as strings. The functions that
1549 operate on a file all expect a file name argument.
1551 In addition to operating on files themselves, Emacs Lisp programs
1552 often need to operate on file names; i.e., to take them apart and to use
1553 part of a name to construct related file names. This section describes
1554 how to manipulate file names.
1556 The functions in this section do not actually access files, so they
1557 can operate on file names that do not refer to an existing file or
1560 On MS-DOS and MS-Windows, these functions (like the function that
1561 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1562 where backslashes separate the components, as well as Unix syntax; but
1563 they always return Unix syntax. On VMS, these functions (and the ones
1564 that operate on files) understand both VMS file-name syntax and Unix
1565 syntax. This enables Lisp programs to specify file names in Unix syntax
1566 and work properly on all systems without change.
1569 * File Name Components:: The directory part of a file name, and the rest.
1570 * Relative File Names:: Some file names are relative to a current directory.
1571 * Directory Names:: A directory's name as a directory
1572 is different from its name as a file.
1573 * File Name Expansion:: Converting relative file names to absolute ones.
1574 * Unique File Names:: Generating names for temporary files.
1575 * File Name Completion:: Finding the completions for a given file name.
1576 * Standard File Names:: If your package uses a fixed file name,
1577 how to handle various operating systems simply.
1580 @node File Name Components
1581 @subsection File Name Components
1582 @cindex directory part (of file name)
1583 @cindex nondirectory part (of file name)
1584 @cindex version number (in file name)
1586 The operating system groups files into directories. To specify a
1587 file, you must specify the directory and the file's name within that
1588 directory. Therefore, Emacs considers a file name as having two main
1589 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1590 (or @dfn{file name within the directory}). Either part may be empty.
1591 Concatenating these two parts reproduces the original file name.
1593 On most systems, the directory part is everything up to and including
1594 the last slash (backslash is also allowed in input on MS-DOS or
1595 MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
1598 For some purposes, the nondirectory part is further subdivided into
1599 the name proper and the @dfn{version number}. On most systems, only
1600 backup files have version numbers in their names. On VMS, every file
1601 has a version number, but most of the time the file name actually used
1602 in Emacs omits the version number, so that version numbers in Emacs are
1603 found mostly in directory lists.
1605 @defun file-name-directory filename
1606 This function returns the directory part of @var{filename}, as a
1607 directory name (@pxref{Directory Names}), or @code{nil} if
1608 @var{filename} does not include a directory part.
1610 On GNU and Unix systems, a string returned by this function always
1611 ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
1612 returns a string ending in one of the three characters @samp{:},
1613 @samp{]}, or @samp{>}.
1617 (file-name-directory "lewis/foo") ; @r{Unix example}
1621 (file-name-directory "foo") ; @r{Unix example}
1625 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
1631 @defun file-name-nondirectory filename
1632 This function returns the nondirectory part of @var{filename}.
1636 (file-name-nondirectory "lewis/foo")
1640 (file-name-nondirectory "foo")
1644 (file-name-nondirectory "lewis/")
1648 ;; @r{The following example is accurate only on VMS.}
1649 (file-name-nondirectory "[X]FOO.TMP")
1655 @defun file-name-sans-versions filename &optional keep-backup-version
1656 This function returns @var{filename} with any file version numbers,
1657 backup version numbers, or trailing tildes discarded.
1659 If @var{keep-backup-version} is non-@code{nil}, then true file version
1660 numbers understood as such by the file system are discarded from the
1661 return value, but backup version numbers are kept.
1665 (file-name-sans-versions "~rms/foo.~1~")
1666 @result{} "~rms/foo"
1669 (file-name-sans-versions "~rms/foo~")
1670 @result{} "~rms/foo"
1673 (file-name-sans-versions "~rms/foo")
1674 @result{} "~rms/foo"
1677 ;; @r{The following example applies to VMS only.}
1678 (file-name-sans-versions "foo;23")
1684 @defun file-name-extension filename &optional period
1685 This function returns @var{filename}'s final ``extension'', if any,
1686 after applying @code{file-name-sans-versions} to remove any
1687 version/backup part. The extension, in a file name, is the part that
1688 starts with the last @samp{.} in the last name component (minus
1689 any version/backup part).
1691 This function returns @code{nil} for extensionless file names such as
1692 @file{foo}. It returns @code{""} for null extensions, as in
1693 @file{foo.}. If the last component of a file name begins with a
1694 @samp{.}, that @samp{.} doesn't count as the beginning of an
1695 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1698 If @var{period} is non-@code{nil}, then the returned value includes
1699 the period that delimits the extension, and if @var{filename} has no
1700 extension, the value is @code{""}.
1703 @defun file-name-sans-extension filename
1704 This function returns @var{filename} minus its extension, if any. The
1705 version/backup part, if present, is only removed if the file has an
1706 extension. For example,
1709 (file-name-sans-extension "foo.lose.c")
1710 @result{} "foo.lose"
1711 (file-name-sans-extension "big.hack/foo")
1712 @result{} "big.hack/foo"
1713 (file-name-sans-extension "/my/home/.emacs")
1714 @result{} "/my/home/.emacs"
1715 (file-name-sans-extension "/my/home/.emacs.el")
1716 @result{} "/my/home/.emacs"
1717 (file-name-sans-extension "~/foo.el.~3~")
1719 (file-name-sans-extension "~/foo.~3~")
1720 @result{} "~/foo.~3~"
1723 Note that the @samp{.~3~} in the two last examples is the backup part,
1728 Andrew Innes says that this
1730 @c @defvar directory-sep-char
1731 @c @tindex directory-sep-char
1732 This variable holds the character that Emacs normally uses to separate
1733 file name components. The default value is @code{?/}, but on MS-Windows
1734 you can set it to @code{?\\}; then the functions that transform file names
1735 use backslashes in their output.
1737 File names using backslashes work as input to Lisp primitives even on
1738 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
1743 @node Relative File Names
1744 @subsection Absolute and Relative File Names
1745 @cindex absolute file name
1746 @cindex relative file name
1748 All the directories in the file system form a tree starting at the
1749 root directory. A file name can specify all the directory names
1750 starting from the root of the tree; then it is called an @dfn{absolute}
1751 file name. Or it can specify the position of the file in the tree
1752 relative to a default directory; then it is called a @dfn{relative} file
1753 name. On Unix and GNU/Linux, an absolute file name starts with a slash
1754 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
1755 MS-Windows, an absolute file name starts with a slash or a backslash, or
1756 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1757 @dfn{drive letter}. The rules on VMS are complicated.
1759 @defun file-name-absolute-p filename
1760 This function returns @code{t} if file @var{filename} is an absolute
1761 file name, @code{nil} otherwise. On VMS, this function understands both
1762 Unix syntax and VMS syntax.
1766 (file-name-absolute-p "~rms/foo")
1770 (file-name-absolute-p "rms/foo")
1774 (file-name-absolute-p "/user/rms/foo")
1780 Given a possibly relative file name, you can convert it to an
1781 absolute name using @code{expand-file-name} (@pxref{File Name
1782 Expansion}). This function converts absolute file names to relative
1785 @defun file-relative-name filename &optional directory
1786 This function tries to return a relative name that is equivalent to
1787 @var{filename}, assuming the result will be interpreted relative to
1788 @var{directory} (an absolute directory name or directory file name).
1789 If @var{directory} is omitted or @code{nil}, it defaults to the
1790 current buffer's default directory.
1792 On some operating systems, an absolute file name begins with a device
1793 name. On such systems, @var{filename} has no relative equivalent based
1794 on @var{directory} if they start with two different device names. In
1795 this case, @code{file-relative-name} returns @var{filename} in absolute
1799 (file-relative-name "/foo/bar" "/foo/")
1801 (file-relative-name "/foo/bar" "/hack/")
1802 @result{} "../foo/bar"
1806 @node Directory Names
1807 @comment node-name, next, previous, up
1808 @subsection Directory Names
1809 @cindex directory name
1810 @cindex file name of directory
1812 A @dfn{directory name} is the name of a directory. A directory is
1813 actually a kind of file, so it has a file name, which is related to
1814 the directory name but not identical to it. (This is not quite the
1815 same as the usual Unix terminology.) These two different names for
1816 the same entity are related by a syntactic transformation. On GNU and
1817 Unix systems, this is simple: a directory name ends in a slash,
1818 whereas the directory's name as a file lacks that slash. On MS-DOS and
1819 VMS, the relationship is more complicated.
1821 The difference between a directory name and its name as a file is
1822 subtle but crucial. When an Emacs variable or function argument is
1823 described as being a directory name, a file name of a directory is not
1824 acceptable. When @code{file-name-directory} returns a string, that is
1825 always a directory name.
1827 The following two functions convert between directory names and file
1828 names. They do nothing special with environment variable substitutions
1829 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1831 @defun file-name-as-directory filename
1832 This function returns a string representing @var{filename} in a form
1833 that the operating system will interpret as the name of a directory. On
1834 most systems, this means appending a slash to the string (if it does not
1835 already end in one). On VMS, the function converts a string of the form
1836 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
1840 (file-name-as-directory "~rms/lewis")
1841 @result{} "~rms/lewis/"
1846 @defun directory-file-name dirname
1847 This function returns a string representing @var{dirname} in a form that
1848 the operating system will interpret as the name of a file. On most
1849 systems, this means removing the final slash (or backslash) from the
1850 string. On VMS, the function converts a string of the form @file{[X.Y]}
1851 to @file{[X]Y.DIR.1}.
1855 (directory-file-name "~lewis/")
1861 Given a directory name, you can combine it with a relative file name
1862 using @code{concat}:
1865 (concat @var{dirname} @var{relfile})
1869 Be sure to verify that the file name is relative before doing that.
1870 If you use an absolute file name, the results could be syntactically
1871 invalid or refer to the wrong file.
1873 If you want to use a directory file name in making such a
1874 combination, you must first convert it to a directory name using
1875 @code{file-name-as-directory}:
1878 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1882 Don't try concatenating a slash by hand, as in
1886 (concat @var{dirfile} "/" @var{relfile})
1890 because this is not portable. Always use
1891 @code{file-name-as-directory}.
1893 @cindex directory name abbreviation
1894 Directory name abbreviations are useful for directories that are
1895 normally accessed through symbolic links. Sometimes the users recognize
1896 primarily the link's name as ``the name'' of the directory, and find it
1897 annoying to see the directory's ``real'' name. If you define the link
1898 name as an abbreviation for the ``real'' name, Emacs shows users the
1899 abbreviation instead.
1901 @defvar directory-abbrev-alist
1902 The variable @code{directory-abbrev-alist} contains an alist of
1903 abbreviations to use for file directories. Each element has the form
1904 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1905 @var{to} when it appears in a directory name. The @var{from} string is
1906 actually a regular expression; it should always start with @samp{^}.
1907 The @var{to} string should be an ordinary absolute directory name. Do
1908 not use @samp{~} to stand for a home directory in that string. The
1909 function @code{abbreviate-file-name} performs these substitutions.
1911 You can set this variable in @file{site-init.el} to describe the
1912 abbreviations appropriate for your site.
1914 Here's an example, from a system on which file system @file{/home/fsf}
1915 and so on are normally accessed through symbolic links named @file{/fsf}
1919 (("^/home/fsf" . "/fsf")
1920 ("^/home/gp" . "/gp")
1921 ("^/home/gd" . "/gd"))
1925 To convert a directory name to its abbreviation, use this
1928 @defun abbreviate-file-name filename
1929 @anchor{Definition of abbreviate-file-name}
1930 This function applies abbreviations from @code{directory-abbrev-alist}
1931 to its argument, and substitutes @samp{~} for the user's home
1932 directory. You can use it for directory names and for file names,
1933 because it recognizes abbreviations even as part of the name.
1936 @node File Name Expansion
1937 @subsection Functions that Expand Filenames
1938 @cindex expansion of file names
1940 @dfn{Expansion} of a file name means converting a relative file name
1941 to an absolute one. Since this is done relative to a default directory,
1942 you must specify the default directory name as well as the file name to
1943 be expanded. Expansion also simplifies file names by eliminating
1944 redundancies such as @file{./} and @file{@var{name}/../}.
1946 @defun expand-file-name filename &optional directory
1947 This function converts @var{filename} to an absolute file name. If
1948 @var{directory} is supplied, it is the default directory to start with
1949 if @var{filename} is relative. (The value of @var{directory} should
1950 itself be an absolute directory name or directory file name; it may
1951 start with @samp{~}.) Otherwise, the current buffer's value of
1952 @code{default-directory} is used. For example:
1956 (expand-file-name "foo")
1957 @result{} "/xcssun/users/rms/lewis/foo"
1960 (expand-file-name "../foo")
1961 @result{} "/xcssun/users/rms/foo"
1964 (expand-file-name "foo" "/usr/spool/")
1965 @result{} "/usr/spool/foo"
1968 (expand-file-name "$HOME/foo")
1969 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1973 If the part of the combined file name before the first slash is
1974 @samp{~}, it expands to the value of the @env{HOME} environment
1975 variable (usually your home directory). If the part before the first
1976 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
1977 it expands to @var{user}'s home directory.
1979 Filenames containing @samp{.} or @samp{..} are simplified to their
1984 (expand-file-name "bar/../foo")
1985 @result{} "/xcssun/users/rms/lewis/foo"
1989 Note that @code{expand-file-name} does @emph{not} expand environment
1990 variables; only @code{substitute-in-file-name} does that.
1992 Note also that @code{expand-file-name} does not follow symbolic links
1993 at any level. This results in a difference between the way
1994 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
1995 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
1996 @samp{/tmp/foo/bar} we get:
2000 (file-truename "/tmp/bar/../myfile")
2001 @result{} "/tmp/foo/myfile"
2004 (expand-file-name "/tmp/bar/../myfile")
2005 @result{} "/tmp/myfile"
2009 If you may need to follow symbolic links preceding @samp{..}, you
2010 should make sure to call @code{file-truename} without prior direct or
2011 indirect calls to @code{expand-file-name}. @xref{Truenames}.
2014 @defvar default-directory
2015 The value of this buffer-local variable is the default directory for the
2016 current buffer. It should be an absolute directory name; it may start
2017 with @samp{~}. This variable is buffer-local in every buffer.
2019 @code{expand-file-name} uses the default directory when its second
2020 argument is @code{nil}.
2022 Aside from VMS, the value is always a string ending with a slash.
2027 @result{} "/user/lewis/manual/"
2032 @defun substitute-in-file-name filename
2033 @anchor{Definition of substitute-in-file-name}
2034 This function replaces environment variable references in
2035 @var{filename} with the environment variable values. Following
2036 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2037 environment variable value. If the input contains @samp{$$}, that is
2038 converted to @samp{$}; this gives the user a way to ``quote'' a
2041 The environment variable name is the series of alphanumeric characters
2042 (including underscores) that follow the @samp{$}. If the character following
2043 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2046 Calling @code{substitute-in-file-name} on output produced by
2047 @code{substitute-in-file-name} tends to give incorrect results. For
2048 instance, use of @samp{$$} to quote a single @samp{$} won't work
2049 properly, and @samp{$} in an environment variable's value could lead
2050 to repeated substitution. Therefore, programs that call this function
2051 and put the output where it will be passed to this function need to
2052 double all @samp{$} characters to prevent subsequent incorrect
2055 @c Wordy to avoid overfull hbox. --rjc 15mar92
2056 Here we assume that the environment variable @code{HOME}, which holds
2057 the user's home directory name, has value @samp{/xcssun/users/rms}.
2061 (substitute-in-file-name "$HOME/foo")
2062 @result{} "/xcssun/users/rms/foo"
2066 After substitution, if a @samp{~} or a @samp{/} appears immediately
2067 after another @samp{/}, the function discards everything before it (up
2068 through the immediately preceding @samp{/}).
2072 (substitute-in-file-name "bar/~/foo")
2076 (substitute-in-file-name "/usr/local/$HOME/foo")
2077 @result{} "/xcssun/users/rms/foo"
2078 ;; @r{@file{/usr/local/} has been discarded.}
2082 On VMS, @samp{$} substitution is not done, so this function does nothing
2083 on VMS except discard superfluous initial components as shown above.
2086 @node Unique File Names
2087 @subsection Generating Unique File Names
2089 Some programs need to write temporary files. Here is the usual way to
2090 construct a name for such a file:
2093 (make-temp-file @var{name-of-application})
2097 The job of @code{make-temp-file} is to prevent two different users or
2098 two different jobs from trying to use the exact same file name.
2100 @defun make-temp-file prefix &optional dir-flag suffix
2101 @tindex make-temp-file
2102 This function creates a temporary file and returns its name. Emacs
2103 creates the temporary file's name by adding to @var{prefix} some
2104 random characters that are different in each Emacs job. The result is
2105 guaranteed to be a newly created empty file. On MS-DOS, this function
2106 can truncate the @var{string} prefix to fit into the 8+3 file-name
2107 limits. If @var{prefix} is a relative file name, it is expanded
2108 against @code{temporary-file-directory}.
2112 (make-temp-file "foo")
2113 @result{} "/tmp/foo232J6v"
2117 When @code{make-temp-file} returns, the file has been created and is
2118 empty. At that point, you should write the intended contents into the
2121 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2122 empty directory instead of an empty file. It returns the file name,
2123 not the directory name, of that directory. @xref{Directory Names}.
2125 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2126 the end of the file name.
2128 To prevent conflicts among different libraries running in the same
2129 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2130 own @var{prefix}. The number added to the end of @var{prefix}
2131 distinguishes between the same application running in different Emacs
2132 jobs. Additional added characters permit a large number of distinct
2133 names even in one Emacs job.
2136 The default directory for temporary files is controlled by the
2137 variable @code{temporary-file-directory}. This variable gives the user
2138 a uniform way to specify the directory for all temporary files. Some
2139 programs use @code{small-temporary-file-directory} instead, if that is
2140 non-@code{nil}. To use it, you should expand the prefix against
2141 the proper directory before calling @code{make-temp-file}.
2143 In older Emacs versions where @code{make-temp-file} does not exist,
2144 you should use @code{make-temp-name} instead:
2148 (expand-file-name @var{name-of-application}
2149 temporary-file-directory))
2152 @defun make-temp-name string
2153 This function generates a string that can be used as a unique file
2154 name. The name starts with @var{string}, and has several random
2155 characters appended to it, which are different in each Emacs job. It
2156 is like @code{make-temp-file} except that it just constructs a name,
2157 and does not create a file. Another difference is that @var{string}
2158 should be an absolute file name. On MS-DOS, this function can
2159 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
2162 @defvar temporary-file-directory
2163 @cindex @code{TMPDIR} environment variable
2164 @cindex @code{TMP} environment variable
2165 @cindex @code{TEMP} environment variable
2166 This variable specifies the directory name for creating temporary files.
2167 Its value should be a directory name (@pxref{Directory Names}), but it
2168 is good for Lisp programs to cope if the value is a directory's file
2169 name instead. Using the value as the second argument to
2170 @code{expand-file-name} is a good way to achieve that.
2172 The default value is determined in a reasonable way for your operating
2173 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2174 environment variables, with a fall-back to a system-dependent name if
2175 none of these variables is defined.
2177 Even if you do not use @code{make-temp-file} to create the temporary
2178 file, you should still use this variable to decide which directory to
2179 put the file in. However, if you expect the file to be small, you
2180 should use @code{small-temporary-file-directory} first if that is
2184 @tindex small-temporary-file-directory
2185 @defvar small-temporary-file-directory
2186 This variable specifies the directory name for
2187 creating certain temporary files, which are likely to be small.
2189 If you want to write a temporary file which is likely to be small, you
2190 should compute the directory like this:
2194 (expand-file-name @var{prefix}
2195 (or small-temporary-file-directory
2196 temporary-file-directory)))
2200 @node File Name Completion
2201 @subsection File Name Completion
2202 @cindex file name completion subroutines
2203 @cindex completion, file name
2205 This section describes low-level subroutines for completing a file
2206 name. For higher level functions, see @ref{Reading File Names}.
2208 @defun file-name-all-completions partial-filename directory
2209 This function returns a list of all possible completions for a file
2210 whose name starts with @var{partial-filename} in directory
2211 @var{directory}. The order of the completions is the order of the files
2212 in the directory, which is unpredictable and conveys no useful
2215 The argument @var{partial-filename} must be a file name containing no
2216 directory part and no slash (or backslash on some systems). The current
2217 buffer's default directory is prepended to @var{directory}, if
2218 @var{directory} is not absolute.
2220 In the following example, suppose that @file{~rms/lewis} is the current
2221 default directory, and has five files whose names begin with @samp{f}:
2222 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2223 @file{file.c.~2~}.@refill
2227 (file-name-all-completions "f" "")
2228 @result{} ("foo" "file~" "file.c.~2~"
2229 "file.c.~1~" "file.c")
2233 (file-name-all-completions "fo" "")
2239 @defun file-name-completion filename directory
2240 This function completes the file name @var{filename} in directory
2241 @var{directory}. It returns the longest prefix common to all file names
2242 in directory @var{directory} that start with @var{filename}.
2244 If only one match exists and @var{filename} matches it exactly, the
2245 function returns @code{t}. The function returns @code{nil} if directory
2246 @var{directory} contains no name starting with @var{filename}.
2248 In the following example, suppose that the current default directory
2249 has five files whose names begin with @samp{f}: @file{foo},
2250 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2251 @file{file.c.~2~}.@refill
2255 (file-name-completion "fi" "")
2260 (file-name-completion "file.c.~1" "")
2261 @result{} "file.c.~1~"
2265 (file-name-completion "file.c.~1~" "")
2270 (file-name-completion "file.c.~3" "")
2276 @defopt completion-ignored-extensions
2277 @code{file-name-completion} usually ignores file names that end in any
2278 string in this list. It does not ignore them when all the possible
2279 completions end in one of these suffixes. This variable has no effect
2280 on @code{file-name-all-completions}.@refill
2282 A typical value might look like this:
2286 completion-ignored-extensions
2287 @result{} (".o" ".elc" "~" ".dvi")
2291 If an element of @code{completion-ignored-extensions} ends in a slash
2292 @samp{/}, it signals a directory. The elements which do @emph{not} end
2293 in a slash will never match a directory; thus, the above value will not
2294 filter out a directory named @file{foo.elc}.
2297 @node Standard File Names
2298 @subsection Standard File Names
2300 Most of the file names used in Lisp programs are entered by the user.
2301 But occasionally a Lisp program needs to specify a standard file name
2302 for a particular use---typically, to hold customization information
2303 about each user. For example, abbrev definitions are stored (by
2304 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2305 package stores completions in the file @file{~/.completions}. These are
2306 two of the many standard file names used by parts of Emacs for certain
2309 Various operating systems have their own conventions for valid file
2310 names and for which file names to use for user profile data. A Lisp
2311 program which reads a file using a standard file name ought to use, on
2312 each type of system, a file name suitable for that system. The function
2313 @code{convert-standard-filename} makes this easy to do.
2315 @defun convert-standard-filename filename
2316 This function alters the file name @var{filename} to fit the conventions
2317 of the operating system in use, and returns the result as a new string.
2320 The recommended way to specify a standard file name in a Lisp program
2321 is to choose a name which fits the conventions of GNU and Unix systems,
2322 usually with a nondirectory part that starts with a period, and pass it
2323 to @code{convert-standard-filename} instead of using it directly. Here
2324 is an example from the @code{completion} package:
2327 (defvar save-completions-file-name
2328 (convert-standard-filename "~/.completions")
2329 "*The file name to save completions to.")
2332 On GNU and Unix systems, and on some other systems as well,
2333 @code{convert-standard-filename} returns its argument unchanged. On
2334 some other systems, it alters the name to fit the system's conventions.
2336 For example, on MS-DOS the alterations made by this function include
2337 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
2338 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2339 a @samp{.} after eight characters if there is none, and truncating to
2340 three characters after the @samp{.}. (It makes other changes as well.)
2341 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2342 @file{.completions} becomes @file{_complet.ion}.
2344 @node Contents of Directories
2345 @section Contents of Directories
2346 @cindex directory-oriented functions
2347 @cindex file names in directory
2349 A directory is a kind of file that contains other files entered under
2350 various names. Directories are a feature of the file system.
2352 Emacs can list the names of the files in a directory as a Lisp list,
2353 or display the names in a buffer using the @code{ls} shell command. In
2354 the latter case, it can optionally display information about each file,
2355 depending on the options passed to the @code{ls} command.
2357 @defun directory-files directory &optional full-name match-regexp nosort
2358 This function returns a list of the names of the files in the directory
2359 @var{directory}. By default, the list is in alphabetical order.
2361 If @var{full-name} is non-@code{nil}, the function returns the files'
2362 absolute file names. Otherwise, it returns the names relative to
2363 the specified directory.
2365 If @var{match-regexp} is non-@code{nil}, this function returns only
2366 those file names that contain a match for that regular expression---the
2367 other file names are excluded from the list. On case-insensitive
2368 filesystems, the regular expression matching is case-insensitive.
2371 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2372 the list, so you get the file names in no particular order. Use this if
2373 you want the utmost possible speed and don't care what order the files
2374 are processed in. If the order of processing is visible to the user,
2375 then the user will probably be happier if you do sort the names.
2379 (directory-files "~lewis")
2380 @result{} ("#foo#" "#foo.el#" "." ".."
2381 "dired-mods.el" "files.texi"
2386 An error is signaled if @var{directory} is not the name of a directory
2390 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2391 This is similar to @code{directory-files} in deciding which files
2392 to report on and how to report their names. However, instead
2393 of returning a list of file names, it returns for each file a
2394 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2395 is what @code{file-attributes} would return for that file.
2396 The optional argument @var{id-format} has the same meaning as the
2397 corresponding argument to @code{file-attributes} (@pxref{Definition
2398 of file-attributes}).
2401 @defun file-name-all-versions file dirname
2402 This function returns a list of all versions of the file named
2403 @var{file} in directory @var{dirname}. It is only available on VMS.
2406 @tindex file-expand-wildcards
2407 @defun file-expand-wildcards pattern &optional full
2408 This function expands the wildcard pattern @var{pattern}, returning
2409 a list of file names that match it.
2411 If @var{pattern} is written as an absolute file name,
2412 the values are absolute also.
2414 If @var{pattern} is written as a relative file name, it is interpreted
2415 relative to the current default directory. The file names returned are
2416 normally also relative to the current default directory. However, if
2417 @var{full} is non-@code{nil}, they are absolute.
2420 @defun insert-directory file switches &optional wildcard full-directory-p
2421 This function inserts (in the current buffer) a directory listing for
2422 directory @var{file}, formatted with @code{ls} according to
2423 @var{switches}. It leaves point after the inserted text.
2424 @var{switches} may be a string of options, or a list of strings
2425 representing individual options.
2427 The argument @var{file} may be either a directory name or a file
2428 specification including wildcard characters. If @var{wildcard} is
2429 non-@code{nil}, that means treat @var{file} as a file specification with
2432 If @var{full-directory-p} is non-@code{nil}, that means the directory
2433 listing is expected to show the full contents of a directory. You
2434 should specify @code{t} when @var{file} is a directory and switches do
2435 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
2436 describe a directory itself as a file, rather than showing its
2439 On most systems, this function works by running a directory listing
2440 program whose name is in the variable @code{insert-directory-program}.
2441 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2442 @code{shell-file-name}, to expand the wildcards.
2444 MS-DOS and MS-Windows systems usually lack the standard Unix program
2445 @code{ls}, so this function emulates the standard Unix program @code{ls}
2448 As a technical detail, when @var{switches} contains the long
2449 @samp{--dired} option, @code{insert-directory} treats it specially,
2450 for the sake of dired. However, the normally equivalent short
2451 @samp{-D} option is just passed on to @code{insert-directory-program},
2452 as any other option.
2455 @defvar insert-directory-program
2456 This variable's value is the program to run to generate a directory listing
2457 for the function @code{insert-directory}. It is ignored on systems
2458 which generate the listing with Lisp code.
2461 @node Create/Delete Dirs
2462 @section Creating and Deleting Directories
2463 @c Emacs 19 features
2465 Most Emacs Lisp file-manipulation functions get errors when used on
2466 files that are directories. For example, you cannot delete a directory
2467 with @code{delete-file}. These special functions exist to create and
2470 @defun make-directory dirname &optional parents
2471 This function creates a directory named @var{dirname}.
2472 If @var{parents} is non-@code{nil}, as is always the case in an
2473 interactive call, that means to create the parent directories first,
2474 if they don't already exist.
2477 @defun delete-directory dirname
2478 This function deletes the directory named @var{dirname}. The function
2479 @code{delete-file} does not work for files that are directories; you
2480 must use @code{delete-directory} for them. If the directory contains
2481 any files, @code{delete-directory} signals an error.
2483 This function only follows symbolic links at the level of parent
2487 @node Magic File Names
2488 @section Making Certain File Names ``Magic''
2489 @cindex magic file names
2492 You can implement special handling for certain file names. This is
2493 called making those names @dfn{magic}. The principal use for this
2494 feature is in implementing remote file names (@pxref{Remote Files,,
2495 Remote Files, emacs, The GNU Emacs Manual}).
2497 To define a kind of magic file name, you must supply a regular
2498 expression to define the class of names (all those that match the
2499 regular expression), plus a handler that implements all the primitive
2500 Emacs file operations for file names that do match.
2502 The variable @code{file-name-handler-alist} holds a list of handlers,
2503 together with regular expressions that determine when to apply each
2504 handler. Each element has this form:
2507 (@var{regexp} . @var{handler})
2511 All the Emacs primitives for file access and file name transformation
2512 check the given file name against @code{file-name-handler-alist}. If
2513 the file name matches @var{regexp}, the primitives handle that file by
2514 calling @var{handler}.
2516 The first argument given to @var{handler} is the name of the
2517 primitive, as a symbol; the remaining arguments are the arguments that
2518 were passed to that primitive. (The first of these arguments is most
2519 often the file name itself.) For example, if you do this:
2522 (file-exists-p @var{filename})
2526 and @var{filename} has handler @var{handler}, then @var{handler} is
2530 (funcall @var{handler} 'file-exists-p @var{filename})
2533 When a function takes two or more arguments that must be file names,
2534 it checks each of those names for a handler. For example, if you do
2538 (expand-file-name @var{filename} @var{dirname})
2542 then it checks for a handler for @var{filename} and then for a handler
2543 for @var{dirname}. In either case, the @var{handler} is called like
2547 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2551 The @var{handler} then needs to figure out whether to handle
2552 @var{filename} or @var{dirname}.
2554 If the specified file name matches more than one handler, the one
2555 whose match starts last in the file name gets precedence. This rule
2556 is chosen so that handlers for jobs such as uncompression are handled
2557 first, before handlers for jobs such as remote file access.
2559 Here are the operations that a magic file name handler gets to handle:
2563 @code{access-file}, @code{add-name-to-file},
2564 @code{byte-compiler-base-file-name},@*
2565 @code{copy-file}, @code{delete-directory},
2567 @code{diff-latest-backup-file},
2568 @code{directory-file-name},
2569 @code{directory-files},
2570 @code{directory-files-and-attributes},
2571 @code{dired-call-process},
2572 @code{dired-compress-file}, @code{dired-uncache},@*
2573 @code{expand-file-name},
2574 @code{file-accessible-directory-p},
2575 @code{file-attributes},
2576 @code{file-directory-p},
2577 @code{file-executable-p}, @code{file-exists-p},
2578 @code{file-local-copy}, @code{file-remote-p},
2579 @code{file-modes}, @code{file-name-all-completions},
2580 @code{file-name-as-directory},
2581 @code{file-name-completion},
2582 @code{file-name-directory},
2583 @code{file-name-nondirectory},
2584 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2585 @code{file-ownership-preserved-p},
2586 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2587 @code{file-truename}, @code{file-writable-p},
2588 @code{find-backup-file-name},
2589 @code{find-file-noselect},@*
2590 @code{get-file-buffer},
2591 @code{insert-directory},
2592 @code{insert-file-contents},@*
2594 @code{make-auto-save-file-name},
2595 @code{make-directory},
2596 @code{make-directory-internal},
2597 @code{make-symbolic-link},@*
2598 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2599 @code{set-visited-file-modtime}, @code{shell-command},
2600 @code{substitute-in-file-name},@*
2601 @code{unhandled-file-name-directory},
2602 @code{vc-registered},
2603 @code{verify-visited-file-modtime},@*
2604 @code{write-region}.
2609 @code{access-file}, @code{add-name-to-file},
2610 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2611 @code{copy-file}, @code{delete-directory},
2613 @code{diff-latest-backup-file},
2614 @code{directory-file-name},
2615 @code{directory-files},
2616 @code{directory-files-and-at@discretionary{}{}{}tributes},
2617 @code{dired-call-process},
2618 @code{dired-compress-file}, @code{dired-uncache},
2619 @code{expand-file-name},
2620 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2621 @code{file-attributes},
2622 @code{file-direct@discretionary{}{}{}ory-p},
2623 @code{file-executable-p}, @code{file-exists-p},
2624 @code{file-local-copy}, @code{file-remote-p},
2625 @code{file-modes}, @code{file-name-all-completions},
2626 @code{file-name-as-directory},
2627 @code{file-name-completion},
2628 @code{file-name-directory},
2629 @code{file-name-nondirec@discretionary{}{}{}tory},
2630 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2631 @code{file-ownership-pre@discretionary{}{}{}served-p},
2632 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2633 @code{file-truename}, @code{file-writable-p},
2634 @code{find-backup-file-name},
2635 @code{find-file-noselect},
2636 @code{get-file-buffer},
2637 @code{insert-directory},
2638 @code{insert-file-contents},
2639 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2640 @code{make-direc@discretionary{}{}{}tory-internal},
2641 @code{make-symbolic-link},
2642 @code{rename-file}, @code{set-file-modes},
2643 @code{set-visited-file-modtime}, @code{shell-command},
2644 @code{substitute-in-file-name},
2645 @code{unhandled-file-name-directory},
2646 @code{vc-regis@discretionary{}{}{}tered},
2647 @code{verify-visited-file-modtime},
2648 @code{write-region}.
2652 Handlers for @code{insert-file-contents} typically need to clear the
2653 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2654 @var{visit} argument is non-@code{nil}. This also has the effect of
2655 unlocking the buffer if it is locked.
2657 The handler function must handle all of the above operations, and
2658 possibly others to be added in the future. It need not implement all
2659 these operations itself---when it has nothing special to do for a
2660 certain operation, it can reinvoke the primitive, to handle the
2661 operation ``in the usual way''. It should always reinvoke the primitive
2662 for an operation it does not recognize. Here's one way to do this:
2665 (defun my-file-handler (operation &rest args)
2666 ;; @r{First check for the specific operations}
2667 ;; @r{that we have special handling for.}
2668 (cond ((eq operation 'insert-file-contents) @dots{})
2669 ((eq operation 'write-region) @dots{})
2671 ;; @r{Handle any operation we don't know about.}
2672 (t (let ((inhibit-file-name-handlers
2673 (cons 'my-file-handler
2674 (and (eq inhibit-file-name-operation operation)
2675 inhibit-file-name-handlers)))
2676 (inhibit-file-name-operation operation))
2677 (apply operation args)))))
2680 When a handler function decides to call the ordinary Emacs primitive for
2681 the operation at hand, it needs to prevent the primitive from calling
2682 the same handler once again, thus leading to an infinite recursion. The
2683 example above shows how to do this, with the variables
2684 @code{inhibit-file-name-handlers} and
2685 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2686 shown above; the details are crucial for proper behavior in the case of
2687 multiple handlers, and for operations that have two file names that may
2690 @kindex safe-magic (@r{property})
2691 Handlers that don't really do anything special for actual access to the
2692 file---such as the ones that implement completion of host names for
2693 remote file names---should have a non-@code{nil} @code{safe-magic}
2694 property. For instance, Emacs normally ``protects'' directory names
2695 it finds in @code{PATH} from becoming magic, if they look like magic
2696 file names, by prefixing them with @samp{/:}. But if the handler that
2697 would be used for them has a non-@code{nil} @code{safe-magic}
2698 property, the @samp{/:} is not added.
2700 @kindex operations (@r{property})
2701 A file name handler can have an @code{operations} property to
2702 declare which operations it handles in a nontrivial way. If this
2703 property has a non-@code{nil} value, it should be a list of
2704 operations; then only those operations will call the handler. This
2705 avoids inefficiency, but its main purpose is for autoloaded handler
2706 functions, so that they won't be loaded except when they have real
2709 @defvar inhibit-file-name-handlers
2710 This variable holds a list of handlers whose use is presently inhibited
2711 for a certain operation.
2714 @defvar inhibit-file-name-operation
2715 The operation for which certain handlers are presently inhibited.
2718 @defun find-file-name-handler file operation
2719 This function returns the handler function for file name @var{file},
2720 or @code{nil} if there is none. The argument @var{operation} should
2721 be the operation to be performed on the file---the value you will pass
2722 to the handler as its first argument when you call it. If
2723 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2724 not found in the @code{operations} property of the handler, this
2725 function returns @code{nil}.
2728 @defun file-local-copy filename
2729 This function copies file @var{filename} to an ordinary non-magic file
2730 on the local machine, if it isn't on the local machine already. Magic
2731 file names should handle the @code{file-local-copy} operation if they
2732 refer to files on other machines. A magic file name that is used for
2733 other purposes than remote file access should not handle
2734 @code{file-local-copy}; then this function will treat the file as
2737 If @var{filename} is local, whether magic or not, this function does
2738 nothing and returns @code{nil}. Otherwise it returns the file name
2739 of the local copy file.
2742 @defun file-remote-p filename
2743 This function tests whether @var{filename} is a remote file. If
2744 @var{filename} is local (not remote), the return value is @code{nil}.
2745 If @var{filename} is indeed remote, the return value is a string that
2746 identifies the remote system.
2748 This identifier string can include a host name and a user name, as
2749 well as characters designating the method used to access the remote
2750 system. For example, the remote identifier string for the filename
2751 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
2753 If @code{file-remote-p} returns the same identifier for two different
2754 filenames, that means they are stored on the same file system and can
2755 be accessed locally with respect to each other. This means, for
2756 example, that it is possible to start a remote process accessing both
2757 files at the same time. Implementors of file handlers need to ensure
2758 this principle is valid.
2761 @defun unhandled-file-name-directory filename
2762 This function returns the name of a directory that is not magic. It
2763 uses the directory part of @var{filename} if that is not magic. For a
2764 magic file name, it invokes the file name handler, which therefore
2765 decides what value to return.
2767 This is useful for running a subprocess; every subprocess must have a
2768 non-magic directory to serve as its current directory, and this function
2769 is a good way to come up with one.
2772 @node Format Conversion
2773 @section File Format Conversion
2775 @cindex file format conversion
2776 @cindex encoding file formats
2777 @cindex decoding file formats
2778 The variable @code{format-alist} defines a list of @dfn{file formats},
2779 which describe textual representations used in files for the data (text,
2780 text-properties, and possibly other information) in an Emacs buffer.
2781 Emacs performs format conversion if appropriate when reading and writing
2784 @defvar format-alist
2785 This list contains one format definition for each defined file format.
2788 @cindex format definition
2789 Each format definition is a list of this form:
2792 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2795 Here is what the elements in a format definition mean:
2799 The name of this format.
2802 A documentation string for the format.
2805 A regular expression which is used to recognize files represented in
2809 A shell command or function to decode data in this format (to convert
2810 file data into the usual Emacs data representation).
2812 A shell command is represented as a string; Emacs runs the command as a
2813 filter to perform the conversion.
2815 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2816 and @var{end}, which specify the part of the buffer it should convert.
2817 It should convert the text by editing it in place. Since this can
2818 change the length of the text, @var{from-fn} should return the modified
2821 One responsibility of @var{from-fn} is to make sure that the beginning
2822 of the file no longer matches @var{regexp}. Otherwise it is likely to
2826 A shell command or function to encode data in this format---that is, to
2827 convert the usual Emacs data representation into this format.
2829 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2830 command as a filter to perform the conversion.
2832 If @var{to-fn} is a function, it is called with two arguments, @var{begin}
2833 and @var{end}, which specify the part of the buffer it should convert.
2834 There are two ways it can do the conversion:
2838 By editing the buffer in place. In this case, @var{to-fn} should
2839 return the end-position of the range of text, as modified.
2842 By returning a list of annotations. This is a list of elements of the
2843 form @code{(@var{position} . @var{string})}, where @var{position} is an
2844 integer specifying the relative position in the text to be written, and
2845 @var{string} is the annotation to add there. The list must be sorted in
2846 order of position when @var{to-fn} returns it.
2848 When @code{write-region} actually writes the text from the buffer to the
2849 file, it intermixes the specified annotations at the corresponding
2850 positions. All this takes place without modifying the buffer.
2854 A flag, @code{t} if the encoding function modifies the buffer, and
2855 @code{nil} if it works by returning a list of annotations.
2858 A minor-mode function to call after visiting a file converted from this
2859 format. The function is called with one argument, the integer 1;
2860 that tells a minor-mode function to enable the mode.
2863 The function @code{insert-file-contents} automatically recognizes file
2864 formats when it reads the specified file. It checks the text of the
2865 beginning of the file against the regular expressions of the format
2866 definitions, and if it finds a match, it calls the decoding function for
2867 that format. Then it checks all the known formats over again.
2868 It keeps checking them until none of them is applicable.
2870 Visiting a file, with @code{find-file-noselect} or the commands that use
2871 it, performs conversion likewise (because it calls
2872 @code{insert-file-contents}); it also calls the mode function for each
2873 format that it decodes. It stores a list of the format names in the
2874 buffer-local variable @code{buffer-file-format}.
2876 @defvar buffer-file-format
2877 This variable states the format of the visited file. More precisely,
2878 this is a list of the file format names that were decoded in the course
2879 of visiting the current buffer's file. It is always buffer-local in all
2883 When @code{write-region} writes data into a file, it first calls the
2884 encoding functions for the formats listed in @code{buffer-file-format},
2885 in the order of appearance in the list.
2887 @deffn Command format-write-file file format &optional confirm
2888 This command writes the current buffer contents into the file
2889 @var{file} in format @var{format}, and makes that format the default
2890 for future saves of the buffer. The argument @var{format} is a list
2891 of format names. Except for the @var{format} argument, this command
2892 is similar to @code{write-file}. In particular, @var{confirm} has the
2893 same meaning and interactive treatment as the corresponding argument
2894 to @code{write-file}. @xref{Definition of write-file}.
2897 @deffn Command format-find-file file format
2898 This command finds the file @var{file}, converting it according to
2899 format @var{format}. It also makes @var{format} the default if the
2900 buffer is saved later.
2902 The argument @var{format} is a list of format names. If @var{format} is
2903 @code{nil}, no conversion takes place. Interactively, typing just
2904 @key{RET} for @var{format} specifies @code{nil}.
2907 @deffn Command format-insert-file file format &optional beg end
2908 This command inserts the contents of file @var{file}, converting it
2909 according to format @var{format}. If @var{beg} and @var{end} are
2910 non-@code{nil}, they specify which part of the file to read, as in
2911 @code{insert-file-contents} (@pxref{Reading from Files}).
2913 The return value is like what @code{insert-file-contents} returns: a
2914 list of the absolute file name and the length of the data inserted
2917 The argument @var{format} is a list of format names. If @var{format} is
2918 @code{nil}, no conversion takes place. Interactively, typing just
2919 @key{RET} for @var{format} specifies @code{nil}.
2922 @defvar buffer-auto-save-file-format
2923 This variable specifies the format to use for auto-saving. Its value is
2924 a list of format names, just like the value of
2925 @code{buffer-file-format}; however, it is used instead of
2926 @code{buffer-file-format} for writing auto-save files. If the value
2927 is @code{t}, the default, auto-saving uses the same format as a
2928 regular save in the same buffer. This variable is always buffer-local
2933 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c