2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/files
7 @node Files, Backups and Auto-Saving, Documentation, Top
8 @comment node-name, next, previous, up
11 This chapter describes the Emacs Lisp functions and variables to
12 find, create, view, save, and otherwise work with files and file
13 directories. A few other file-related functions are described in
14 @ref{Buffers}, and those related to backups and auto-saving are
15 described in @ref{Backups and Auto-Saving}.
17 Many of the file functions take one or more arguments that are file
18 names. A file name is actually a string. Most of these functions
19 expand file name arguments by calling @code{expand-file-name}, so that
20 @file{~} is handled correctly, as are relative file names (including
21 @samp{../}). @xref{File Name Expansion}.
23 In addition, certain @dfn{magic} file names are handled specially.
24 For example, when a remote file name is specified, Emacs accesses the
25 file over the network via an appropriate protocol (@pxref{Remote
26 Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is
27 done at a very low level, so you may assume that all the functions
28 described in this chapter accept magic file names as file name
29 arguments, except where noted. @xref{Magic File Names}, for details.
31 When file I/O functions signal Lisp errors, they usually use the
32 condition @code{file-error} (@pxref{Handling Errors}). The error
33 message is in most cases obtained from the operating system, according
34 to locale @code{system-message-locale}, and decoded using coding system
35 @code{locale-coding-system} (@pxref{Locales}).
38 * Visiting Files:: Reading files into Emacs buffers for editing.
39 * Saving Buffers:: Writing changed buffers back into files.
40 * Reading from Files:: Reading files into buffers without visiting.
41 * Writing to Files:: Writing new files from parts of buffers.
42 * File Locks:: Locking and unlocking files, to prevent
43 simultaneous editing by two people.
44 * Information about Files:: Testing existence, accessibility, size of files.
45 * Changing Files:: Renaming files, changing permissions, etc.
46 * File Names:: Decomposing and expanding file names.
47 * Contents of Directories:: Getting a list of the files in a directory.
48 * Create/Delete Dirs:: Creating and Deleting Directories.
49 * Magic File Names:: Special handling for certain file names.
50 * Format Conversion:: Conversion to and from various file formats.
54 @section Visiting Files
56 @cindex visiting files
58 Visiting a file means reading a file into a buffer. Once this is
59 done, we say that the buffer is @dfn{visiting} that file, and call the
60 file ``the visited file'' of the buffer.
62 A file and a buffer are two different things. A file is information
63 recorded permanently in the computer (unless you delete it). A buffer,
64 on the other hand, is information inside of Emacs that will vanish at
65 the end of the editing session (or when you kill the buffer). Usually,
66 a buffer contains information that you have copied from a file; then we
67 say the buffer is visiting that file. The copy in the buffer is what
68 you modify with editing commands. Such changes to the buffer do not
69 change the file; therefore, to make the changes permanent, you must
70 @dfn{save} the buffer, which means copying the altered buffer contents
73 In spite of the distinction between files and buffers, people often
74 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
75 ``I am editing a file,'' rather than, ``I am editing a buffer that I
76 will soon save as a file of the same name.'' Humans do not usually need
77 to make the distinction explicit. When dealing with a computer program,
78 however, it is good to keep the distinction in mind.
81 * Visiting Functions:: The usual interface functions for visiting.
82 * Subroutines of Visiting:: Lower-level subroutines that they use.
85 @node Visiting Functions
86 @subsection Functions for Visiting Files
88 This section describes the functions normally used to visit files.
89 For historical reasons, these functions have names starting with
90 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
91 functions and variables that access the visited file name of a buffer or
92 that find an existing buffer by its visited file name.
94 In a Lisp program, if you want to look at the contents of a file but
95 not alter it, the fastest way is to use @code{insert-file-contents} in a
96 temporary buffer. Visiting the file is not necessary and takes longer.
97 @xref{Reading from Files}.
99 @deffn Command find-file filename &optional wildcards
100 This command selects a buffer visiting the file @var{filename},
101 using an existing buffer if there is one, and otherwise creating a
102 new buffer and reading the file into it. It also returns that buffer.
104 Aside from some technical details, the body of the @code{find-file}
105 function is basically equivalent to:
108 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
112 (See @code{switch-to-buffer} in @ref{Switching Buffers}.)
114 If @var{wildcards} is non-@code{nil}, which is always true in an
115 interactive call, then @code{find-file} expands wildcard characters in
116 @var{filename} and visits all the matching files.
118 When @code{find-file} is called interactively, it prompts for
119 @var{filename} in the minibuffer.
122 @deffn Command find-file-literally filename
123 This command visits @var{filename}, like @code{find-file} does, but it
124 does not perform any format conversions (@pxref{Format Conversion}),
125 character code conversions (@pxref{Coding Systems}), or end-of-line
126 conversions (@pxref{Coding System Basics, End of line conversion}).
127 The buffer visiting the file is made unibyte, and its major mode is
128 Fundamental mode, regardless of the file name. File local variable
129 specifications in the file (@pxref{File Local Variables}) are
130 ignored, and automatic decompression and adding a newline at the end
131 of the file due to @code{require-final-newline} (@pxref{Saving
132 Buffers, require-final-newline}) are also disabled.
134 Note that if Emacs already has a buffer visiting the same file
135 non-literally, it will not visit the same file literally, but instead
136 just switch to the existing buffer. If you want to be sure of
137 accessing a file's contents literally, you should create a temporary
138 buffer and then read the file contents into it using
139 @code{insert-file-contents-literally} (@pxref{Reading from Files}).
142 @defun find-file-noselect filename &optional nowarn rawfile wildcards
143 This function is the guts of all the file-visiting functions. It
144 returns a buffer visiting the file @var{filename}. You may make the
145 buffer current or display it in a window if you wish, but this
146 function does not do so.
148 The function returns an existing buffer if there is one; otherwise it
149 creates a new buffer and reads the file into it. When
150 @code{find-file-noselect} uses an existing buffer, it first verifies
151 that the file has not changed since it was last visited or saved in
152 that buffer. If the file has changed, this function asks the user
153 whether to reread the changed file. If the user says @samp{yes}, any
154 edits previously made in the buffer are lost.
156 Reading the file involves decoding the file's contents (@pxref{Coding
157 Systems}), including end-of-line conversion, and format conversion
158 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
159 then @code{find-file-noselect} expands wildcard characters in
160 @var{filename} and visits all the matching files.
162 This function displays warning or advisory messages in various peculiar
163 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
164 example, if it needs to create a buffer, and there is no file named
165 @var{filename}, it displays the message @samp{(New file)} in the echo
166 area, and leaves the buffer empty.
168 The @code{find-file-noselect} function normally calls
169 @code{after-find-file} after reading the file (@pxref{Subroutines of
170 Visiting}). That function sets the buffer major mode, parses local
171 variables, warns the user if there exists an auto-save file more recent
172 than the file just visited, and finishes by running the functions in
173 @code{find-file-hook}.
175 If the optional argument @var{rawfile} is non-@code{nil}, then
176 @code{after-find-file} is not called, and the
177 @code{find-file-not-found-functions} are not run in case of failure.
178 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
179 system conversion and format conversion.
181 The @code{find-file-noselect} function usually returns the buffer that
182 is visiting the file @var{filename}. But, if wildcards are actually
183 used and expanded, it returns a list of buffers that are visiting the
188 (find-file-noselect "/etc/fstab")
189 @result{} #<buffer fstab>
194 @deffn Command find-file-other-window filename &optional wildcards
195 This command selects a buffer visiting the file @var{filename}, but
196 does so in a window other than the selected window. It may use
197 another existing window or split a window; see @ref{Switching
200 When this command is called interactively, it prompts for
204 @deffn Command find-file-read-only filename &optional wildcards
205 This command selects a buffer visiting the file @var{filename}, like
206 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
207 Buffers}, for related functions and variables.
209 When this command is called interactively, it prompts for
213 @defopt find-file-wildcards
214 If this variable is non-@code{nil}, then the various @code{find-file}
215 commands check for wildcard characters and visit all the files that
216 match them (when invoked interactively or when their @var{wildcards}
217 argument is non-@code{nil}). If this option is @code{nil}, then
218 the @code{find-file} commands ignore their @var{wildcards} argument
219 and never treat wildcard characters specially.
222 @defopt find-file-hook
223 The value of this variable is a list of functions to be called after a
224 file is visited. The file's local-variables specification (if any) will
225 have been processed before the hooks are run. The buffer visiting the
226 file is current when the hook functions are run.
228 This variable is a normal hook. @xref{Hooks}.
231 @defvar find-file-not-found-functions
232 The value of this variable is a list of functions to be called when
233 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
234 file name. @code{find-file-noselect} calls these functions as soon as
235 it detects a nonexistent file. It calls them in the order of the list,
236 until one of them returns non-@code{nil}. @code{buffer-file-name} is
239 This is not a normal hook because the values of the functions are
240 used, and in many cases only some of the functions are called.
243 @defvar find-file-literally
244 This buffer-local variable, if set to a non-@code{nil} value, makes
245 @code{save-buffer} behave as if the buffer were visiting its file
246 literally, i.e. without conversions of any kind. The command
247 @code{find-file-literally} sets this variable's local value, but other
248 equivalent functions and commands can do that as well, e.g.@: to avoid
249 automatic addition of a newline at the end of the file. This variable
250 is permanent local, so it is unaffected by changes of major modes.
253 @node Subroutines of Visiting
254 @comment node-name, next, previous, up
255 @subsection Subroutines of Visiting
257 The @code{find-file-noselect} function uses two important subroutines
258 which are sometimes useful in user Lisp code: @code{create-file-buffer}
259 and @code{after-find-file}. This section explains how to use them.
261 @defun create-file-buffer filename
262 This function creates a suitably named buffer for visiting
263 @var{filename}, and returns it. It uses @var{filename} (sans directory)
264 as the name if that name is free; otherwise, it appends a string such as
265 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
267 @strong{Please note:} @code{create-file-buffer} does @emph{not}
268 associate the new buffer with a file and does not select the buffer.
269 It also does not use the default major mode.
273 (create-file-buffer "foo")
274 @result{} #<buffer foo>
277 (create-file-buffer "foo")
278 @result{} #<buffer foo<2>>
281 (create-file-buffer "foo")
282 @result{} #<buffer foo<3>>
286 This function is used by @code{find-file-noselect}.
287 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
290 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
291 This function sets the buffer major mode, and parses local variables
292 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
293 and by the default revert function (@pxref{Reverting}).
295 @cindex new file message
296 @cindex file open error
297 If reading the file got an error because the file does not exist, but
298 its directory does exist, the caller should pass a non-@code{nil} value
299 for @var{error}. In that case, @code{after-find-file} issues a warning:
300 @samp{(New file)}. For more serious errors, the caller should usually not
301 call @code{after-find-file}.
303 If @var{warn} is non-@code{nil}, then this function issues a warning
304 if an auto-save file exists and is more recent than the visited file.
306 If @var{noauto} is non-@code{nil}, that says not to enable or disable
307 Auto-Save mode. The mode remains enabled if it was enabled before.
309 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
310 means this call was from @code{revert-buffer}. This has no direct
311 effect, but some mode functions and hook functions check the value
314 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
315 major mode, don't process local variables specifications in the file,
316 and don't run @code{find-file-hook}. This feature is used by
317 @code{revert-buffer} in some cases.
319 The last thing @code{after-find-file} does is call all the functions
320 in the list @code{find-file-hook}.
324 @section Saving Buffers
325 @cindex saving buffers
327 When you edit a file in Emacs, you are actually working on a buffer
328 that is visiting that file---that is, the contents of the file are
329 copied into the buffer and the copy is what you edit. Changes to the
330 buffer do not change the file until you @dfn{save} the buffer, which
331 means copying the contents of the buffer into the file.
333 @deffn Command save-buffer &optional backup-option
334 This function saves the contents of the current buffer in its visited
335 file if the buffer has been modified since it was last visited or saved.
336 Otherwise it does nothing.
338 @code{save-buffer} is responsible for making backup files. Normally,
339 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
340 file only if this is the first save since visiting the file. Other
341 values for @var{backup-option} request the making of backup files in
346 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
347 @code{save-buffer} function marks this version of the file to be
348 backed up when the buffer is next saved.
351 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
352 @code{save-buffer} function unconditionally backs up the previous
353 version of the file before saving it.
356 With an argument of 0, unconditionally do @emph{not} make any backup file.
360 @deffn Command save-some-buffers &optional save-silently-p pred
361 @anchor{Definition of save-some-buffers}
362 This command saves some modified file-visiting buffers. Normally it
363 asks the user about each buffer. But if @var{save-silently-p} is
364 non-@code{nil}, it saves all the file-visiting buffers without querying
367 The optional @var{pred} argument controls which buffers to ask about
368 (or to save silently if @var{save-silently-p} is non-@code{nil}).
369 If it is @code{nil}, that means to ask only about file-visiting buffers.
370 If it is @code{t}, that means also offer to save certain other non-file
371 buffers---those that have a non-@code{nil} buffer-local value of
372 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
373 @samp{yes} to saving a non-file buffer is asked to specify the file
374 name to use. The @code{save-buffers-kill-emacs} function passes the
375 value @code{t} for @var{pred}.
377 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
378 a function of no arguments. It will be called in each buffer to decide
379 whether to offer to save that buffer. If it returns a non-@code{nil}
380 value in a certain buffer, that means do offer to save that buffer.
383 @deffn Command write-file filename &optional confirm
384 @anchor{Definition of write-file}
385 This function writes the current buffer into file @var{filename}, makes
386 the buffer visit that file, and marks it not modified. Then it renames
387 the buffer based on @var{filename}, appending a string like @samp{<2>}
388 if necessary to make a unique buffer name. It does most of this work by
389 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
392 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
393 before overwriting an existing file. Interactively, confirmation is
394 required, unless the user supplies a prefix argument.
396 If @var{filename} is an existing directory, or a symbolic link to one,
397 @code{write-file} uses the name of the visited file, in directory
398 @var{filename}. If the buffer is not visiting a file, it uses the
402 Saving a buffer runs several hooks. It also performs format
403 conversion (@pxref{Format Conversion}).
405 @defvar write-file-functions
406 The value of this variable is a list of functions to be called before
407 writing out a buffer to its visited file. If one of them returns
408 non-@code{nil}, the file is considered already written and the rest of
409 the functions are not called, nor is the usual code for writing the file
412 If a function in @code{write-file-functions} returns non-@code{nil}, it
413 is responsible for making a backup file (if that is appropriate).
414 To do so, execute the following code:
417 (or buffer-backed-up (backup-buffer))
420 You might wish to save the file modes value returned by
421 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
422 bits of the file that you write. This is what @code{save-buffer}
423 normally does. @xref{Making Backups,, Making Backup Files}.
425 The hook functions in @code{write-file-functions} are also responsible
426 for encoding the data (if desired): they must choose a suitable coding
427 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
428 perform the encoding (@pxref{Explicit Encoding}), and set
429 @code{last-coding-system-used} to the coding system that was used
430 (@pxref{Encoding and I/O}).
432 If you set this hook locally in a buffer, it is assumed to be
433 associated with the file or the way the contents of the buffer were
434 obtained. Thus the variable is marked as a permanent local, so that
435 changing the major mode does not alter a buffer-local value. On the
436 other hand, calling @code{set-visited-file-name} will reset it.
437 If this is not what you want, you might like to use
438 @code{write-contents-functions} instead.
440 Even though this is not a normal hook, you can use @code{add-hook} and
441 @code{remove-hook} to manipulate the list. @xref{Hooks}.
445 @defvar write-contents-functions
446 This works just like @code{write-file-functions}, but it is intended
447 for hooks that pertain to the buffer's contents, not to the particular
448 visited file or its location. Such hooks are usually set up by major
449 modes, as buffer-local bindings for this variable. This variable
450 automatically becomes buffer-local whenever it is set; switching to a
451 new major mode always resets this variable, but calling
452 @code{set-visited-file-name} does not.
454 If any of the functions in this hook returns non-@code{nil}, the file
455 is considered already written and the rest are not called and neither
456 are the functions in @code{write-file-functions}.
459 @defopt before-save-hook
460 This normal hook runs before a buffer is saved in its visited file,
461 regardless of whether that is done normally or by one of the hooks
462 described above. For instance, the @file{copyright.el} program uses
463 this hook to make sure the file you are saving has the current year in
464 its copyright notice.
468 @defopt after-save-hook
469 This normal hook runs after a buffer has been saved in its visited file.
470 One use of this hook is in Fast Lock mode; it uses this hook to save the
471 highlighting information in a cache file.
474 @defopt file-precious-flag
475 If this variable is non-@code{nil}, then @code{save-buffer} protects
476 against I/O errors while saving by writing the new file to a temporary
477 name instead of the name it is supposed to have, and then renaming it to
478 the intended name after it is clear there are no errors. This procedure
479 prevents problems such as a lack of disk space from resulting in an
482 As a side effect, backups are necessarily made by copying. @xref{Rename
483 or Copy}. Yet, at the same time, saving a precious file always breaks
484 all hard links between the file you save and other file names.
486 Some modes give this variable a non-@code{nil} buffer-local value
487 in particular buffers.
490 @defopt require-final-newline
491 This variable determines whether files may be written out that do
492 @emph{not} end with a newline. If the value of the variable is
493 @code{t}, then @code{save-buffer} silently adds a newline at the end of
494 the file whenever the buffer being saved does not already end in one.
495 If the value of the variable is non-@code{nil}, but not @code{t}, then
496 @code{save-buffer} asks the user whether to add a newline each time the
499 If the value of the variable is @code{nil}, then @code{save-buffer}
500 doesn't add newlines at all. @code{nil} is the default value, but a few
501 major modes set it to @code{t} in particular buffers.
504 See also the function @code{set-visited-file-name} (@pxref{Buffer File
507 @node Reading from Files
508 @comment node-name, next, previous, up
509 @section Reading from Files
510 @cindex reading from files
512 You can copy a file from the disk and insert it into a buffer
513 using the @code{insert-file-contents} function. Don't use the user-level
514 command @code{insert-file} in a Lisp program, as that sets the mark.
516 @defun insert-file-contents filename &optional visit beg end replace
517 This function inserts the contents of file @var{filename} into the
518 current buffer after point. It returns a list of the absolute file name
519 and the length of the data inserted. An error is signaled if
520 @var{filename} is not the name of a file that can be read.
522 This function checks the file contents against the defined file
523 formats, and converts the file contents if appropriate and also calls
524 the functions in the list @code{after-insert-file-functions}.
525 @xref{Format Conversion}. Normally, one of the functions in the
526 @code{after-insert-file-functions} list determines the coding system
527 (@pxref{Coding Systems}) used for decoding the file's contents,
528 including end-of-line conversion. However, if the file contains null
529 bytes, it is by default visited without any code conversions.
530 @xref{Lisp and Coding Systems, inhibit-null-byte-detection}.
532 If @var{visit} is non-@code{nil}, this function additionally marks the
533 buffer as unmodified and sets up various fields in the buffer so that it
534 is visiting the file @var{filename}: these include the buffer's visited
535 file name and its last save file modtime. This feature is used by
536 @code{find-file-noselect} and you probably should not use it yourself.
538 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
539 specifying the portion of the file to insert. In this case, @var{visit}
540 must be @code{nil}. For example,
543 (insert-file-contents filename nil 0 500)
547 inserts the first 500 characters of a file.
549 If the argument @var{replace} is non-@code{nil}, it means to replace the
550 contents of the buffer (actually, just the accessible portion) with the
551 contents of the file. This is better than simply deleting the buffer
552 contents and inserting the whole file, because (1) it preserves some
553 marker positions and (2) it puts less data in the undo list.
555 It is possible to read a special file (such as a FIFO or an I/O device)
556 with @code{insert-file-contents}, as long as @var{replace} and
557 @var{visit} are @code{nil}.
560 @defun insert-file-contents-literally filename &optional visit beg end replace
561 This function works like @code{insert-file-contents} except that it
562 does not run @code{find-file-hook}, and does not do format decoding,
563 character code conversion, automatic uncompression, and so on.
566 If you want to pass a file name to another process so that another
567 program can read the file, use the function @code{file-local-copy}; see
568 @ref{Magic File Names}.
570 @node Writing to Files
571 @comment node-name, next, previous, up
572 @section Writing to Files
573 @cindex writing to files
575 You can write the contents of a buffer, or part of a buffer, directly
576 to a file on disk using the @code{append-to-file} and
577 @code{write-region} functions. Don't use these functions to write to
578 files that are being visited; that could cause confusion in the
579 mechanisms for visiting.
581 @deffn Command append-to-file start end filename
582 This function appends the contents of the region delimited by
583 @var{start} and @var{end} in the current buffer to the end of file
584 @var{filename}. If that file does not exist, it is created. This
585 function returns @code{nil}.
587 An error is signaled if @var{filename} specifies a nonwritable file,
588 or a nonexistent file in a directory where files cannot be created.
590 When called from Lisp, this function is completely equivalent to:
593 (write-region start end filename t)
597 @deffn Command write-region start end filename &optional append visit lockname mustbenew
598 This function writes the region delimited by @var{start} and @var{end}
599 in the current buffer into the file specified by @var{filename}.
601 If @var{start} is @code{nil}, then the command writes the entire buffer
602 contents (@emph{not} just the accessible portion) to the file and
606 If @var{start} is a string, then @code{write-region} writes or appends
607 that string, rather than text from the buffer. @var{end} is ignored in
610 If @var{append} is non-@code{nil}, then the specified text is appended
611 to the existing file contents (if any). If @var{append} is an
612 integer, @code{write-region} seeks to that byte offset from the start
613 of the file and writes the data from there.
615 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
616 for confirmation if @var{filename} names an existing file. If
617 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
618 does not ask for confirmation, but instead it signals an error
619 @code{file-already-exists} if the file already exists.
621 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
622 a special system feature. At least for files on a local disk, there is
623 no chance that some other program could create a file of the same name
624 before Emacs does, without Emacs's noticing.
626 If @var{visit} is @code{t}, then Emacs establishes an association
627 between the buffer and the file: the buffer is then visiting that file.
628 It also sets the last file modification time for the current buffer to
629 @var{filename}'s modtime, and marks the buffer as not modified. This
630 feature is used by @code{save-buffer}, but you probably should not use
634 If @var{visit} is a string, it specifies the file name to visit. This
635 way, you can write the data to one file (@var{filename}) while recording
636 the buffer as visiting another file (@var{visit}). The argument
637 @var{visit} is used in the echo area message and also for file locking;
638 @var{visit} is stored in @code{buffer-file-name}. This feature is used
639 to implement @code{file-precious-flag}; don't use it yourself unless you
640 really know what you're doing.
642 The optional argument @var{lockname}, if non-@code{nil}, specifies the
643 file name to use for purposes of locking and unlocking, overriding
644 @var{filename} and @var{visit} for that purpose.
646 The function @code{write-region} converts the data which it writes to
647 the appropriate file formats specified by @code{buffer-file-format}
648 and also calls the functions in the list
649 @code{write-region-annotate-functions}.
650 @xref{Format Conversion}.
652 Normally, @code{write-region} displays the message @samp{Wrote
653 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
654 nor @code{nil} nor a string, then this message is inhibited. This
655 feature is useful for programs that use files for internal purposes,
656 files that the user does not need to know about.
659 @defmac with-temp-file file body@dots{}
660 @anchor{Definition of with-temp-file}
661 The @code{with-temp-file} macro evaluates the @var{body} forms with a
662 temporary buffer as the current buffer; then, at the end, it writes the
663 buffer contents into file @var{file}. It kills the temporary buffer
664 when finished, restoring the buffer that was current before the
665 @code{with-temp-file} form. Then it returns the value of the last form
668 The current buffer is restored even in case of an abnormal exit via
669 @code{throw} or error (@pxref{Nonlocal Exits}).
671 See also @code{with-temp-buffer} in @ref{Definition of
672 with-temp-buffer,, The Current Buffer}.
680 When two users edit the same file at the same time, they are likely
681 to interfere with each other. Emacs tries to prevent this situation
682 from arising by recording a @dfn{file lock} when a file is being
683 modified. (File locks are not implemented on Microsoft systems.)
684 Emacs can then detect the first attempt to modify a buffer visiting a
685 file that is locked by another Emacs job, and ask the user what to do.
686 The file lock is really a file, a symbolic link with a special name,
687 stored in the same directory as the file you are editing.
689 When you access files using NFS, there may be a small probability that
690 you and another user will both lock the same file ``simultaneously.''
691 If this happens, it is possible for the two users to make changes
692 simultaneously, but Emacs will still warn the user who saves second.
693 Also, the detection of modification of a buffer visiting a file changed
694 on disk catches some cases of simultaneous editing; see
695 @ref{Modification Time}.
697 @defun file-locked-p filename
698 This function returns @code{nil} if the file @var{filename} is not
699 locked. It returns @code{t} if it is locked by this Emacs process, and
700 it returns the name of the user who has locked it if it is locked by
705 (file-locked-p "foo")
711 @defun lock-buffer &optional filename
712 This function locks the file @var{filename}, if the current buffer is
713 modified. The argument @var{filename} defaults to the current buffer's
714 visited file. Nothing is done if the current buffer is not visiting a
715 file, or is not modified, or if the system does not support locking.
719 This function unlocks the file being visited in the current buffer,
720 if the buffer is modified. If the buffer is not modified, then
721 the file should not be locked, so this function does nothing. It also
722 does nothing if the current buffer is not visiting a file, or if the
723 system does not support locking.
726 File locking is not supported on some systems. On systems that do not
727 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
728 @code{file-locked-p} do nothing and return @code{nil}.
730 @defun ask-user-about-lock file other-user
731 This function is called when the user tries to modify @var{file}, but it
732 is locked by another user named @var{other-user}. The default
733 definition of this function asks the user to say what to do. The value
734 this function returns determines what Emacs does next:
738 A value of @code{t} says to grab the lock on the file. Then
739 this user may edit the file and @var{other-user} loses the lock.
742 A value of @code{nil} says to ignore the lock and let this
743 user edit the file anyway.
747 This function may instead signal a @code{file-locked} error, in which
748 case the change that the user was about to make does not take place.
750 The error message for this error looks like this:
753 @error{} File is locked: @var{file} @var{other-user}
757 where @code{file} is the name of the file and @var{other-user} is the
758 name of the user who has locked the file.
761 If you wish, you can replace the @code{ask-user-about-lock} function
762 with your own version that makes the decision in another way. The code
763 for its usual definition is in @file{userlock.el}.
766 @node Information about Files
767 @section Information about Files
768 @cindex file, information about
770 The functions described in this section all operate on strings that
771 designate file names. With a few exceptions, all the functions have
772 names that begin with the word @samp{file}. These functions all
773 return information about actual files or directories, so their
774 arguments must all exist as actual files or directories unless
778 * Testing Accessibility:: Is a given file readable? Writable?
779 * Kinds of Files:: Is it a directory? A symbolic link?
780 * Truenames:: Eliminating symbolic links from a file name.
781 * File Attributes:: How large is it? Any other names? Etc.
782 * Locating Files:: How to find a file in standard places.
785 @node Testing Accessibility
786 @comment node-name, next, previous, up
787 @subsection Testing Accessibility
788 @cindex accessibility of a file
789 @cindex file accessibility
791 These functions test for permission to access a file in specific
792 ways. Unless explicitly stated otherwise, they recursively follow
793 symbolic links for their file name arguments, at all levels (at the
794 level of the file itself and at all levels of parent directories).
796 @defun file-exists-p filename
797 This function returns @code{t} if a file named @var{filename} appears
798 to exist. This does not mean you can necessarily read the file, only
799 that you can find out its attributes. (On Unix and GNU/Linux, this is
800 true if the file exists and you have execute permission on the
801 containing directories, regardless of the permissions of the file
804 If the file does not exist, or if fascist access control policies
805 prevent you from finding the attributes of the file, this function
808 Directories are files, so @code{file-exists-p} returns @code{t} when
809 given a directory name. However, symbolic links are treated
810 specially; @code{file-exists-p} returns @code{t} for a symbolic link
811 name only if the target file exists.
814 @defun file-readable-p filename
815 This function returns @code{t} if a file named @var{filename} exists
816 and you can read it. It returns @code{nil} otherwise.
820 (file-readable-p "files.texi")
824 (file-exists-p "/usr/spool/mqueue")
828 (file-readable-p "/usr/spool/mqueue")
835 @defun file-executable-p filename
836 This function returns @code{t} if a file named @var{filename} exists and
837 you can execute it. It returns @code{nil} otherwise. On Unix and
838 GNU/Linux, if the file is a directory, execute permission means you can
839 check the existence and attributes of files inside the directory, and
840 open those files if their modes permit.
843 @defun file-writable-p filename
844 This function returns @code{t} if the file @var{filename} can be written
845 or created by you, and @code{nil} otherwise. A file is writable if the
846 file exists and you can write it. It is creatable if it does not exist,
847 but the specified directory does exist and you can write in that
850 In the third example below, @file{foo} is not writable because the
851 parent directory does not exist, even though the user could create such
856 (file-writable-p "~/foo")
860 (file-writable-p "/foo")
864 (file-writable-p "~/no-such-dir/foo")
871 @defun file-accessible-directory-p dirname
872 This function returns @code{t} if you have permission to open existing
873 files in the directory whose name as a file is @var{dirname};
874 otherwise (or if there is no such directory), it returns @code{nil}.
875 The value of @var{dirname} may be either a directory name (such as
876 @file{/foo/}) or the file name of a file which is a directory
877 (such as @file{/foo}, without the final slash).
879 Example: after the following,
882 (file-accessible-directory-p "/foo")
887 we can deduce that any attempt to read a file in @file{/foo/} will
891 @defun access-file filename string
892 This function opens file @var{filename} for reading, then closes it and
893 returns @code{nil}. However, if the open fails, it signals an error
894 using @var{string} as the error message text.
897 @defun file-ownership-preserved-p filename
898 This function returns @code{t} if deleting the file @var{filename} and
899 then creating it anew would keep the file's owner unchanged. It also
900 returns @code{t} for nonexistent files.
902 If @var{filename} is a symbolic link, then, unlike the other functions
903 discussed here, @code{file-ownership-preserved-p} does @emph{not}
904 replace @var{filename} with its target. However, it does recursively
905 follow symbolic links at all levels of parent directories.
908 @defun file-newer-than-file-p filename1 filename2
910 @cindex file modification time
911 This function returns @code{t} if the file @var{filename1} is
912 newer than file @var{filename2}. If @var{filename1} does not
913 exist, it returns @code{nil}. If @var{filename1} does exist, but
914 @var{filename2} does not, it returns @code{t}.
916 In the following example, assume that the file @file{aug-19} was written
917 on the 19th, @file{aug-20} was written on the 20th, and the file
918 @file{no-file} doesn't exist at all.
922 (file-newer-than-file-p "aug-19" "aug-20")
926 (file-newer-than-file-p "aug-20" "aug-19")
930 (file-newer-than-file-p "aug-19" "no-file")
934 (file-newer-than-file-p "no-file" "aug-19")
939 You can use @code{file-attributes} to get a file's last modification
940 time as a list of two numbers. @xref{File Attributes}.
944 @comment node-name, next, previous, up
945 @subsection Distinguishing Kinds of Files
947 This section describes how to distinguish various kinds of files, such
948 as directories, symbolic links, and ordinary files.
950 @defun file-symlink-p filename
951 @cindex file symbolic links
952 If the file @var{filename} is a symbolic link, the
953 @code{file-symlink-p} function returns the (non-recursive) link target
954 as a string. (Determining the file name that the link points to from
955 the target is nontrivial.) First, this function recursively follows
956 symbolic links at all levels of parent directories.
958 If the file @var{filename} is not a symbolic link (or there is no such file),
959 @code{file-symlink-p} returns @code{nil}.
963 (file-symlink-p "foo")
967 (file-symlink-p "sym-link")
971 (file-symlink-p "sym-link2")
975 (file-symlink-p "/bin")
980 @c !!! file-symlink-p: should show output of ls -l for comparison
983 The next two functions recursively follow symbolic links at
984 all levels for @var{filename}.
986 @defun file-directory-p filename
987 This function returns @code{t} if @var{filename} is the name of an
988 existing directory, @code{nil} otherwise.
992 (file-directory-p "~rms")
996 (file-directory-p "~rms/lewis/files.texi")
1000 (file-directory-p "~rms/lewis/no-such-file")
1004 (file-directory-p "$HOME")
1009 (substitute-in-file-name "$HOME"))
1015 @defun file-regular-p filename
1016 This function returns @code{t} if the file @var{filename} exists and is
1017 a regular file (not a directory, named pipe, terminal, or
1022 @subsection Truenames
1023 @cindex truename (of file)
1025 The @dfn{truename} of a file is the name that you get by following
1026 symbolic links at all levels until none remain, then simplifying away
1027 @samp{.}@: and @samp{..}@: appearing as name components. This results
1028 in a sort of canonical name for the file. A file does not always have a
1029 unique truename; the number of distinct truenames a file has is equal to
1030 the number of hard links to the file. However, truenames are useful
1031 because they eliminate symbolic links as a cause of name variation.
1033 @defun file-truename filename
1034 This function returns the truename of the file @var{filename}. If the
1035 argument is not an absolute file name, this function first expands it
1036 against @code{default-directory}.
1038 This function does not expand environment variables. Only
1039 @code{substitute-in-file-name} does that. @xref{Definition of
1040 substitute-in-file-name}.
1042 If you may need to follow symbolic links preceding @samp{..}@:
1043 appearing as a name component, you should make sure to call
1044 @code{file-truename} without prior direct or indirect calls to
1045 @code{expand-file-name}, as otherwise the file name component
1046 immediately preceding @samp{..} will be ``simplified away'' before
1047 @code{file-truename} is called. To eliminate the need for a call to
1048 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1049 same way that @code{expand-file-name} does. @xref{File Name
1050 Expansion,, Functions that Expand Filenames}.
1053 @defun file-chase-links filename &optional limit
1054 This function follows symbolic links, starting with @var{filename},
1055 until it finds a file name which is not the name of a symbolic link.
1056 Then it returns that file name. This function does @emph{not} follow
1057 symbolic links at the level of parent directories.
1059 If you specify a number for @var{limit}, then after chasing through
1060 that many links, the function just returns what it has even if that is
1061 still a symbolic link.
1064 To illustrate the difference between @code{file-chase-links} and
1065 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1066 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1067 ordinary file (or at least, not a symbolic link) or nonexistent. Then
1071 (file-chase-links "/usr/foo/hello")
1072 ;; @r{This does not follow the links in the parent directories.}
1073 @result{} "/usr/foo/hello"
1074 (file-truename "/usr/foo/hello")
1075 ;; @r{Assuming that @file{/home} is not a symbolic link.}
1076 @result{} "/home/foo/hello"
1079 @xref{Buffer File Name}, for related information.
1081 @node File Attributes
1082 @comment node-name, next, previous, up
1083 @subsection Other Information about Files
1085 This section describes the functions for getting detailed
1086 information about a file, other than its contents. This information
1087 includes the mode bits that control access permissions, the owner and
1088 group numbers, the number of names, the inode number, the size, and
1089 the times of access and modification.
1091 @defun file-modes filename
1092 @cindex file permissions
1093 @cindex permissions, file
1094 @cindex file attributes
1096 This function returns the @dfn{mode bits} describing the @dfn{file
1097 permissions} of @var{filename}, as an integer. It recursively follows
1098 symbolic links in @var{filename} at all levels. If @var{filename}
1099 does not exist, the return value is @code{nil}.
1101 @xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
1102 Manual}, for a description of mode bits. If the low-order bit is 1,
1103 then the file is executable by all users, if the second-lowest-order
1104 bit is 1, then the file is writable by all users, etc. The highest
1105 value returnable is 4095 (7777 octal), meaning that everyone has read,
1106 write, and execute permission, that the @acronym{SUID} bit is set for
1107 both others and group, and that the sticky bit is set.
1111 (file-modes "~/junk/diffs")
1112 @result{} 492 ; @r{Decimal integer.}
1116 @result{} "754" ; @r{Convert to octal.}
1120 (set-file-modes "~/junk/diffs" #o666)
1126 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1130 @xref{Changing Files}, for functions that change file permissions,
1131 such as @code{set-file-modes}.
1133 @cindex MS-DOS and file modes
1134 @cindex file modes and MS-DOS
1135 @strong{MS-DOS note:} On MS-DOS, there is no such thing as an
1136 ``executable'' file mode bit. So @code{file-modes} considers a file
1137 executable if its name ends in one of the standard executable
1138 extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
1139 others. Files that begin with the Unix-standard @samp{#!} signature,
1140 such as shell and Perl scripts, are also considered executable.
1141 Directories are also reported as executable, for compatibility with
1142 Unix. These conventions are also followed by @code{file-attributes},
1146 If the @var{filename} argument to the next two functions is a
1147 symbolic link, then these function do @emph{not} replace it with its
1148 target. However, they both recursively follow symbolic links at all
1149 levels of parent directories.
1151 @defun file-nlinks filename
1152 This functions returns the number of names (i.e., hard links) that
1153 file @var{filename} has. If the file does not exist, then this function
1154 returns @code{nil}. Note that symbolic links have no effect on this
1155 function, because they are not considered to be names of the files they
1161 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1162 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1170 (file-nlinks "doesnt-exist")
1176 @defun file-attributes filename &optional id-format
1177 @anchor{Definition of file-attributes}
1178 This function returns a list of attributes of file @var{filename}. If
1179 the specified file cannot be opened, it returns @code{nil}.
1180 The optional parameter @var{id-format} specifies the preferred format
1181 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1182 valid values are @code{'string} and @code{'integer}. The latter is
1183 the default, but we plan to change that, so you should specify a
1184 non-@code{nil} value for @var{id-format} if you use the returned
1185 @acronym{UID} or @acronym{GID}.
1187 The elements of the list, in order, are:
1191 @code{t} for a directory, a string for a symbolic link (the name
1192 linked to), or @code{nil} for a text file.
1194 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
1196 The number of names the file has. Alternate names, also known as hard
1197 links, can be created by using the @code{add-name-to-file} function
1198 (@pxref{Changing Files}).
1201 The file's @acronym{UID}, normally as a string. However, if it does
1202 not correspond to a named user, the value is an integer or a floating
1206 The file's @acronym{GID}, likewise.
1209 The time of last access, as a list of two integers.
1210 The first integer has the high-order 16 bits of time,
1211 the second has the low 16 bits. (This is similar to the
1212 value of @code{current-time}; see @ref{Time of Day}.) Note that on
1213 some FAT-based filesystems, only the date of last access is recorded,
1214 so this time will always hold the midnight of the day of last access.
1216 @cindex modification time of file
1218 The time of last modification as a list of two integers (as above).
1219 This is the last time when the file's contents were modified.
1222 The time of last status change as a list of two integers (as above).
1223 This is the time of the last change to the file's access mode bits,
1224 its owner and group, and other information recorded in the filesystem
1225 for the file, beyond the file's contents.
1228 The size of the file in bytes. If the size is too large to fit in a
1229 Lisp integer, this is a floating point number.
1232 The file's modes, as a string of ten letters or dashes,
1236 @code{t} if the file's @acronym{GID} would change if file were
1237 deleted and recreated; @code{nil} otherwise.
1240 The file's inode number. If possible, this is an integer. If the
1241 inode number is too large to be represented as an integer in Emacs
1242 Lisp but dividing it by @math{2^16} yields a representable integer,
1243 then the value has the
1244 form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
1245 bits. If the inode number is too wide for even that, the value is of the form
1246 @code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
1247 the high bits, @var{middle} the middle 24 bits, and @var{low} the low
1251 The filesystem number of the device that the file is on. Depending on
1252 the magnitude of the value, this can be either an integer or a cons
1253 cell, in the same manner as the inode number. This element and the
1254 file's inode number together give enough information to distinguish
1255 any two files on the system---no two files can have the same values
1256 for both of these numbers.
1259 For example, here are the file attributes for @file{files.texi}:
1263 (file-attributes "files.texi" 'string)
1264 @result{} (nil 1 "lh" "users"
1269 nil (5888 2 . 43978)
1275 and here is how the result is interpreted:
1279 is neither a directory nor a symbolic link.
1282 has only one name (the name @file{files.texi} in the current default
1286 is owned by the user with name "lh".
1289 is in the group with name "users".
1292 was last accessed on Oct 5 2009, at 10:01:37.
1295 last had its contents modified on Oct 2 2009, at 13:49:12.
1298 last had its status changed on Feb 2 2008, at 12:19:00.
1301 is 122295 bytes long. (It may not contain 122295 characters, though,
1302 if some of the bytes belong to multibyte sequences, and also if the
1303 end-of-line format is CR-LF.)
1306 has a mode of read and write access for the owner, group, and world.
1309 would retain the same @acronym{GID} if it were recreated.
1311 @item (5888 2 . 43978)
1312 has an inode number of 6473924464520138.
1314 @item (15479 . 46724)
1315 is on the file-system device whose number is 1014478468.
1319 @cindex SELinux context
1320 SELinux is a Linux kernel feature which provides more sophisticated
1321 file access controls than ordinary ``Unix-style'' file permissions.
1322 If Emacs has been compiled with SELinux support on a system with
1323 SELinux enabled, you can use the function @code{file-selinux-context}
1324 to retrieve a file's SELinux security context. For the function
1325 @code{set-file-selinux-context}, see @ref{Changing Files}.
1327 @defun file-selinux-context filename
1328 This function returns the SELinux security context of the file
1329 @var{filename}. This return value is a list of the form
1330 @code{(@var{user} @var{role} @var{type} @var{range})}, whose elements
1331 are the context's user, role, type, and range respectively, as Lisp
1332 strings. See the SELinux documentation for details about what these
1335 If the file does not exist or is inaccessible, or if the system does
1336 not support SELinux, or if Emacs was not compiled with SELinux
1337 support, then the return value is @code{(nil nil nil nil)}.
1340 @node Locating Files
1341 @subsection How to Locate Files in Standard Places
1342 @cindex locate file in path
1343 @cindex find file in path
1345 This section explains how to search for a file in a list of
1346 directories (a @dfn{path}), or for an executable file in the standard
1347 list of executable file directories, or for an Emacs-specific user
1350 @defun locate-file filename path &optional suffixes predicate
1351 This function searches for a file whose name is @var{filename} in a
1352 list of directories given by @var{path}, trying the suffixes in
1353 @var{suffixes}. If it finds such a file, it returns the file's
1354 absolute file name (@pxref{Relative File Names}); otherwise it returns
1357 The optional argument @var{suffixes} gives the list of file-name
1358 suffixes to append to @var{filename} when searching.
1359 @code{locate-file} tries each possible directory with each of these
1360 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
1361 are no suffixes, and @var{filename} is used only as-is. Typical
1362 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1363 Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and
1364 the return value of the function @code{get-load-suffixes} (@pxref{Load
1367 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1368 Creation}) when looking for executable programs, or @code{load-path}
1369 (@pxref{Library Search}) when looking for Lisp files. If
1370 @var{filename} is absolute, @var{path} has no effect, but the suffixes
1371 in @var{suffixes} are still tried.
1373 The optional argument @var{predicate}, if non-@code{nil}, specifies a
1374 predicate function for testing whether a candidate file is suitable.
1375 The predicate is passed the candidate file name as its single
1376 argument. If @var{predicate} is @code{nil} or omitted,
1377 @code{locate-file} uses @code{file-readable-p} as the predicate.
1378 @xref{Kinds of Files}, for other useful predicates, e.g.@:
1379 @code{file-executable-p} and @code{file-directory-p}.
1381 For compatibility, @var{predicate} can also be one of the symbols
1382 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1383 a list of one or more of these symbols.
1386 @defun executable-find program
1387 This function searches for the executable file of the named
1388 @var{program} and returns the absolute file name of the executable,
1389 including its file-name extensions, if any. It returns @code{nil} if
1390 the file is not found. The functions searches in all the directories
1391 in @code{exec-path}, and tries all the file-name extensions in
1392 @code{exec-suffixes} (@pxref{Subprocess Creation}).
1395 @defun locate-user-emacs-file base-name &optional old-name
1396 This function returns an absolute file name for an Emacs-specific
1397 configuration or data file. The argument @file{base-name} should be a
1398 relative file name. The return value is the absolute name of a file
1399 in the directory specified by @code{user-emacs-directory}; if that
1400 directory does not exist, this function creates it.
1402 If the optional argument @var{old-name} is non-@code{nil}, it
1403 specifies a file in the user's home directory,
1404 @file{~/@var{old-name}}. If such a file exists, the return value is
1405 the absolute name of that file, instead of the file specified by
1406 @var{base-name}. This argument is intended to be used by Emacs
1407 packages to provide backward compatibility. For instance, prior to
1408 the introduction of @code{user-emacs-directory}, the abbrev file was
1409 located in @file{~/.abbrev_defs}, so the definition of
1410 @code{abbrev-file-name} is
1413 (defcustom abbrev-file-name
1414 (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
1415 "Default name of file from which to read abbrevs."
1421 @node Changing Files
1422 @section Changing File Names and Attributes
1423 @c @cindex renaming files Duplicates rename-file
1424 @cindex copying files
1425 @cindex deleting files
1426 @cindex linking files
1427 @cindex setting modes of files
1429 The functions in this section rename, copy, delete, link, and set
1430 the modes (permissions) of files.
1432 In the functions that have an argument @var{newname}, if a file by the
1433 name of @var{newname} already exists, the actions taken depend on the
1434 value of the argument @var{ok-if-already-exists}:
1438 Signal a @code{file-already-exists} error if
1439 @var{ok-if-already-exists} is @code{nil}.
1442 Request confirmation if @var{ok-if-already-exists} is a number.
1445 Replace the old file without confirmation if @var{ok-if-already-exists}
1449 The next four commands all recursively follow symbolic links at all
1450 levels of parent directories for their first argument, but, if that
1451 argument is itself a symbolic link, then only @code{copy-file}
1452 replaces it with its (recursive) target.
1454 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1455 @cindex file with multiple names
1456 @cindex file hard link
1457 This function gives the file named @var{oldname} the additional name
1458 @var{newname}. This means that @var{newname} becomes a new ``hard
1459 link'' to @var{oldname}.
1461 In the first part of the following example, we list two files,
1462 @file{foo} and @file{foo3}.
1467 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1468 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1472 Now we create a hard link, by calling @code{add-name-to-file}, then list
1473 the files again. This shows two names for one file, @file{foo} and
1478 (add-name-to-file "foo" "foo2")
1484 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1485 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1486 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1490 Finally, we evaluate the following:
1493 (add-name-to-file "foo" "foo3" t)
1497 and list the files again. Now there are three names
1498 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1499 contents of @file{foo3} are lost.
1503 (add-name-to-file "foo1" "foo3")
1509 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1510 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1511 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1515 This function is meaningless on operating systems where multiple names
1516 for one file are not allowed. Some systems implement multiple names
1517 by copying the file instead.
1519 See also @code{file-nlinks} in @ref{File Attributes}.
1522 @deffn Command rename-file filename newname &optional ok-if-already-exists
1523 This command renames the file @var{filename} as @var{newname}.
1525 If @var{filename} has additional names aside from @var{filename}, it
1526 continues to have those names. In fact, adding the name @var{newname}
1527 with @code{add-name-to-file} and then deleting @var{filename} has the
1528 same effect as renaming, aside from momentary intermediate states.
1531 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux
1532 This command copies the file @var{oldname} to @var{newname}. An
1533 error is signaled if @var{oldname} does not exist. If @var{newname}
1534 names a directory, it copies @var{oldname} into that directory,
1535 preserving its final name component.
1537 If @var{time} is non-@code{nil}, then this function gives the new file
1538 the same last-modified time that the old one has. (This works on only
1539 some operating systems.) If setting the time gets an error,
1540 @code{copy-file} signals a @code{file-date-error} error. In an
1541 interactive call, a prefix argument specifies a non-@code{nil} value
1544 This function copies the file modes, too.
1546 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
1547 system decide the user and group ownership of the new file (this is
1548 usually set to the user running Emacs). If @var{preserve-uid-gid} is
1549 non-@code{nil}, we attempt to copy the user and group ownership of the
1550 file. This works only on some operating systems, and only if you have
1551 the correct permissions to do so.
1553 If the optional argument @var{preserve-selinux} is non-@code{nil}, and
1554 Emacs has been compiled with SELinux support, this function attempts
1555 to copy the file's SELinux context (@pxref{File Attributes}).
1558 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
1560 @kindex file-already-exists
1561 This command makes a symbolic link to @var{filename}, named
1562 @var{newname}. This is like the shell command @samp{ln -s
1563 @var{filename} @var{newname}}.
1565 This function is not available on systems that don't support symbolic
1570 @vindex delete-by-moving-to-trash
1571 @deffn Command delete-file filename &optional trash
1573 This command deletes the file @var{filename}. If the file has
1574 multiple names, it continues to exist under the other names. If
1575 @var{filename} is a symbolic link, @code{delete-file} deletes only the
1576 symbolic link and not its target (though it does follow symbolic links
1577 at all levels of parent directories).
1579 A suitable kind of @code{file-error} error is signaled if the file
1580 does not exist, or is not deletable. (On Unix and GNU/Linux, a file
1581 is deletable if its directory is writable.)
1583 If the optional argument @var{trash} is non-@code{nil} and the
1584 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
1585 command moves the file into the system Trash instead of deleting it.
1586 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
1587 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
1588 no prefix argument is given, and @code{nil} otherwise.
1590 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1593 @cindex file permissions, setting
1594 @cindex permissions, file
1595 @cindex file modes, setting
1596 @deffn Command set-file-modes filename mode
1597 This function sets the @dfn{file mode} (or @dfn{file permissions}) of
1598 @var{filename} to @var{mode}. It recursively follows symbolic links
1599 at all levels for @var{filename}.
1601 If called non-interactively, @var{mode} must be an integer. Only the
1602 lowest 12 bits of the integer are used; on most systems, only the
1603 lowest 9 bits are meaningful. You can use the Lisp construct for
1604 octal numbers to enter @var{mode}. For example,
1607 (set-file-modes #o644)
1611 specifies that the file should be readable and writable for its owner,
1612 readable for group members, and readable for all other users.
1613 @xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
1614 Manual}, for a description of mode bit specifications.
1616 Interactively, @var{mode} is read from the minibuffer using
1617 @code{read-file-modes} (see below), which lets the user type in either
1618 an integer or a string representing the permissions symbolically.
1620 @xref{File Attributes}, for the function @code{file-modes}, which
1621 returns the permissions of a file.
1624 @defun set-default-file-modes mode
1626 This function sets the default file permissions for new files created
1627 by Emacs and its subprocesses. Every file created with Emacs
1628 initially has these permissions, or a subset of them
1629 (@code{write-region} will not grant execute permissions even if the
1630 default file permissions allow execution). On Unix and GNU/Linux, the
1631 default permissions are given by the bitwise complement of the
1634 The argument @var{mode} should be an integer which specifies the
1635 permissions, similar to @code{set-file-modes} above. Only the lowest
1636 9 bits are meaningful.
1638 The default file permissions have no effect when you save a modified
1639 version of an existing file; saving a file preserves its existing
1643 @defun default-file-modes
1644 This function returns the default file permissions, as an integer.
1647 @defun read-file-modes &optional prompt base-file
1648 This function reads a set of file mode bits from the minibuffer. The
1649 first optional argument @var{prompt} specifies a non-default prompt.
1650 Second second optional argument @var{base-file} is the name of a file
1651 on whose permissions to base the mode bits that this function returns,
1652 if what the user types specifies mode bits relative to permissions of
1655 If user input represents an octal number, this function returns that
1656 number. If it is a complete symbolic specification of mode bits, as
1657 in @code{"u=rwx"}, the function converts it to the equivalent numeric
1658 value using @code{file-modes-symbolic-to-number} and returns the
1659 result. If the specification is relative, as in @code{"o+g"}, then
1660 the permissions on which the specification is based are taken from the
1661 mode bits of @var{base-file}. If @var{base-file} is omitted or
1662 @code{nil}, the function uses @code{0} as the base mode bits. The
1663 complete and relative specifications can be combined, as in
1664 @code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
1665 @sc{gnu} @code{Coreutils} Manual}, for a description of file mode
1669 @defun file-modes-symbolic-to-number modes &optional base-modes
1670 This function converts a symbolic file mode specification in
1671 @var{modes} into the equivalent integer value. If the symbolic
1672 specification is based on an existing file, that file's mode bits are
1673 taken from the optional argument @var{base-modes}; if that argument is
1674 omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at
1678 @defun set-file-times filename &optional time
1679 This function sets the access and modification times of @var{filename}
1680 to @var{time}. The return value is @code{t} if the times are successfully
1681 set, otherwise it is @code{nil}. @var{time} defaults to the current
1682 time and must be in the format returned by @code{current-time}
1683 (@pxref{Time of Day}).
1686 @defun set-file-selinux-context filename context
1687 This function sets the SELinux security context of the file
1688 @var{filename} to @var{context}. @xref{File Attributes}, for a brief
1689 description of SELinux contexts. The @var{context} argument should be
1690 a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
1691 return value of @code{file-selinux-context}. The function does
1692 nothing if SELinux is disabled, or if Emacs was compiled without
1700 Files are generally referred to by their names, in Emacs as elsewhere.
1701 File names in Emacs are represented as strings. The functions that
1702 operate on a file all expect a file name argument.
1704 In addition to operating on files themselves, Emacs Lisp programs
1705 often need to operate on file names; i.e., to take them apart and to use
1706 part of a name to construct related file names. This section describes
1707 how to manipulate file names.
1709 The functions in this section do not actually access files, so they
1710 can operate on file names that do not refer to an existing file or
1713 On MS-DOS and MS-Windows, these functions (like the function that
1714 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1715 where backslashes separate the components, as well as Unix syntax; but
1716 they always return Unix syntax. This enables Lisp programs to specify
1717 file names in Unix syntax and work properly on all systems without
1721 * File Name Components:: The directory part of a file name, and the rest.
1722 * Relative File Names:: Some file names are relative to a current directory.
1723 * Directory Names:: A directory's name as a directory
1724 is different from its name as a file.
1725 * File Name Expansion:: Converting relative file names to absolute ones.
1726 * Unique File Names:: Generating names for temporary files.
1727 * File Name Completion:: Finding the completions for a given file name.
1728 * Standard File Names:: If your package uses a fixed file name,
1729 how to handle various operating systems simply.
1732 @node File Name Components
1733 @subsection File Name Components
1734 @cindex directory part (of file name)
1735 @cindex nondirectory part (of file name)
1736 @cindex version number (in file name)
1738 The operating system groups files into directories. To specify a
1739 file, you must specify the directory and the file's name within that
1740 directory. Therefore, Emacs considers a file name as having two main
1741 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1742 (or @dfn{file name within the directory}). Either part may be empty.
1743 Concatenating these two parts reproduces the original file name.
1745 On most systems, the directory part is everything up to and including
1746 the last slash (backslash is also allowed in input on MS-DOS or
1747 MS-Windows); the nondirectory part is the rest.
1749 For some purposes, the nondirectory part is further subdivided into
1750 the name proper and the @dfn{version number}. On most systems, only
1751 backup files have version numbers in their names.
1753 @defun file-name-directory filename
1754 This function returns the directory part of @var{filename}, as a
1755 directory name (@pxref{Directory Names}), or @code{nil} if
1756 @var{filename} does not include a directory part.
1758 On GNU and Unix systems, a string returned by this function always
1759 ends in a slash. On MS-DOS it can also end in a colon.
1763 (file-name-directory "lewis/foo") ; @r{Unix example}
1767 (file-name-directory "foo") ; @r{Unix example}
1773 @defun file-name-nondirectory filename
1774 This function returns the nondirectory part of @var{filename}.
1778 (file-name-nondirectory "lewis/foo")
1782 (file-name-nondirectory "foo")
1786 (file-name-nondirectory "lewis/")
1792 @defun file-name-sans-versions filename &optional keep-backup-version
1793 This function returns @var{filename} with any file version numbers,
1794 backup version numbers, or trailing tildes discarded.
1796 If @var{keep-backup-version} is non-@code{nil}, then true file version
1797 numbers understood as such by the file system are discarded from the
1798 return value, but backup version numbers are kept.
1802 (file-name-sans-versions "~rms/foo.~1~")
1803 @result{} "~rms/foo"
1806 (file-name-sans-versions "~rms/foo~")
1807 @result{} "~rms/foo"
1810 (file-name-sans-versions "~rms/foo")
1811 @result{} "~rms/foo"
1816 @defun file-name-extension filename &optional period
1817 This function returns @var{filename}'s final ``extension,'' if any,
1818 after applying @code{file-name-sans-versions} to remove any
1819 version/backup part. The extension, in a file name, is the part that
1820 follows the last @samp{.} in the last name component (minus any
1821 version/backup part).
1823 This function returns @code{nil} for extensionless file names such as
1824 @file{foo}. It returns @code{""} for null extensions, as in
1825 @file{foo.}. If the last component of a file name begins with a
1826 @samp{.}, that @samp{.} doesn't count as the beginning of an
1827 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1830 If @var{period} is non-@code{nil}, then the returned value includes
1831 the period that delimits the extension, and if @var{filename} has no
1832 extension, the value is @code{""}.
1835 @defun file-name-sans-extension filename
1836 This function returns @var{filename} minus its extension, if any. The
1837 version/backup part, if present, is only removed if the file has an
1838 extension. For example,
1841 (file-name-sans-extension "foo.lose.c")
1842 @result{} "foo.lose"
1843 (file-name-sans-extension "big.hack/foo")
1844 @result{} "big.hack/foo"
1845 (file-name-sans-extension "/my/home/.emacs")
1846 @result{} "/my/home/.emacs"
1847 (file-name-sans-extension "/my/home/.emacs.el")
1848 @result{} "/my/home/.emacs"
1849 (file-name-sans-extension "~/foo.el.~3~")
1851 (file-name-sans-extension "~/foo.~3~")
1852 @result{} "~/foo.~3~"
1855 Note that the @samp{.~3~} in the two last examples is the backup part,
1860 @node Relative File Names
1861 @subsection Absolute and Relative File Names
1862 @cindex absolute file name
1863 @cindex relative file name
1865 All the directories in the file system form a tree starting at the
1866 root directory. A file name can specify all the directory names
1867 starting from the root of the tree; then it is called an @dfn{absolute}
1868 file name. Or it can specify the position of the file in the tree
1869 relative to a default directory; then it is called a @dfn{relative} file
1870 name. On Unix and GNU/Linux, an absolute file name starts with a slash
1871 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
1872 MS-Windows, an absolute file name starts with a slash or a backslash, or
1873 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1876 @defun file-name-absolute-p filename
1877 This function returns @code{t} if file @var{filename} is an absolute
1878 file name, @code{nil} otherwise.
1882 (file-name-absolute-p "~rms/foo")
1886 (file-name-absolute-p "rms/foo")
1890 (file-name-absolute-p "/user/rms/foo")
1896 Given a possibly relative file name, you can convert it to an
1897 absolute name using @code{expand-file-name} (@pxref{File Name
1898 Expansion}). This function converts absolute file names to relative
1901 @defun file-relative-name filename &optional directory
1902 This function tries to return a relative name that is equivalent to
1903 @var{filename}, assuming the result will be interpreted relative to
1904 @var{directory} (an absolute directory name or directory file name).
1905 If @var{directory} is omitted or @code{nil}, it defaults to the
1906 current buffer's default directory.
1908 On some operating systems, an absolute file name begins with a device
1909 name. On such systems, @var{filename} has no relative equivalent based
1910 on @var{directory} if they start with two different device names. In
1911 this case, @code{file-relative-name} returns @var{filename} in absolute
1915 (file-relative-name "/foo/bar" "/foo/")
1917 (file-relative-name "/foo/bar" "/hack/")
1918 @result{} "../foo/bar"
1922 @node Directory Names
1923 @comment node-name, next, previous, up
1924 @subsection Directory Names
1925 @cindex directory name
1926 @cindex file name of directory
1928 A @dfn{directory name} is the name of a directory. A directory is
1929 actually a kind of file, so it has a file name, which is related to
1930 the directory name but not identical to it. (This is not quite the
1931 same as the usual Unix terminology.) These two different names for
1932 the same entity are related by a syntactic transformation. On GNU and
1933 Unix systems, this is simple: a directory name ends in a slash,
1934 whereas the directory's name as a file lacks that slash. On MS-DOS
1935 the relationship is more complicated.
1937 The difference between a directory name and its name as a file is
1938 subtle but crucial. When an Emacs variable or function argument is
1939 described as being a directory name, a file name of a directory is not
1940 acceptable. When @code{file-name-directory} returns a string, that is
1941 always a directory name.
1943 The following two functions convert between directory names and file
1944 names. They do nothing special with environment variable substitutions
1945 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1947 @defun file-name-as-directory filename
1948 This function returns a string representing @var{filename} in a form
1949 that the operating system will interpret as the name of a directory. On
1950 most systems, this means appending a slash to the string (if it does not
1951 already end in one).
1955 (file-name-as-directory "~rms/lewis")
1956 @result{} "~rms/lewis/"
1961 @defun directory-file-name dirname
1962 This function returns a string representing @var{dirname} in a form that
1963 the operating system will interpret as the name of a file. On most
1964 systems, this means removing the final slash (or backslash) from the
1969 (directory-file-name "~lewis/")
1975 Given a directory name, you can combine it with a relative file name
1976 using @code{concat}:
1979 (concat @var{dirname} @var{relfile})
1983 Be sure to verify that the file name is relative before doing that.
1984 If you use an absolute file name, the results could be syntactically
1985 invalid or refer to the wrong file.
1987 If you want to use a directory file name in making such a
1988 combination, you must first convert it to a directory name using
1989 @code{file-name-as-directory}:
1992 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1996 Don't try concatenating a slash by hand, as in
2000 (concat @var{dirfile} "/" @var{relfile})
2004 because this is not portable. Always use
2005 @code{file-name-as-directory}.
2007 To convert a directory name to its abbreviation, use this
2010 @defun abbreviate-file-name filename
2011 @anchor{Definition of abbreviate-file-name}
2012 This function returns an abbreviated form of @var{filename}. It
2013 applies the abbreviations specified in @code{directory-abbrev-alist}
2014 (@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
2015 then substitutes @samp{~} for the user's home directory if the
2016 argument names a file in the home directory or one of its
2017 subdirectories. If the home directory is a root directory, it is not
2018 replaced with @samp{~}, because this does not make the result shorter
2021 You can use this function for directory names and for file names,
2022 because it recognizes abbreviations even as part of the name.
2025 @node File Name Expansion
2026 @subsection Functions that Expand Filenames
2027 @cindex expansion of file names
2029 @dfn{Expansion} of a file name means converting a relative file name
2030 to an absolute one. Since this is done relative to a default directory,
2031 you must specify the default directory name as well as the file name to
2032 be expanded. Expansion also simplifies file names by eliminating
2033 redundancies such as @file{./} and @file{@var{name}/../}.
2035 @defun expand-file-name filename &optional directory
2036 This function converts @var{filename} to an absolute file name. If
2037 @var{directory} is supplied, it is the default directory to start with
2038 if @var{filename} is relative. (The value of @var{directory} should
2039 itself be an absolute directory name or directory file name; it may
2040 start with @samp{~}.) Otherwise, the current buffer's value of
2041 @code{default-directory} is used. For example:
2045 (expand-file-name "foo")
2046 @result{} "/xcssun/users/rms/lewis/foo"
2049 (expand-file-name "../foo")
2050 @result{} "/xcssun/users/rms/foo"
2053 (expand-file-name "foo" "/usr/spool/")
2054 @result{} "/usr/spool/foo"
2057 (expand-file-name "$HOME/foo")
2058 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
2062 If the part of the combined file name before the first slash is
2063 @samp{~}, it expands to the value of the @env{HOME} environment
2064 variable (usually your home directory). If the part before the first
2065 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
2066 it expands to @var{user}'s home directory.
2068 Filenames containing @samp{.} or @samp{..} are simplified to their
2073 (expand-file-name "bar/../foo")
2074 @result{} "/xcssun/users/rms/lewis/foo"
2078 In some cases, a leading @samp{..} component can remain in the output:
2082 (expand-file-name "../home" "/")
2083 @result{} "/../home"
2088 This is for the sake of filesystems that have the concept of a
2089 ``superroot'' above the root directory @file{/}. On other filesystems,
2090 @file{/../} is interpreted exactly the same as @file{/}.
2092 Note that @code{expand-file-name} does @emph{not} expand environment
2093 variables; only @code{substitute-in-file-name} does that.
2095 Note also that @code{expand-file-name} does not follow symbolic links
2096 at any level. This results in a difference between the way
2097 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
2098 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
2099 @samp{/tmp/foo/bar} we get:
2103 (file-truename "/tmp/bar/../myfile")
2104 @result{} "/tmp/foo/myfile"
2107 (expand-file-name "/tmp/bar/../myfile")
2108 @result{} "/tmp/myfile"
2112 If you may need to follow symbolic links preceding @samp{..}, you
2113 should make sure to call @code{file-truename} without prior direct or
2114 indirect calls to @code{expand-file-name}. @xref{Truenames}.
2117 @defvar default-directory
2118 The value of this buffer-local variable is the default directory for the
2119 current buffer. It should be an absolute directory name; it may start
2120 with @samp{~}. This variable is buffer-local in every buffer.
2122 @code{expand-file-name} uses the default directory when its second
2123 argument is @code{nil}.
2125 The value is always a string ending with a slash.
2130 @result{} "/user/lewis/manual/"
2135 @defun substitute-in-file-name filename
2136 @anchor{Definition of substitute-in-file-name}
2137 This function replaces environment variable references in
2138 @var{filename} with the environment variable values. Following
2139 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2140 environment variable value. If the input contains @samp{$$}, that is
2141 converted to @samp{$}; this gives the user a way to ``quote'' a
2144 The environment variable name is the series of alphanumeric characters
2145 (including underscores) that follow the @samp{$}. If the character following
2146 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2149 Calling @code{substitute-in-file-name} on output produced by
2150 @code{substitute-in-file-name} tends to give incorrect results. For
2151 instance, use of @samp{$$} to quote a single @samp{$} won't work
2152 properly, and @samp{$} in an environment variable's value could lead
2153 to repeated substitution. Therefore, programs that call this function
2154 and put the output where it will be passed to this function need to
2155 double all @samp{$} characters to prevent subsequent incorrect
2158 @c Wordy to avoid overfull hbox. --rjc 15mar92
2159 Here we assume that the environment variable @code{HOME}, which holds
2160 the user's home directory name, has value @samp{/xcssun/users/rms}.
2164 (substitute-in-file-name "$HOME/foo")
2165 @result{} "/xcssun/users/rms/foo"
2169 After substitution, if a @samp{~} or a @samp{/} appears immediately
2170 after another @samp{/}, the function discards everything before it (up
2171 through the immediately preceding @samp{/}).
2175 (substitute-in-file-name "bar/~/foo")
2179 (substitute-in-file-name "/usr/local/$HOME/foo")
2180 @result{} "/xcssun/users/rms/foo"
2181 ;; @r{@file{/usr/local/} has been discarded.}
2187 @node Unique File Names
2188 @subsection Generating Unique File Names
2190 Some programs need to write temporary files. Here is the usual way to
2191 construct a name for such a file:
2194 (make-temp-file @var{name-of-application})
2198 The job of @code{make-temp-file} is to prevent two different users or
2199 two different jobs from trying to use the exact same file name.
2201 @defun make-temp-file prefix &optional dir-flag suffix
2202 This function creates a temporary file and returns its name. Emacs
2203 creates the temporary file's name by adding to @var{prefix} some
2204 random characters that are different in each Emacs job. The result is
2205 guaranteed to be a newly created empty file. On MS-DOS, this function
2206 can truncate the @var{string} prefix to fit into the 8+3 file-name
2207 limits. If @var{prefix} is a relative file name, it is expanded
2208 against @code{temporary-file-directory}.
2212 (make-temp-file "foo")
2213 @result{} "/tmp/foo232J6v"
2217 When @code{make-temp-file} returns, the file has been created and is
2218 empty. At that point, you should write the intended contents into the
2221 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2222 empty directory instead of an empty file. It returns the file name,
2223 not the directory name, of that directory. @xref{Directory Names}.
2225 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2226 the end of the file name.
2228 To prevent conflicts among different libraries running in the same
2229 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2230 own @var{prefix}. The number added to the end of @var{prefix}
2231 distinguishes between the same application running in different Emacs
2232 jobs. Additional added characters permit a large number of distinct
2233 names even in one Emacs job.
2236 The default directory for temporary files is controlled by the
2237 variable @code{temporary-file-directory}. This variable gives the user
2238 a uniform way to specify the directory for all temporary files. Some
2239 programs use @code{small-temporary-file-directory} instead, if that is
2240 non-@code{nil}. To use it, you should expand the prefix against
2241 the proper directory before calling @code{make-temp-file}.
2243 @defopt temporary-file-directory
2244 @cindex @code{TMPDIR} environment variable
2245 @cindex @code{TMP} environment variable
2246 @cindex @code{TEMP} environment variable
2247 This variable specifies the directory name for creating temporary files.
2248 Its value should be a directory name (@pxref{Directory Names}), but it
2249 is good for Lisp programs to cope if the value is a directory's file
2250 name instead. Using the value as the second argument to
2251 @code{expand-file-name} is a good way to achieve that.
2253 The default value is determined in a reasonable way for your operating
2254 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2255 environment variables, with a fall-back to a system-dependent name if
2256 none of these variables is defined.
2258 Even if you do not use @code{make-temp-file} to create the temporary
2259 file, you should still use this variable to decide which directory to
2260 put the file in. However, if you expect the file to be small, you
2261 should use @code{small-temporary-file-directory} first if that is
2265 @defopt small-temporary-file-directory
2266 This variable specifies the directory name for
2267 creating certain temporary files, which are likely to be small.
2269 If you want to write a temporary file which is likely to be small, you
2270 should compute the directory like this:
2274 (expand-file-name @var{prefix}
2275 (or small-temporary-file-directory
2276 temporary-file-directory)))
2280 @defun make-temp-name base-name
2281 This function generates a string that can be used as a unique file
2282 name. The name starts with @var{base-name}, and has several random
2283 characters appended to it, which are different in each Emacs job. It
2284 is like @code{make-temp-file} except that (i) it just constructs a
2285 name, and does not create a file, and (ii) @var{base-name} should be
2286 an absolute file name (on MS-DOS, this function can truncate
2287 @var{base-name} to fit into the 8+3 file-name limits).
2289 @strong{Warning:} In most cases, you should not use this function; use
2290 @code{make-temp-file} instead! This function is susceptible to a race
2291 condition, between the @code{make-temp-name} call and the creation of
2292 the file, which in some cases may cause a security hole.
2295 @node File Name Completion
2296 @subsection File Name Completion
2297 @cindex file name completion subroutines
2298 @cindex completion, file name
2300 This section describes low-level subroutines for completing a file
2301 name. For higher level functions, see @ref{Reading File Names}.
2303 @defun file-name-all-completions partial-filename directory
2304 This function returns a list of all possible completions for a file
2305 whose name starts with @var{partial-filename} in directory
2306 @var{directory}. The order of the completions is the order of the files
2307 in the directory, which is unpredictable and conveys no useful
2310 The argument @var{partial-filename} must be a file name containing no
2311 directory part and no slash (or backslash on some systems). The current
2312 buffer's default directory is prepended to @var{directory}, if
2313 @var{directory} is not absolute.
2315 In the following example, suppose that @file{~rms/lewis} is the current
2316 default directory, and has five files whose names begin with @samp{f}:
2317 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2318 @file{file.c.~2~}.@refill
2322 (file-name-all-completions "f" "")
2323 @result{} ("foo" "file~" "file.c.~2~"
2324 "file.c.~1~" "file.c")
2328 (file-name-all-completions "fo" "")
2334 @defun file-name-completion filename directory &optional predicate
2335 This function completes the file name @var{filename} in directory
2336 @var{directory}. It returns the longest prefix common to all file names
2337 in directory @var{directory} that start with @var{filename}. If
2338 @var{predicate} is non-@code{nil} then it ignores possible completions
2339 that don't satisfy @var{predicate}, after calling that function
2340 with one argument, the expanded absolute file name.
2342 If only one match exists and @var{filename} matches it exactly, the
2343 function returns @code{t}. The function returns @code{nil} if directory
2344 @var{directory} contains no name starting with @var{filename}.
2346 In the following example, suppose that the current default directory
2347 has five files whose names begin with @samp{f}: @file{foo},
2348 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2349 @file{file.c.~2~}.@refill
2353 (file-name-completion "fi" "")
2358 (file-name-completion "file.c.~1" "")
2359 @result{} "file.c.~1~"
2363 (file-name-completion "file.c.~1~" "")
2368 (file-name-completion "file.c.~3" "")
2374 @defopt completion-ignored-extensions
2375 @code{file-name-completion} usually ignores file names that end in any
2376 string in this list. It does not ignore them when all the possible
2377 completions end in one of these suffixes. This variable has no effect
2378 on @code{file-name-all-completions}.@refill
2380 A typical value might look like this:
2384 completion-ignored-extensions
2385 @result{} (".o" ".elc" "~" ".dvi")
2389 If an element of @code{completion-ignored-extensions} ends in a slash
2390 @samp{/}, it signals a directory. The elements which do @emph{not} end
2391 in a slash will never match a directory; thus, the above value will not
2392 filter out a directory named @file{foo.elc}.
2395 @node Standard File Names
2396 @subsection Standard File Names
2398 Most of the file names used in Lisp programs are entered by the user.
2399 But occasionally a Lisp program needs to specify a standard file name
2400 for a particular use---typically, to hold customization information
2401 about each user. For example, abbrev definitions are stored (by
2402 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2403 package stores completions in the file @file{~/.completions}. These are
2404 two of the many standard file names used by parts of Emacs for certain
2407 Various operating systems have their own conventions for valid file
2408 names and for which file names to use for user profile data. A Lisp
2409 program which reads a file using a standard file name ought to use, on
2410 each type of system, a file name suitable for that system. The function
2411 @code{convert-standard-filename} makes this easy to do.
2413 @defun convert-standard-filename filename
2414 This function alters the file name @var{filename} to fit the conventions
2415 of the operating system in use, and returns the result as a new string.
2418 The recommended way to specify a standard file name in a Lisp program
2419 is to choose a name which fits the conventions of GNU and Unix systems,
2420 usually with a nondirectory part that starts with a period, and pass it
2421 to @code{convert-standard-filename} instead of using it directly. Here
2422 is an example from the @code{completion} package:
2425 (defvar save-completions-file-name
2426 (convert-standard-filename "~/.completions")
2427 "*The file name to save completions to.")
2430 On GNU and Unix systems, and on some other systems as well,
2431 @code{convert-standard-filename} returns its argument unchanged. On
2432 some other systems, it alters the name to fit the system's conventions.
2434 For example, on MS-DOS the alterations made by this function include
2435 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
2436 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2437 a @samp{.} after eight characters if there is none, and truncating to
2438 three characters after the @samp{.}. (It makes other changes as well.)
2439 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2440 @file{.completions} becomes @file{_complet.ion}.
2442 @node Contents of Directories
2443 @section Contents of Directories
2444 @cindex directory-oriented functions
2445 @cindex file names in directory
2447 A directory is a kind of file that contains other files entered under
2448 various names. Directories are a feature of the file system.
2450 Emacs can list the names of the files in a directory as a Lisp list,
2451 or display the names in a buffer using the @code{ls} shell command. In
2452 the latter case, it can optionally display information about each file,
2453 depending on the options passed to the @code{ls} command.
2455 @defun directory-files directory &optional full-name match-regexp nosort
2456 This function returns a list of the names of the files in the directory
2457 @var{directory}. By default, the list is in alphabetical order.
2459 If @var{full-name} is non-@code{nil}, the function returns the files'
2460 absolute file names. Otherwise, it returns the names relative to
2461 the specified directory.
2463 If @var{match-regexp} is non-@code{nil}, this function returns only
2464 those file names that contain a match for that regular expression---the
2465 other file names are excluded from the list. On case-insensitive
2466 filesystems, the regular expression matching is case-insensitive.
2469 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2470 the list, so you get the file names in no particular order. Use this if
2471 you want the utmost possible speed and don't care what order the files
2472 are processed in. If the order of processing is visible to the user,
2473 then the user will probably be happier if you do sort the names.
2477 (directory-files "~lewis")
2478 @result{} ("#foo#" "#foo.el#" "." ".."
2479 "dired-mods.el" "files.texi"
2484 An error is signaled if @var{directory} is not the name of a directory
2488 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2489 This is similar to @code{directory-files} in deciding which files
2490 to report on and how to report their names. However, instead
2491 of returning a list of file names, it returns for each file a
2492 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2493 is what @code{file-attributes} would return for that file.
2494 The optional argument @var{id-format} has the same meaning as the
2495 corresponding argument to @code{file-attributes} (@pxref{Definition
2496 of file-attributes}).
2499 @defun file-expand-wildcards pattern &optional full
2500 This function expands the wildcard pattern @var{pattern}, returning
2501 a list of file names that match it.
2503 If @var{pattern} is written as an absolute file name,
2504 the values are absolute also.
2506 If @var{pattern} is written as a relative file name, it is interpreted
2507 relative to the current default directory. The file names returned are
2508 normally also relative to the current default directory. However, if
2509 @var{full} is non-@code{nil}, they are absolute.
2512 @defun insert-directory file switches &optional wildcard full-directory-p
2513 This function inserts (in the current buffer) a directory listing for
2514 directory @var{file}, formatted with @code{ls} according to
2515 @var{switches}. It leaves point after the inserted text.
2516 @var{switches} may be a string of options, or a list of strings
2517 representing individual options.
2519 The argument @var{file} may be either a directory name or a file
2520 specification including wildcard characters. If @var{wildcard} is
2521 non-@code{nil}, that means treat @var{file} as a file specification with
2524 If @var{full-directory-p} is non-@code{nil}, that means the directory
2525 listing is expected to show the full contents of a directory. You
2526 should specify @code{t} when @var{file} is a directory and switches do
2527 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
2528 describe a directory itself as a file, rather than showing its
2531 On most systems, this function works by running a directory listing
2532 program whose name is in the variable @code{insert-directory-program}.
2533 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2534 @code{shell-file-name}, to expand the wildcards.
2536 MS-DOS and MS-Windows systems usually lack the standard Unix program
2537 @code{ls}, so this function emulates the standard Unix program @code{ls}
2540 As a technical detail, when @var{switches} contains the long
2541 @samp{--dired} option, @code{insert-directory} treats it specially,
2542 for the sake of dired. However, the normally equivalent short
2543 @samp{-D} option is just passed on to @code{insert-directory-program},
2544 as any other option.
2547 @defvar insert-directory-program
2548 This variable's value is the program to run to generate a directory listing
2549 for the function @code{insert-directory}. It is ignored on systems
2550 which generate the listing with Lisp code.
2553 @node Create/Delete Dirs
2554 @section Creating, Copying and Deleting Directories
2555 @cindex creating, copying and deleting directories
2556 @c Emacs 19 features
2558 Most Emacs Lisp file-manipulation functions get errors when used on
2559 files that are directories. For example, you cannot delete a directory
2560 with @code{delete-file}. These special functions exist to create and
2564 @deffn Command make-directory dirname &optional parents
2565 This command creates a directory named @var{dirname}. If
2566 @var{parents} is non-@code{nil}, as is always the case in an
2567 interactive call, that means to create the parent directories first,
2568 if they don't already exist.
2570 @code{mkdir} is an alias for this.
2573 @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
2574 This command copies the directory named @var{dirname} to
2575 @var{newname}. If @var{newname} names an existing directory,
2576 @var{dirname} will be copied to a subdirectory there.
2578 It always sets the file modes of the copied files to match the
2579 corresponding original file.
2581 The third argument @var{keep-time} non-@code{nil} means to preserve the
2582 modification time of the copied files. A prefix arg makes
2583 @var{keep-time} non-@code{nil}.
2585 The fourth argument @var{parents} says whether to
2586 create parent directories if they don't exist. Interactively,
2587 this happens by default.
2589 The fifth argument @var{copy-contents}, if non-@code{nil}, means to
2590 copy the contents of @var{dirname} directly into @var{newname} if the
2591 latter is an existing directory, instead of copying @var{dirname} into
2592 it as a subdirectory.
2596 @vindex delete-by-moving-to-trash
2597 @deffn Command delete-directory dirname &optional recursive trash
2598 This command deletes the directory named @var{dirname}. The function
2599 @code{delete-file} does not work for files that are directories; you
2600 must use @code{delete-directory} for them. If @var{recursive} is
2601 @code{nil}, and the directory contains any files,
2602 @code{delete-directory} signals an error.
2604 @code{delete-directory} only follows symbolic links at the level of
2607 If the optional argument @var{trash} is non-@code{nil} and the
2608 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
2609 command moves the file into the system Trash instead of deleting it.
2610 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
2611 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
2612 no prefix argument is given, and @code{nil} otherwise.
2615 @node Magic File Names
2616 @section Making Certain File Names ``Magic''
2617 @cindex magic file names
2619 You can implement special handling for certain file names. This is
2620 called making those names @dfn{magic}. The principal use for this
2621 feature is in implementing remote file names (@pxref{Remote Files,,
2622 Remote Files, emacs, The GNU Emacs Manual}).
2624 To define a kind of magic file name, you must supply a regular
2625 expression to define the class of names (all those that match the
2626 regular expression), plus a handler that implements all the primitive
2627 Emacs file operations for file names that match.
2629 @vindex file-name-handler-alist
2630 The variable @code{file-name-handler-alist} holds a list of handlers,
2631 together with regular expressions that determine when to apply each
2632 handler. Each element has this form:
2635 (@var{regexp} . @var{handler})
2639 All the Emacs primitives for file access and file name transformation
2640 check the given file name against @code{file-name-handler-alist}. If
2641 the file name matches @var{regexp}, the primitives handle that file by
2642 calling @var{handler}.
2644 The first argument given to @var{handler} is the name of the
2645 primitive, as a symbol; the remaining arguments are the arguments that
2646 were passed to that primitive. (The first of these arguments is most
2647 often the file name itself.) For example, if you do this:
2650 (file-exists-p @var{filename})
2654 and @var{filename} has handler @var{handler}, then @var{handler} is
2658 (funcall @var{handler} 'file-exists-p @var{filename})
2661 When a function takes two or more arguments that must be file names,
2662 it checks each of those names for a handler. For example, if you do
2666 (expand-file-name @var{filename} @var{dirname})
2670 then it checks for a handler for @var{filename} and then for a handler
2671 for @var{dirname}. In either case, the @var{handler} is called like
2675 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2679 The @var{handler} then needs to figure out whether to handle
2680 @var{filename} or @var{dirname}.
2682 If the specified file name matches more than one handler, the one
2683 whose match starts last in the file name gets precedence. This rule
2684 is chosen so that handlers for jobs such as uncompression are handled
2685 first, before handlers for jobs such as remote file access.
2687 Here are the operations that a magic file name handler gets to handle:
2691 @code{access-file}, @code{add-name-to-file},
2692 @code{byte-compiler-base-file-name},@*
2693 @code{copy-directory}, @code{copy-file},
2694 @code{delete-directory}, @code{delete-file},
2695 @code{diff-latest-backup-file},
2696 @code{directory-file-name},
2697 @code{directory-files},
2698 @code{directory-files-and-attributes},
2699 @code{dired-compress-file}, @code{dired-uncache},@*
2700 @code{expand-file-name},
2701 @code{file-accessible-directory-p},
2702 @code{file-attributes},
2703 @code{file-directory-p},
2704 @code{file-executable-p}, @code{file-exists-p},
2705 @code{file-local-copy}, @code{file-remote-p},
2706 @code{file-modes}, @code{file-name-all-completions},
2707 @code{file-name-as-directory},
2708 @code{file-name-completion},
2709 @code{file-name-directory},
2710 @code{file-name-nondirectory},
2711 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2712 @code{file-ownership-preserved-p},
2713 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2714 @code{file-truename}, @code{file-writable-p},
2715 @code{find-backup-file-name},
2716 @c Not sure why it was here: @code{find-file-noselect},@*
2717 @code{get-file-buffer},
2718 @code{insert-directory},
2719 @code{insert-file-contents},@*
2721 @code{make-auto-save-file-name},
2722 @code{make-directory},
2723 @code{make-directory-internal},
2724 @code{make-symbolic-link},@*
2725 @code{process-file},
2726 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2727 @code{set-visited-file-modtime}, @code{shell-command},
2728 @code{start-file-process},
2729 @code{substitute-in-file-name},@*
2730 @code{unhandled-file-name-directory},
2731 @code{vc-registered},
2732 @code{verify-visited-file-modtime},@*
2733 @code{write-region}.
2738 @code{access-file}, @code{add-name-to-file},
2739 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2740 @code{copy-directory}, @code{copy-file},
2741 @code{delete-directory}, @code{delete-file},
2742 @code{diff-latest-backup-file},
2743 @code{directory-file-name},
2744 @code{directory-files},
2745 @code{directory-files-and-at@discretionary{}{}{}tributes},
2746 @code{dired-compress-file}, @code{dired-uncache},
2747 @code{expand-file-name},
2748 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2749 @code{file-attributes},
2750 @code{file-direct@discretionary{}{}{}ory-p},
2751 @code{file-executable-p}, @code{file-exists-p},
2752 @code{file-local-copy}, @code{file-remote-p},
2753 @code{file-modes}, @code{file-name-all-completions},
2754 @code{file-name-as-directory},
2755 @code{file-name-completion},
2756 @code{file-name-directory},
2757 @code{file-name-nondirec@discretionary{}{}{}tory},
2758 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2759 @code{file-ownership-pre@discretionary{}{}{}served-p},
2760 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2761 @code{file-truename}, @code{file-writable-p},
2762 @code{find-backup-file-name},
2763 @c Not sure why it was here: @code{find-file-noselect},
2764 @code{get-file-buffer},
2765 @code{insert-directory},
2766 @code{insert-file-contents},
2767 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2768 @code{make-direc@discretionary{}{}{}tory-internal},
2769 @code{make-symbolic-link},
2770 @code{process-file},
2771 @code{rename-file}, @code{set-file-modes},
2772 @code{set-visited-file-modtime}, @code{shell-command},
2773 @code{start-file-process},
2774 @code{substitute-in-file-name},
2775 @code{unhandled-file-name-directory},
2776 @code{vc-regis@discretionary{}{}{}tered},
2777 @code{verify-visited-file-modtime},
2778 @code{write-region}.
2782 Handlers for @code{insert-file-contents} typically need to clear the
2783 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2784 @var{visit} argument is non-@code{nil}. This also has the effect of
2785 unlocking the buffer if it is locked.
2787 The handler function must handle all of the above operations, and
2788 possibly others to be added in the future. It need not implement all
2789 these operations itself---when it has nothing special to do for a
2790 certain operation, it can reinvoke the primitive, to handle the
2791 operation ``in the usual way.'' It should always reinvoke the primitive
2792 for an operation it does not recognize. Here's one way to do this:
2795 (defun my-file-handler (operation &rest args)
2796 ;; @r{First check for the specific operations}
2797 ;; @r{that we have special handling for.}
2798 (cond ((eq operation 'insert-file-contents) @dots{})
2799 ((eq operation 'write-region) @dots{})
2801 ;; @r{Handle any operation we don't know about.}
2802 (t (let ((inhibit-file-name-handlers
2803 (cons 'my-file-handler
2804 (and (eq inhibit-file-name-operation operation)
2805 inhibit-file-name-handlers)))
2806 (inhibit-file-name-operation operation))
2807 (apply operation args)))))
2810 When a handler function decides to call the ordinary Emacs primitive for
2811 the operation at hand, it needs to prevent the primitive from calling
2812 the same handler once again, thus leading to an infinite recursion. The
2813 example above shows how to do this, with the variables
2814 @code{inhibit-file-name-handlers} and
2815 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2816 shown above; the details are crucial for proper behavior in the case of
2817 multiple handlers, and for operations that have two file names that may
2820 @kindex safe-magic (@r{property})
2821 Handlers that don't really do anything special for actual access to the
2822 file---such as the ones that implement completion of host names for
2823 remote file names---should have a non-@code{nil} @code{safe-magic}
2824 property. For instance, Emacs normally ``protects'' directory names
2825 it finds in @code{PATH} from becoming magic, if they look like magic
2826 file names, by prefixing them with @samp{/:}. But if the handler that
2827 would be used for them has a non-@code{nil} @code{safe-magic}
2828 property, the @samp{/:} is not added.
2830 @kindex operations (@r{property})
2831 A file name handler can have an @code{operations} property to
2832 declare which operations it handles in a nontrivial way. If this
2833 property has a non-@code{nil} value, it should be a list of
2834 operations; then only those operations will call the handler. This
2835 avoids inefficiency, but its main purpose is for autoloaded handler
2836 functions, so that they won't be loaded except when they have real
2839 Simply deferring all operations to the usual primitives does not
2840 work. For instance, if the file name handler applies to
2841 @code{file-exists-p}, then it must handle @code{load} itself, because
2842 the usual @code{load} code won't work properly in that case. However,
2843 if the handler uses the @code{operations} property to say it doesn't
2844 handle @code{file-exists-p}, then it need not handle @code{load}
2847 @defvar inhibit-file-name-handlers
2848 This variable holds a list of handlers whose use is presently inhibited
2849 for a certain operation.
2852 @defvar inhibit-file-name-operation
2853 The operation for which certain handlers are presently inhibited.
2856 @defun find-file-name-handler file operation
2857 This function returns the handler function for file name @var{file},
2858 or @code{nil} if there is none. The argument @var{operation} should
2859 be the operation to be performed on the file---the value you will pass
2860 to the handler as its first argument when you call it. If
2861 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2862 not found in the @code{operations} property of the handler, this
2863 function returns @code{nil}.
2866 @defun file-local-copy filename
2867 This function copies file @var{filename} to an ordinary non-magic file
2868 on the local machine, if it isn't on the local machine already. Magic
2869 file names should handle the @code{file-local-copy} operation if they
2870 refer to files on other machines. A magic file name that is used for
2871 other purposes than remote file access should not handle
2872 @code{file-local-copy}; then this function will treat the file as
2875 If @var{filename} is local, whether magic or not, this function does
2876 nothing and returns @code{nil}. Otherwise it returns the file name
2877 of the local copy file.
2880 @defun file-remote-p filename &optional identification connected
2881 This function tests whether @var{filename} is a remote file. If
2882 @var{filename} is local (not remote), the return value is @code{nil}.
2883 If @var{filename} is indeed remote, the return value is a string that
2884 identifies the remote system.
2886 This identifier string can include a host name and a user name, as
2887 well as characters designating the method used to access the remote
2888 system. For example, the remote identifier string for the filename
2889 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
2891 If @code{file-remote-p} returns the same identifier for two different
2892 filenames, that means they are stored on the same file system and can
2893 be accessed locally with respect to each other. This means, for
2894 example, that it is possible to start a remote process accessing both
2895 files at the same time. Implementers of file handlers need to ensure
2896 this principle is valid.
2898 @var{identification} specifies which part of the identifier shall be
2899 returned as string. @var{identification} can be the symbol
2900 @code{method}, @code{user} or @code{host}; any other value is handled
2901 like @code{nil} and means to return the complete identifier string.
2902 In the example above, the remote @code{user} identifier string would
2905 If @var{connected} is non-@code{nil}, this function returns @code{nil}
2906 even if @var{filename} is remote, if Emacs has no network connection
2907 to its host. This is useful when you want to avoid the delay of
2908 making connections when they don't exist.
2911 @defun unhandled-file-name-directory filename
2912 This function returns the name of a directory that is not magic. It
2913 uses the directory part of @var{filename} if that is not magic. For a
2914 magic file name, it invokes the file name handler, which therefore
2915 decides what value to return. If @var{filename} is not accessible
2916 from a local process, then the file name handler should indicate it by
2917 returning @code{nil}.
2919 This is useful for running a subprocess; every subprocess must have a
2920 non-magic directory to serve as its current directory, and this function
2921 is a good way to come up with one.
2924 @defopt remote-file-name-inhibit-cache
2925 The attributes of remote files can be cached for better performance. If
2926 they are changed outside of Emacs's control, the cached values become
2927 invalid, and must be reread.
2929 When this variable is set to @code{nil}, cached values are never
2930 expired. Use this setting with caution, only if you are sure nothing
2931 other than Emacs ever changes the remote files. If it is set to
2932 @code{t}, cached values are never used. This is the safest value, but
2933 could result in performance degradation.
2935 A compromise is to set it to a positive number. This means that
2936 cached values are used for that amount of seconds since they were
2937 cached. If a remote file is checked regularly, it might be a good
2938 idea to let-bind this variable to a value less than the time period
2939 between consecutive checks. For example:
2942 (defun display-time-file-nonempty-p (file)
2943 (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
2944 (and (file-exists-p file)
2945 (< 0 (nth 7 (file-attributes (file-chase-links file)))))))
2949 @node Format Conversion
2950 @section File Format Conversion
2952 @cindex file format conversion
2953 @cindex encoding file formats
2954 @cindex decoding file formats
2955 @cindex text properties in files
2956 @cindex saving text properties
2957 Emacs performs several steps to convert the data in a buffer (text,
2958 text properties, and possibly other information) to and from a
2959 representation suitable for storing into a file. This section describes
2960 the fundamental functions that perform this @dfn{format conversion},
2961 namely @code{insert-file-contents} for reading a file into a buffer,
2962 and @code{write-region} for writing a buffer into a file.
2965 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}.
2966 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
2967 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
2970 @node Format Conversion Overview
2971 @subsection Overview
2973 The function @code{insert-file-contents}:
2976 @item initially, inserts bytes from the file into the buffer;
2977 @item decodes bytes to characters as appropriate;
2978 @item processes formats as defined by entries in @code{format-alist}; and
2979 @item calls functions in @code{after-insert-file-functions}.
2983 The function @code{write-region}:
2986 @item initially, calls functions in @code{write-region-annotate-functions};
2987 @item processes formats as defined by entries in @code{format-alist};
2988 @item encodes characters to bytes as appropriate; and
2989 @item modifies the file with the bytes.
2992 This shows the symmetry of the lowest-level operations; reading and
2993 writing handle things in opposite order. The rest of this section
2994 describes the two facilities surrounding the three variables named
2995 above, as well as some related functions. @ref{Coding Systems}, for
2996 details on character encoding and decoding.
2998 @node Format Conversion Round-Trip
2999 @subsection Round-Trip Specification
3001 The most general of the two facilities is controlled by the variable
3002 @code{format-alist}, a list of @dfn{file format} specifications, which
3003 describe textual representations used in files for the data in an Emacs
3004 buffer. The descriptions for reading and writing are paired, which is
3005 why we call this ``round-trip'' specification
3006 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
3008 @defvar format-alist
3009 This list contains one format definition for each defined file format.
3010 Each format definition is a list of this form:
3013 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
3017 @cindex format definition
3019 Here is what the elements in a format definition mean:
3023 The name of this format.
3026 A documentation string for the format.
3029 A regular expression which is used to recognize files represented in
3030 this format. If @code{nil}, the format is never applied automatically.
3033 A shell command or function to decode data in this format (to convert
3034 file data into the usual Emacs data representation).
3036 A shell command is represented as a string; Emacs runs the command as a
3037 filter to perform the conversion.
3039 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
3040 and @var{end}, which specify the part of the buffer it should convert.
3041 It should convert the text by editing it in place. Since this can
3042 change the length of the text, @var{from-fn} should return the modified
3045 One responsibility of @var{from-fn} is to make sure that the beginning
3046 of the file no longer matches @var{regexp}. Otherwise it is likely to
3050 A shell command or function to encode data in this format---that is, to
3051 convert the usual Emacs data representation into this format.
3053 If @var{to-fn} is a string, it is a shell command; Emacs runs the
3054 command as a filter to perform the conversion.
3056 If @var{to-fn} is a function, it is called with three arguments:
3057 @var{begin} and @var{end}, which specify the part of the buffer it
3058 should convert, and @var{buffer}, which specifies which buffer. There
3059 are two ways it can do the conversion:
3063 By editing the buffer in place. In this case, @var{to-fn} should
3064 return the end-position of the range of text, as modified.
3067 By returning a list of annotations. This is a list of elements of the
3068 form @code{(@var{position} . @var{string})}, where @var{position} is an
3069 integer specifying the relative position in the text to be written, and
3070 @var{string} is the annotation to add there. The list must be sorted in
3071 order of position when @var{to-fn} returns it.
3073 When @code{write-region} actually writes the text from the buffer to the
3074 file, it intermixes the specified annotations at the corresponding
3075 positions. All this takes place without modifying the buffer.
3079 A flag, @code{t} if the encoding function modifies the buffer, and
3080 @code{nil} if it works by returning a list of annotations.
3083 A minor-mode function to call after visiting a file converted from this
3084 format. The function is called with one argument, the integer 1;
3085 that tells a minor-mode function to enable the mode.
3088 A flag, @code{t} if @code{format-write-file} should not remove this format
3089 from @code{buffer-file-format}.
3092 The function @code{insert-file-contents} automatically recognizes file
3093 formats when it reads the specified file. It checks the text of the
3094 beginning of the file against the regular expressions of the format
3095 definitions, and if it finds a match, it calls the decoding function for
3096 that format. Then it checks all the known formats over again.
3097 It keeps checking them until none of them is applicable.
3099 Visiting a file, with @code{find-file-noselect} or the commands that use
3100 it, performs conversion likewise (because it calls
3101 @code{insert-file-contents}); it also calls the mode function for each
3102 format that it decodes. It stores a list of the format names in the
3103 buffer-local variable @code{buffer-file-format}.
3105 @defvar buffer-file-format
3106 This variable states the format of the visited file. More precisely,
3107 this is a list of the file format names that were decoded in the course
3108 of visiting the current buffer's file. It is always buffer-local in all
3112 When @code{write-region} writes data into a file, it first calls the
3113 encoding functions for the formats listed in @code{buffer-file-format},
3114 in the order of appearance in the list.
3116 @deffn Command format-write-file file format &optional confirm
3117 This command writes the current buffer contents into the file @var{file}
3118 in a format based on @var{format}, which is a list of format names. It
3119 constructs the actual format starting from @var{format}, then appending
3120 any elements from the value of @code{buffer-file-format} with a non-nil
3121 @var{preserve} flag (see above), if they are not already present in
3122 @var{format}. It then updates @code{buffer-file-format} with this
3123 format, making it the default for future saves. Except for the
3124 @var{format} argument, this command is similar to @code{write-file}. In
3125 particular, @var{confirm} has the same meaning and interactive treatment
3126 as the corresponding argument to @code{write-file}. @xref{Definition of
3130 @deffn Command format-find-file file format
3131 This command finds the file @var{file}, converting it according to
3132 format @var{format}. It also makes @var{format} the default if the
3133 buffer is saved later.
3135 The argument @var{format} is a list of format names. If @var{format} is
3136 @code{nil}, no conversion takes place. Interactively, typing just
3137 @key{RET} for @var{format} specifies @code{nil}.
3140 @deffn Command format-insert-file file format &optional beg end
3141 This command inserts the contents of file @var{file}, converting it
3142 according to format @var{format}. If @var{beg} and @var{end} are
3143 non-@code{nil}, they specify which part of the file to read, as in
3144 @code{insert-file-contents} (@pxref{Reading from Files}).
3146 The return value is like what @code{insert-file-contents} returns: a
3147 list of the absolute file name and the length of the data inserted
3150 The argument @var{format} is a list of format names. If @var{format} is
3151 @code{nil}, no conversion takes place. Interactively, typing just
3152 @key{RET} for @var{format} specifies @code{nil}.
3155 @defvar buffer-auto-save-file-format
3156 This variable specifies the format to use for auto-saving. Its value is
3157 a list of format names, just like the value of
3158 @code{buffer-file-format}; however, it is used instead of
3159 @code{buffer-file-format} for writing auto-save files. If the value
3160 is @code{t}, the default, auto-saving uses the same format as a
3161 regular save in the same buffer. This variable is always buffer-local
3165 @node Format Conversion Piecemeal
3166 @subsection Piecemeal Specification
3168 In contrast to the round-trip specification described in the previous
3169 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
3170 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
3171 to separately control the respective reading and writing conversions.
3173 Conversion starts with one representation and produces another
3174 representation. When there is only one conversion to do, there is no
3175 conflict about what to start with. However, when there are multiple
3176 conversions involved, conflict may arise when two conversions need to
3177 start with the same data.
3179 This situation is best understood in the context of converting text
3180 properties during @code{write-region}. For example, the character at
3181 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
3182 the conversion for @code{foo} is done by inserting into the buffer, say,
3183 @samp{FOO:}, then that changes the character at position 42 from
3184 @samp{X} to @samp{F}. The next conversion will start with the wrong
3187 To avoid conflict, cooperative conversions do not modify the buffer,
3188 but instead specify @dfn{annotations}, a list of elements of the form
3189 @code{(@var{position} . @var{string})}, sorted in order of increasing
3192 If there is more than one conversion, @code{write-region} merges their
3193 annotations destructively into one sorted list. Later, when the text
3194 from the buffer is actually written to the file, it intermixes the
3195 specified annotations at the corresponding positions. All this takes
3196 place without modifying the buffer.
3198 @c ??? What about ``overriding'' conversions like those allowed
3199 @c ??? for `write-region-annotate-functions', below? --ttn
3201 In contrast, when reading, the annotations intermixed with the text
3202 are handled immediately. @code{insert-file-contents} sets point to
3203 the beginning of some text to be converted, then calls the conversion
3204 functions with the length of that text. These functions should always
3205 return with point at the beginning of the inserted text. This
3206 approach makes sense for reading because annotations removed by the
3207 first converter can't be mistakenly processed by a later converter.
3208 Each conversion function should scan for the annotations it
3209 recognizes, remove the annotation, modify the buffer text (to set a
3210 text property, for example), and return the updated length of the
3211 text, as it stands after those changes. The value returned by one
3212 function becomes the argument to the next function.
3214 @defvar write-region-annotate-functions
3215 A list of functions for @code{write-region} to call. Each function in
3216 the list is called with two arguments: the start and end of the region
3217 to be written. These functions should not alter the contents of the
3218 buffer. Instead, they should return annotations.
3220 As a special case, a function may return with a different buffer
3221 current. Emacs takes this to mean that the current buffer contains
3222 altered text to be output. It therefore changes the @var{start} and
3223 @var{end} arguments of the @code{write-region} call, giving them the
3224 values of @code{point-min} and @code{point-max} in the new buffer,
3225 respectively. It also discards all previous annotations, because they
3226 should have been dealt with by this function.
3229 @defvar write-region-post-annotation-function
3230 The value of this variable, if non-@code{nil}, should be a function.
3231 This function is called, with no arguments, after @code{write-region}
3234 If any function in @code{write-region-annotate-functions} returns with
3235 a different buffer current, Emacs calls
3236 @code{write-region-post-annotation-function} more than once. Emacs
3237 calls it with the last buffer that was current, and again with the
3238 buffer before that, and so on back to the original buffer.
3240 Thus, a function in @code{write-region-annotate-functions} can create
3241 a buffer, give this variable the local value of @code{kill-buffer} in
3242 that buffer, set up the buffer with altered text, and make the buffer
3243 current. The buffer will be killed after @code{write-region} is done.
3246 @defvar after-insert-file-functions
3247 Each function in this list is called by @code{insert-file-contents}
3248 with one argument, the number of characters inserted, and with point
3249 at the beginning of the inserted text. Each function should leave
3250 point unchanged, and return the new character count describing the
3251 inserted text as modified by the function.
3252 @c ??? The docstring mentions a handler from `file-name-handler-alist'
3253 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
3256 We invite users to write Lisp programs to store and retrieve text
3257 properties in files, using these hooks, and thus to experiment with
3258 various data formats and find good ones. Eventually we hope users
3259 will produce good, general extensions we can install in Emacs.
3261 We suggest not trying to handle arbitrary Lisp objects as text property
3262 names or values---because a program that general is probably difficult
3263 to write, and slow. Instead, choose a set of possible data types that
3264 are reasonably flexible, and not too hard to encode.