2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
5 @c See the file elisp.texi for copying conditions.
9 This chapter describes the Emacs Lisp functions and variables to
10 find, create, view, save, and otherwise work with files and file
11 directories. A few other file-related functions are described in
12 @ref{Buffers}, and those related to backups and auto-saving are
13 described in @ref{Backups and Auto-Saving}.
15 Many of the file functions take one or more arguments that are file
16 names. A file name is actually a string. Most of these functions
17 expand file name arguments by calling @code{expand-file-name}, so that
18 @file{~} is handled correctly, as are relative file names (including
19 @samp{../}). @xref{File Name Expansion}.
21 In addition, certain @dfn{magic} file names are handled specially.
22 For example, when a remote file name is specified, Emacs accesses the
23 file over the network via an appropriate protocol (@pxref{Remote
24 Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is
25 done at a very low level, so you may assume that all the functions
26 described in this chapter accept magic file names as file name
27 arguments, except where noted. @xref{Magic File Names}, for details.
29 When file I/O functions signal Lisp errors, they usually use the
30 condition @code{file-error} (@pxref{Handling Errors}). The error
31 message is in most cases obtained from the operating system, according
32 to locale @code{system-messages-locale}, and decoded using coding system
33 @code{locale-coding-system} (@pxref{Locales}).
36 * Visiting Files:: Reading files into Emacs buffers for editing.
37 * Saving Buffers:: Writing changed buffers back into files.
38 * Reading from Files:: Reading files into buffers without visiting.
39 * Writing to Files:: Writing new files from parts of buffers.
40 * File Locks:: Locking and unlocking files, to prevent
41 simultaneous editing by two people.
42 * Information about Files:: Testing existence, accessibility, size of files.
43 * Changing Files:: Renaming files, changing permissions, etc.
44 * File Names:: Decomposing and expanding file names.
45 * Contents of Directories:: Getting a list of the files in a directory.
46 * Create/Delete Dirs:: Creating and Deleting Directories.
47 * Magic File Names:: Special handling for certain file names.
48 * Format Conversion:: Conversion to and from various file formats.
52 @section Visiting Files
54 @cindex visiting files
56 Visiting a file means reading a file into a buffer. Once this is
57 done, we say that the buffer is @dfn{visiting} that file, and call the
58 file ``the visited file'' of the buffer.
60 A file and a buffer are two different things. A file is information
61 recorded permanently in the computer (unless you delete it). A buffer,
62 on the other hand, is information inside of Emacs that will vanish at
63 the end of the editing session (or when you kill the buffer). Usually,
64 a buffer contains information that you have copied from a file; then we
65 say the buffer is visiting that file. The copy in the buffer is what
66 you modify with editing commands. Such changes to the buffer do not
67 change the file; therefore, to make the changes permanent, you must
68 @dfn{save} the buffer, which means copying the altered buffer contents
71 In spite of the distinction between files and buffers, people often
72 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
73 ``I am editing a file'', rather than, ``I am editing a buffer that I
74 will soon save as a file of the same name''. Humans do not usually need
75 to make the distinction explicit. When dealing with a computer program,
76 however, it is good to keep the distinction in mind.
79 * Visiting Functions:: The usual interface functions for visiting.
80 * Subroutines of Visiting:: Lower-level subroutines that they use.
83 @node Visiting Functions
84 @subsection Functions for Visiting Files
86 This section describes the functions normally used to visit files.
87 For historical reasons, these functions have names starting with
88 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
89 functions and variables that access the visited file name of a buffer or
90 that find an existing buffer by its visited file name.
92 In a Lisp program, if you want to look at the contents of a file but
93 not alter it, the fastest way is to use @code{insert-file-contents} in a
94 temporary buffer. Visiting the file is not necessary and takes longer.
95 @xref{Reading from Files}.
97 @deffn Command find-file filename &optional wildcards
98 This command selects a buffer visiting the file @var{filename},
99 using an existing buffer if there is one, and otherwise creating a
100 new buffer and reading the file into it. It also returns that buffer.
102 Aside from some technical details, the body of the @code{find-file}
103 function is basically equivalent to:
106 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
110 (See @code{switch-to-buffer} in @ref{Switching Buffers}.)
112 If @var{wildcards} is non-@code{nil}, which is always true in an
113 interactive call, then @code{find-file} expands wildcard characters in
114 @var{filename} and visits all the matching files.
116 When @code{find-file} is called interactively, it prompts for
117 @var{filename} in the minibuffer.
120 @deffn Command find-file-literally filename
121 This command visits @var{filename}, like @code{find-file} does, but it
122 does not perform any format conversions (@pxref{Format Conversion}),
123 character code conversions (@pxref{Coding Systems}), or end-of-line
124 conversions (@pxref{Coding System Basics, End of line conversion}).
125 The buffer visiting the file is made unibyte, and its major mode is
126 Fundamental mode, regardless of the file name. File local variable
127 specifications in the file (@pxref{File Local Variables}) are
128 ignored, and automatic decompression and adding a newline at the end
129 of the file due to @code{require-final-newline} (@pxref{Saving
130 Buffers, require-final-newline}) are also disabled.
132 Note that if Emacs already has a buffer visiting the same file
133 non-literally, it will not visit the same file literally, but instead
134 just switch to the existing buffer. If you want to be sure of
135 accessing a file's contents literally, you should create a temporary
136 buffer and then read the file contents into it using
137 @code{insert-file-contents-literally} (@pxref{Reading from Files}).
140 @defun find-file-noselect filename &optional nowarn rawfile wildcards
141 This function is the guts of all the file-visiting functions. It
142 returns a buffer visiting the file @var{filename}. You may make the
143 buffer current or display it in a window if you wish, but this
144 function does not do so.
146 The function returns an existing buffer if there is one; otherwise it
147 creates a new buffer and reads the file into it. When
148 @code{find-file-noselect} uses an existing buffer, it first verifies
149 that the file has not changed since it was last visited or saved in
150 that buffer. If the file has changed, this function asks the user
151 whether to reread the changed file. If the user says @samp{yes}, any
152 edits previously made in the buffer are lost.
154 Reading the file involves decoding the file's contents (@pxref{Coding
155 Systems}), including end-of-line conversion, and format conversion
156 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
157 then @code{find-file-noselect} expands wildcard characters in
158 @var{filename} and visits all the matching files.
160 This function displays warning or advisory messages in various peculiar
161 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
162 example, if it needs to create a buffer, and there is no file named
163 @var{filename}, it displays the message @samp{(New file)} in the echo
164 area, and leaves the buffer empty.
166 The @code{find-file-noselect} function normally calls
167 @code{after-find-file} after reading the file (@pxref{Subroutines of
168 Visiting}). That function sets the buffer major mode, parses local
169 variables, warns the user if there exists an auto-save file more recent
170 than the file just visited, and finishes by running the functions in
171 @code{find-file-hook}.
173 If the optional argument @var{rawfile} is non-@code{nil}, then
174 @code{after-find-file} is not called, and the
175 @code{find-file-not-found-functions} are not run in case of failure.
176 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
177 system conversion and format conversion.
179 The @code{find-file-noselect} function usually returns the buffer that
180 is visiting the file @var{filename}. But, if wildcards are actually
181 used and expanded, it returns a list of buffers that are visiting the
186 (find-file-noselect "/etc/fstab")
187 @result{} #<buffer fstab>
192 @deffn Command find-file-other-window filename &optional wildcards
193 This command selects a buffer visiting the file @var{filename}, but
194 does so in a window other than the selected window. It may use
195 another existing window or split a window; see @ref{Switching
198 When this command is called interactively, it prompts for
202 @deffn Command find-file-read-only filename &optional wildcards
203 This command selects a buffer visiting the file @var{filename}, like
204 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
205 Buffers}, for related functions and variables.
207 When this command is called interactively, it prompts for
211 @defopt find-file-wildcards
212 If this variable is non-@code{nil}, then the various @code{find-file}
213 commands check for wildcard characters and visit all the files that
214 match them (when invoked interactively or when their @var{wildcards}
215 argument is non-@code{nil}). If this option is @code{nil}, then
216 the @code{find-file} commands ignore their @var{wildcards} argument
217 and never treat wildcard characters specially.
220 @defopt find-file-hook
221 The value of this variable is a list of functions to be called after a
222 file is visited. The file's local-variables specification (if any) will
223 have been processed before the hooks are run. The buffer visiting the
224 file is current when the hook functions are run.
226 This variable is a normal hook. @xref{Hooks}.
229 @defvar find-file-not-found-functions
230 The value of this variable is a list of functions to be called when
231 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
232 file name. @code{find-file-noselect} calls these functions as soon as
233 it detects a nonexistent file. It calls them in the order of the list,
234 until one of them returns non-@code{nil}. @code{buffer-file-name} is
237 This is not a normal hook because the values of the functions are
238 used, and in many cases only some of the functions are called.
241 @defvar find-file-literally
242 This buffer-local variable, if set to a non-@code{nil} value, makes
243 @code{save-buffer} behave as if the buffer were visiting its file
244 literally, i.e., without conversions of any kind. The command
245 @code{find-file-literally} sets this variable's local value, but other
246 equivalent functions and commands can do that as well, e.g., to avoid
247 automatic addition of a newline at the end of the file. This variable
248 is permanent local, so it is unaffected by changes of major modes.
251 @node Subroutines of Visiting
252 @subsection Subroutines of Visiting
254 The @code{find-file-noselect} function uses two important subroutines
255 which are sometimes useful in user Lisp code: @code{create-file-buffer}
256 and @code{after-find-file}. This section explains how to use them.
258 @defun create-file-buffer filename
259 This function creates a suitably named buffer for visiting
260 @var{filename}, and returns it. It uses @var{filename} (sans directory)
261 as the name if that name is free; otherwise, it appends a string such as
262 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
264 @strong{Please note:} @code{create-file-buffer} does @emph{not}
265 associate the new buffer with a file and does not select the buffer.
266 It also does not use the default major mode.
270 (create-file-buffer "foo")
271 @result{} #<buffer foo>
274 (create-file-buffer "foo")
275 @result{} #<buffer foo<2>>
278 (create-file-buffer "foo")
279 @result{} #<buffer foo<3>>
283 This function is used by @code{find-file-noselect}.
284 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
287 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
288 This function sets the buffer major mode, and parses local variables
289 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
290 and by the default revert function (@pxref{Reverting}).
292 @cindex new file message
293 @cindex file open error
294 If reading the file got an error because the file does not exist, but
295 its directory does exist, the caller should pass a non-@code{nil} value
296 for @var{error}. In that case, @code{after-find-file} issues a warning:
297 @samp{(New file)}. For more serious errors, the caller should usually not
298 call @code{after-find-file}.
300 If @var{warn} is non-@code{nil}, then this function issues a warning
301 if an auto-save file exists and is more recent than the visited file.
303 If @var{noauto} is non-@code{nil}, that says not to enable or disable
304 Auto-Save mode. The mode remains enabled if it was enabled before.
306 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
307 means this call was from @code{revert-buffer}. This has no direct
308 effect, but some mode functions and hook functions check the value
311 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
312 major mode, don't process local variables specifications in the file,
313 and don't run @code{find-file-hook}. This feature is used by
314 @code{revert-buffer} in some cases.
316 The last thing @code{after-find-file} does is call all the functions
317 in the list @code{find-file-hook}.
321 @section Saving Buffers
322 @cindex saving buffers
324 When you edit a file in Emacs, you are actually working on a buffer
325 that is visiting that file---that is, the contents of the file are
326 copied into the buffer and the copy is what you edit. Changes to the
327 buffer do not change the file until you @dfn{save} the buffer, which
328 means copying the contents of the buffer into the file.
330 @deffn Command save-buffer &optional backup-option
331 This function saves the contents of the current buffer in its visited
332 file if the buffer has been modified since it was last visited or saved.
333 Otherwise it does nothing.
335 @code{save-buffer} is responsible for making backup files. Normally,
336 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
337 file only if this is the first save since visiting the file. Other
338 values for @var{backup-option} request the making of backup files in
343 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
344 @code{save-buffer} function marks this version of the file to be
345 backed up when the buffer is next saved.
348 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
349 @code{save-buffer} function unconditionally backs up the previous
350 version of the file before saving it.
353 With an argument of 0, unconditionally do @emph{not} make any backup file.
357 @deffn Command save-some-buffers &optional save-silently-p pred
358 @anchor{Definition of save-some-buffers}
359 This command saves some modified file-visiting buffers. Normally it
360 asks the user about each buffer. But if @var{save-silently-p} is
361 non-@code{nil}, it saves all the file-visiting buffers without querying
364 The optional @var{pred} argument controls which buffers to ask about
365 (or to save silently if @var{save-silently-p} is non-@code{nil}).
366 If it is @code{nil}, that means to ask only about file-visiting buffers.
367 If it is @code{t}, that means also offer to save certain other non-file
368 buffers---those that have a non-@code{nil} buffer-local value of
369 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
370 @samp{yes} to saving a non-file buffer is asked to specify the file
371 name to use. The @code{save-buffers-kill-emacs} function passes the
372 value @code{t} for @var{pred}.
374 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
375 a function of no arguments. It will be called in each buffer to decide
376 whether to offer to save that buffer. If it returns a non-@code{nil}
377 value in a certain buffer, that means do offer to save that buffer.
380 @deffn Command write-file filename &optional confirm
381 @anchor{Definition of write-file}
382 This function writes the current buffer into file @var{filename}, makes
383 the buffer visit that file, and marks it not modified. Then it renames
384 the buffer based on @var{filename}, appending a string like @samp{<2>}
385 if necessary to make a unique buffer name. It does most of this work by
386 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
389 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
390 before overwriting an existing file. Interactively, confirmation is
391 required, unless the user supplies a prefix argument.
393 If @var{filename} is an existing directory, or a symbolic link to one,
394 @code{write-file} uses the name of the visited file, in directory
395 @var{filename}. If the buffer is not visiting a file, it uses the
399 Saving a buffer runs several hooks. It also performs format
400 conversion (@pxref{Format Conversion}).
402 @defvar write-file-functions
403 The value of this variable is a list of functions to be called before
404 writing out a buffer to its visited file. If one of them returns
405 non-@code{nil}, the file is considered already written and the rest of
406 the functions are not called, nor is the usual code for writing the file
409 If a function in @code{write-file-functions} returns non-@code{nil}, it
410 is responsible for making a backup file (if that is appropriate).
411 To do so, execute the following code:
414 (or buffer-backed-up (backup-buffer))
417 You might wish to save the file modes value returned by
418 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
419 bits of the file that you write. This is what @code{save-buffer}
420 normally does. @xref{Making Backups,, Making Backup Files}.
422 The hook functions in @code{write-file-functions} are also responsible
423 for encoding the data (if desired): they must choose a suitable coding
424 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
425 perform the encoding (@pxref{Explicit Encoding}), and set
426 @code{last-coding-system-used} to the coding system that was used
427 (@pxref{Encoding and I/O}).
429 If you set this hook locally in a buffer, it is assumed to be
430 associated with the file or the way the contents of the buffer were
431 obtained. Thus the variable is marked as a permanent local, so that
432 changing the major mode does not alter a buffer-local value. On the
433 other hand, calling @code{set-visited-file-name} will reset it.
434 If this is not what you want, you might like to use
435 @code{write-contents-functions} instead.
437 Even though this is not a normal hook, you can use @code{add-hook} and
438 @code{remove-hook} to manipulate the list. @xref{Hooks}.
442 @defvar write-contents-functions
443 This works just like @code{write-file-functions}, but it is intended
444 for hooks that pertain to the buffer's contents, not to the particular
445 visited file or its location. Such hooks are usually set up by major
446 modes, as buffer-local bindings for this variable. This variable
447 automatically becomes buffer-local whenever it is set; switching to a
448 new major mode always resets this variable, but calling
449 @code{set-visited-file-name} does not.
451 If any of the functions in this hook returns non-@code{nil}, the file
452 is considered already written and the rest are not called and neither
453 are the functions in @code{write-file-functions}.
456 @defopt before-save-hook
457 This normal hook runs before a buffer is saved in its visited file,
458 regardless of whether that is done normally or by one of the hooks
459 described above. For instance, the @file{copyright.el} program uses
460 this hook to make sure the file you are saving has the current year in
461 its copyright notice.
465 @defopt after-save-hook
466 This normal hook runs after a buffer has been saved in its visited file.
467 One use of this hook is in Fast Lock mode; it uses this hook to save the
468 highlighting information in a cache file.
471 @defopt file-precious-flag
472 If this variable is non-@code{nil}, then @code{save-buffer} protects
473 against I/O errors while saving by writing the new file to a temporary
474 name instead of the name it is supposed to have, and then renaming it to
475 the intended name after it is clear there are no errors. This procedure
476 prevents problems such as a lack of disk space from resulting in an
479 As a side effect, backups are necessarily made by copying. @xref{Rename
480 or Copy}. Yet, at the same time, saving a precious file always breaks
481 all hard links between the file you save and other file names.
483 Some modes give this variable a non-@code{nil} buffer-local value
484 in particular buffers.
487 @defopt require-final-newline
488 This variable determines whether files may be written out that do
489 @emph{not} end with a newline. If the value of the variable is
490 @code{t}, then @code{save-buffer} silently adds a newline at the end
491 of the buffer whenever it does not already end in one. If the value
492 is @code{visit}, Emacs adds a missing newline just after it visits the
493 file. If the value is @code{visit-save}, Emacs adds a missing newline
494 both on visiting and on saving. For any other non-@code{nil} value,
495 @code{save-buffer} asks the user whether to add a newline each time
498 If the value of the variable is @code{nil}, then @code{save-buffer}
499 doesn't add newlines at all. @code{nil} is the default value, but a few
500 major modes set it to @code{t} in particular buffers.
503 See also the function @code{set-visited-file-name} (@pxref{Buffer File
506 @node Reading from Files
507 @section Reading from Files
508 @cindex reading from files
510 You can copy a file from the disk and insert it into a buffer
511 using the @code{insert-file-contents} function. Don't use the user-level
512 command @code{insert-file} in a Lisp program, as that sets the mark.
514 @defun insert-file-contents filename &optional visit beg end replace
515 This function inserts the contents of file @var{filename} into the
516 current buffer after point. It returns a list of the absolute file name
517 and the length of the data inserted. An error is signaled if
518 @var{filename} is not the name of a file that can be read.
520 This function checks the file contents against the defined file
521 formats, and converts the file contents if appropriate and also calls
522 the functions in the list @code{after-insert-file-functions}.
523 @xref{Format Conversion}. Normally, one of the functions in the
524 @code{after-insert-file-functions} list determines the coding system
525 (@pxref{Coding Systems}) used for decoding the file's contents,
526 including end-of-line conversion. However, if the file contains null
527 bytes, it is by default visited without any code conversions.
528 @xref{Lisp and Coding Systems, inhibit-null-byte-detection}.
530 If @var{visit} is non-@code{nil}, this function additionally marks the
531 buffer as unmodified and sets up various fields in the buffer so that it
532 is visiting the file @var{filename}: these include the buffer's visited
533 file name and its last save file modtime. This feature is used by
534 @code{find-file-noselect} and you probably should not use it yourself.
536 If @var{beg} and @var{end} are non-@code{nil}, they should be numbers
537 that are byte offsets specifying the portion of the file to insert.
538 In this case, @var{visit} must be @code{nil}. For example,
541 (insert-file-contents filename nil 0 500)
545 inserts the first 500 characters of a file.
547 If the argument @var{replace} is non-@code{nil}, it means to replace the
548 contents of the buffer (actually, just the accessible portion) with the
549 contents of the file. This is better than simply deleting the buffer
550 contents and inserting the whole file, because (1) it preserves some
551 marker positions and (2) it puts less data in the undo list.
553 It is possible to read a special file (such as a FIFO or an I/O device)
554 with @code{insert-file-contents}, as long as @var{replace} and
555 @var{visit} are @code{nil}.
558 @defun insert-file-contents-literally filename &optional visit beg end replace
559 This function works like @code{insert-file-contents} except that it
560 does not run @code{find-file-hook}, and does not do format decoding,
561 character code conversion, automatic uncompression, and so on.
564 If you want to pass a file name to another process so that another
565 program can read the file, use the function @code{file-local-copy}; see
566 @ref{Magic File Names}.
568 @node Writing to Files
569 @section Writing to Files
570 @cindex writing to files
572 You can write the contents of a buffer, or part of a buffer, directly
573 to a file on disk using the @code{append-to-file} and
574 @code{write-region} functions. Don't use these functions to write to
575 files that are being visited; that could cause confusion in the
576 mechanisms for visiting.
578 @deffn Command append-to-file start end filename
579 This function appends the contents of the region delimited by
580 @var{start} and @var{end} in the current buffer to the end of file
581 @var{filename}. If that file does not exist, it is created. This
582 function returns @code{nil}.
584 An error is signaled if @var{filename} specifies a nonwritable file,
585 or a nonexistent file in a directory where files cannot be created.
587 When called from Lisp, this function is completely equivalent to:
590 (write-region start end filename t)
594 @deffn Command write-region start end filename &optional append visit lockname mustbenew
595 This function writes the region delimited by @var{start} and @var{end}
596 in the current buffer into the file specified by @var{filename}.
598 If @var{start} is @code{nil}, then the command writes the entire buffer
599 contents (@emph{not} just the accessible portion) to the file and
603 If @var{start} is a string, then @code{write-region} writes or appends
604 that string, rather than text from the buffer. @var{end} is ignored in
607 If @var{append} is non-@code{nil}, then the specified text is appended
608 to the existing file contents (if any). If @var{append} is a
609 number, @code{write-region} seeks to that byte offset from the start
610 of the file and writes the data from there.
612 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
613 for confirmation if @var{filename} names an existing file. If
614 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
615 does not ask for confirmation, but instead it signals an error
616 @code{file-already-exists} if the file already exists.
618 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
619 a special system feature. At least for files on a local disk, there is
620 no chance that some other program could create a file of the same name
621 before Emacs does, without Emacs's noticing.
623 If @var{visit} is @code{t}, then Emacs establishes an association
624 between the buffer and the file: the buffer is then visiting that file.
625 It also sets the last file modification time for the current buffer to
626 @var{filename}'s modtime, and marks the buffer as not modified. This
627 feature is used by @code{save-buffer}, but you probably should not use
631 If @var{visit} is a string, it specifies the file name to visit. This
632 way, you can write the data to one file (@var{filename}) while recording
633 the buffer as visiting another file (@var{visit}). The argument
634 @var{visit} is used in the echo area message and also for file locking;
635 @var{visit} is stored in @code{buffer-file-name}. This feature is used
636 to implement @code{file-precious-flag}; don't use it yourself unless you
637 really know what you're doing.
639 The optional argument @var{lockname}, if non-@code{nil}, specifies the
640 file name to use for purposes of locking and unlocking, overriding
641 @var{filename} and @var{visit} for that purpose.
643 The function @code{write-region} converts the data which it writes to
644 the appropriate file formats specified by @code{buffer-file-format}
645 and also calls the functions in the list
646 @code{write-region-annotate-functions}.
647 @xref{Format Conversion}.
649 Normally, @code{write-region} displays the message @samp{Wrote
650 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
651 nor @code{nil} nor a string, then this message is inhibited. This
652 feature is useful for programs that use files for internal purposes,
653 files that the user does not need to know about.
656 @defmac with-temp-file file body@dots{}
657 @anchor{Definition of with-temp-file}
658 The @code{with-temp-file} macro evaluates the @var{body} forms with a
659 temporary buffer as the current buffer; then, at the end, it writes the
660 buffer contents into file @var{file}. It kills the temporary buffer
661 when finished, restoring the buffer that was current before the
662 @code{with-temp-file} form. Then it returns the value of the last form
665 The current buffer is restored even in case of an abnormal exit via
666 @code{throw} or error (@pxref{Nonlocal Exits}).
668 See also @code{with-temp-buffer} in @ref{Definition of
669 with-temp-buffer,, The Current Buffer}.
677 When two users edit the same file at the same time, they are likely
678 to interfere with each other. Emacs tries to prevent this situation
679 from arising by recording a @dfn{file lock} when a file is being
680 modified. (File locks are not implemented on Microsoft systems.)
681 Emacs can then detect the first attempt to modify a buffer visiting a
682 file that is locked by another Emacs job, and ask the user what to do.
683 The file lock is really a file, a symbolic link with a special name,
684 stored in the same directory as the file you are editing.
686 When you access files using NFS, there may be a small probability that
687 you and another user will both lock the same file ``simultaneously''.
688 If this happens, it is possible for the two users to make changes
689 simultaneously, but Emacs will still warn the user who saves second.
690 Also, the detection of modification of a buffer visiting a file changed
691 on disk catches some cases of simultaneous editing; see
692 @ref{Modification Time}.
694 @defun file-locked-p filename
695 This function returns @code{nil} if the file @var{filename} is not
696 locked. It returns @code{t} if it is locked by this Emacs process, and
697 it returns the name of the user who has locked it if it is locked by
702 (file-locked-p "foo")
708 @defun lock-buffer &optional filename
709 This function locks the file @var{filename}, if the current buffer is
710 modified. The argument @var{filename} defaults to the current buffer's
711 visited file. Nothing is done if the current buffer is not visiting a
712 file, or is not modified, or if the system does not support locking.
716 This function unlocks the file being visited in the current buffer,
717 if the buffer is modified. If the buffer is not modified, then
718 the file should not be locked, so this function does nothing. It also
719 does nothing if the current buffer is not visiting a file, or if the
720 system does not support locking.
723 File locking is not supported on some systems. On systems that do not
724 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
725 @code{file-locked-p} do nothing and return @code{nil}. It is also
726 possible to disable locking, by setting the variable @code{create-lockfiles}.
728 @defopt create-lockfiles
729 If this variable is @code{nil}, Emacs does not lock files.
732 @defun ask-user-about-lock file other-user
733 This function is called when the user tries to modify @var{file}, but it
734 is locked by another user named @var{other-user}. The default
735 definition of this function asks the user to say what to do. The value
736 this function returns determines what Emacs does next:
740 A value of @code{t} says to grab the lock on the file. Then
741 this user may edit the file and @var{other-user} loses the lock.
744 A value of @code{nil} says to ignore the lock and let this
745 user edit the file anyway.
749 This function may instead signal a @code{file-locked} error, in which
750 case the change that the user was about to make does not take place.
752 The error message for this error looks like this:
755 @error{} File is locked: @var{file} @var{other-user}
759 where @code{file} is the name of the file and @var{other-user} is the
760 name of the user who has locked the file.
763 If you wish, you can replace the @code{ask-user-about-lock} function
764 with your own version that makes the decision in another way. The code
765 for its usual definition is in @file{userlock.el}.
768 @node Information about Files
769 @section Information about Files
770 @cindex file, information about
772 The functions described in this section all operate on strings that
773 designate file names. With a few exceptions, all the functions have
774 names that begin with the word @samp{file}. These functions all
775 return information about actual files or directories, so their
776 arguments must all exist as actual files or directories unless
780 * Testing Accessibility:: Is a given file readable? Writable?
781 * Kinds of Files:: Is it a directory? A symbolic link?
782 * Truenames:: Eliminating symbolic links from a file name.
783 * File Attributes:: How large is it? Any other names? Etc.
784 * Locating Files:: How to find a file in standard places.
787 @node Testing Accessibility
788 @subsection Testing Accessibility
789 @cindex accessibility of a file
790 @cindex file accessibility
792 These functions test for permission to access a file in specific
793 ways. Unless explicitly stated otherwise, they recursively follow
794 symbolic links for their file name arguments, at all levels (at the
795 level of the file itself and at all levels of parent directories).
797 @defun file-exists-p filename
798 This function returns @code{t} if a file named @var{filename} appears
799 to exist. This does not mean you can necessarily read the file, only
800 that you can find out its attributes. (On Unix and GNU/Linux, this is
801 true if the file exists and you have execute permission on the
802 containing directories, regardless of the permissions of the file
805 If the file does not exist, or if fascist access control policies
806 prevent you from finding the attributes of the file, this function
809 Directories are files, so @code{file-exists-p} returns @code{t} when
810 given a directory name. However, symbolic links are treated
811 specially; @code{file-exists-p} returns @code{t} for a symbolic link
812 name only if the target file exists.
815 @defun file-readable-p filename
816 This function returns @code{t} if a file named @var{filename} exists
817 and you can read it. It returns @code{nil} otherwise.
821 (file-readable-p "files.texi")
825 (file-exists-p "/usr/spool/mqueue")
829 (file-readable-p "/usr/spool/mqueue")
836 @defun file-executable-p filename
837 This function returns @code{t} if a file named @var{filename} exists and
838 you can execute it. It returns @code{nil} otherwise. On Unix and
839 GNU/Linux, if the file is a directory, execute permission means you can
840 check the existence and attributes of files inside the directory, and
841 open those files if their modes permit.
844 @defun file-writable-p filename
845 This function returns @code{t} if the file @var{filename} can be written
846 or created by you, and @code{nil} otherwise. A file is writable if the
847 file exists and you can write it. It is creatable if it does not exist,
848 but the specified directory does exist and you can write in that
851 In the third example below, @file{foo} is not writable because the
852 parent directory does not exist, even though the user could create such
857 (file-writable-p "~/foo")
861 (file-writable-p "/foo")
865 (file-writable-p "~/no-such-dir/foo")
872 @defun file-accessible-directory-p dirname
873 This function returns @code{t} if you have permission to open existing
874 files in the directory whose name as a file is @var{dirname};
875 otherwise (or if there is no such directory), it returns @code{nil}.
876 The value of @var{dirname} may be either a directory name (such as
877 @file{/foo/}) or the file name of a file which is a directory
878 (such as @file{/foo}, without the final slash).
880 Example: after the following,
883 (file-accessible-directory-p "/foo")
888 we can deduce that any attempt to read a file in @file{/foo/} will
892 @defun access-file filename string
893 This function opens file @var{filename} for reading, then closes it and
894 returns @code{nil}. However, if the open fails, it signals an error
895 using @var{string} as the error message text.
898 @defun file-ownership-preserved-p filename &optional group
899 This function returns @code{t} if deleting the file @var{filename} and
900 then creating it anew would keep the file's owner unchanged. It also
901 returns @code{t} for nonexistent files.
903 If the optional argument @var{group} is non-@code{nil}, this function
904 also checks that the file's group would be unchanged.
906 If @var{filename} is a symbolic link, then, unlike the other functions
907 discussed here, @code{file-ownership-preserved-p} does @emph{not}
908 replace @var{filename} with its target. However, it does recursively
909 follow symbolic links at all levels of parent directories.
912 @defun file-newer-than-file-p filename1 filename2
914 @cindex file modification time
915 This function returns @code{t} if the file @var{filename1} is
916 newer than file @var{filename2}. If @var{filename1} does not
917 exist, it returns @code{nil}. If @var{filename1} does exist, but
918 @var{filename2} does not, it returns @code{t}.
920 In the following example, assume that the file @file{aug-19} was written
921 on the 19th, @file{aug-20} was written on the 20th, and the file
922 @file{no-file} doesn't exist at all.
926 (file-newer-than-file-p "aug-19" "aug-20")
930 (file-newer-than-file-p "aug-20" "aug-19")
934 (file-newer-than-file-p "aug-19" "no-file")
938 (file-newer-than-file-p "no-file" "aug-19")
943 You can use @code{file-attributes} to get a file's last modification
944 time as a list of four integers. @xref{File Attributes}.
948 @subsection Distinguishing Kinds of Files
950 This section describes how to distinguish various kinds of files, such
951 as directories, symbolic links, and ordinary files.
953 @defun file-symlink-p filename
954 @cindex file symbolic links
955 If the file @var{filename} is a symbolic link, the
956 @code{file-symlink-p} function returns the (non-recursive) link target
957 as a string. (Determining the file name that the link points to from
958 the target is nontrivial.) First, this function recursively follows
959 symbolic links at all levels of parent directories.
961 If the file @var{filename} is not a symbolic link (or there is no such file),
962 @code{file-symlink-p} returns @code{nil}.
966 (file-symlink-p "foo")
970 (file-symlink-p "sym-link")
974 (file-symlink-p "sym-link2")
978 (file-symlink-p "/bin")
983 @c !!! file-symlink-p: should show output of ls -l for comparison
986 The next two functions recursively follow symbolic links at
987 all levels for @var{filename}.
989 @defun file-directory-p filename
990 This function returns @code{t} if @var{filename} is the name of an
991 existing directory, @code{nil} otherwise.
995 (file-directory-p "~rms")
999 (file-directory-p "~rms/lewis/files.texi")
1003 (file-directory-p "~rms/lewis/no-such-file")
1007 (file-directory-p "$HOME")
1012 (substitute-in-file-name "$HOME"))
1018 @defun file-regular-p filename
1019 This function returns @code{t} if the file @var{filename} exists and is
1020 a regular file (not a directory, named pipe, terminal, or
1024 @defun file-equal-p file1 file2
1025 This function returns @code{t} if the files @var{file1} and
1026 @var{file2} name the same file. If @var{file1} or @var{file2} does
1027 not exist, the return value is unspecified.
1030 @defun file-in-directory-p file dir
1031 This function returns @code{t} if @var{file} is a file in directory
1032 @var{dir}, or in a subdirectory of @var{dir}. It also returns
1033 @code{t} if @var{file} and @var{dir} are the same directory. It
1034 compares the @code{file-truename} values of the two directories
1035 (@pxref{Truenames}). If @var{dir} does not name an existing
1036 directory, the return value is @code{nil}.
1040 @subsection Truenames
1041 @cindex truename (of file)
1043 The @dfn{truename} of a file is the name that you get by following
1044 symbolic links at all levels until none remain, then simplifying away
1045 @samp{.}@: and @samp{..}@: appearing as name components. This results
1046 in a sort of canonical name for the file. A file does not always have a
1047 unique truename; the number of distinct truenames a file has is equal to
1048 the number of hard links to the file. However, truenames are useful
1049 because they eliminate symbolic links as a cause of name variation.
1051 @defun file-truename filename
1052 This function returns the truename of the file @var{filename}. If the
1053 argument is not an absolute file name, this function first expands it
1054 against @code{default-directory}.
1056 This function does not expand environment variables. Only
1057 @code{substitute-in-file-name} does that. @xref{Definition of
1058 substitute-in-file-name}.
1060 If you may need to follow symbolic links preceding @samp{..}@:
1061 appearing as a name component, you should make sure to call
1062 @code{file-truename} without prior direct or indirect calls to
1063 @code{expand-file-name}, as otherwise the file name component
1064 immediately preceding @samp{..} will be ``simplified away'' before
1065 @code{file-truename} is called. To eliminate the need for a call to
1066 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1067 same way that @code{expand-file-name} does. @xref{File Name
1068 Expansion,, Functions that Expand Filenames}.
1071 @defun file-chase-links filename &optional limit
1072 This function follows symbolic links, starting with @var{filename},
1073 until it finds a file name which is not the name of a symbolic link.
1074 Then it returns that file name. This function does @emph{not} follow
1075 symbolic links at the level of parent directories.
1077 If you specify a number for @var{limit}, then after chasing through
1078 that many links, the function just returns what it has even if that is
1079 still a symbolic link.
1082 To illustrate the difference between @code{file-chase-links} and
1083 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1084 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1085 ordinary file (or at least, not a symbolic link) or nonexistent. Then
1089 (file-chase-links "/usr/foo/hello")
1090 ;; @r{This does not follow the links in the parent directories.}
1091 @result{} "/usr/foo/hello"
1092 (file-truename "/usr/foo/hello")
1093 ;; @r{Assuming that @file{/home} is not a symbolic link.}
1094 @result{} "/home/foo/hello"
1097 @xref{Buffer File Name}, for related information.
1099 @node File Attributes
1100 @subsection Other Information about Files
1102 This section describes the functions for getting detailed
1103 information about a file, other than its contents. This information
1104 includes the mode bits that control access permissions, the owner and
1105 group numbers, the number of names, the inode number, the size, and
1106 the times of access and modification.
1108 @defun file-modes filename
1109 @cindex file permissions
1110 @cindex permissions, file
1111 @cindex file attributes
1113 This function returns the @dfn{mode bits} describing the @dfn{file
1114 permissions} of @var{filename}, as an integer. It recursively follows
1115 symbolic links in @var{filename} at all levels. If @var{filename}
1116 does not exist, the return value is @code{nil}.
1118 @xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
1119 Manual}, for a description of mode bits. If the low-order bit is 1,
1120 then the file is executable by all users, if the second-lowest-order
1121 bit is 1, then the file is writable by all users, etc. The highest
1122 value returnable is 4095 (7777 octal), meaning that everyone has read,
1123 write, and execute permission, that the @acronym{SUID} bit is set for
1124 both others and group, and that the sticky bit is set.
1128 (file-modes "~/junk/diffs")
1129 @result{} 492 ; @r{Decimal integer.}
1133 @result{} "754" ; @r{Convert to octal.}
1137 (set-file-modes "~/junk/diffs" #o666)
1143 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1147 @xref{Changing Files}, for functions that change file permissions,
1148 such as @code{set-file-modes}.
1150 @cindex MS-DOS and file modes
1151 @cindex file modes and MS-DOS
1152 @strong{MS-DOS note:} On MS-DOS, there is no such thing as an
1153 ``executable'' file mode bit. So @code{file-modes} considers a file
1154 executable if its name ends in one of the standard executable
1155 extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
1156 others. Files that begin with the Unix-standard @samp{#!} signature,
1157 such as shell and Perl scripts, are also considered executable.
1158 Directories are also reported as executable, for compatibility with
1159 Unix. These conventions are also followed by @code{file-attributes},
1163 If the @var{filename} argument to the next two functions is a
1164 symbolic link, then these function do @emph{not} replace it with its
1165 target. However, they both recursively follow symbolic links at all
1166 levels of parent directories.
1168 @defun file-nlinks filename
1169 This functions returns the number of names (i.e., hard links) that
1170 file @var{filename} has. If the file does not exist, then this function
1171 returns @code{nil}. Note that symbolic links have no effect on this
1172 function, because they are not considered to be names of the files they
1178 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1179 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1187 (file-nlinks "doesnt-exist")
1193 @defun file-attributes filename &optional id-format
1194 @anchor{Definition of file-attributes}
1195 This function returns a list of attributes of file @var{filename}. If
1196 the specified file cannot be opened, it returns @code{nil}.
1197 The optional parameter @var{id-format} specifies the preferred format
1198 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1199 valid values are @code{'string} and @code{'integer}. The latter is
1200 the default, but we plan to change that, so you should specify a
1201 non-@code{nil} value for @var{id-format} if you use the returned
1202 @acronym{UID} or @acronym{GID}.
1204 The elements of the list, in order, are:
1208 @code{t} for a directory, a string for a symbolic link (the name
1209 linked to), or @code{nil} for a text file.
1211 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
1213 The number of names the file has. Alternate names, also known as hard
1214 links, can be created by using the @code{add-name-to-file} function
1215 (@pxref{Changing Files}).
1218 The file's @acronym{UID}, normally as a string. However, if it does
1219 not correspond to a named user, the value is an integer or a floating
1223 The file's @acronym{GID}, likewise.
1226 The time of last access, as a list of four integers @code{(@var{sec-high}
1227 @var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the
1228 value of @code{current-time}; see @ref{Time of Day}.) Note that on
1229 some FAT-based filesystems, only the date of last access is recorded,
1230 so this time will always hold the midnight of the day of last access.
1232 @cindex modification time of file
1234 The time of last modification as a list of four integers (as above).
1235 This is the last time when the file's contents were modified.
1238 The time of last status change as a list of four integers (as above).
1239 This is the time of the last change to the file's access mode bits,
1240 its owner and group, and other information recorded in the filesystem
1241 for the file, beyond the file's contents.
1244 The size of the file in bytes. If the size is too large to fit in a
1245 Lisp integer, this is a floating point number.
1248 The file's modes, as a string of ten letters or dashes,
1252 An unspecified value, present for backward compatibility.
1255 The file's inode number. If possible, this is an integer. If the
1256 inode number is too large to be represented as an integer in Emacs
1257 Lisp but dividing it by @math{2^16} yields a representable integer,
1258 then the value has the
1259 form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
1260 bits. If the inode number is too wide for even that, the value is of the form
1261 @code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
1262 the high bits, @var{middle} the middle 24 bits, and @var{low} the low
1266 The filesystem number of the device that the file is on. Depending on
1267 the magnitude of the value, this can be either an integer or a cons
1268 cell, in the same manner as the inode number. This element and the
1269 file's inode number together give enough information to distinguish
1270 any two files on the system---no two files can have the same values
1271 for both of these numbers.
1274 For example, here are the file attributes for @file{files.texi}:
1278 (file-attributes "files.texi" 'string)
1279 @result{} (nil 1 "lh" "users"
1280 (20614 64019 50040 152000)
1282 (20614 64555 902289 872000)
1290 and here is how the result is interpreted:
1294 is neither a directory nor a symbolic link.
1297 has only one name (the name @file{files.texi} in the current default
1301 is owned by the user with name "lh".
1304 is in the group with name "users".
1306 @item (20614 64019 50040 152000)
1307 was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
1309 @item (20000 23 0 0)
1310 was last modified on July 15, 2001, at 08:53:43 UTC.
1312 @item (20614 64555 902289 872000)
1313 last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
1316 is 122295 bytes long. (It may not contain 122295 characters, though,
1317 if some of the bytes belong to multibyte sequences, and also if the
1318 end-of-line format is CR-LF.)
1321 has a mode of read and write access for the owner, group, and world.
1324 is merely a placeholder; it carries no information.
1326 @item (5888 2 . 43978)
1327 has an inode number of 6473924464520138.
1329 @item (15479 . 46724)
1330 is on the file-system device whose number is 1014478468.
1334 @cindex SELinux context
1335 SELinux is a Linux kernel feature which provides more sophisticated
1336 file access controls than ordinary ``Unix-style'' file permissions.
1337 If Emacs has been compiled with SELinux support on a system with
1338 SELinux enabled, you can use the function @code{file-selinux-context}
1339 to retrieve a file's SELinux security context. For the function
1340 @code{set-file-selinux-context}, see @ref{Changing Files}.
1342 @defun file-selinux-context filename
1343 This function returns the SELinux security context of the file
1344 @var{filename}. This return value is a list of the form
1345 @code{(@var{user} @var{role} @var{type} @var{range})}, whose elements
1346 are the context's user, role, type, and range respectively, as Lisp
1347 strings. See the SELinux documentation for details about what these
1350 If the file does not exist or is inaccessible, or if the system does
1351 not support SELinux, or if Emacs was not compiled with SELinux
1352 support, then the return value is @code{(nil nil nil nil)}.
1355 @cindex access control list
1357 If Emacs has been compiled with @dfn{ACL} (access control list)
1358 support, you can use the function @code{file-acl} to retrieve a file's
1359 ACL entries. The interface implementation is platform-specific; on
1360 GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
1361 MS-Windows Emacs emulates the POSIX ACL interface with native file
1364 @defun file-acl filename
1365 This function returns the ACL entries of the file @var{filename}. The
1366 return value is a platform-dependent object containing some
1367 representation of the ACL entries. Don't use it for anything except
1368 passing it to the @code{set-file-acl} function (@pxref{Changing Files,
1371 If the file does not exist or is inaccessible, or if Emacs was unable to
1372 determine the ACL entries, then the return value is @code{nil}. The
1373 latter can happen for local files if Emacs was not compiled with ACL
1374 support, or for remote files if the file handler returns nil for the
1378 @node Locating Files
1379 @subsection How to Locate Files in Standard Places
1380 @cindex locate file in path
1381 @cindex find file in path
1383 This section explains how to search for a file in a list of
1384 directories (a @dfn{path}), or for an executable file in the standard
1385 list of executable file directories.
1387 To search for a user-specific configuration file, @xref{Standard
1388 File Names}, for the @code{locate-user-emacs-file} function.
1390 @defun locate-file filename path &optional suffixes predicate
1391 This function searches for a file whose name is @var{filename} in a
1392 list of directories given by @var{path}, trying the suffixes in
1393 @var{suffixes}. If it finds such a file, it returns the file's
1394 absolute file name (@pxref{Relative File Names}); otherwise it returns
1397 The optional argument @var{suffixes} gives the list of file-name
1398 suffixes to append to @var{filename} when searching.
1399 @code{locate-file} tries each possible directory with each of these
1400 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
1401 are no suffixes, and @var{filename} is used only as-is. Typical
1402 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1403 Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and
1404 the return value of the function @code{get-load-suffixes} (@pxref{Load
1407 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1408 Creation}) when looking for executable programs, or @code{load-path}
1409 (@pxref{Library Search}) when looking for Lisp files. If
1410 @var{filename} is absolute, @var{path} has no effect, but the suffixes
1411 in @var{suffixes} are still tried.
1413 The optional argument @var{predicate}, if non-@code{nil}, specifies a
1414 predicate function for testing whether a candidate file is suitable.
1415 The predicate is passed the candidate file name as its single
1416 argument. If @var{predicate} is @code{nil} or omitted,
1417 @code{locate-file} uses @code{file-readable-p} as the predicate.
1418 @xref{Kinds of Files}, for other useful predicates, e.g.,
1419 @code{file-executable-p} and @code{file-directory-p}.
1421 For compatibility, @var{predicate} can also be one of the symbols
1422 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1423 a list of one or more of these symbols.
1426 @defun executable-find program
1427 This function searches for the executable file of the named
1428 @var{program} and returns the absolute file name of the executable,
1429 including its file-name extensions, if any. It returns @code{nil} if
1430 the file is not found. The functions searches in all the directories
1431 in @code{exec-path}, and tries all the file-name extensions in
1432 @code{exec-suffixes} (@pxref{Subprocess Creation}).
1435 @node Changing Files
1436 @section Changing File Names and Attributes
1437 @c @cindex renaming files Duplicates rename-file
1438 @cindex copying files
1439 @cindex deleting files
1440 @cindex linking files
1441 @cindex setting modes of files
1443 The functions in this section rename, copy, delete, link, and set
1444 the modes (permissions) of files.
1446 In the functions that have an argument @var{newname}, if a file by the
1447 name of @var{newname} already exists, the actions taken depend on the
1448 value of the argument @var{ok-if-already-exists}:
1452 Signal a @code{file-already-exists} error if
1453 @var{ok-if-already-exists} is @code{nil}.
1456 Request confirmation if @var{ok-if-already-exists} is a number.
1459 Replace the old file without confirmation if @var{ok-if-already-exists}
1463 The next four commands all recursively follow symbolic links at all
1464 levels of parent directories for their first argument, but, if that
1465 argument is itself a symbolic link, then only @code{copy-file}
1466 replaces it with its (recursive) target.
1468 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1469 @cindex file with multiple names
1470 @cindex file hard link
1471 This function gives the file named @var{oldname} the additional name
1472 @var{newname}. This means that @var{newname} becomes a new ``hard
1473 link'' to @var{oldname}.
1475 In the first part of the following example, we list two files,
1476 @file{foo} and @file{foo3}.
1481 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1482 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1486 Now we create a hard link, by calling @code{add-name-to-file}, then list
1487 the files again. This shows two names for one file, @file{foo} and
1492 (add-name-to-file "foo" "foo2")
1498 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1499 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1500 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1504 Finally, we evaluate the following:
1507 (add-name-to-file "foo" "foo3" t)
1511 and list the files again. Now there are three names
1512 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1513 contents of @file{foo3} are lost.
1517 (add-name-to-file "foo1" "foo3")
1523 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1524 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1525 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1529 This function is meaningless on operating systems where multiple names
1530 for one file are not allowed. Some systems implement multiple names
1531 by copying the file instead.
1533 See also @code{file-nlinks} in @ref{File Attributes}.
1536 @deffn Command rename-file filename newname &optional ok-if-already-exists
1537 This command renames the file @var{filename} as @var{newname}.
1539 If @var{filename} has additional names aside from @var{filename}, it
1540 continues to have those names. In fact, adding the name @var{newname}
1541 with @code{add-name-to-file} and then deleting @var{filename} has the
1542 same effect as renaming, aside from momentary intermediate states.
1545 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux
1546 This command copies the file @var{oldname} to @var{newname}. An
1547 error is signaled if @var{oldname} does not exist. If @var{newname}
1548 names a directory, it copies @var{oldname} into that directory,
1549 preserving its final name component.
1551 If @var{time} is non-@code{nil}, then this function gives the new file
1552 the same last-modified time that the old one has. (This works on only
1553 some operating systems.) If setting the time gets an error,
1554 @code{copy-file} signals a @code{file-date-error} error. In an
1555 interactive call, a prefix argument specifies a non-@code{nil} value
1558 This function copies the file modes, too.
1560 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
1561 system decide the user and group ownership of the new file (this is
1562 usually set to the user running Emacs). If @var{preserve-uid-gid} is
1563 non-@code{nil}, we attempt to copy the user and group ownership of the
1564 file. This works only on some operating systems, and only if you have
1565 the correct permissions to do so.
1567 If the optional argument @var{preserve-extended-attributes} is
1568 non-@code{nil}, and Emacs has been built with the appropriate support,
1569 this function attempts to copy the file's extended attributes, such as
1570 its SELinux context and ACL entries (@pxref{File Attributes}).
1573 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
1575 @kindex file-already-exists
1576 This command makes a symbolic link to @var{filename}, named
1577 @var{newname}. This is like the shell command @samp{ln -s
1578 @var{filename} @var{newname}}.
1580 This function is not available on systems that don't support symbolic
1585 @vindex delete-by-moving-to-trash
1586 @deffn Command delete-file filename &optional trash
1588 This command deletes the file @var{filename}. If the file has
1589 multiple names, it continues to exist under the other names. If
1590 @var{filename} is a symbolic link, @code{delete-file} deletes only the
1591 symbolic link and not its target (though it does follow symbolic links
1592 at all levels of parent directories).
1594 A suitable kind of @code{file-error} error is signaled if the file
1595 does not exist, or is not deletable. (On Unix and GNU/Linux, a file
1596 is deletable if its directory is writable.)
1598 If the optional argument @var{trash} is non-@code{nil} and the
1599 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
1600 command moves the file into the system Trash instead of deleting it.
1601 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
1602 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
1603 no prefix argument is given, and @code{nil} otherwise.
1605 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1608 @cindex file permissions, setting
1609 @cindex permissions, file
1610 @cindex file modes, setting
1611 @deffn Command set-file-modes filename mode
1612 This function sets the @dfn{file mode} (or @dfn{file permissions}) of
1613 @var{filename} to @var{mode}. It recursively follows symbolic links
1614 at all levels for @var{filename}.
1616 If called non-interactively, @var{mode} must be an integer. Only the
1617 lowest 12 bits of the integer are used; on most systems, only the
1618 lowest 9 bits are meaningful. You can use the Lisp construct for
1619 octal numbers to enter @var{mode}. For example,
1622 (set-file-modes #o644)
1626 specifies that the file should be readable and writable for its owner,
1627 readable for group members, and readable for all other users.
1628 @xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
1629 Manual}, for a description of mode bit specifications.
1631 Interactively, @var{mode} is read from the minibuffer using
1632 @code{read-file-modes} (see below), which lets the user type in either
1633 an integer or a string representing the permissions symbolically.
1635 @xref{File Attributes}, for the function @code{file-modes}, which
1636 returns the permissions of a file.
1639 @defun set-default-file-modes mode
1641 This function sets the default file permissions for new files created
1642 by Emacs and its subprocesses. Every file created with Emacs
1643 initially has these permissions, or a subset of them
1644 (@code{write-region} will not grant execute permissions even if the
1645 default file permissions allow execution). On Unix and GNU/Linux, the
1646 default permissions are given by the bitwise complement of the
1649 The argument @var{mode} should be an integer which specifies the
1650 permissions, similar to @code{set-file-modes} above. Only the lowest
1651 9 bits are meaningful.
1653 The default file permissions have no effect when you save a modified
1654 version of an existing file; saving a file preserves its existing
1658 @defun default-file-modes
1659 This function returns the default file permissions, as an integer.
1662 @defun read-file-modes &optional prompt base-file
1663 This function reads a set of file mode bits from the minibuffer. The
1664 first optional argument @var{prompt} specifies a non-default prompt.
1665 Second second optional argument @var{base-file} is the name of a file
1666 on whose permissions to base the mode bits that this function returns,
1667 if what the user types specifies mode bits relative to permissions of
1670 If user input represents an octal number, this function returns that
1671 number. If it is a complete symbolic specification of mode bits, as
1672 in @code{"u=rwx"}, the function converts it to the equivalent numeric
1673 value using @code{file-modes-symbolic-to-number} and returns the
1674 result. If the specification is relative, as in @code{"o+g"}, then
1675 the permissions on which the specification is based are taken from the
1676 mode bits of @var{base-file}. If @var{base-file} is omitted or
1677 @code{nil}, the function uses @code{0} as the base mode bits. The
1678 complete and relative specifications can be combined, as in
1679 @code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
1680 @sc{gnu} @code{Coreutils} Manual}, for a description of file mode
1684 @defun file-modes-symbolic-to-number modes &optional base-modes
1685 This function converts a symbolic file mode specification in
1686 @var{modes} into the equivalent integer value. If the symbolic
1687 specification is based on an existing file, that file's mode bits are
1688 taken from the optional argument @var{base-modes}; if that argument is
1689 omitted or @code{nil}, it defaults to 0, i.e., no access rights at
1693 @defun set-file-times filename &optional time
1694 This function sets the access and modification times of @var{filename}
1695 to @var{time}. The return value is @code{t} if the times are successfully
1696 set, otherwise it is @code{nil}. @var{time} defaults to the current
1697 time and must be in the format returned by @code{current-time}
1698 (@pxref{Time of Day}).
1701 @defun set-file-selinux-context filename context
1702 This function sets the SELinux security context of the file
1703 @var{filename} to @var{context}. @xref{File Attributes}, for a brief
1704 description of SELinux contexts. The @var{context} argument should be
1705 a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
1706 return value of @code{file-selinux-context}. The function returns
1707 @code{t} if it succeeds to set the SELinux security context of
1708 @var{filename}, @code{nil} otherwise. The function does nothing and
1709 returns @code{nil} if SELinux is disabled, or if Emacs was compiled
1710 without SELinux support.
1713 @defun set-file-acl filename acl-string
1714 This function sets the ACL entries of the file @var{filename} to
1715 @var{acl-string}. @xref{File Attributes}, for a brief description of
1716 ACLs. The @var{acl-string} argument should be a string containing the
1717 textual representation of the desired ACL entries as returned by
1718 @code{file-acl} (@pxref{File Attributes, file-acl}). The function
1719 returns @code{t} if it succeeds to set the ACL entries of
1720 @var{filename}, @code{nil} otherwise.
1727 Files are generally referred to by their names, in Emacs as elsewhere.
1728 File names in Emacs are represented as strings. The functions that
1729 operate on a file all expect a file name argument.
1731 In addition to operating on files themselves, Emacs Lisp programs
1732 often need to operate on file names; i.e., to take them apart and to use
1733 part of a name to construct related file names. This section describes
1734 how to manipulate file names.
1736 The functions in this section do not actually access files, so they
1737 can operate on file names that do not refer to an existing file or
1740 @findex cygwin-convert-file-name-from-windows
1741 @findex cygwin-convert-file-name-to-windows
1742 @cindex MS-Windows file-name syntax
1743 @cindex converting file names from/to MS-Windows syntax
1744 On MS-DOS and MS-Windows, these functions (like the function that
1745 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1746 where backslashes separate the components, as well as Unix syntax; but
1747 they always return Unix syntax. This enables Lisp programs to specify
1748 file names in Unix syntax and work properly on all systems without
1749 change.@footnote{In MS-Windows versions of Emacs compiled for the Cygwin
1750 environment, you can use the functions
1751 @code{cygwin-convert-file-name-to-windows} and
1752 @code{cygwin-convert-file-name-from-windows} to convert between the
1753 two file-name syntaxes.}
1756 * File Name Components:: The directory part of a file name, and the rest.
1757 * Relative File Names:: Some file names are relative to a current directory.
1758 * Directory Names:: A directory's name as a directory
1759 is different from its name as a file.
1760 * File Name Expansion:: Converting relative file names to absolute ones.
1761 * Unique File Names:: Generating names for temporary files.
1762 * File Name Completion:: Finding the completions for a given file name.
1763 * Standard File Names:: If your package uses a fixed file name,
1764 how to handle various operating systems simply.
1767 @node File Name Components
1768 @subsection File Name Components
1769 @cindex directory part (of file name)
1770 @cindex nondirectory part (of file name)
1771 @cindex version number (in file name)
1773 The operating system groups files into directories. To specify a
1774 file, you must specify the directory and the file's name within that
1775 directory. Therefore, Emacs considers a file name as having two main
1776 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1777 (or @dfn{file name within the directory}). Either part may be empty.
1778 Concatenating these two parts reproduces the original file name.
1780 On most systems, the directory part is everything up to and including
1781 the last slash (backslash is also allowed in input on MS-DOS or
1782 MS-Windows); the nondirectory part is the rest.
1784 For some purposes, the nondirectory part is further subdivided into
1785 the name proper and the @dfn{version number}. On most systems, only
1786 backup files have version numbers in their names.
1788 @defun file-name-directory filename
1789 This function returns the directory part of @var{filename}, as a
1790 directory name (@pxref{Directory Names}), or @code{nil} if
1791 @var{filename} does not include a directory part.
1793 On GNU and Unix systems, a string returned by this function always
1794 ends in a slash. On MS-DOS it can also end in a colon.
1798 (file-name-directory "lewis/foo") ; @r{Unix example}
1802 (file-name-directory "foo") ; @r{Unix example}
1808 @defun file-name-nondirectory filename
1809 This function returns the nondirectory part of @var{filename}.
1813 (file-name-nondirectory "lewis/foo")
1817 (file-name-nondirectory "foo")
1821 (file-name-nondirectory "lewis/")
1827 @defun file-name-sans-versions filename &optional keep-backup-version
1828 This function returns @var{filename} with any file version numbers,
1829 backup version numbers, or trailing tildes discarded.
1831 If @var{keep-backup-version} is non-@code{nil}, then true file version
1832 numbers understood as such by the file system are discarded from the
1833 return value, but backup version numbers are kept.
1837 (file-name-sans-versions "~rms/foo.~1~")
1838 @result{} "~rms/foo"
1841 (file-name-sans-versions "~rms/foo~")
1842 @result{} "~rms/foo"
1845 (file-name-sans-versions "~rms/foo")
1846 @result{} "~rms/foo"
1851 @defun file-name-extension filename &optional period
1852 This function returns @var{filename}'s final ``extension'', if any,
1853 after applying @code{file-name-sans-versions} to remove any
1854 version/backup part. The extension, in a file name, is the part that
1855 follows the last @samp{.} in the last name component (minus any
1856 version/backup part).
1858 This function returns @code{nil} for extensionless file names such as
1859 @file{foo}. It returns @code{""} for null extensions, as in
1860 @file{foo.}. If the last component of a file name begins with a
1861 @samp{.}, that @samp{.} doesn't count as the beginning of an
1862 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1865 If @var{period} is non-@code{nil}, then the returned value includes
1866 the period that delimits the extension, and if @var{filename} has no
1867 extension, the value is @code{""}.
1870 @defun file-name-sans-extension filename
1871 This function returns @var{filename} minus its extension, if any. The
1872 version/backup part, if present, is only removed if the file has an
1873 extension. For example,
1876 (file-name-sans-extension "foo.lose.c")
1877 @result{} "foo.lose"
1878 (file-name-sans-extension "big.hack/foo")
1879 @result{} "big.hack/foo"
1880 (file-name-sans-extension "/my/home/.emacs")
1881 @result{} "/my/home/.emacs"
1882 (file-name-sans-extension "/my/home/.emacs.el")
1883 @result{} "/my/home/.emacs"
1884 (file-name-sans-extension "~/foo.el.~3~")
1886 (file-name-sans-extension "~/foo.~3~")
1887 @result{} "~/foo.~3~"
1890 Note that the @samp{.~3~} in the two last examples is the backup part,
1894 @defun file-name-base &optional filename
1895 This function is the composition of @code{file-name-sans-extension}
1896 and @code{file-name-nondirectory}. For example,
1899 (file-name-base "/my/home/foo.c")
1903 The @var{filename} argument defaults to @code{buffer-file-name}.
1906 @node Relative File Names
1907 @subsection Absolute and Relative File Names
1908 @cindex absolute file name
1909 @cindex relative file name
1911 All the directories in the file system form a tree starting at the
1912 root directory. A file name can specify all the directory names
1913 starting from the root of the tree; then it is called an
1914 @dfn{absolute} file name. Or it can specify the position of the file
1915 in the tree relative to a default directory; then it is called a
1916 @dfn{relative} file name. On Unix and GNU/Linux, an absolute file
1917 name starts with a @samp{/} or a @samp{~}
1918 (@pxref{abbreviate-file-name}), and a relative one does not. On
1919 MS-DOS and MS-Windows, an absolute file name starts with a slash or a
1920 backslash, or with a drive specification @samp{@var{x}:/}, where
1921 @var{x} is the @dfn{drive letter}.
1923 @defun file-name-absolute-p filename
1924 This function returns @code{t} if file @var{filename} is an absolute
1925 file name, @code{nil} otherwise.
1929 (file-name-absolute-p "~rms/foo")
1933 (file-name-absolute-p "rms/foo")
1937 (file-name-absolute-p "/user/rms/foo")
1943 Given a possibly relative file name, you can convert it to an
1944 absolute name using @code{expand-file-name} (@pxref{File Name
1945 Expansion}). This function converts absolute file names to relative
1948 @defun file-relative-name filename &optional directory
1949 This function tries to return a relative name that is equivalent to
1950 @var{filename}, assuming the result will be interpreted relative to
1951 @var{directory} (an absolute directory name or directory file name).
1952 If @var{directory} is omitted or @code{nil}, it defaults to the
1953 current buffer's default directory.
1955 On some operating systems, an absolute file name begins with a device
1956 name. On such systems, @var{filename} has no relative equivalent based
1957 on @var{directory} if they start with two different device names. In
1958 this case, @code{file-relative-name} returns @var{filename} in absolute
1962 (file-relative-name "/foo/bar" "/foo/")
1964 (file-relative-name "/foo/bar" "/hack/")
1965 @result{} "../foo/bar"
1969 @node Directory Names
1970 @subsection Directory Names
1971 @cindex directory name
1972 @cindex file name of directory
1974 A @dfn{directory name} is the name of a directory. A directory is
1975 actually a kind of file, so it has a file name, which is related to
1976 the directory name but not identical to it. (This is not quite the
1977 same as the usual Unix terminology.) These two different names for
1978 the same entity are related by a syntactic transformation. On GNU and
1979 Unix systems, this is simple: a directory name ends in a slash,
1980 whereas the directory's name as a file lacks that slash. On MS-DOS
1981 the relationship is more complicated.
1983 The difference between a directory name and its name as a file is
1984 subtle but crucial. When an Emacs variable or function argument is
1985 described as being a directory name, a file name of a directory is not
1986 acceptable. When @code{file-name-directory} returns a string, that is
1987 always a directory name.
1989 The following two functions convert between directory names and file
1990 names. They do nothing special with environment variable substitutions
1991 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1993 @defun file-name-as-directory filename
1994 This function returns a string representing @var{filename} in a form
1995 that the operating system will interpret as the name of a directory. On
1996 most systems, this means appending a slash to the string (if it does not
1997 already end in one).
2001 (file-name-as-directory "~rms/lewis")
2002 @result{} "~rms/lewis/"
2007 @defun directory-file-name dirname
2008 This function returns a string representing @var{dirname} in a form that
2009 the operating system will interpret as the name of a file. On most
2010 systems, this means removing the final slash (or backslash) from the
2015 (directory-file-name "~lewis/")
2021 Given a directory name, you can combine it with a relative file name
2022 using @code{concat}:
2025 (concat @var{dirname} @var{relfile})
2029 Be sure to verify that the file name is relative before doing that.
2030 If you use an absolute file name, the results could be syntactically
2031 invalid or refer to the wrong file.
2033 If you want to use a directory file name in making such a
2034 combination, you must first convert it to a directory name using
2035 @code{file-name-as-directory}:
2038 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
2042 Don't try concatenating a slash by hand, as in
2046 (concat @var{dirfile} "/" @var{relfile})
2050 because this is not portable. Always use
2051 @code{file-name-as-directory}.
2053 To convert a directory name to its abbreviation, use this
2056 @cindex file name abbreviations
2057 @cindex abbreviated file names
2058 @defun abbreviate-file-name filename
2059 @anchor{abbreviate-file-name}
2060 This function returns an abbreviated form of @var{filename}. It
2061 applies the abbreviations specified in @code{directory-abbrev-alist}
2062 (@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
2063 then substitutes @samp{~} for the user's home directory if the
2064 argument names a file in the home directory or one of its
2065 subdirectories. If the home directory is a root directory, it is not
2066 replaced with @samp{~}, because this does not make the result shorter
2069 You can use this function for directory names and for file names,
2070 because it recognizes abbreviations even as part of the name.
2073 @node File Name Expansion
2074 @subsection Functions that Expand Filenames
2075 @cindex expansion of file names
2077 @dfn{Expanding} a file name means converting a relative file name to
2078 an absolute one. Since this is done relative to a default directory,
2079 you must specify the default directory name as well as the file name
2080 to be expanded. It also involves expanding abbreviations like
2083 (@pxref{abbreviate-file-name}),
2085 and eliminating redundancies like @file{./} and @file{@var{name}/../}.
2087 @defun expand-file-name filename &optional directory
2088 This function converts @var{filename} to an absolute file name. If
2089 @var{directory} is supplied, it is the default directory to start with
2090 if @var{filename} is relative. (The value of @var{directory} should
2091 itself be an absolute directory name or directory file name; it may
2092 start with @samp{~}.) Otherwise, the current buffer's value of
2093 @code{default-directory} is used. For example:
2097 (expand-file-name "foo")
2098 @result{} "/xcssun/users/rms/lewis/foo"
2101 (expand-file-name "../foo")
2102 @result{} "/xcssun/users/rms/foo"
2105 (expand-file-name "foo" "/usr/spool/")
2106 @result{} "/usr/spool/foo"
2109 (expand-file-name "$HOME/foo")
2110 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
2114 If the part of the combined file name before the first slash is
2115 @samp{~}, it expands to the value of the @env{HOME} environment
2116 variable (usually your home directory). If the part before the first
2117 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
2118 it expands to @var{user}'s home directory.
2120 Filenames containing @samp{.} or @samp{..} are simplified to their
2125 (expand-file-name "bar/../foo")
2126 @result{} "/xcssun/users/rms/lewis/foo"
2130 In some cases, a leading @samp{..} component can remain in the output:
2134 (expand-file-name "../home" "/")
2135 @result{} "/../home"
2140 This is for the sake of filesystems that have the concept of a
2141 ``superroot'' above the root directory @file{/}. On other filesystems,
2142 @file{/../} is interpreted exactly the same as @file{/}.
2144 Note that @code{expand-file-name} does @emph{not} expand environment
2145 variables; only @code{substitute-in-file-name} does that.
2147 Note also that @code{expand-file-name} does not follow symbolic links
2148 at any level. This results in a difference between the way
2149 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
2150 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
2151 @samp{/tmp/foo/bar} we get:
2155 (file-truename "/tmp/bar/../myfile")
2156 @result{} "/tmp/foo/myfile"
2159 (expand-file-name "/tmp/bar/../myfile")
2160 @result{} "/tmp/myfile"
2164 If you may need to follow symbolic links preceding @samp{..}, you
2165 should make sure to call @code{file-truename} without prior direct or
2166 indirect calls to @code{expand-file-name}. @xref{Truenames}.
2169 @defvar default-directory
2170 The value of this buffer-local variable is the default directory for the
2171 current buffer. It should be an absolute directory name; it may start
2172 with @samp{~}. This variable is buffer-local in every buffer.
2174 @code{expand-file-name} uses the default directory when its second
2175 argument is @code{nil}.
2177 The value is always a string ending with a slash.
2182 @result{} "/user/lewis/manual/"
2187 @defun substitute-in-file-name filename
2188 @anchor{Definition of substitute-in-file-name}
2189 This function replaces environment variable references in
2190 @var{filename} with the environment variable values. Following
2191 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2192 environment variable value. If the input contains @samp{$$}, that is
2193 converted to @samp{$}; this gives the user a way to ``quote'' a
2196 The environment variable name is the series of alphanumeric characters
2197 (including underscores) that follow the @samp{$}. If the character following
2198 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2201 Calling @code{substitute-in-file-name} on output produced by
2202 @code{substitute-in-file-name} tends to give incorrect results. For
2203 instance, use of @samp{$$} to quote a single @samp{$} won't work
2204 properly, and @samp{$} in an environment variable's value could lead
2205 to repeated substitution. Therefore, programs that call this function
2206 and put the output where it will be passed to this function need to
2207 double all @samp{$} characters to prevent subsequent incorrect
2210 @c Wordy to avoid overfull hbox. --rjc 15mar92
2211 Here we assume that the environment variable @env{HOME}, which holds
2212 the user's home directory name, has value @samp{/xcssun/users/rms}.
2216 (substitute-in-file-name "$HOME/foo")
2217 @result{} "/xcssun/users/rms/foo"
2221 After substitution, if a @samp{~} or a @samp{/} appears immediately
2222 after another @samp{/}, the function discards everything before it (up
2223 through the immediately preceding @samp{/}).
2227 (substitute-in-file-name "bar/~/foo")
2231 (substitute-in-file-name "/usr/local/$HOME/foo")
2232 @result{} "/xcssun/users/rms/foo"
2233 ;; @r{@file{/usr/local/} has been discarded.}
2239 @node Unique File Names
2240 @subsection Generating Unique File Names
2242 Some programs need to write temporary files. Here is the usual way to
2243 construct a name for such a file:
2246 (make-temp-file @var{name-of-application})
2250 The job of @code{make-temp-file} is to prevent two different users or
2251 two different jobs from trying to use the exact same file name.
2253 @defun make-temp-file prefix &optional dir-flag suffix
2254 This function creates a temporary file and returns its name. Emacs
2255 creates the temporary file's name by adding to @var{prefix} some
2256 random characters that are different in each Emacs job. The result is
2257 guaranteed to be a newly created empty file. On MS-DOS, this function
2258 can truncate the @var{string} prefix to fit into the 8+3 file-name
2259 limits. If @var{prefix} is a relative file name, it is expanded
2260 against @code{temporary-file-directory}.
2264 (make-temp-file "foo")
2265 @result{} "/tmp/foo232J6v"
2269 When @code{make-temp-file} returns, the file has been created and is
2270 empty. At that point, you should write the intended contents into the
2273 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2274 empty directory instead of an empty file. It returns the file name,
2275 not the directory name, of that directory. @xref{Directory Names}.
2277 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2278 the end of the file name.
2280 To prevent conflicts among different libraries running in the same
2281 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2282 own @var{prefix}. The number added to the end of @var{prefix}
2283 distinguishes between the same application running in different Emacs
2284 jobs. Additional added characters permit a large number of distinct
2285 names even in one Emacs job.
2288 The default directory for temporary files is controlled by the
2289 variable @code{temporary-file-directory}. This variable gives the user
2290 a uniform way to specify the directory for all temporary files. Some
2291 programs use @code{small-temporary-file-directory} instead, if that is
2292 non-@code{nil}. To use it, you should expand the prefix against
2293 the proper directory before calling @code{make-temp-file}.
2295 @defopt temporary-file-directory
2296 @cindex @env{TMPDIR} environment variable
2297 @cindex @env{TMP} environment variable
2298 @cindex @env{TEMP} environment variable
2299 This variable specifies the directory name for creating temporary files.
2300 Its value should be a directory name (@pxref{Directory Names}), but it
2301 is good for Lisp programs to cope if the value is a directory's file
2302 name instead. Using the value as the second argument to
2303 @code{expand-file-name} is a good way to achieve that.
2305 The default value is determined in a reasonable way for your operating
2306 system; it is based on the @env{TMPDIR}, @env{TMP} and @env{TEMP}
2307 environment variables, with a fall-back to a system-dependent name if
2308 none of these variables is defined.
2310 Even if you do not use @code{make-temp-file} to create the temporary
2311 file, you should still use this variable to decide which directory to
2312 put the file in. However, if you expect the file to be small, you
2313 should use @code{small-temporary-file-directory} first if that is
2317 @defopt small-temporary-file-directory
2318 This variable specifies the directory name for
2319 creating certain temporary files, which are likely to be small.
2321 If you want to write a temporary file which is likely to be small, you
2322 should compute the directory like this:
2326 (expand-file-name @var{prefix}
2327 (or small-temporary-file-directory
2328 temporary-file-directory)))
2332 @defun make-temp-name base-name
2333 This function generates a string that can be used as a unique file
2334 name. The name starts with @var{base-name}, and has several random
2335 characters appended to it, which are different in each Emacs job. It
2336 is like @code{make-temp-file} except that (i) it just constructs a
2337 name, and does not create a file, and (ii) @var{base-name} should be
2338 an absolute file name (on MS-DOS, this function can truncate
2339 @var{base-name} to fit into the 8+3 file-name limits).
2341 @strong{Warning:} In most cases, you should not use this function; use
2342 @code{make-temp-file} instead! This function is susceptible to a race
2343 condition, between the @code{make-temp-name} call and the creation of
2344 the file, which in some cases may cause a security hole.
2347 @node File Name Completion
2348 @subsection File Name Completion
2349 @cindex file name completion subroutines
2350 @cindex completion, file name
2352 This section describes low-level subroutines for completing a file
2353 name. For higher level functions, see @ref{Reading File Names}.
2355 @defun file-name-all-completions partial-filename directory
2356 This function returns a list of all possible completions for a file
2357 whose name starts with @var{partial-filename} in directory
2358 @var{directory}. The order of the completions is the order of the files
2359 in the directory, which is unpredictable and conveys no useful
2362 The argument @var{partial-filename} must be a file name containing no
2363 directory part and no slash (or backslash on some systems). The current
2364 buffer's default directory is prepended to @var{directory}, if
2365 @var{directory} is not absolute.
2367 In the following example, suppose that @file{~rms/lewis} is the current
2368 default directory, and has five files whose names begin with @samp{f}:
2369 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2370 @file{file.c.~2~}.@refill
2374 (file-name-all-completions "f" "")
2375 @result{} ("foo" "file~" "file.c.~2~"
2376 "file.c.~1~" "file.c")
2380 (file-name-all-completions "fo" "")
2386 @defun file-name-completion filename directory &optional predicate
2387 This function completes the file name @var{filename} in directory
2388 @var{directory}. It returns the longest prefix common to all file names
2389 in directory @var{directory} that start with @var{filename}. If
2390 @var{predicate} is non-@code{nil} then it ignores possible completions
2391 that don't satisfy @var{predicate}, after calling that function
2392 with one argument, the expanded absolute file name.
2394 If only one match exists and @var{filename} matches it exactly, the
2395 function returns @code{t}. The function returns @code{nil} if directory
2396 @var{directory} contains no name starting with @var{filename}.
2398 In the following example, suppose that the current default directory
2399 has five files whose names begin with @samp{f}: @file{foo},
2400 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2401 @file{file.c.~2~}.@refill
2405 (file-name-completion "fi" "")
2410 (file-name-completion "file.c.~1" "")
2411 @result{} "file.c.~1~"
2415 (file-name-completion "file.c.~1~" "")
2420 (file-name-completion "file.c.~3" "")
2426 @defopt completion-ignored-extensions
2427 @code{file-name-completion} usually ignores file names that end in any
2428 string in this list. It does not ignore them when all the possible
2429 completions end in one of these suffixes. This variable has no effect
2430 on @code{file-name-all-completions}.@refill
2432 A typical value might look like this:
2436 completion-ignored-extensions
2437 @result{} (".o" ".elc" "~" ".dvi")
2441 If an element of @code{completion-ignored-extensions} ends in a slash
2442 @samp{/}, it signals a directory. The elements which do @emph{not} end
2443 in a slash will never match a directory; thus, the above value will not
2444 filter out a directory named @file{foo.elc}.
2447 @node Standard File Names
2448 @subsection Standard File Names
2450 Sometimes, an Emacs Lisp program needs to specify a standard file
2451 name for a particular use---typically, to hold configuration data
2452 specified by the current user. Usually, such files should be located
2453 in the directory specified by @code{user-emacs-directory}, which is
2454 @file{~/.emacs.d} by default (@pxref{Init File}). For example, abbrev
2455 definitions are stored by default in @file{~/.emacs.d/abbrev_defs}.
2456 The easiest way to specify such a file name is to use the function
2457 @code{locate-user-emacs-file}.
2459 @defun locate-user-emacs-file base-name &optional old-name
2460 This function returns an absolute file name for an Emacs-specific
2461 configuration or data file. The argument @file{base-name} should be a
2462 relative file name. The return value is the absolute name of a file
2463 in the directory specified by @code{user-emacs-directory}; if that
2464 directory does not exist, this function creates it.
2466 If the optional argument @var{old-name} is non-@code{nil}, it
2467 specifies a file in the user's home directory,
2468 @file{~/@var{old-name}}. If such a file exists, the return value is
2469 the absolute name of that file, instead of the file specified by
2470 @var{base-name}. This argument is intended to be used by Emacs
2471 packages to provide backward compatibility. For instance, prior to
2472 the introduction of @code{user-emacs-directory}, the abbrev file was
2473 located in @file{~/.abbrev_defs}. Here is the definition of
2474 @code{abbrev-file-name}:
2477 (defcustom abbrev-file-name
2478 (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
2479 "Default name of file from which to read abbrevs."
2485 A lower-level function for standardizing file names, which
2486 @code{locate-user-emacs-file} uses as a subroutine, is
2487 @code{convert-standard-filename}.
2489 @defun convert-standard-filename filename
2490 This function returns a file name based on @var{filename}, which fits
2491 the conventions of the current operating system.
2493 On GNU and Unix systems, this simply returns @var{filename}. On other
2494 operating systems, it may enforce system-specific file name
2495 conventions; for example, on MS-DOS this function performs a variety
2496 of changes to enforce MS-DOS file name limitations, including
2497 converting any leading @samp{.} to @samp{_} and truncating to three
2498 characters after the @samp{.}.
2500 The recommended way to use this function is to specify a name which
2501 fits the conventions of GNU and Unix systems, and pass it to
2502 @code{convert-standard-filename}.
2505 @node Contents of Directories
2506 @section Contents of Directories
2507 @cindex directory-oriented functions
2508 @cindex file names in directory
2510 A directory is a kind of file that contains other files entered under
2511 various names. Directories are a feature of the file system.
2513 Emacs can list the names of the files in a directory as a Lisp list,
2514 or display the names in a buffer using the @code{ls} shell command. In
2515 the latter case, it can optionally display information about each file,
2516 depending on the options passed to the @code{ls} command.
2518 @defun directory-files directory &optional full-name match-regexp nosort
2519 This function returns a list of the names of the files in the directory
2520 @var{directory}. By default, the list is in alphabetical order.
2522 If @var{full-name} is non-@code{nil}, the function returns the files'
2523 absolute file names. Otherwise, it returns the names relative to
2524 the specified directory.
2526 If @var{match-regexp} is non-@code{nil}, this function returns only
2527 those file names that contain a match for that regular expression---the
2528 other file names are excluded from the list. On case-insensitive
2529 filesystems, the regular expression matching is case-insensitive.
2532 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2533 the list, so you get the file names in no particular order. Use this if
2534 you want the utmost possible speed and don't care what order the files
2535 are processed in. If the order of processing is visible to the user,
2536 then the user will probably be happier if you do sort the names.
2540 (directory-files "~lewis")
2541 @result{} ("#foo#" "#foo.el#" "." ".."
2542 "dired-mods.el" "files.texi"
2547 An error is signaled if @var{directory} is not the name of a directory
2551 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2552 This is similar to @code{directory-files} in deciding which files
2553 to report on and how to report their names. However, instead
2554 of returning a list of file names, it returns for each file a
2555 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2556 is what @code{file-attributes} would return for that file.
2557 The optional argument @var{id-format} has the same meaning as the
2558 corresponding argument to @code{file-attributes} (@pxref{Definition
2559 of file-attributes}).
2562 @defun file-expand-wildcards pattern &optional full
2563 This function expands the wildcard pattern @var{pattern}, returning
2564 a list of file names that match it.
2566 If @var{pattern} is written as an absolute file name,
2567 the values are absolute also.
2569 If @var{pattern} is written as a relative file name, it is interpreted
2570 relative to the current default directory. The file names returned are
2571 normally also relative to the current default directory. However, if
2572 @var{full} is non-@code{nil}, they are absolute.
2575 @defun insert-directory file switches &optional wildcard full-directory-p
2576 This function inserts (in the current buffer) a directory listing for
2577 directory @var{file}, formatted with @code{ls} according to
2578 @var{switches}. It leaves point after the inserted text.
2579 @var{switches} may be a string of options, or a list of strings
2580 representing individual options.
2582 The argument @var{file} may be either a directory name or a file
2583 specification including wildcard characters. If @var{wildcard} is
2584 non-@code{nil}, that means treat @var{file} as a file specification with
2587 If @var{full-directory-p} is non-@code{nil}, that means the directory
2588 listing is expected to show the full contents of a directory. You
2589 should specify @code{t} when @var{file} is a directory and switches do
2590 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
2591 describe a directory itself as a file, rather than showing its
2594 On most systems, this function works by running a directory listing
2595 program whose name is in the variable @code{insert-directory-program}.
2596 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2597 @code{shell-file-name}, to expand the wildcards.
2599 MS-DOS and MS-Windows systems usually lack the standard Unix program
2600 @code{ls}, so this function emulates the standard Unix program @code{ls}
2603 As a technical detail, when @var{switches} contains the long
2604 @samp{--dired} option, @code{insert-directory} treats it specially,
2605 for the sake of dired. However, the normally equivalent short
2606 @samp{-D} option is just passed on to @code{insert-directory-program},
2607 as any other option.
2610 @defvar insert-directory-program
2611 This variable's value is the program to run to generate a directory listing
2612 for the function @code{insert-directory}. It is ignored on systems
2613 which generate the listing with Lisp code.
2616 @node Create/Delete Dirs
2617 @section Creating, Copying and Deleting Directories
2618 @cindex creating, copying and deleting directories
2619 @c Emacs 19 features
2621 Most Emacs Lisp file-manipulation functions get errors when used on
2622 files that are directories. For example, you cannot delete a directory
2623 with @code{delete-file}. These special functions exist to create and
2627 @deffn Command make-directory dirname &optional parents
2628 This command creates a directory named @var{dirname}. If
2629 @var{parents} is non-@code{nil}, as is always the case in an
2630 interactive call, that means to create the parent directories first,
2631 if they don't already exist.
2633 @code{mkdir} is an alias for this.
2636 @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
2637 This command copies the directory named @var{dirname} to
2638 @var{newname}. If @var{newname} names an existing directory,
2639 @var{dirname} will be copied to a subdirectory there.
2641 It always sets the file modes of the copied files to match the
2642 corresponding original file.
2644 The third argument @var{keep-time} non-@code{nil} means to preserve the
2645 modification time of the copied files. A prefix arg makes
2646 @var{keep-time} non-@code{nil}.
2648 The fourth argument @var{parents} says whether to
2649 create parent directories if they don't exist. Interactively,
2650 this happens by default.
2652 The fifth argument @var{copy-contents}, if non-@code{nil}, means to
2653 copy the contents of @var{dirname} directly into @var{newname} if the
2654 latter is an existing directory, instead of copying @var{dirname} into
2655 it as a subdirectory.
2659 @vindex delete-by-moving-to-trash
2660 @deffn Command delete-directory dirname &optional recursive trash
2661 This command deletes the directory named @var{dirname}. The function
2662 @code{delete-file} does not work for files that are directories; you
2663 must use @code{delete-directory} for them. If @var{recursive} is
2664 @code{nil}, and the directory contains any files,
2665 @code{delete-directory} signals an error.
2667 @code{delete-directory} only follows symbolic links at the level of
2670 If the optional argument @var{trash} is non-@code{nil} and the
2671 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
2672 command moves the file into the system Trash instead of deleting it.
2673 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
2674 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
2675 no prefix argument is given, and @code{nil} otherwise.
2678 @node Magic File Names
2679 @section Making Certain File Names ``Magic''
2680 @cindex magic file names
2682 You can implement special handling for certain file names. This is
2683 called making those names @dfn{magic}. The principal use for this
2684 feature is in implementing access to remote files (@pxref{Remote Files,,
2685 Remote Files, emacs, The GNU Emacs Manual}).
2687 To define a kind of magic file name, you must supply a regular
2688 expression to define the class of names (all those that match the
2689 regular expression), plus a handler that implements all the primitive
2690 Emacs file operations for file names that match.
2692 @cindex file handler
2693 @vindex file-name-handler-alist
2694 The variable @code{file-name-handler-alist} holds a list of handlers,
2695 together with regular expressions that determine when to apply each
2696 handler. Each element has this form:
2699 (@var{regexp} . @var{handler})
2703 All the Emacs primitives for file access and file name transformation
2704 check the given file name against @code{file-name-handler-alist}. If
2705 the file name matches @var{regexp}, the primitives handle that file by
2706 calling @var{handler}.
2708 The first argument given to @var{handler} is the name of the
2709 primitive, as a symbol; the remaining arguments are the arguments that
2710 were passed to that primitive. (The first of these arguments is most
2711 often the file name itself.) For example, if you do this:
2714 (file-exists-p @var{filename})
2718 and @var{filename} has handler @var{handler}, then @var{handler} is
2722 (funcall @var{handler} 'file-exists-p @var{filename})
2725 When a function takes two or more arguments that must be file names,
2726 it checks each of those names for a handler. For example, if you do
2730 (expand-file-name @var{filename} @var{dirname})
2734 then it checks for a handler for @var{filename} and then for a handler
2735 for @var{dirname}. In either case, the @var{handler} is called like
2739 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2743 The @var{handler} then needs to figure out whether to handle
2744 @var{filename} or @var{dirname}.
2746 If the specified file name matches more than one handler, the one
2747 whose match starts last in the file name gets precedence. This rule
2748 is chosen so that handlers for jobs such as uncompression are handled
2749 first, before handlers for jobs such as remote file access.
2751 Here are the operations that a magic file name handler gets to handle:
2755 @code{access-file}, @code{add-name-to-file},
2756 @code{byte-compiler-base-file-name},@*
2757 @code{copy-directory}, @code{copy-file},
2758 @code{delete-directory}, @code{delete-file},
2759 @code{diff-latest-backup-file},
2760 @code{directory-file-name},
2761 @code{directory-files},
2762 @code{directory-files-and-attributes},
2763 @code{dired-compress-file}, @code{dired-uncache},@*
2764 @code{expand-file-name},
2765 @code{file-accessible-directory-p},
2767 @code{file-attributes},
2768 @code{file-directory-p},
2769 @code{file-equal-p},
2770 @code{file-executable-p}, @code{file-exists-p},
2771 @code{file-in-directory-p},
2772 @code{file-local-copy}, @code{file-remote-p},
2773 @code{file-modes}, @code{file-name-all-completions},
2774 @code{file-name-as-directory},
2775 @code{file-name-completion},
2776 @code{file-name-directory},
2777 @code{file-name-nondirectory},
2778 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2779 @code{file-ownership-preserved-p},
2780 @code{file-readable-p}, @code{file-regular-p},
2781 @code{file-selinux-context},
2782 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
2783 @code{find-backup-file-name},
2784 @c Not sure why it was here: @code{find-file-noselect},@*
2785 @code{get-file-buffer},
2786 @code{insert-directory},
2787 @code{insert-file-contents},@*
2789 @code{make-auto-save-file-name},
2790 @code{make-directory},
2791 @code{make-directory-internal},
2792 @code{make-symbolic-link},@*
2793 @code{process-file},
2794 @code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
2795 @code{set-file-selinux-context}, @code{set-file-times},
2796 @code{set-visited-file-modtime}, @code{shell-command},
2797 @code{start-file-process},
2798 @code{substitute-in-file-name},@*
2799 @code{unhandled-file-name-directory},
2800 @code{vc-registered},
2801 @code{verify-visited-file-modtime},@*
2802 @code{write-region}.
2807 @code{access-file}, @code{add-name-to-file},
2808 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2809 @code{copy-directory}, @code{copy-file},
2810 @code{delete-directory}, @code{delete-file},
2811 @code{diff-latest-backup-file},
2812 @code{directory-file-name},
2813 @code{directory-files},
2814 @code{directory-files-and-at@discretionary{}{}{}tributes},
2815 @code{dired-compress-file}, @code{dired-uncache},
2816 @code{expand-file-name},
2817 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2819 @code{file-attributes},
2820 @code{file-direct@discretionary{}{}{}ory-p},
2821 @code{file-equal-p},
2822 @code{file-executable-p}, @code{file-exists-p},
2823 @code{file-in-directory-p},
2824 @code{file-local-copy}, @code{file-remote-p},
2825 @code{file-modes}, @code{file-name-all-completions},
2826 @code{file-name-as-directory},
2827 @code{file-name-completion},
2828 @code{file-name-directory},
2829 @code{file-name-nondirec@discretionary{}{}{}tory},
2830 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2831 @code{file-ownership-pre@discretionary{}{}{}served-p},
2832 @code{file-readable-p}, @code{file-regular-p},
2833 @code{file-selinux-context},
2834 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
2835 @code{find-backup-file-name},
2836 @c Not sure why it was here: @code{find-file-noselect},
2837 @code{get-file-buffer},
2838 @code{insert-directory},
2839 @code{insert-file-contents},
2841 @code{make-auto-save-file-name},
2842 @code{make-direc@discretionary{}{}{}tory},
2843 @code{make-direc@discretionary{}{}{}tory-internal},
2844 @code{make-symbolic-link},
2845 @code{process-file},
2846 @code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
2847 @code{set-file-selinux-context}, @code{set-file-times},
2848 @code{set-visited-file-modtime}, @code{shell-command},
2849 @code{start-file-process},
2850 @code{substitute-in-file-name},
2851 @code{unhandled-file-name-directory},
2852 @code{vc-regis@discretionary{}{}{}tered},
2853 @code{verify-visited-file-modtime},
2854 @code{write-region}.
2858 Handlers for @code{insert-file-contents} typically need to clear the
2859 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2860 @var{visit} argument is non-@code{nil}. This also has the effect of
2861 unlocking the buffer if it is locked.
2863 The handler function must handle all of the above operations, and
2864 possibly others to be added in the future. It need not implement all
2865 these operations itself---when it has nothing special to do for a
2866 certain operation, it can reinvoke the primitive, to handle the
2867 operation ``in the usual way''. It should always reinvoke the primitive
2868 for an operation it does not recognize. Here's one way to do this:
2871 (defun my-file-handler (operation &rest args)
2872 ;; @r{First check for the specific operations}
2873 ;; @r{that we have special handling for.}
2874 (cond ((eq operation 'insert-file-contents) @dots{})
2875 ((eq operation 'write-region) @dots{})
2877 ;; @r{Handle any operation we don't know about.}
2878 (t (let ((inhibit-file-name-handlers
2879 (cons 'my-file-handler
2880 (and (eq inhibit-file-name-operation operation)
2881 inhibit-file-name-handlers)))
2882 (inhibit-file-name-operation operation))
2883 (apply operation args)))))
2886 When a handler function decides to call the ordinary Emacs primitive for
2887 the operation at hand, it needs to prevent the primitive from calling
2888 the same handler once again, thus leading to an infinite recursion. The
2889 example above shows how to do this, with the variables
2890 @code{inhibit-file-name-handlers} and
2891 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2892 shown above; the details are crucial for proper behavior in the case of
2893 multiple handlers, and for operations that have two file names that may
2896 @kindex safe-magic (@r{property})
2897 Handlers that don't really do anything special for actual access to the
2898 file---such as the ones that implement completion of host names for
2899 remote file names---should have a non-@code{nil} @code{safe-magic}
2900 property. For instance, Emacs normally ``protects'' directory names
2901 it finds in @code{PATH} from becoming magic, if they look like magic
2902 file names, by prefixing them with @samp{/:}. But if the handler that
2903 would be used for them has a non-@code{nil} @code{safe-magic}
2904 property, the @samp{/:} is not added.
2906 @kindex operations (@r{property})
2907 A file name handler can have an @code{operations} property to
2908 declare which operations it handles in a nontrivial way. If this
2909 property has a non-@code{nil} value, it should be a list of
2910 operations; then only those operations will call the handler. This
2911 avoids inefficiency, but its main purpose is for autoloaded handler
2912 functions, so that they won't be loaded except when they have real
2915 Simply deferring all operations to the usual primitives does not
2916 work. For instance, if the file name handler applies to
2917 @code{file-exists-p}, then it must handle @code{load} itself, because
2918 the usual @code{load} code won't work properly in that case. However,
2919 if the handler uses the @code{operations} property to say it doesn't
2920 handle @code{file-exists-p}, then it need not handle @code{load}
2923 @defvar inhibit-file-name-handlers
2924 This variable holds a list of handlers whose use is presently inhibited
2925 for a certain operation.
2928 @defvar inhibit-file-name-operation
2929 The operation for which certain handlers are presently inhibited.
2932 @defun find-file-name-handler file operation
2933 This function returns the handler function for file name @var{file},
2934 or @code{nil} if there is none. The argument @var{operation} should
2935 be the operation to be performed on the file---the value you will pass
2936 to the handler as its first argument when you call it. If
2937 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2938 not found in the @code{operations} property of the handler, this
2939 function returns @code{nil}.
2942 @defun file-local-copy filename
2943 This function copies file @var{filename} to an ordinary non-magic file
2944 on the local machine, if it isn't on the local machine already. Magic
2945 file names should handle the @code{file-local-copy} operation if they
2946 refer to files on other machines. A magic file name that is used for
2947 other purposes than remote file access should not handle
2948 @code{file-local-copy}; then this function will treat the file as
2951 If @var{filename} is local, whether magic or not, this function does
2952 nothing and returns @code{nil}. Otherwise it returns the file name
2953 of the local copy file.
2956 @defun file-remote-p filename &optional identification connected
2957 This function tests whether @var{filename} is a remote file. If
2958 @var{filename} is local (not remote), the return value is @code{nil}.
2959 If @var{filename} is indeed remote, the return value is a string that
2960 identifies the remote system.
2962 This identifier string can include a host name and a user name, as
2963 well as characters designating the method used to access the remote
2964 system. For example, the remote identifier string for the filename
2965 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
2967 If @code{file-remote-p} returns the same identifier for two different
2968 filenames, that means they are stored on the same file system and can
2969 be accessed locally with respect to each other. This means, for
2970 example, that it is possible to start a remote process accessing both
2971 files at the same time. Implementers of file handlers need to ensure
2972 this principle is valid.
2974 @var{identification} specifies which part of the identifier shall be
2975 returned as string. @var{identification} can be the symbol
2976 @code{method}, @code{user} or @code{host}; any other value is handled
2977 like @code{nil} and means to return the complete identifier string.
2978 In the example above, the remote @code{user} identifier string would
2981 If @var{connected} is non-@code{nil}, this function returns @code{nil}
2982 even if @var{filename} is remote, if Emacs has no network connection
2983 to its host. This is useful when you want to avoid the delay of
2984 making connections when they don't exist.
2987 @defun unhandled-file-name-directory filename
2988 This function returns the name of a directory that is not magic. It
2989 uses the directory part of @var{filename} if that is not magic. For a
2990 magic file name, it invokes the file name handler, which therefore
2991 decides what value to return. If @var{filename} is not accessible
2992 from a local process, then the file name handler should indicate it by
2993 returning @code{nil}.
2995 This is useful for running a subprocess; every subprocess must have a
2996 non-magic directory to serve as its current directory, and this function
2997 is a good way to come up with one.
3000 @defopt remote-file-name-inhibit-cache
3001 The attributes of remote files can be cached for better performance. If
3002 they are changed outside of Emacs's control, the cached values become
3003 invalid, and must be reread.
3005 When this variable is set to @code{nil}, cached values are never
3006 expired. Use this setting with caution, only if you are sure nothing
3007 other than Emacs ever changes the remote files. If it is set to
3008 @code{t}, cached values are never used. This is the safest value, but
3009 could result in performance degradation.
3011 A compromise is to set it to a positive number. This means that
3012 cached values are used for that amount of seconds since they were
3013 cached. If a remote file is checked regularly, it might be a good
3014 idea to let-bind this variable to a value less than the time period
3015 between consecutive checks. For example:
3018 (defun display-time-file-nonempty-p (file)
3019 (let ((remote-file-name-inhibit-cache
3020 (- display-time-interval 5)))
3021 (and (file-exists-p file)
3022 (< 0 (nth 7 (file-attributes
3023 (file-chase-links file)))))))
3027 @node Format Conversion
3028 @section File Format Conversion
3030 @cindex file format conversion
3031 @cindex encoding file formats
3032 @cindex decoding file formats
3033 @cindex text properties in files
3034 @cindex saving text properties
3035 Emacs performs several steps to convert the data in a buffer (text,
3036 text properties, and possibly other information) to and from a
3037 representation suitable for storing into a file. This section describes
3038 the fundamental functions that perform this @dfn{format conversion},
3039 namely @code{insert-file-contents} for reading a file into a buffer,
3040 and @code{write-region} for writing a buffer into a file.
3043 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}.
3044 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
3045 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
3048 @node Format Conversion Overview
3049 @subsection Overview
3051 The function @code{insert-file-contents}:
3054 @item initially, inserts bytes from the file into the buffer;
3055 @item decodes bytes to characters as appropriate;
3056 @item processes formats as defined by entries in @code{format-alist}; and
3057 @item calls functions in @code{after-insert-file-functions}.
3061 The function @code{write-region}:
3064 @item initially, calls functions in @code{write-region-annotate-functions};
3065 @item processes formats as defined by entries in @code{format-alist};
3066 @item encodes characters to bytes as appropriate; and
3067 @item modifies the file with the bytes.
3070 This shows the symmetry of the lowest-level operations; reading and
3071 writing handle things in opposite order. The rest of this section
3072 describes the two facilities surrounding the three variables named
3073 above, as well as some related functions. @ref{Coding Systems}, for
3074 details on character encoding and decoding.
3076 @node Format Conversion Round-Trip
3077 @subsection Round-Trip Specification
3079 The most general of the two facilities is controlled by the variable
3080 @code{format-alist}, a list of @dfn{file format} specifications, which
3081 describe textual representations used in files for the data in an Emacs
3082 buffer. The descriptions for reading and writing are paired, which is
3083 why we call this ``round-trip'' specification
3084 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
3086 @defvar format-alist
3087 This list contains one format definition for each defined file format.
3088 Each format definition is a list of this form:
3091 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
3095 @cindex format definition
3097 Here is what the elements in a format definition mean:
3101 The name of this format.
3104 A documentation string for the format.
3107 A regular expression which is used to recognize files represented in
3108 this format. If @code{nil}, the format is never applied automatically.
3111 A shell command or function to decode data in this format (to convert
3112 file data into the usual Emacs data representation).
3114 A shell command is represented as a string; Emacs runs the command as a
3115 filter to perform the conversion.
3117 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
3118 and @var{end}, which specify the part of the buffer it should convert.
3119 It should convert the text by editing it in place. Since this can
3120 change the length of the text, @var{from-fn} should return the modified
3123 One responsibility of @var{from-fn} is to make sure that the beginning
3124 of the file no longer matches @var{regexp}. Otherwise it is likely to
3128 A shell command or function to encode data in this format---that is, to
3129 convert the usual Emacs data representation into this format.
3131 If @var{to-fn} is a string, it is a shell command; Emacs runs the
3132 command as a filter to perform the conversion.
3134 If @var{to-fn} is a function, it is called with three arguments:
3135 @var{begin} and @var{end}, which specify the part of the buffer it
3136 should convert, and @var{buffer}, which specifies which buffer. There
3137 are two ways it can do the conversion:
3141 By editing the buffer in place. In this case, @var{to-fn} should
3142 return the end-position of the range of text, as modified.
3145 By returning a list of annotations. This is a list of elements of the
3146 form @code{(@var{position} . @var{string})}, where @var{position} is an
3147 integer specifying the relative position in the text to be written, and
3148 @var{string} is the annotation to add there. The list must be sorted in
3149 order of position when @var{to-fn} returns it.
3151 When @code{write-region} actually writes the text from the buffer to the
3152 file, it intermixes the specified annotations at the corresponding
3153 positions. All this takes place without modifying the buffer.
3157 A flag, @code{t} if the encoding function modifies the buffer, and
3158 @code{nil} if it works by returning a list of annotations.
3161 A minor-mode function to call after visiting a file converted from this
3162 format. The function is called with one argument, the integer 1;
3163 that tells a minor-mode function to enable the mode.
3166 A flag, @code{t} if @code{format-write-file} should not remove this format
3167 from @code{buffer-file-format}.
3170 The function @code{insert-file-contents} automatically recognizes file
3171 formats when it reads the specified file. It checks the text of the
3172 beginning of the file against the regular expressions of the format
3173 definitions, and if it finds a match, it calls the decoding function for
3174 that format. Then it checks all the known formats over again.
3175 It keeps checking them until none of them is applicable.
3177 Visiting a file, with @code{find-file-noselect} or the commands that use
3178 it, performs conversion likewise (because it calls
3179 @code{insert-file-contents}); it also calls the mode function for each
3180 format that it decodes. It stores a list of the format names in the
3181 buffer-local variable @code{buffer-file-format}.
3183 @defvar buffer-file-format
3184 This variable states the format of the visited file. More precisely,
3185 this is a list of the file format names that were decoded in the course
3186 of visiting the current buffer's file. It is always buffer-local in all
3190 When @code{write-region} writes data into a file, it first calls the
3191 encoding functions for the formats listed in @code{buffer-file-format},
3192 in the order of appearance in the list.
3194 @deffn Command format-write-file file format &optional confirm
3195 This command writes the current buffer contents into the file @var{file}
3196 in a format based on @var{format}, which is a list of format names. It
3197 constructs the actual format starting from @var{format}, then appending
3198 any elements from the value of @code{buffer-file-format} with a
3199 non-@code{nil} @var{preserve} flag (see above), if they are not already
3200 present in @var{format}. It then updates @code{buffer-file-format} with
3201 this format, making it the default for future saves. Except for the
3202 @var{format} argument, this command is similar to @code{write-file}. In
3203 particular, @var{confirm} has the same meaning and interactive treatment
3204 as the corresponding argument to @code{write-file}. @xref{Definition of
3208 @deffn Command format-find-file file format
3209 This command finds the file @var{file}, converting it according to
3210 format @var{format}. It also makes @var{format} the default if the
3211 buffer is saved later.
3213 The argument @var{format} is a list of format names. If @var{format} is
3214 @code{nil}, no conversion takes place. Interactively, typing just
3215 @key{RET} for @var{format} specifies @code{nil}.
3218 @deffn Command format-insert-file file format &optional beg end
3219 This command inserts the contents of file @var{file}, converting it
3220 according to format @var{format}. If @var{beg} and @var{end} are
3221 non-@code{nil}, they specify which part of the file to read, as in
3222 @code{insert-file-contents} (@pxref{Reading from Files}).
3224 The return value is like what @code{insert-file-contents} returns: a
3225 list of the absolute file name and the length of the data inserted
3228 The argument @var{format} is a list of format names. If @var{format} is
3229 @code{nil}, no conversion takes place. Interactively, typing just
3230 @key{RET} for @var{format} specifies @code{nil}.
3233 @defvar buffer-auto-save-file-format
3234 This variable specifies the format to use for auto-saving. Its value is
3235 a list of format names, just like the value of
3236 @code{buffer-file-format}; however, it is used instead of
3237 @code{buffer-file-format} for writing auto-save files. If the value
3238 is @code{t}, the default, auto-saving uses the same format as a
3239 regular save in the same buffer. This variable is always buffer-local
3243 @node Format Conversion Piecemeal
3244 @subsection Piecemeal Specification
3246 In contrast to the round-trip specification described in the previous
3247 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
3248 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
3249 to separately control the respective reading and writing conversions.
3251 Conversion starts with one representation and produces another
3252 representation. When there is only one conversion to do, there is no
3253 conflict about what to start with. However, when there are multiple
3254 conversions involved, conflict may arise when two conversions need to
3255 start with the same data.
3257 This situation is best understood in the context of converting text
3258 properties during @code{write-region}. For example, the character at
3259 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
3260 the conversion for @code{foo} is done by inserting into the buffer, say,
3261 @samp{FOO:}, then that changes the character at position 42 from
3262 @samp{X} to @samp{F}. The next conversion will start with the wrong
3265 To avoid conflict, cooperative conversions do not modify the buffer,
3266 but instead specify @dfn{annotations}, a list of elements of the form
3267 @code{(@var{position} . @var{string})}, sorted in order of increasing
3270 If there is more than one conversion, @code{write-region} merges their
3271 annotations destructively into one sorted list. Later, when the text
3272 from the buffer is actually written to the file, it intermixes the
3273 specified annotations at the corresponding positions. All this takes
3274 place without modifying the buffer.
3276 @c ??? What about ``overriding'' conversions like those allowed
3277 @c ??? for `write-region-annotate-functions', below? --ttn
3279 In contrast, when reading, the annotations intermixed with the text
3280 are handled immediately. @code{insert-file-contents} sets point to
3281 the beginning of some text to be converted, then calls the conversion
3282 functions with the length of that text. These functions should always
3283 return with point at the beginning of the inserted text. This
3284 approach makes sense for reading because annotations removed by the
3285 first converter can't be mistakenly processed by a later converter.
3286 Each conversion function should scan for the annotations it
3287 recognizes, remove the annotation, modify the buffer text (to set a
3288 text property, for example), and return the updated length of the
3289 text, as it stands after those changes. The value returned by one
3290 function becomes the argument to the next function.
3292 @defvar write-region-annotate-functions
3293 A list of functions for @code{write-region} to call. Each function in
3294 the list is called with two arguments: the start and end of the region
3295 to be written. These functions should not alter the contents of the
3296 buffer. Instead, they should return annotations.
3298 As a special case, a function may return with a different buffer
3299 current. Emacs takes this to mean that the current buffer contains
3300 altered text to be output. It therefore changes the @var{start} and
3301 @var{end} arguments of the @code{write-region} call, giving them the
3302 values of @code{point-min} and @code{point-max} in the new buffer,
3303 respectively. It also discards all previous annotations, because they
3304 should have been dealt with by this function.
3307 @defvar write-region-post-annotation-function
3308 The value of this variable, if non-@code{nil}, should be a function.
3309 This function is called, with no arguments, after @code{write-region}
3312 If any function in @code{write-region-annotate-functions} returns with
3313 a different buffer current, Emacs calls
3314 @code{write-region-post-annotation-function} more than once. Emacs
3315 calls it with the last buffer that was current, and again with the
3316 buffer before that, and so on back to the original buffer.
3318 Thus, a function in @code{write-region-annotate-functions} can create
3319 a buffer, give this variable the local value of @code{kill-buffer} in
3320 that buffer, set up the buffer with altered text, and make the buffer
3321 current. The buffer will be killed after @code{write-region} is done.
3324 @defvar after-insert-file-functions
3325 Each function in this list is called by @code{insert-file-contents}
3326 with one argument, the number of characters inserted, and with point
3327 at the beginning of the inserted text. Each function should leave
3328 point unchanged, and return the new character count describing the
3329 inserted text as modified by the function.
3330 @c ??? The docstring mentions a handler from `file-name-handler-alist'
3331 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
3334 We invite users to write Lisp programs to store and retrieve text
3335 properties in files, using these hooks, and thus to experiment with
3336 various data formats and find good ones. Eventually we hope users
3337 will produce good, general extensions we can install in Emacs.
3339 We suggest not trying to handle arbitrary Lisp objects as text property
3340 names or values---because a program that general is probably difficult
3341 to write, and slow. Instead, choose a set of possible data types that
3342 are reasonably flexible, and not too hard to encode.