2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
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 In Emacs, you can find, create, view, save, and otherwise work with
12 files and file directories. This chapter describes most of the
13 file-related functions of Emacs Lisp, but a few others are described in
14 @ref{Buffers}, and those related to backups and auto-saving are
15 described in @ref{Backups and Auto-Saving}.
17 Many of the file functions take one or more arguments that are file
18 names. A file name is actually a string. Most of these functions
19 expand file name arguments by calling @code{expand-file-name}, so that
20 @file{~} is handled correctly, as are relative file names (including
21 @samp{../}). These functions don't recognize environment variable
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
24 When file I/O functions signal Lisp errors, they usually use the
25 condition @code{file-error} (@pxref{Handling Errors}). The error
26 message is in most cases obtained from the operating system, according
27 to locale @code{system-message-locale}, and decoded using coding system
28 @code{locale-coding-system} (@pxref{Locales}).
31 * Visiting Files:: Reading files into Emacs buffers for editing.
32 * Saving Buffers:: Writing changed buffers back into files.
33 * Reading from Files:: Reading files into buffers without visiting.
34 * Writing to Files:: Writing new files from parts of buffers.
35 * File Locks:: Locking and unlocking files, to prevent
36 simultaneous editing by two people.
37 * Information about Files:: Testing existence, accessibility, size of files.
38 * Changing Files:: Renaming files, changing protection, etc.
39 * File Names:: Decomposing and expanding file names.
40 * Contents of Directories:: Getting a list of the files in a directory.
41 * Create/Delete Dirs:: Creating and Deleting Directories.
42 * Magic File Names:: Defining "magic" special handling
43 for certain file names.
44 * Format Conversion:: Conversion to and from various file formats.
48 @section Visiting Files
50 @cindex visiting files
52 Visiting a file means reading a file into a buffer. Once this is
53 done, we say that the buffer is @dfn{visiting} that file, and call the
54 file ``the visited file'' of the buffer.
56 A file and a buffer are two different things. A file is information
57 recorded permanently in the computer (unless you delete it). A buffer,
58 on the other hand, is information inside of Emacs that will vanish at
59 the end of the editing session (or when you kill the buffer). Usually,
60 a buffer contains information that you have copied from a file; then we
61 say the buffer is visiting that file. The copy in the buffer is what
62 you modify with editing commands. Such changes to the buffer do not
63 change the file; therefore, to make the changes permanent, you must
64 @dfn{save} the buffer, which means copying the altered buffer contents
67 In spite of the distinction between files and buffers, people often
68 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
70 will soon save as a file of the same name.'' Humans do not usually need
71 to make the distinction explicit. When dealing with a computer program,
72 however, it is good to keep the distinction in mind.
75 * Visiting Functions:: The usual interface functions for visiting.
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
79 @node Visiting Functions
80 @subsection Functions for Visiting Files
82 This section describes the functions normally used to visit files.
83 For historical reasons, these functions have names starting with
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
85 functions and variables that access the visited file name of a buffer or
86 that find an existing buffer by its visited file name.
88 In a Lisp program, if you want to look at the contents of a file but
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
90 temporary buffer. Visiting the file is not necessary and takes longer.
91 @xref{Reading from Files}.
93 @deffn Command find-file filename &optional wildcards
94 This command selects a buffer visiting the file @var{filename},
95 using an existing buffer if there is one, and otherwise creating a
96 new buffer and reading the file into it. It also returns that buffer.
98 Aside from some technical details, the body of the @code{find-file}
99 function is basically equivalent to:
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
108 If @var{wildcards} is non-@code{nil}, which is always true in an
109 interactive call, then @code{find-file} expands wildcard characters in
110 @var{filename} and visits all the matching files.
112 When @code{find-file} is called interactively, it prompts for
113 @var{filename} in the minibuffer.
116 @deffn Command find-file-literally filename
117 This command visits @var{filename}, like @code{find-file} does, but it
118 does not perform any format conversions (@pxref{Format Conversion}),
119 character code conversions (@pxref{Coding Systems}), or end-of-line
120 conversions (@pxref{Coding System Basics, End of line conversion}).
121 The buffer visiting the file is made unibyte, and its major mode is
122 Fundamental mode, regardless of the file name. File local variable
123 specifications in the file (@pxref{File Local Variables}) are
124 ignored, and automatic decompression and adding a newline at the end
125 of the file due to @code{require-final-newline} (@pxref{Saving
126 Buffers, require-final-newline}) are also disabled.
128 Note that if Emacs already has a buffer visiting the same file
129 non-literally, it will not visit the same file literally, but instead
130 just switch to the existing buffer. If you want to be sure of
131 accessing a file's contents literally, you should create a temporary
132 buffer and then read the file contents into it using
133 @code{insert-file-contents-literally} (@pxref{Reading from Files}).
136 @defun find-file-noselect filename &optional nowarn rawfile wildcards
137 This function is the guts of all the file-visiting functions. It
138 returns a buffer visiting the file @var{filename}. You may make the
139 buffer current or display it in a window if you wish, but this
140 function does not do so.
142 The function returns an existing buffer if there is one; otherwise it
143 creates a new buffer and reads the file into it. When
144 @code{find-file-noselect} uses an existing buffer, it first verifies
145 that the file has not changed since it was last visited or saved in
146 that buffer. If the file has changed, this function asks the user
147 whether to reread the changed file. If the user says @samp{yes}, any
148 edits previously made in the buffer are lost.
150 Reading the file involves decoding the file's contents (@pxref{Coding
151 Systems}), including end-of-line conversion, and format conversion
152 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
153 then @code{find-file-noselect} expands wildcard characters in
154 @var{filename} and visits all the matching files.
156 This function displays warning or advisory messages in various peculiar
157 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
158 example, if it needs to create a buffer, and there is no file named
159 @var{filename}, it displays the message @samp{(New file)} in the echo
160 area, and leaves the buffer empty.
162 The @code{find-file-noselect} function normally calls
163 @code{after-find-file} after reading the file (@pxref{Subroutines of
164 Visiting}). That function sets the buffer major mode, parses local
165 variables, warns the user if there exists an auto-save file more recent
166 than the file just visited, and finishes by running the functions in
167 @code{find-file-hook}.
169 If the optional argument @var{rawfile} is non-@code{nil}, then
170 @code{after-find-file} is not called, and the
171 @code{find-file-not-found-functions} are not run in case of failure.
172 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
173 system conversion and format conversion.
175 The @code{find-file-noselect} function usually returns the buffer that
176 is visiting the file @var{filename}. But, if wildcards are actually
177 used and expanded, it returns a list of buffers that are visiting the
182 (find-file-noselect "/etc/fstab")
183 @result{} #<buffer fstab>
188 @deffn Command find-file-other-window filename &optional wildcards
189 This command selects a buffer visiting the file @var{filename}, but
190 does so in a window other than the selected window. It may use another
191 existing window or split a window; see @ref{Displaying Buffers}.
193 When this command is called interactively, it prompts for
197 @deffn Command find-file-read-only filename &optional wildcards
198 This command selects a buffer visiting the file @var{filename}, like
199 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
200 Buffers}, for related functions and variables.
202 When this command is called interactively, it prompts for
206 @defopt find-file-wildcards
207 If this variable is non-@code{nil}, then the various @code{find-file}
208 commands check for wildcard characters and visit all the files that
209 match them (when invoked interactively or when their @var{wildcards}
210 argument is non-@code{nil}). If this option is @code{nil}, then
211 the @code{find-file} commands ignore their @var{wildcards} argument
212 and never treat wildcard characters specially.
215 @defopt find-file-hook
216 The value of this variable is a list of functions to be called after a
217 file is visited. The file's local-variables specification (if any) will
218 have been processed before the hooks are run. The buffer visiting the
219 file is current when the hook functions are run.
221 This variable is a normal hook. @xref{Hooks}.
224 @defvar find-file-not-found-functions
225 The value of this variable is a list of functions to be called when
226 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
227 file name. @code{find-file-noselect} calls these functions as soon as
228 it detects a nonexistent file. It calls them in the order of the list,
229 until one of them returns non-@code{nil}. @code{buffer-file-name} is
232 This is not a normal hook because the values of the functions are
233 used, and in many cases only some of the functions are called.
236 @defvar find-file-literally
237 This buffer-local variable, if set to a non-@code{nil} value, makes
238 @code{save-buffer} behave as if the buffer were visiting its file
239 literally, i.e. without conversions of any kind. The command
240 @code{find-file-literally} sets this variable's local value, but other
241 equivalent functions and commands can do that as well, e.g.@: to avoid
242 automatic addition of a newline at the end of the file. This variable
243 is permanent local, so it is unaffected by changes of major modes.
246 @node Subroutines of Visiting
247 @comment node-name, next, previous, up
248 @subsection Subroutines of Visiting
250 The @code{find-file-noselect} function uses two important subroutines
251 which are sometimes useful in user Lisp code: @code{create-file-buffer}
252 and @code{after-find-file}. This section explains how to use them.
254 @defun create-file-buffer filename
255 This function creates a suitably named buffer for visiting
256 @var{filename}, and returns it. It uses @var{filename} (sans directory)
257 as the name if that name is free; otherwise, it appends a string such as
258 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
260 @strong{Please note:} @code{create-file-buffer} does @emph{not}
261 associate the new buffer with a file and does not select the buffer.
262 It also does not use the default major mode.
266 (create-file-buffer "foo")
267 @result{} #<buffer foo>
270 (create-file-buffer "foo")
271 @result{} #<buffer foo<2>>
274 (create-file-buffer "foo")
275 @result{} #<buffer foo<3>>
279 This function is used by @code{find-file-noselect}.
280 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
283 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
284 This function sets the buffer major mode, and parses local variables
285 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
286 and by the default revert function (@pxref{Reverting}).
288 @cindex new file message
289 @cindex file open error
290 If reading the file got an error because the file does not exist, but
291 its directory does exist, the caller should pass a non-@code{nil} value
292 for @var{error}. In that case, @code{after-find-file} issues a warning:
293 @samp{(New file)}. For more serious errors, the caller should usually not
294 call @code{after-find-file}.
296 If @var{warn} is non-@code{nil}, then this function issues a warning
297 if an auto-save file exists and is more recent than the visited file.
299 If @var{noauto} is non-@code{nil}, that says not to enable or disable
300 Auto-Save mode. The mode remains enabled if it was enabled before.
302 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
303 means this call was from @code{revert-buffer}. This has no direct
304 effect, but some mode functions and hook functions check the value
307 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
308 major mode, don't process local variables specifications in the file,
309 and don't run @code{find-file-hook}. This feature is used by
310 @code{revert-buffer} in some cases.
312 The last thing @code{after-find-file} does is call all the functions
313 in the list @code{find-file-hook}.
317 @section Saving Buffers
318 @cindex saving buffers
320 When you edit a file in Emacs, you are actually working on a buffer
321 that is visiting that file---that is, the contents of the file are
322 copied into the buffer and the copy is what you edit. Changes to the
323 buffer do not change the file until you @dfn{save} the buffer, which
324 means copying the contents of the buffer into the file.
326 @deffn Command save-buffer &optional backup-option
327 This function saves the contents of the current buffer in its visited
328 file if the buffer has been modified since it was last visited or saved.
329 Otherwise it does nothing.
331 @code{save-buffer} is responsible for making backup files. Normally,
332 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
333 file only if this is the first save since visiting the file. Other
334 values for @var{backup-option} request the making of backup files in
339 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
340 @code{save-buffer} function marks this version of the file to be
341 backed up when the buffer is next saved.
344 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
345 @code{save-buffer} function unconditionally backs up the previous
346 version of the file before saving it.
349 With an argument of 0, unconditionally do @emph{not} make any backup file.
353 @deffn Command save-some-buffers &optional save-silently-p pred
354 @anchor{Definition of save-some-buffers}
355 This command saves some modified file-visiting buffers. Normally it
356 asks the user about each buffer. But if @var{save-silently-p} is
357 non-@code{nil}, it saves all the file-visiting buffers without querying
360 The optional @var{pred} argument controls which buffers to ask about
361 (or to save silently if @var{save-silently-p} is non-@code{nil}).
362 If it is @code{nil}, that means to ask only about file-visiting buffers.
363 If it is @code{t}, that means also offer to save certain other non-file
364 buffers---those that have a non-@code{nil} buffer-local value of
365 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
366 @samp{yes} to saving a non-file buffer is asked to specify the file
367 name to use. The @code{save-buffers-kill-emacs} function passes the
368 value @code{t} for @var{pred}.
370 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
371 a function of no arguments. It will be called in each buffer to decide
372 whether to offer to save that buffer. If it returns a non-@code{nil}
373 value in a certain buffer, that means do offer to save that buffer.
376 @deffn Command write-file filename &optional confirm
377 @anchor{Definition of write-file}
378 This function writes the current buffer into file @var{filename}, makes
379 the buffer visit that file, and marks it not modified. Then it renames
380 the buffer based on @var{filename}, appending a string like @samp{<2>}
381 if necessary to make a unique buffer name. It does most of this work by
382 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
385 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
386 before overwriting an existing file. Interactively, confirmation is
387 required, unless the user supplies a prefix argument.
389 If @var{filename} is an existing directory, or a symbolic link to one,
390 @code{write-file} uses the name of the visited file, in directory
391 @var{filename}. If the buffer is not visiting a file, it uses the
395 Saving a buffer runs several hooks. It also performs format
396 conversion (@pxref{Format Conversion}).
398 @defvar write-file-functions
399 The value of this variable is a list of functions to be called before
400 writing out a buffer to its visited file. If one of them returns
401 non-@code{nil}, the file is considered already written and the rest of
402 the functions are not called, nor is the usual code for writing the file
405 If a function in @code{write-file-functions} returns non-@code{nil}, it
406 is responsible for making a backup file (if that is appropriate).
407 To do so, execute the following code:
410 (or buffer-backed-up (backup-buffer))
413 You might wish to save the file modes value returned by
414 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
415 bits of the file that you write. This is what @code{save-buffer}
416 normally does. @xref{Making Backups,, Making Backup Files}.
418 The hook functions in @code{write-file-functions} are also responsible
419 for encoding the data (if desired): they must choose a suitable coding
420 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
421 perform the encoding (@pxref{Explicit Encoding}), and set
422 @code{last-coding-system-used} to the coding system that was used
423 (@pxref{Encoding and I/O}).
425 If you set this hook locally in a buffer, it is assumed to be
426 associated with the file or the way the contents of the buffer were
427 obtained. Thus the variable is marked as a permanent local, so that
428 changing the major mode does not alter a buffer-local value. On the
429 other hand, calling @code{set-visited-file-name} will reset it.
430 If this is not what you want, you might like to use
431 @code{write-contents-functions} instead.
433 Even though this is not a normal hook, you can use @code{add-hook} and
434 @code{remove-hook} to manipulate the list. @xref{Hooks}.
438 @defvar write-contents-functions
439 This works just like @code{write-file-functions}, but it is intended
440 for hooks that pertain to the buffer's contents, not to the particular
441 visited file or its location. Such hooks are usually set up by major
442 modes, as buffer-local bindings for this variable. This variable
443 automatically becomes buffer-local whenever it is set; switching to a
444 new major mode always resets this variable, but calling
445 @code{set-visited-file-name} does not.
447 If any of the functions in this hook returns non-@code{nil}, the file
448 is considered already written and the rest are not called and neither
449 are the functions in @code{write-file-functions}.
452 @defopt before-save-hook
453 This normal hook runs before a buffer is saved in its visited file,
454 regardless of whether that is done normally or by one of the hooks
455 described above. For instance, the @file{copyright.el} program uses
456 this hook to make sure the file you are saving has the current year in
457 its copyright notice.
461 @defopt after-save-hook
462 This normal hook runs after a buffer has been saved in its visited file.
463 One use of this hook is in Fast Lock mode; it uses this hook to save the
464 highlighting information in a cache file.
467 @defopt file-precious-flag
468 If this variable is non-@code{nil}, then @code{save-buffer} protects
469 against I/O errors while saving by writing the new file to a temporary
470 name instead of the name it is supposed to have, and then renaming it to
471 the intended name after it is clear there are no errors. This procedure
472 prevents problems such as a lack of disk space from resulting in an
475 As a side effect, backups are necessarily made by copying. @xref{Rename
476 or Copy}. Yet, at the same time, saving a precious file always breaks
477 all hard links between the file you save and other file names.
479 Some modes give this variable a non-@code{nil} buffer-local value
480 in particular buffers.
483 @defopt require-final-newline
484 This variable determines whether files may be written out that do
485 @emph{not} end with a newline. If the value of the variable is
486 @code{t}, then @code{save-buffer} silently adds a newline at the end of
487 the file whenever the buffer being saved does not already end in one.
488 If the value of the variable is non-@code{nil}, but not @code{t}, then
489 @code{save-buffer} asks the user whether to add a newline each time the
492 If the value of the variable is @code{nil}, then @code{save-buffer}
493 doesn't add newlines at all. @code{nil} is the default value, but a few
494 major modes set it to @code{t} in particular buffers.
497 See also the function @code{set-visited-file-name} (@pxref{Buffer File
500 @node Reading from Files
501 @comment node-name, next, previous, up
502 @section Reading from Files
503 @cindex reading from files
505 You can copy a file from the disk and insert it into a buffer
506 using the @code{insert-file-contents} function. Don't use the user-level
507 command @code{insert-file} in a Lisp program, as that sets the mark.
509 @defun insert-file-contents filename &optional visit beg end replace
510 This function inserts the contents of file @var{filename} into the
511 current buffer after point. It returns a list of the absolute file name
512 and the length of the data inserted. An error is signaled if
513 @var{filename} is not the name of a file that can be read.
515 The function @code{insert-file-contents} checks the file contents
516 against the defined file formats, and converts the file contents if
517 appropriate and also calls the functions in
518 the list @code{after-insert-file-functions}. @xref{Format Conversion}.
519 Normally, one of the functions in the
520 @code{after-insert-file-functions} list determines the coding system
521 (@pxref{Coding Systems}) used for decoding the file's contents,
522 including end-of-line conversion. However, if the file contains null
523 bytes, it is by default visited without any code conversions; see
524 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
525 control this behavior.
527 If @var{visit} is non-@code{nil}, this function additionally marks the
528 buffer as unmodified and sets up various fields in the buffer so that it
529 is visiting the file @var{filename}: these include the buffer's visited
530 file name and its last save file modtime. This feature is used by
531 @code{find-file-noselect} and you probably should not use it yourself.
533 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
534 specifying the portion of the file to insert. In this case, @var{visit}
535 must be @code{nil}. For example,
538 (insert-file-contents filename nil 0 500)
542 inserts the first 500 characters of a file.
544 If the argument @var{replace} is non-@code{nil}, it means to replace the
545 contents of the buffer (actually, just the accessible portion) with the
546 contents of the file. This is better than simply deleting the buffer
547 contents and inserting the whole file, because (1) it preserves some
548 marker positions and (2) it puts less data in the undo list.
550 It is possible to read a special file (such as a FIFO or an I/O device)
551 with @code{insert-file-contents}, as long as @var{replace} and
552 @var{visit} are @code{nil}.
555 @defun insert-file-contents-literally filename &optional visit beg end replace
556 This function works like @code{insert-file-contents} except that it does
557 not do format decoding (@pxref{Format Conversion}), does not do
558 character code conversion (@pxref{Coding Systems}), does not run
559 @code{find-file-hook}, does not perform automatic uncompression, and so
563 If you want to pass a file name to another process so that another
564 program can read the file, use the function @code{file-local-copy}; see
565 @ref{Magic File Names}.
567 @node Writing to Files
568 @comment node-name, next, previous, up
569 @section Writing to Files
570 @cindex writing to files
572 You can write the contents of a buffer, or part of a buffer, directly
573 to a file on disk using the @code{append-to-file} and
574 @code{write-region} functions. Don't use these functions to write to
575 files that are being visited; that could cause confusion in the
576 mechanisms for visiting.
578 @deffn Command append-to-file start end filename
579 This function appends the contents of the region delimited by
580 @var{start} and @var{end} in the current buffer to the end of file
581 @var{filename}. If that file does not exist, it is created. This
582 function returns @code{nil}.
584 An error is signaled if @var{filename} specifies a nonwritable file,
585 or a nonexistent file in a directory where files cannot be created.
587 When called from Lisp, this function is completely equivalent to:
590 (write-region start end filename t)
594 @deffn Command write-region start end filename &optional append visit lockname mustbenew
595 This function writes the region delimited by @var{start} and @var{end}
596 in the current buffer into the file specified by @var{filename}.
598 If @var{start} is @code{nil}, then the command writes the entire buffer
599 contents (@emph{not} just the accessible portion) to the file and
603 If @var{start} is a string, then @code{write-region} writes or appends
604 that string, rather than text from the buffer. @var{end} is ignored in
607 If @var{append} is non-@code{nil}, then the specified text is appended
608 to the existing file contents (if any). If @var{append} is an
609 integer, @code{write-region} seeks to that byte offset from the start
610 of the file and writes the data from there.
612 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
613 for confirmation if @var{filename} names an existing file. If
614 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
615 does not ask for confirmation, but instead it signals an error
616 @code{file-already-exists} if the file already exists.
618 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
619 a special system feature. At least for files on a local disk, there is
620 no chance that some other program could create a file of the same name
621 before Emacs does, without Emacs's noticing.
623 If @var{visit} is @code{t}, then Emacs establishes an association
624 between the buffer and the file: the buffer is then visiting that file.
625 It also sets the last file modification time for the current buffer to
626 @var{filename}'s modtime, and marks the buffer as not modified. This
627 feature is used by @code{save-buffer}, but you probably should not use
631 If @var{visit} is a string, it specifies the file name to visit. This
632 way, you can write the data to one file (@var{filename}) while recording
633 the buffer as visiting another file (@var{visit}). The argument
634 @var{visit} is used in the echo area message and also for file locking;
635 @var{visit} is stored in @code{buffer-file-name}. This feature is used
636 to implement @code{file-precious-flag}; don't use it yourself unless you
637 really know what you're doing.
639 The optional argument @var{lockname}, if non-@code{nil}, specifies the
640 file name to use for purposes of locking and unlocking, overriding
641 @var{filename} and @var{visit} for that purpose.
643 The function @code{write-region} converts the data which it writes to
644 the appropriate file formats specified by @code{buffer-file-format}
645 and also calls the functions in the list
646 @code{write-region-annotate-functions}.
647 @xref{Format Conversion}.
649 Normally, @code{write-region} displays the message @samp{Wrote
650 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
651 nor @code{nil} nor a string, then this message is inhibited. This
652 feature is useful for programs that use files for internal purposes,
653 files that the user does not need to know about.
656 @defmac with-temp-file file body@dots{}
657 @anchor{Definition of with-temp-file}
658 The @code{with-temp-file} macro evaluates the @var{body} forms with a
659 temporary buffer as the current buffer; then, at the end, it writes the
660 buffer contents into file @var{file}. It kills the temporary buffer
661 when finished, restoring the buffer that was current before the
662 @code{with-temp-file} form. Then it returns the value of the last form
665 The current buffer is restored even in case of an abnormal exit via
666 @code{throw} or error (@pxref{Nonlocal Exits}).
668 See also @code{with-temp-buffer} in @ref{Definition of
669 with-temp-buffer,, The Current Buffer}.
677 When two users edit the same file at the same time, they are likely
678 to interfere with each other. Emacs tries to prevent this situation
679 from arising by recording a @dfn{file lock} when a file is being
680 modified. (File locks are not implemented on Microsoft systems.)
681 Emacs can then detect the first attempt to modify a buffer visiting a
682 file that is locked by another Emacs job, and ask the user what to do.
683 The file lock is really a file, a symbolic link with a special name,
684 stored in the same directory as the file you are editing.
686 When you access files using NFS, there may be a small probability that
687 you and another user will both lock the same file ``simultaneously.''
688 If this happens, it is possible for the two users to make changes
689 simultaneously, but Emacs will still warn the user who saves second.
690 Also, the detection of modification of a buffer visiting a file changed
691 on disk catches some cases of simultaneous editing; see
692 @ref{Modification Time}.
694 @defun file-locked-p filename
695 This function returns @code{nil} if the file @var{filename} is not
696 locked. It returns @code{t} if it is locked by this Emacs process, and
697 it returns the name of the user who has locked it if it is locked by
702 (file-locked-p "foo")
708 @defun lock-buffer &optional filename
709 This function locks the file @var{filename}, if the current buffer is
710 modified. The argument @var{filename} defaults to the current buffer's
711 visited file. Nothing is done if the current buffer is not visiting a
712 file, or is not modified, or if the system does not support locking.
716 This function unlocks the file being visited in the current buffer,
717 if the buffer is modified. If the buffer is not modified, then
718 the file should not be locked, so this function does nothing. It also
719 does nothing if the current buffer is not visiting a file, or if the
720 system does not support locking.
723 File locking is not supported on some systems. On systems that do not
724 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
725 @code{file-locked-p} do nothing and return @code{nil}.
727 @defun ask-user-about-lock file other-user
728 This function is called when the user tries to modify @var{file}, but it
729 is locked by another user named @var{other-user}. The default
730 definition of this function asks the user to say what to do. The value
731 this function returns determines what Emacs does next:
735 A value of @code{t} says to grab the lock on the file. Then
736 this user may edit the file and @var{other-user} loses the lock.
739 A value of @code{nil} says to ignore the lock and let this
740 user edit the file anyway.
744 This function may instead signal a @code{file-locked} error, in which
745 case the change that the user was about to make does not take place.
747 The error message for this error looks like this:
750 @error{} File is locked: @var{file} @var{other-user}
754 where @code{file} is the name of the file and @var{other-user} is the
755 name of the user who has locked the file.
758 If you wish, you can replace the @code{ask-user-about-lock} function
759 with your own version that makes the decision in another way. The code
760 for its usual definition is in @file{userlock.el}.
763 @node Information about Files
764 @section Information about Files
765 @cindex file, information about
767 The functions described in this section all operate on strings that
768 designate file names. With a few exceptions, all the functions have
769 names that begin with the word @samp{file}. These functions all
770 return information about actual files or directories, so their
771 arguments must all exist as actual files or directories unless
775 * Testing Accessibility:: Is a given file readable? Writable?
776 * Kinds of Files:: Is it a directory? A symbolic link?
777 * Truenames:: Eliminating symbolic links from a file name.
778 * File Attributes:: How large is it? Any other names? Etc.
779 * Locating Files:: How to find a file in standard places.
782 @node Testing Accessibility
783 @comment node-name, next, previous, up
784 @subsection Testing Accessibility
785 @cindex accessibility of a file
786 @cindex file accessibility
788 These functions test for permission to access a file in specific
789 ways. Unless explicitly stated otherwise, they recursively follow
790 symbolic links for their file name arguments, at all levels (at the
791 level of the file itself and at all levels of parent directories).
793 @defun file-exists-p filename
794 This function returns @code{t} if a file named @var{filename} appears
795 to exist. This does not mean you can necessarily read the file, only
796 that you can find out its attributes. (On Unix and GNU/Linux, this is
797 true if the file exists and you have execute permission on the
798 containing directories, regardless of the protection of the file
801 If the file does not exist, or if fascist access control policies
802 prevent you from finding the attributes of the file, this function
805 Directories are files, so @code{file-exists-p} returns @code{t} when
806 given a directory name. However, symbolic links are treated
807 specially; @code{file-exists-p} returns @code{t} for a symbolic link
808 name only if the target file exists.
811 @defun file-readable-p filename
812 This function returns @code{t} if a file named @var{filename} exists
813 and you can read it. It returns @code{nil} otherwise.
817 (file-readable-p "files.texi")
821 (file-exists-p "/usr/spool/mqueue")
825 (file-readable-p "/usr/spool/mqueue")
832 @defun file-executable-p filename
833 This function returns @code{t} if a file named @var{filename} exists and
834 you can execute it. It returns @code{nil} otherwise. On Unix and
835 GNU/Linux, if the file is a directory, execute permission means you can
836 check the existence and attributes of files inside the directory, and
837 open those files if their modes permit.
840 @defun file-writable-p filename
841 This function returns @code{t} if the file @var{filename} can be written
842 or created by you, and @code{nil} otherwise. A file is writable if the
843 file exists and you can write it. It is creatable if it does not exist,
844 but the specified directory does exist and you can write in that
847 In the third example below, @file{foo} is not writable because the
848 parent directory does not exist, even though the user could create such
853 (file-writable-p "~/foo")
857 (file-writable-p "/foo")
861 (file-writable-p "~/no-such-dir/foo")
868 @defun file-accessible-directory-p dirname
869 This function returns @code{t} if you have permission to open existing
870 files in the directory whose name as a file is @var{dirname};
871 otherwise (or if there is no such directory), it returns @code{nil}.
872 The value of @var{dirname} may be either a directory name (such as
873 @file{/foo/}) or the file name of a file which is a directory
874 (such as @file{/foo}, without the final slash).
876 Example: after the following,
879 (file-accessible-directory-p "/foo")
884 we can deduce that any attempt to read a file in @file{/foo/} will
888 @defun access-file filename string
889 This function opens file @var{filename} for reading, then closes it and
890 returns @code{nil}. However, if the open fails, it signals an error
891 using @var{string} as the error message text.
894 @defun file-ownership-preserved-p filename
895 This function returns @code{t} if deleting the file @var{filename} and
896 then creating it anew would keep the file's owner unchanged. It also
897 returns @code{t} for nonexistent files.
899 If @var{filename} is a symbolic link, then, unlike the other functions
900 discussed here, @code{file-ownership-preserved-p} does @emph{not}
901 replace @var{filename} with its target. However, it does recursively
902 follow symbolic links at all levels of parent directories.
905 @defun file-newer-than-file-p filename1 filename2
907 @cindex file modification time
908 This function returns @code{t} if the file @var{filename1} is
909 newer than file @var{filename2}. If @var{filename1} does not
910 exist, it returns @code{nil}. If @var{filename1} does exist, but
911 @var{filename2} does not, it returns @code{t}.
913 In the following example, assume that the file @file{aug-19} was written
914 on the 19th, @file{aug-20} was written on the 20th, and the file
915 @file{no-file} doesn't exist at all.
919 (file-newer-than-file-p "aug-19" "aug-20")
923 (file-newer-than-file-p "aug-20" "aug-19")
927 (file-newer-than-file-p "aug-19" "no-file")
931 (file-newer-than-file-p "no-file" "aug-19")
936 You can use @code{file-attributes} to get a file's last modification
937 time as a list of two numbers. @xref{File Attributes}.
941 @comment node-name, next, previous, up
942 @subsection Distinguishing Kinds of Files
944 This section describes how to distinguish various kinds of files, such
945 as directories, symbolic links, and ordinary files.
947 @defun file-symlink-p filename
948 @cindex file symbolic links
949 If the file @var{filename} is a symbolic link, the
950 @code{file-symlink-p} function returns the (non-recursive) link target
951 as a string. (Determining the file name that the link points to from
952 the target is nontrivial.) First, this function recursively follows
953 symbolic links at all levels of parent directories.
955 If the file @var{filename} is not a symbolic link (or there is no such file),
956 @code{file-symlink-p} returns @code{nil}.
960 (file-symlink-p "foo")
964 (file-symlink-p "sym-link")
968 (file-symlink-p "sym-link2")
972 (file-symlink-p "/bin")
977 @c !!! file-symlink-p: should show output of ls -l for comparison
980 The next two functions recursively follow symbolic links at
981 all levels for @var{filename}.
983 @defun file-directory-p filename
984 This function returns @code{t} if @var{filename} is the name of an
985 existing directory, @code{nil} otherwise.
989 (file-directory-p "~rms")
993 (file-directory-p "~rms/lewis/files.texi")
997 (file-directory-p "~rms/lewis/no-such-file")
1001 (file-directory-p "$HOME")
1006 (substitute-in-file-name "$HOME"))
1012 @defun file-regular-p filename
1013 This function returns @code{t} if the file @var{filename} exists and is
1014 a regular file (not a directory, named pipe, terminal, or
1019 @subsection Truenames
1020 @cindex truename (of file)
1022 @c Emacs 19 features
1023 The @dfn{truename} of a file is the name that you get by following
1024 symbolic links at all levels until none remain, then simplifying away
1025 @samp{.}@: and @samp{..}@: appearing as name components. This results
1026 in a sort of canonical name for the file. A file does not always have a
1027 unique truename; the number of distinct truenames a file has is equal to
1028 the number of hard links to the file. However, truenames are useful
1029 because they eliminate symbolic links as a cause of name variation.
1031 @defun file-truename filename
1032 The function @code{file-truename} returns the truename of the file
1033 @var{filename}. If the argument is not an absolute file name,
1034 this function first expands it against @code{default-directory}.
1036 This function does not expand environment variables. Only
1037 @code{substitute-in-file-name} does that. @xref{Definition of
1038 substitute-in-file-name}.
1040 If you may need to follow symbolic links preceding @samp{..}@:
1041 appearing as a name component, you should make sure to call
1042 @code{file-truename} without prior direct or indirect calls to
1043 @code{expand-file-name}, as otherwise the file name component
1044 immediately preceding @samp{..} will be ``simplified away'' before
1045 @code{file-truename} is called. To eliminate the need for a call to
1046 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1047 same way that @code{expand-file-name} does. @xref{File Name
1048 Expansion,, Functions that Expand Filenames}.
1051 @defun file-chase-links filename &optional limit
1052 This function follows symbolic links, starting with @var{filename},
1053 until it finds a file name which is not the name of a symbolic link.
1054 Then it returns that file name. This function does @emph{not} follow
1055 symbolic links at the level of parent directories.
1057 If you specify a number for @var{limit}, then after chasing through
1058 that many links, the function just returns what it has even if that is
1059 still a symbolic link.
1062 To illustrate the difference between @code{file-chase-links} and
1063 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1064 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1065 ordinary file (or at least, not a symbolic link) or nonexistent. Then
1069 (file-chase-links "/usr/foo/hello")
1070 ;; @r{This does not follow the links in the parent directories.}
1071 @result{} "/usr/foo/hello"
1072 (file-truename "/usr/foo/hello")
1073 ;; @r{Assuming that @file{/home} is not a symbolic link.}
1074 @result{} "/home/foo/hello"
1077 @xref{Buffer File Name}, for related information.
1079 @node File Attributes
1080 @comment node-name, next, previous, up
1081 @subsection Other Information about Files
1083 This section describes the functions for getting detailed information
1084 about a file, other than its contents. This information includes the
1085 mode bits that control access permission, the owner and group numbers,
1086 the number of names, the inode number, the size, and the times of access
1089 @defun file-modes filename
1091 @cindex file attributes
1092 This function returns the mode bits of @var{filename}, as an integer.
1093 The mode bits are also called the file permissions, and they specify
1094 access control in the usual Unix fashion. If the low-order bit is 1,
1095 then the file is executable by all users, if the second-lowest-order bit
1096 is 1, then the file is writable by all users, etc.
1098 The highest value returnable is 4095 (7777 octal), meaning that
1099 everyone has read, write, and execute permission, that the @acronym{SUID} bit
1100 is set for both others and group, and that the sticky bit is set.
1102 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
1104 This function recursively follows symbolic links at all levels.
1108 (file-modes "~/junk/diffs")
1109 @result{} 492 ; @r{Decimal integer.}
1113 @result{} "754" ; @r{Convert to octal.}
1117 (set-file-modes "~/junk/diffs" 438)
1123 @result{} "666" ; @r{Convert to octal.}
1128 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1133 If the @var{filename} argument to the next two functions is a symbolic
1134 link, then these function do @emph{not} replace it with its target.
1135 However, they both recursively follow symbolic links at all levels of
1138 @defun file-nlinks filename
1139 This functions returns the number of names (i.e., hard links) that
1140 file @var{filename} has. If the file does not exist, then this function
1141 returns @code{nil}. Note that symbolic links have no effect on this
1142 function, because they are not considered to be names of the files they
1148 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1149 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1157 (file-nlinks "doesnt-exist")
1163 @defun file-attributes filename &optional id-format
1164 @anchor{Definition of file-attributes}
1165 This function returns a list of attributes of file @var{filename}. If
1166 the specified file cannot be opened, it returns @code{nil}.
1167 The optional parameter @var{id-format} specifies the preferred format
1168 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1169 valid values are @code{'string} and @code{'integer}. The latter is
1170 the default, but we plan to change that, so you should specify a
1171 non-@code{nil} value for @var{id-format} if you use the returned
1172 @acronym{UID} or @acronym{GID}.
1174 The elements of the list, in order, are:
1178 @code{t} for a directory, a string for a symbolic link (the name
1179 linked to), or @code{nil} for a text file.
1181 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
1183 The number of names the file has. Alternate names, also known as hard
1184 links, can be created by using the @code{add-name-to-file} function
1185 (@pxref{Changing Files}).
1188 The file's @acronym{UID}, normally as a string. However, if it does
1189 not correspond to a named user, the value is an integer or a floating
1193 The file's @acronym{GID}, likewise.
1196 The time of last access, as a list of two integers.
1197 The first integer has the high-order 16 bits of time,
1198 the second has the low 16 bits. (This is similar to the
1199 value of @code{current-time}; see @ref{Time of Day}.) Note that on
1200 some FAT-based filesystems, only the date of last access is recorded,
1201 so this time will always hold the midnight of the day of last access.
1203 @cindex modification time of file
1205 The time of last modification as a list of two integers (as above).
1206 This is the last time when the file's contents were modified.
1209 The time of last status change as a list of two integers (as above).
1210 This is the time of the last change to the file's access mode bits,
1211 its owner and group, and other information recorded in the filesystem
1212 for the file, beyond the file's contents.
1215 The size of the file in bytes. If the size is too large to fit in a
1216 Lisp integer, this is a floating point number.
1219 The file's modes, as a string of ten letters or dashes,
1223 @code{t} if the file's @acronym{GID} would change if file were
1224 deleted and recreated; @code{nil} otherwise.
1227 The file's inode number. If possible, this is an integer. If the
1228 inode number is too large to be represented as an integer in Emacs
1229 Lisp but dividing it by @math{2^16} yields a representable integer,
1230 then the value has the
1231 form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
1232 bits. If the inode number is too wide for even that, the value is of the form
1233 @code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
1234 the high bits, @var{middle} the middle 24 bits, and @var{low} the low
1238 The filesystem number of the device that the file is on. Depending on
1239 the magnitude of the value, this can be either an integer or a cons
1240 cell, in the same manner as the inode number. This element and the
1241 file's inode number together give enough information to distinguish
1242 any two files on the system---no two files can have the same values
1243 for both of these numbers.
1246 For example, here are the file attributes for @file{files.texi}:
1250 (file-attributes "files.texi" 'string)
1251 @result{} (nil 1 "lh" "users"
1256 nil (5888 2 . 43978)
1262 and here is how the result is interpreted:
1266 is neither a directory nor a symbolic link.
1269 has only one name (the name @file{files.texi} in the current default
1273 is owned by the user with name "lh".
1276 is in the group with name "users".
1279 was last accessed on Oct 5 2009, at 10:01:37.
1282 last had its contents modified on Oct 2 2009, at 13:49:12.
1285 last had its status changed on Feb 2 2008, at 12:19:00.
1288 is 122295 bytes long. (It may not contain 122295 characters, though,
1289 if some of the bytes belong to multibyte sequences, and also if the
1290 end-of-line format is CR-LF.)
1293 has a mode of read and write access for the owner, group, and world.
1296 would retain the same @acronym{GID} if it were recreated.
1298 @item (5888 2 . 43978)
1299 has an inode number of 6473924464520138.
1301 @item (15479 . 46724)
1302 is on the file-system device whose number is 1014478468.
1306 @cindex MS-DOS and file modes
1307 @cindex file modes and MS-DOS
1308 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1309 So Emacs considers a file executable if its name ends in one of the
1310 standard executable extensions, such as @file{.com}, @file{.bat},
1311 @file{.exe}, and some others. Files that begin with the Unix-standard
1312 @samp{#!} signature, such as shell and Perl scripts, are also considered
1313 as executable files. This is reflected in the values returned by
1314 @code{file-modes} and @code{file-attributes}. Directories are also
1315 reported with executable bit set, for compatibility with Unix.
1317 @node Locating Files
1318 @subsection How to Locate Files in Standard Places
1319 @cindex locate file in path
1320 @cindex find file in path
1322 This section explains how to search for a file in a list of
1323 directories (a @dfn{path}). One example is when you need to look for
1324 a program's executable file, e.g., to find out whether a given program
1325 is installed on the user's system. Another example is the search for
1326 Lisp libraries (@pxref{Library Search}). Such searches generally need
1327 to try various possible file name extensions, in addition to various
1328 possible directories. Emacs provides a function for such a
1329 generalized search for a file.
1331 @defun locate-file filename path &optional suffixes predicate
1332 This function searches for a file whose name is @var{filename} in a
1333 list of directories given by @var{path}, trying the suffixes in
1334 @var{suffixes}. If it finds such a file, it returns the full
1335 @dfn{absolute file name} of the file (@pxref{Relative File Names});
1336 otherwise it returns @code{nil}.
1338 The optional argument @var{suffixes} gives the list of file-name
1339 suffixes to append to @var{filename} when searching.
1340 @code{locate-file} tries each possible directory with each of these
1341 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
1342 are no suffixes, and @var{filename} is used only as-is. Typical
1343 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
1344 Creation, exec-suffixes}), @code{load-suffixes},
1345 @code{load-file-rep-suffixes} and the return value of the function
1346 @code{get-load-suffixes} (@pxref{Load Suffixes}).
1348 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
1349 Creation, exec-path}) when looking for executable programs or
1350 @code{load-path} (@pxref{Library Search, load-path}) when looking for
1351 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
1352 but the suffixes in @var{suffixes} are still tried.
1354 The optional argument @var{predicate}, if non-@code{nil}, specifies
1355 the predicate function to use for testing whether a candidate file is
1356 suitable. The predicate function is passed the candidate file name as
1357 its single argument. If @var{predicate} is @code{nil} or unspecified,
1358 @code{locate-file} uses @code{file-readable-p} as the default
1359 predicate. Useful non-default predicates include
1360 @code{file-executable-p}, @code{file-directory-p}, and other
1361 predicates described in @ref{Kinds of Files}.
1363 For compatibility, @var{predicate} can also be one of the symbols
1364 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
1365 a list of one or more of these symbols.
1368 @defun executable-find program
1369 This function searches for the executable file of the named
1370 @var{program} and returns the full absolute name of the executable,
1371 including its file-name extensions, if any. It returns @code{nil} if
1372 the file is not found. The functions searches in all the directories
1373 in @code{exec-path} and tries all the file-name extensions in
1374 @code{exec-suffixes}.
1377 @node Changing Files
1378 @section Changing File Names and Attributes
1379 @c @cindex renaming files Duplicates rename-file
1380 @cindex copying files
1381 @cindex deleting files
1382 @cindex linking files
1383 @cindex setting modes of files
1385 The functions in this section rename, copy, delete, link, and set the
1388 In the functions that have an argument @var{newname}, if a file by the
1389 name of @var{newname} already exists, the actions taken depend on the
1390 value of the argument @var{ok-if-already-exists}:
1394 Signal a @code{file-already-exists} error if
1395 @var{ok-if-already-exists} is @code{nil}.
1398 Request confirmation if @var{ok-if-already-exists} is a number.
1401 Replace the old file without confirmation if @var{ok-if-already-exists}
1405 The next four commands all recursively follow symbolic links at all
1406 levels of parent directories for their first argument, but, if that
1407 argument is itself a symbolic link, then only @code{copy-file}
1408 replaces it with its (recursive) target.
1410 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1411 @cindex file with multiple names
1412 @cindex file hard link
1413 This function gives the file named @var{oldname} the additional name
1414 @var{newname}. This means that @var{newname} becomes a new ``hard
1415 link'' to @var{oldname}.
1417 In the first part of the following example, we list two files,
1418 @file{foo} and @file{foo3}.
1423 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1424 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1428 Now we create a hard link, by calling @code{add-name-to-file}, then list
1429 the files again. This shows two names for one file, @file{foo} and
1434 (add-name-to-file "foo" "foo2")
1440 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1441 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1442 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1446 Finally, we evaluate the following:
1449 (add-name-to-file "foo" "foo3" t)
1453 and list the files again. Now there are three names
1454 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1455 contents of @file{foo3} are lost.
1459 (add-name-to-file "foo1" "foo3")
1465 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1466 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1467 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1471 This function is meaningless on operating systems where multiple names
1472 for one file are not allowed. Some systems implement multiple names
1473 by copying the file instead.
1475 See also @code{file-nlinks} in @ref{File Attributes}.
1478 @deffn Command rename-file filename newname &optional ok-if-already-exists
1479 This command renames the file @var{filename} as @var{newname}.
1481 If @var{filename} has additional names aside from @var{filename}, it
1482 continues to have those names. In fact, adding the name @var{newname}
1483 with @code{add-name-to-file} and then deleting @var{filename} has the
1484 same effect as renaming, aside from momentary intermediate states.
1487 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
1488 This command copies the file @var{oldname} to @var{newname}. An
1489 error is signaled if @var{oldname} does not exist. If @var{newname}
1490 names a directory, it copies @var{oldname} into that directory,
1491 preserving its final name component.
1493 If @var{time} is non-@code{nil}, then this function gives the new file
1494 the same last-modified time that the old one has. (This works on only
1495 some operating systems.) If setting the time gets an error,
1496 @code{copy-file} signals a @code{file-date-error} error. In an
1497 interactive call, a prefix argument specifies a non-@code{nil} value
1500 This function copies the file modes, too.
1502 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
1503 system decide the user and group ownership of the new file (this is
1504 usually set to the user running Emacs). If @var{preserve-uid-gid} is
1505 non-@code{nil}, we attempt to copy the user and group ownership of the
1506 file. This works only on some operating systems, and only if you have
1507 the correct permissions to do so.
1510 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
1512 @kindex file-already-exists
1513 This command makes a symbolic link to @var{filename}, named
1514 @var{newname}. This is like the shell command @samp{ln -s
1515 @var{filename} @var{newname}}.
1517 This function is not available on systems that don't support symbolic
1522 @vindex delete-by-moving-to-trash
1523 @deffn Command delete-file filename &optional trash
1525 This command deletes the file @var{filename}. If the file has
1526 multiple names, it continues to exist under the other names. If
1527 @var{filename} is a symbolic link, @code{delete-file} deletes only the
1528 symbolic link and not its target (though it does follow symbolic links
1529 at all levels of parent directories).
1531 A suitable kind of @code{file-error} error is signaled if the file
1532 does not exist, or is not deletable. (On Unix and GNU/Linux, a file
1533 is deletable if its directory is writable.)
1535 If the optional argument @var{trash} is non-@code{nil} and the
1536 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
1537 command moves the file into the system Trash instead of deleting it.
1538 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
1539 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
1540 no prefix argument is given, and @code{nil} otherwise.
1542 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1545 @deffn Command set-file-modes filename mode
1546 This function sets mode bits of @var{filename} to @var{mode} (which
1547 must be an integer when the function is called non-interactively).
1548 Only the low 12 bits of @var{mode} are used.
1550 Interactively, @var{mode} is read from the minibuffer using
1551 @code{read-file-modes}, which accepts mode bits either as a number or
1552 as a character string representing the mode bits symbolically. See
1553 the description of @code{read-file-modes} below for the supported
1554 forms of symbolic notation for mode bits.
1556 This function recursively follows symbolic links at all levels for
1561 @defun set-default-file-modes mode
1563 This function sets the default file protection for new files created by
1564 Emacs and its subprocesses. Every file created with Emacs initially has
1565 this protection, or a subset of it (@code{write-region} will not give a
1566 file execute permission even if the default file protection allows
1567 execute permission). On Unix and GNU/Linux, the default protection is
1568 the bitwise complement of the ``umask'' value.
1570 The argument @var{mode} must be an integer. On most systems, only the
1571 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
1572 for octal character codes to enter @var{mode}; for example,
1575 (set-default-file-modes ?\644)
1578 Saving a modified version of an existing file does not count as creating
1579 the file; it preserves the existing file's mode, whatever that is. So
1580 the default file protection has no effect.
1583 @defun default-file-modes
1584 This function returns the current default protection value.
1587 @defun read-file-modes &optional prompt base-file
1588 This function reads file mode bits from the minibuffer. The optional
1589 argument @var{prompt} specifies a non-default prompt. Second optional
1590 argument @var{base-file} is the name of a file on whose permissions to
1591 base the mode bits that this function returns, if what the user types
1592 specifies mode bits relative to permissions of an existing file.
1594 If user input represents an octal number, this function returns that
1595 number. If it is a complete symbolic specification of mode bits, as
1596 in @code{"u=rwx"}, the function converts it to the equivalent numeric
1597 value using @code{file-modes-symbolic-to-number} and returns the
1598 result. If the specification is relative, as in @code{"o+g"}, then
1599 the permissions on which the specification is based are taken from the
1600 mode bits of @var{base-file}. If @var{base-file} is omitted or
1601 @code{nil}, the function uses @code{0} as the base mode bits. The
1602 complete and relative specifications can be combined, as in
1603 @code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
1604 @sc{gnu} @code{Coreutils} Manual}, for detailed description of
1605 symbolic mode bits specifications.
1608 @defun file-modes-symbolic-to-number modes &optional base-modes
1609 This subroutine converts a symbolic specification of file mode bits in
1610 @var{modes} into the equivalent numeric value. If the symbolic
1611 specification is based on an existing file, that file's mode bits are
1612 taken from the optional argument @var{base-modes}; if that argument is
1613 omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
1617 @defun set-file-times filename &optional time
1618 This function sets the access and modification times of @var{filename}
1619 to @var{time}. The return value is @code{t} if the times are successfully
1620 set, otherwise it is @code{nil}. @var{time} defaults to the current
1621 time and must be in the format returned by @code{current-time}
1622 (@pxref{Time of Day}).
1629 Files are generally referred to by their names, in Emacs as elsewhere.
1630 File names in Emacs are represented as strings. The functions that
1631 operate on a file all expect a file name argument.
1633 In addition to operating on files themselves, Emacs Lisp programs
1634 often need to operate on file names; i.e., to take them apart and to use
1635 part of a name to construct related file names. This section describes
1636 how to manipulate file names.
1638 The functions in this section do not actually access files, so they
1639 can operate on file names that do not refer to an existing file or
1642 On MS-DOS and MS-Windows, these functions (like the function that
1643 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1644 where backslashes separate the components, as well as Unix syntax; but
1645 they always return Unix syntax. This enables Lisp programs to specify
1646 file names in Unix syntax and work properly on all systems without
1650 * File Name Components:: The directory part of a file name, and the rest.
1651 * Relative File Names:: Some file names are relative to a current directory.
1652 * Directory Names:: A directory's name as a directory
1653 is different from its name as a file.
1654 * File Name Expansion:: Converting relative file names to absolute ones.
1655 * Unique File Names:: Generating names for temporary files.
1656 * File Name Completion:: Finding the completions for a given file name.
1657 * Standard File Names:: If your package uses a fixed file name,
1658 how to handle various operating systems simply.
1661 @node File Name Components
1662 @subsection File Name Components
1663 @cindex directory part (of file name)
1664 @cindex nondirectory part (of file name)
1665 @cindex version number (in file name)
1667 The operating system groups files into directories. To specify a
1668 file, you must specify the directory and the file's name within that
1669 directory. Therefore, Emacs considers a file name as having two main
1670 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1671 (or @dfn{file name within the directory}). Either part may be empty.
1672 Concatenating these two parts reproduces the original file name.
1674 On most systems, the directory part is everything up to and including
1675 the last slash (backslash is also allowed in input on MS-DOS or
1676 MS-Windows); the nondirectory part is the rest.
1678 For some purposes, the nondirectory part is further subdivided into
1679 the name proper and the @dfn{version number}. On most systems, only
1680 backup files have version numbers in their names.
1682 @defun file-name-directory filename
1683 This function returns the directory part of @var{filename}, as a
1684 directory name (@pxref{Directory Names}), or @code{nil} if
1685 @var{filename} does not include a directory part.
1687 On GNU and Unix systems, a string returned by this function always
1688 ends in a slash. On MS-DOS it can also end in a colon.
1692 (file-name-directory "lewis/foo") ; @r{Unix example}
1696 (file-name-directory "foo") ; @r{Unix example}
1702 @defun file-name-nondirectory filename
1703 This function returns the nondirectory part of @var{filename}.
1707 (file-name-nondirectory "lewis/foo")
1711 (file-name-nondirectory "foo")
1715 (file-name-nondirectory "lewis/")
1721 @defun file-name-sans-versions filename &optional keep-backup-version
1722 This function returns @var{filename} with any file version numbers,
1723 backup version numbers, or trailing tildes discarded.
1725 If @var{keep-backup-version} is non-@code{nil}, then true file version
1726 numbers understood as such by the file system are discarded from the
1727 return value, but backup version numbers are kept.
1731 (file-name-sans-versions "~rms/foo.~1~")
1732 @result{} "~rms/foo"
1735 (file-name-sans-versions "~rms/foo~")
1736 @result{} "~rms/foo"
1739 (file-name-sans-versions "~rms/foo")
1740 @result{} "~rms/foo"
1745 @defun file-name-extension filename &optional period
1746 This function returns @var{filename}'s final ``extension,'' if any,
1747 after applying @code{file-name-sans-versions} to remove any
1748 version/backup part. The extension, in a file name, is the part that
1749 follows the last @samp{.} in the last name component (minus any
1750 version/backup part).
1752 This function returns @code{nil} for extensionless file names such as
1753 @file{foo}. It returns @code{""} for null extensions, as in
1754 @file{foo.}. If the last component of a file name begins with a
1755 @samp{.}, that @samp{.} doesn't count as the beginning of an
1756 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1759 If @var{period} is non-@code{nil}, then the returned value includes
1760 the period that delimits the extension, and if @var{filename} has no
1761 extension, the value is @code{""}.
1764 @defun file-name-sans-extension filename
1765 This function returns @var{filename} minus its extension, if any. The
1766 version/backup part, if present, is only removed if the file has an
1767 extension. For example,
1770 (file-name-sans-extension "foo.lose.c")
1771 @result{} "foo.lose"
1772 (file-name-sans-extension "big.hack/foo")
1773 @result{} "big.hack/foo"
1774 (file-name-sans-extension "/my/home/.emacs")
1775 @result{} "/my/home/.emacs"
1776 (file-name-sans-extension "/my/home/.emacs.el")
1777 @result{} "/my/home/.emacs"
1778 (file-name-sans-extension "~/foo.el.~3~")
1780 (file-name-sans-extension "~/foo.~3~")
1781 @result{} "~/foo.~3~"
1784 Note that the @samp{.~3~} in the two last examples is the backup part,
1789 @node Relative File Names
1790 @subsection Absolute and Relative File Names
1791 @cindex absolute file name
1792 @cindex relative file name
1794 All the directories in the file system form a tree starting at the
1795 root directory. A file name can specify all the directory names
1796 starting from the root of the tree; then it is called an @dfn{absolute}
1797 file name. Or it can specify the position of the file in the tree
1798 relative to a default directory; then it is called a @dfn{relative} file
1799 name. On Unix and GNU/Linux, an absolute file name starts with a slash
1800 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
1801 MS-Windows, an absolute file name starts with a slash or a backslash, or
1802 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1805 @defun file-name-absolute-p filename
1806 This function returns @code{t} if file @var{filename} is an absolute
1807 file name, @code{nil} otherwise.
1811 (file-name-absolute-p "~rms/foo")
1815 (file-name-absolute-p "rms/foo")
1819 (file-name-absolute-p "/user/rms/foo")
1825 Given a possibly relative file name, you can convert it to an
1826 absolute name using @code{expand-file-name} (@pxref{File Name
1827 Expansion}). This function converts absolute file names to relative
1830 @defun file-relative-name filename &optional directory
1831 This function tries to return a relative name that is equivalent to
1832 @var{filename}, assuming the result will be interpreted relative to
1833 @var{directory} (an absolute directory name or directory file name).
1834 If @var{directory} is omitted or @code{nil}, it defaults to the
1835 current buffer's default directory.
1837 On some operating systems, an absolute file name begins with a device
1838 name. On such systems, @var{filename} has no relative equivalent based
1839 on @var{directory} if they start with two different device names. In
1840 this case, @code{file-relative-name} returns @var{filename} in absolute
1844 (file-relative-name "/foo/bar" "/foo/")
1846 (file-relative-name "/foo/bar" "/hack/")
1847 @result{} "../foo/bar"
1851 @node Directory Names
1852 @comment node-name, next, previous, up
1853 @subsection Directory Names
1854 @cindex directory name
1855 @cindex file name of directory
1857 A @dfn{directory name} is the name of a directory. A directory is
1858 actually a kind of file, so it has a file name, which is related to
1859 the directory name but not identical to it. (This is not quite the
1860 same as the usual Unix terminology.) These two different names for
1861 the same entity are related by a syntactic transformation. On GNU and
1862 Unix systems, this is simple: a directory name ends in a slash,
1863 whereas the directory's name as a file lacks that slash. On MS-DOS
1864 the relationship is more complicated.
1866 The difference between a directory name and its name as a file is
1867 subtle but crucial. When an Emacs variable or function argument is
1868 described as being a directory name, a file name of a directory is not
1869 acceptable. When @code{file-name-directory} returns a string, that is
1870 always a directory name.
1872 The following two functions convert between directory names and file
1873 names. They do nothing special with environment variable substitutions
1874 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1876 @defun file-name-as-directory filename
1877 This function returns a string representing @var{filename} in a form
1878 that the operating system will interpret as the name of a directory. On
1879 most systems, this means appending a slash to the string (if it does not
1880 already end in one).
1884 (file-name-as-directory "~rms/lewis")
1885 @result{} "~rms/lewis/"
1890 @defun directory-file-name dirname
1891 This function returns a string representing @var{dirname} in a form that
1892 the operating system will interpret as the name of a file. On most
1893 systems, this means removing the final slash (or backslash) from the
1898 (directory-file-name "~lewis/")
1904 Given a directory name, you can combine it with a relative file name
1905 using @code{concat}:
1908 (concat @var{dirname} @var{relfile})
1912 Be sure to verify that the file name is relative before doing that.
1913 If you use an absolute file name, the results could be syntactically
1914 invalid or refer to the wrong file.
1916 If you want to use a directory file name in making such a
1917 combination, you must first convert it to a directory name using
1918 @code{file-name-as-directory}:
1921 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1925 Don't try concatenating a slash by hand, as in
1929 (concat @var{dirfile} "/" @var{relfile})
1933 because this is not portable. Always use
1934 @code{file-name-as-directory}.
1936 To convert a directory name to its abbreviation, use this
1939 @defun abbreviate-file-name filename
1940 @anchor{Definition of abbreviate-file-name}
1941 This function returns an abbreviated form of @var{filename}. It
1942 applies the abbreviations specified in @code{directory-abbrev-alist}
1943 (@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
1944 then substitutes @samp{~} for the user's home directory if the
1945 argument names a file in the home directory or one of its
1946 subdirectories. If the home directory is a root directory, it is not
1947 replaced with @samp{~}, because this does not make the result shorter
1950 You can use this function for directory names and for file names,
1951 because it recognizes abbreviations even as part of the name.
1954 @node File Name Expansion
1955 @subsection Functions that Expand Filenames
1956 @cindex expansion of file names
1958 @dfn{Expansion} of a file name means converting a relative file name
1959 to an absolute one. Since this is done relative to a default directory,
1960 you must specify the default directory name as well as the file name to
1961 be expanded. Expansion also simplifies file names by eliminating
1962 redundancies such as @file{./} and @file{@var{name}/../}.
1964 @defun expand-file-name filename &optional directory
1965 This function converts @var{filename} to an absolute file name. If
1966 @var{directory} is supplied, it is the default directory to start with
1967 if @var{filename} is relative. (The value of @var{directory} should
1968 itself be an absolute directory name or directory file name; it may
1969 start with @samp{~}.) Otherwise, the current buffer's value of
1970 @code{default-directory} is used. For example:
1974 (expand-file-name "foo")
1975 @result{} "/xcssun/users/rms/lewis/foo"
1978 (expand-file-name "../foo")
1979 @result{} "/xcssun/users/rms/foo"
1982 (expand-file-name "foo" "/usr/spool/")
1983 @result{} "/usr/spool/foo"
1986 (expand-file-name "$HOME/foo")
1987 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1991 If the part of the combined file name before the first slash is
1992 @samp{~}, it expands to the value of the @env{HOME} environment
1993 variable (usually your home directory). If the part before the first
1994 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
1995 it expands to @var{user}'s home directory.
1997 Filenames containing @samp{.} or @samp{..} are simplified to their
2002 (expand-file-name "bar/../foo")
2003 @result{} "/xcssun/users/rms/lewis/foo"
2007 In some cases, a leading @samp{..} component can remain in the output:
2011 (expand-file-name "../home" "/")
2012 @result{} "/../home"
2017 This is for the sake of filesystems that have the concept of a
2018 ``superroot'' above the root directory @file{/}. On other filesystems,
2019 @file{/../} is interpreted exactly the same as @file{/}.
2021 Note that @code{expand-file-name} does @emph{not} expand environment
2022 variables; only @code{substitute-in-file-name} does that.
2024 Note also that @code{expand-file-name} does not follow symbolic links
2025 at any level. This results in a difference between the way
2026 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
2027 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
2028 @samp{/tmp/foo/bar} we get:
2032 (file-truename "/tmp/bar/../myfile")
2033 @result{} "/tmp/foo/myfile"
2036 (expand-file-name "/tmp/bar/../myfile")
2037 @result{} "/tmp/myfile"
2041 If you may need to follow symbolic links preceding @samp{..}, you
2042 should make sure to call @code{file-truename} without prior direct or
2043 indirect calls to @code{expand-file-name}. @xref{Truenames}.
2046 @defvar default-directory
2047 The value of this buffer-local variable is the default directory for the
2048 current buffer. It should be an absolute directory name; it may start
2049 with @samp{~}. This variable is buffer-local in every buffer.
2051 @code{expand-file-name} uses the default directory when its second
2052 argument is @code{nil}.
2054 The value is always a string ending with a slash.
2059 @result{} "/user/lewis/manual/"
2064 @defun substitute-in-file-name filename
2065 @anchor{Definition of substitute-in-file-name}
2066 This function replaces environment variable references in
2067 @var{filename} with the environment variable values. Following
2068 standard Unix shell syntax, @samp{$} is the prefix to substitute an
2069 environment variable value. If the input contains @samp{$$}, that is
2070 converted to @samp{$}; this gives the user a way to ``quote'' a
2073 The environment variable name is the series of alphanumeric characters
2074 (including underscores) that follow the @samp{$}. If the character following
2075 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
2078 Calling @code{substitute-in-file-name} on output produced by
2079 @code{substitute-in-file-name} tends to give incorrect results. For
2080 instance, use of @samp{$$} to quote a single @samp{$} won't work
2081 properly, and @samp{$} in an environment variable's value could lead
2082 to repeated substitution. Therefore, programs that call this function
2083 and put the output where it will be passed to this function need to
2084 double all @samp{$} characters to prevent subsequent incorrect
2087 @c Wordy to avoid overfull hbox. --rjc 15mar92
2088 Here we assume that the environment variable @code{HOME}, which holds
2089 the user's home directory name, has value @samp{/xcssun/users/rms}.
2093 (substitute-in-file-name "$HOME/foo")
2094 @result{} "/xcssun/users/rms/foo"
2098 After substitution, if a @samp{~} or a @samp{/} appears immediately
2099 after another @samp{/}, the function discards everything before it (up
2100 through the immediately preceding @samp{/}).
2104 (substitute-in-file-name "bar/~/foo")
2108 (substitute-in-file-name "/usr/local/$HOME/foo")
2109 @result{} "/xcssun/users/rms/foo"
2110 ;; @r{@file{/usr/local/} has been discarded.}
2116 @node Unique File Names
2117 @subsection Generating Unique File Names
2119 Some programs need to write temporary files. Here is the usual way to
2120 construct a name for such a file:
2123 (make-temp-file @var{name-of-application})
2127 The job of @code{make-temp-file} is to prevent two different users or
2128 two different jobs from trying to use the exact same file name.
2130 @defun make-temp-file prefix &optional dir-flag suffix
2131 This function creates a temporary file and returns its name. Emacs
2132 creates the temporary file's name by adding to @var{prefix} some
2133 random characters that are different in each Emacs job. The result is
2134 guaranteed to be a newly created empty file. On MS-DOS, this function
2135 can truncate the @var{string} prefix to fit into the 8+3 file-name
2136 limits. If @var{prefix} is a relative file name, it is expanded
2137 against @code{temporary-file-directory}.
2141 (make-temp-file "foo")
2142 @result{} "/tmp/foo232J6v"
2146 When @code{make-temp-file} returns, the file has been created and is
2147 empty. At that point, you should write the intended contents into the
2150 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2151 empty directory instead of an empty file. It returns the file name,
2152 not the directory name, of that directory. @xref{Directory Names}.
2154 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2155 the end of the file name.
2157 To prevent conflicts among different libraries running in the same
2158 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2159 own @var{prefix}. The number added to the end of @var{prefix}
2160 distinguishes between the same application running in different Emacs
2161 jobs. Additional added characters permit a large number of distinct
2162 names even in one Emacs job.
2165 The default directory for temporary files is controlled by the
2166 variable @code{temporary-file-directory}. This variable gives the user
2167 a uniform way to specify the directory for all temporary files. Some
2168 programs use @code{small-temporary-file-directory} instead, if that is
2169 non-@code{nil}. To use it, you should expand the prefix against
2170 the proper directory before calling @code{make-temp-file}.
2172 In older Emacs versions where @code{make-temp-file} does not exist,
2173 you should use @code{make-temp-name} instead:
2177 (expand-file-name @var{name-of-application}
2178 temporary-file-directory))
2181 @defun make-temp-name string
2182 This function generates a string that can be used as a unique file
2183 name. The name starts with @var{string}, and has several random
2184 characters appended to it, which are different in each Emacs job. It
2185 is like @code{make-temp-file} except that it just constructs a name,
2186 and does not create a file. Another difference is that @var{string}
2187 should be an absolute file name. On MS-DOS, this function can
2188 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
2191 @defopt temporary-file-directory
2192 @cindex @code{TMPDIR} environment variable
2193 @cindex @code{TMP} environment variable
2194 @cindex @code{TEMP} environment variable
2195 This variable specifies the directory name for creating temporary files.
2196 Its value should be a directory name (@pxref{Directory Names}), but it
2197 is good for Lisp programs to cope if the value is a directory's file
2198 name instead. Using the value as the second argument to
2199 @code{expand-file-name} is a good way to achieve that.
2201 The default value is determined in a reasonable way for your operating
2202 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2203 environment variables, with a fall-back to a system-dependent name if
2204 none of these variables is defined.
2206 Even if you do not use @code{make-temp-file} to create the temporary
2207 file, you should still use this variable to decide which directory to
2208 put the file in. However, if you expect the file to be small, you
2209 should use @code{small-temporary-file-directory} first if that is
2213 @defopt small-temporary-file-directory
2214 This variable specifies the directory name for
2215 creating certain temporary files, which are likely to be small.
2217 If you want to write a temporary file which is likely to be small, you
2218 should compute the directory like this:
2222 (expand-file-name @var{prefix}
2223 (or small-temporary-file-directory
2224 temporary-file-directory)))
2228 @node File Name Completion
2229 @subsection File Name Completion
2230 @cindex file name completion subroutines
2231 @cindex completion, file name
2233 This section describes low-level subroutines for completing a file
2234 name. For higher level functions, see @ref{Reading File Names}.
2236 @defun file-name-all-completions partial-filename directory
2237 This function returns a list of all possible completions for a file
2238 whose name starts with @var{partial-filename} in directory
2239 @var{directory}. The order of the completions is the order of the files
2240 in the directory, which is unpredictable and conveys no useful
2243 The argument @var{partial-filename} must be a file name containing no
2244 directory part and no slash (or backslash on some systems). The current
2245 buffer's default directory is prepended to @var{directory}, if
2246 @var{directory} is not absolute.
2248 In the following example, suppose that @file{~rms/lewis} is the current
2249 default directory, and has five files whose names begin with @samp{f}:
2250 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2251 @file{file.c.~2~}.@refill
2255 (file-name-all-completions "f" "")
2256 @result{} ("foo" "file~" "file.c.~2~"
2257 "file.c.~1~" "file.c")
2261 (file-name-all-completions "fo" "")
2267 @defun file-name-completion filename directory &optional predicate
2268 This function completes the file name @var{filename} in directory
2269 @var{directory}. It returns the longest prefix common to all file names
2270 in directory @var{directory} that start with @var{filename}. If
2271 @var{predicate} is non-@code{nil} then it ignores possible completions
2272 that don't satisfy @var{predicate}, after calling that function
2273 with one argument, the expanded absolute file name.
2275 If only one match exists and @var{filename} matches it exactly, the
2276 function returns @code{t}. The function returns @code{nil} if directory
2277 @var{directory} contains no name starting with @var{filename}.
2279 In the following example, suppose that the current default directory
2280 has five files whose names begin with @samp{f}: @file{foo},
2281 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2282 @file{file.c.~2~}.@refill
2286 (file-name-completion "fi" "")
2291 (file-name-completion "file.c.~1" "")
2292 @result{} "file.c.~1~"
2296 (file-name-completion "file.c.~1~" "")
2301 (file-name-completion "file.c.~3" "")
2307 @defopt completion-ignored-extensions
2308 @code{file-name-completion} usually ignores file names that end in any
2309 string in this list. It does not ignore them when all the possible
2310 completions end in one of these suffixes. This variable has no effect
2311 on @code{file-name-all-completions}.@refill
2313 A typical value might look like this:
2317 completion-ignored-extensions
2318 @result{} (".o" ".elc" "~" ".dvi")
2322 If an element of @code{completion-ignored-extensions} ends in a slash
2323 @samp{/}, it signals a directory. The elements which do @emph{not} end
2324 in a slash will never match a directory; thus, the above value will not
2325 filter out a directory named @file{foo.elc}.
2328 @node Standard File Names
2329 @subsection Standard File Names
2331 Most of the file names used in Lisp programs are entered by the user.
2332 But occasionally a Lisp program needs to specify a standard file name
2333 for a particular use---typically, to hold customization information
2334 about each user. For example, abbrev definitions are stored (by
2335 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2336 package stores completions in the file @file{~/.completions}. These are
2337 two of the many standard file names used by parts of Emacs for certain
2340 Various operating systems have their own conventions for valid file
2341 names and for which file names to use for user profile data. A Lisp
2342 program which reads a file using a standard file name ought to use, on
2343 each type of system, a file name suitable for that system. The function
2344 @code{convert-standard-filename} makes this easy to do.
2346 @defun convert-standard-filename filename
2347 This function alters the file name @var{filename} to fit the conventions
2348 of the operating system in use, and returns the result as a new string.
2351 The recommended way to specify a standard file name in a Lisp program
2352 is to choose a name which fits the conventions of GNU and Unix systems,
2353 usually with a nondirectory part that starts with a period, and pass it
2354 to @code{convert-standard-filename} instead of using it directly. Here
2355 is an example from the @code{completion} package:
2358 (defvar save-completions-file-name
2359 (convert-standard-filename "~/.completions")
2360 "*The file name to save completions to.")
2363 On GNU and Unix systems, and on some other systems as well,
2364 @code{convert-standard-filename} returns its argument unchanged. On
2365 some other systems, it alters the name to fit the system's conventions.
2367 For example, on MS-DOS the alterations made by this function include
2368 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
2369 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2370 a @samp{.} after eight characters if there is none, and truncating to
2371 three characters after the @samp{.}. (It makes other changes as well.)
2372 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2373 @file{.completions} becomes @file{_complet.ion}.
2375 @node Contents of Directories
2376 @section Contents of Directories
2377 @cindex directory-oriented functions
2378 @cindex file names in directory
2380 A directory is a kind of file that contains other files entered under
2381 various names. Directories are a feature of the file system.
2383 Emacs can list the names of the files in a directory as a Lisp list,
2384 or display the names in a buffer using the @code{ls} shell command. In
2385 the latter case, it can optionally display information about each file,
2386 depending on the options passed to the @code{ls} command.
2388 @defun directory-files directory &optional full-name match-regexp nosort
2389 This function returns a list of the names of the files in the directory
2390 @var{directory}. By default, the list is in alphabetical order.
2392 If @var{full-name} is non-@code{nil}, the function returns the files'
2393 absolute file names. Otherwise, it returns the names relative to
2394 the specified directory.
2396 If @var{match-regexp} is non-@code{nil}, this function returns only
2397 those file names that contain a match for that regular expression---the
2398 other file names are excluded from the list. On case-insensitive
2399 filesystems, the regular expression matching is case-insensitive.
2402 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2403 the list, so you get the file names in no particular order. Use this if
2404 you want the utmost possible speed and don't care what order the files
2405 are processed in. If the order of processing is visible to the user,
2406 then the user will probably be happier if you do sort the names.
2410 (directory-files "~lewis")
2411 @result{} ("#foo#" "#foo.el#" "." ".."
2412 "dired-mods.el" "files.texi"
2417 An error is signaled if @var{directory} is not the name of a directory
2421 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2422 This is similar to @code{directory-files} in deciding which files
2423 to report on and how to report their names. However, instead
2424 of returning a list of file names, it returns for each file a
2425 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2426 is what @code{file-attributes} would return for that file.
2427 The optional argument @var{id-format} has the same meaning as the
2428 corresponding argument to @code{file-attributes} (@pxref{Definition
2429 of file-attributes}).
2432 @defun file-expand-wildcards pattern &optional full
2433 This function expands the wildcard pattern @var{pattern}, returning
2434 a list of file names that match it.
2436 If @var{pattern} is written as an absolute file name,
2437 the values are absolute also.
2439 If @var{pattern} is written as a relative file name, it is interpreted
2440 relative to the current default directory. The file names returned are
2441 normally also relative to the current default directory. However, if
2442 @var{full} is non-@code{nil}, they are absolute.
2445 @defun insert-directory file switches &optional wildcard full-directory-p
2446 This function inserts (in the current buffer) a directory listing for
2447 directory @var{file}, formatted with @code{ls} according to
2448 @var{switches}. It leaves point after the inserted text.
2449 @var{switches} may be a string of options, or a list of strings
2450 representing individual options.
2452 The argument @var{file} may be either a directory name or a file
2453 specification including wildcard characters. If @var{wildcard} is
2454 non-@code{nil}, that means treat @var{file} as a file specification with
2457 If @var{full-directory-p} is non-@code{nil}, that means the directory
2458 listing is expected to show the full contents of a directory. You
2459 should specify @code{t} when @var{file} is a directory and switches do
2460 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
2461 describe a directory itself as a file, rather than showing its
2464 On most systems, this function works by running a directory listing
2465 program whose name is in the variable @code{insert-directory-program}.
2466 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2467 @code{shell-file-name}, to expand the wildcards.
2469 MS-DOS and MS-Windows systems usually lack the standard Unix program
2470 @code{ls}, so this function emulates the standard Unix program @code{ls}
2473 As a technical detail, when @var{switches} contains the long
2474 @samp{--dired} option, @code{insert-directory} treats it specially,
2475 for the sake of dired. However, the normally equivalent short
2476 @samp{-D} option is just passed on to @code{insert-directory-program},
2477 as any other option.
2480 @defvar insert-directory-program
2481 This variable's value is the program to run to generate a directory listing
2482 for the function @code{insert-directory}. It is ignored on systems
2483 which generate the listing with Lisp code.
2486 @node Create/Delete Dirs
2487 @section Creating, Copying and Deleting Directories
2488 @cindex creating, copying and deleting directories
2489 @c Emacs 19 features
2491 Most Emacs Lisp file-manipulation functions get errors when used on
2492 files that are directories. For example, you cannot delete a directory
2493 with @code{delete-file}. These special functions exist to create and
2497 @deffn Command make-directory dirname &optional parents
2498 This command creates a directory named @var{dirname}. If
2499 @var{parents} is non-@code{nil}, as is always the case in an
2500 interactive call, that means to create the parent directories first,
2501 if they don't already exist.
2503 @code{mkdir} is an alias for this.
2506 @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
2507 This command copies the directory named @var{dirname} to
2508 @var{newname}. If @var{newname} names an existing directory,
2509 @var{dirname} will be copied to a subdirectory there.
2511 It always sets the file modes of the copied files to match the
2512 corresponding original file.
2514 The third argument @var{keep-time} non-@code{nil} means to preserve the
2515 modification time of the copied files. A prefix arg makes
2516 @var{keep-time} non-@code{nil}.
2518 The fourth argument @var{parents} says whether to
2519 create parent directories if they don't exist. Interactively,
2520 this happens by default.
2522 The fifth argument @var{copy-contents}, if non-@code{nil}, means to
2523 copy the contents of @var{dirname} directly into @var{newname} if the
2524 latter is an existing directory, instead of copying @var{dirname} into
2525 it as a subdirectory.
2529 @vindex delete-by-moving-to-trash
2530 @deffn Command delete-directory dirname &optional recursive trash
2531 This command deletes the directory named @var{dirname}. The function
2532 @code{delete-file} does not work for files that are directories; you
2533 must use @code{delete-directory} for them. If @var{recursive} is
2534 @code{nil}, and the directory contains any files,
2535 @code{delete-directory} signals an error.
2537 @code{delete-directory} only follows symbolic links at the level of
2540 If the optional argument @var{trash} is non-@code{nil} and the
2541 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
2542 command moves the file into the system Trash instead of deleting it.
2543 @xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
2544 Emacs Manual}. When called interactively, @var{trash} is @code{t} if
2545 no prefix argument is given, and @code{nil} otherwise.
2548 @node Magic File Names
2549 @section Making Certain File Names ``Magic''
2550 @cindex magic file names
2553 You can implement special handling for certain file names. This is
2554 called making those names @dfn{magic}. The principal use for this
2555 feature is in implementing remote file names (@pxref{Remote Files,,
2556 Remote Files, emacs, The GNU Emacs Manual}).
2558 To define a kind of magic file name, you must supply a regular
2559 expression to define the class of names (all those that match the
2560 regular expression), plus a handler that implements all the primitive
2561 Emacs file operations for file names that do match.
2563 @vindex file-name-handler-alist
2564 The variable @code{file-name-handler-alist} holds a list of handlers,
2565 together with regular expressions that determine when to apply each
2566 handler. Each element has this form:
2569 (@var{regexp} . @var{handler})
2573 All the Emacs primitives for file access and file name transformation
2574 check the given file name against @code{file-name-handler-alist}. If
2575 the file name matches @var{regexp}, the primitives handle that file by
2576 calling @var{handler}.
2578 The first argument given to @var{handler} is the name of the
2579 primitive, as a symbol; the remaining arguments are the arguments that
2580 were passed to that primitive. (The first of these arguments is most
2581 often the file name itself.) For example, if you do this:
2584 (file-exists-p @var{filename})
2588 and @var{filename} has handler @var{handler}, then @var{handler} is
2592 (funcall @var{handler} 'file-exists-p @var{filename})
2595 When a function takes two or more arguments that must be file names,
2596 it checks each of those names for a handler. For example, if you do
2600 (expand-file-name @var{filename} @var{dirname})
2604 then it checks for a handler for @var{filename} and then for a handler
2605 for @var{dirname}. In either case, the @var{handler} is called like
2609 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2613 The @var{handler} then needs to figure out whether to handle
2614 @var{filename} or @var{dirname}.
2616 If the specified file name matches more than one handler, the one
2617 whose match starts last in the file name gets precedence. This rule
2618 is chosen so that handlers for jobs such as uncompression are handled
2619 first, before handlers for jobs such as remote file access.
2621 Here are the operations that a magic file name handler gets to handle:
2625 @code{access-file}, @code{add-name-to-file},
2626 @code{byte-compiler-base-file-name},@*
2627 @code{copy-directory}, @code{copy-file},
2628 @code{delete-directory}, @code{delete-file},
2629 @code{diff-latest-backup-file},
2630 @code{directory-file-name},
2631 @code{directory-files},
2632 @code{directory-files-and-attributes},
2633 @code{dired-compress-file}, @code{dired-uncache},@*
2634 @code{expand-file-name},
2635 @code{file-accessible-directory-p},
2636 @code{file-attributes},
2637 @code{file-directory-p},
2638 @code{file-executable-p}, @code{file-exists-p},
2639 @code{file-local-copy}, @code{file-remote-p},
2640 @code{file-modes}, @code{file-name-all-completions},
2641 @code{file-name-as-directory},
2642 @code{file-name-completion},
2643 @code{file-name-directory},
2644 @code{file-name-nondirectory},
2645 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2646 @code{file-ownership-preserved-p},
2647 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2648 @code{file-truename}, @code{file-writable-p},
2649 @code{find-backup-file-name},
2650 @c Not sure why it was here: @code{find-file-noselect},@*
2651 @code{get-file-buffer},
2652 @code{insert-directory},
2653 @code{insert-file-contents},@*
2655 @code{make-auto-save-file-name},
2656 @code{make-directory},
2657 @code{make-directory-internal},
2658 @code{make-symbolic-link},@*
2659 @code{process-file},
2660 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2661 @code{set-visited-file-modtime}, @code{shell-command},
2662 @code{start-file-process},
2663 @code{substitute-in-file-name},@*
2664 @code{unhandled-file-name-directory},
2665 @code{vc-registered},
2666 @code{verify-visited-file-modtime},@*
2667 @code{write-region}.
2672 @code{access-file}, @code{add-name-to-file},
2673 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2674 @code{copy-directory}, @code{copy-file},
2675 @code{delete-directory}, @code{delete-file},
2676 @code{diff-latest-backup-file},
2677 @code{directory-file-name},
2678 @code{directory-files},
2679 @code{directory-files-and-at@discretionary{}{}{}tributes},
2680 @code{dired-compress-file}, @code{dired-uncache},
2681 @code{expand-file-name},
2682 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2683 @code{file-attributes},
2684 @code{file-direct@discretionary{}{}{}ory-p},
2685 @code{file-executable-p}, @code{file-exists-p},
2686 @code{file-local-copy}, @code{file-remote-p},
2687 @code{file-modes}, @code{file-name-all-completions},
2688 @code{file-name-as-directory},
2689 @code{file-name-completion},
2690 @code{file-name-directory},
2691 @code{file-name-nondirec@discretionary{}{}{}tory},
2692 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2693 @code{file-ownership-pre@discretionary{}{}{}served-p},
2694 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2695 @code{file-truename}, @code{file-writable-p},
2696 @code{find-backup-file-name},
2697 @c Not sure why it was here: @code{find-file-noselect},
2698 @code{get-file-buffer},
2699 @code{insert-directory},
2700 @code{insert-file-contents},
2701 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2702 @code{make-direc@discretionary{}{}{}tory-internal},
2703 @code{make-symbolic-link},
2704 @code{process-file},
2705 @code{rename-file}, @code{set-file-modes},
2706 @code{set-visited-file-modtime}, @code{shell-command},
2707 @code{start-file-process},
2708 @code{substitute-in-file-name},
2709 @code{unhandled-file-name-directory},
2710 @code{vc-regis@discretionary{}{}{}tered},
2711 @code{verify-visited-file-modtime},
2712 @code{write-region}.
2716 Handlers for @code{insert-file-contents} typically need to clear the
2717 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2718 @var{visit} argument is non-@code{nil}. This also has the effect of
2719 unlocking the buffer if it is locked.
2721 The handler function must handle all of the above operations, and
2722 possibly others to be added in the future. It need not implement all
2723 these operations itself---when it has nothing special to do for a
2724 certain operation, it can reinvoke the primitive, to handle the
2725 operation ``in the usual way.'' It should always reinvoke the primitive
2726 for an operation it does not recognize. Here's one way to do this:
2729 (defun my-file-handler (operation &rest args)
2730 ;; @r{First check for the specific operations}
2731 ;; @r{that we have special handling for.}
2732 (cond ((eq operation 'insert-file-contents) @dots{})
2733 ((eq operation 'write-region) @dots{})
2735 ;; @r{Handle any operation we don't know about.}
2736 (t (let ((inhibit-file-name-handlers
2737 (cons 'my-file-handler
2738 (and (eq inhibit-file-name-operation operation)
2739 inhibit-file-name-handlers)))
2740 (inhibit-file-name-operation operation))
2741 (apply operation args)))))
2744 When a handler function decides to call the ordinary Emacs primitive for
2745 the operation at hand, it needs to prevent the primitive from calling
2746 the same handler once again, thus leading to an infinite recursion. The
2747 example above shows how to do this, with the variables
2748 @code{inhibit-file-name-handlers} and
2749 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2750 shown above; the details are crucial for proper behavior in the case of
2751 multiple handlers, and for operations that have two file names that may
2754 @kindex safe-magic (@r{property})
2755 Handlers that don't really do anything special for actual access to the
2756 file---such as the ones that implement completion of host names for
2757 remote file names---should have a non-@code{nil} @code{safe-magic}
2758 property. For instance, Emacs normally ``protects'' directory names
2759 it finds in @code{PATH} from becoming magic, if they look like magic
2760 file names, by prefixing them with @samp{/:}. But if the handler that
2761 would be used for them has a non-@code{nil} @code{safe-magic}
2762 property, the @samp{/:} is not added.
2764 @kindex operations (@r{property})
2765 A file name handler can have an @code{operations} property to
2766 declare which operations it handles in a nontrivial way. If this
2767 property has a non-@code{nil} value, it should be a list of
2768 operations; then only those operations will call the handler. This
2769 avoids inefficiency, but its main purpose is for autoloaded handler
2770 functions, so that they won't be loaded except when they have real
2773 Simply deferring all operations to the usual primitives does not
2774 work. For instance, if the file name handler applies to
2775 @code{file-exists-p}, then it must handle @code{load} itself, because
2776 the usual @code{load} code won't work properly in that case. However,
2777 if the handler uses the @code{operations} property to say it doesn't
2778 handle @code{file-exists-p}, then it need not handle @code{load}
2781 @defvar inhibit-file-name-handlers
2782 This variable holds a list of handlers whose use is presently inhibited
2783 for a certain operation.
2786 @defvar inhibit-file-name-operation
2787 The operation for which certain handlers are presently inhibited.
2790 @defun find-file-name-handler file operation
2791 This function returns the handler function for file name @var{file},
2792 or @code{nil} if there is none. The argument @var{operation} should
2793 be the operation to be performed on the file---the value you will pass
2794 to the handler as its first argument when you call it. If
2795 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
2796 not found in the @code{operations} property of the handler, this
2797 function returns @code{nil}.
2800 @defun file-local-copy filename
2801 This function copies file @var{filename} to an ordinary non-magic file
2802 on the local machine, if it isn't on the local machine already. Magic
2803 file names should handle the @code{file-local-copy} operation if they
2804 refer to files on other machines. A magic file name that is used for
2805 other purposes than remote file access should not handle
2806 @code{file-local-copy}; then this function will treat the file as
2809 If @var{filename} is local, whether magic or not, this function does
2810 nothing and returns @code{nil}. Otherwise it returns the file name
2811 of the local copy file.
2814 @defun file-remote-p filename &optional identification connected
2815 This function tests whether @var{filename} is a remote file. If
2816 @var{filename} is local (not remote), the return value is @code{nil}.
2817 If @var{filename} is indeed remote, the return value is a string that
2818 identifies the remote system.
2820 This identifier string can include a host name and a user name, as
2821 well as characters designating the method used to access the remote
2822 system. For example, the remote identifier string for the filename
2823 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
2825 If @code{file-remote-p} returns the same identifier for two different
2826 filenames, that means they are stored on the same file system and can
2827 be accessed locally with respect to each other. This means, for
2828 example, that it is possible to start a remote process accessing both
2829 files at the same time. Implementors of file handlers need to ensure
2830 this principle is valid.
2832 @var{identification} specifies which part of the identifier shall be
2833 returned as string. @var{identification} can be the symbol
2834 @code{method}, @code{user} or @code{host}; any other value is handled
2835 like @code{nil} and means to return the complete identifier string.
2836 In the example above, the remote @code{user} identifier string would
2839 If @var{connected} is non-@code{nil}, this function returns @code{nil}
2840 even if @var{filename} is remote, if Emacs has no network connection
2841 to its host. This is useful when you want to avoid the delay of
2842 making connections when they don't exist.
2845 @defun unhandled-file-name-directory filename
2846 This function returns the name of a directory that is not magic. It
2847 uses the directory part of @var{filename} if that is not magic. For a
2848 magic file name, it invokes the file name handler, which therefore
2849 decides what value to return. If @var{filename} is not accessible
2850 from a local process, then the file name handler should indicate it by
2851 returning @code{nil}.
2853 This is useful for running a subprocess; every subprocess must have a
2854 non-magic directory to serve as its current directory, and this function
2855 is a good way to come up with one.
2858 @defopt remote-file-name-inhibit-cache
2859 Whether to use the remote file-name cache for read access.
2861 File attributes of remote files are cached for better performance. If
2862 they are changed out of Emacs' control, the cached values become
2863 invalid, and must be reread.
2865 When set to @code{nil}, cached values are always used. This shall be
2866 set with care. When set to @code{t}, cached values are never used.
2867 ALthough this is the safest value, it could result in performance
2870 A compromise is to set it to a positive number. This means that
2871 cached values are used for that amount of seconds since they were
2874 In case a remote file is checked regularly, it might be reasonable to
2875 let-bind this variable to a value less then the time period between
2876 two checks. Example:
2879 (defun display-time-file-nonempty-p (file)
2880 (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
2881 (and (file-exists-p file)
2882 (< 0 (nth 7 (file-attributes (file-chase-links file)))))))
2886 @node Format Conversion
2887 @section File Format Conversion
2889 @cindex file format conversion
2890 @cindex encoding file formats
2891 @cindex decoding file formats
2892 @cindex text properties in files
2893 @cindex saving text properties
2894 Emacs performs several steps to convert the data in a buffer (text,
2895 text properties, and possibly other information) to and from a
2896 representation suitable for storing into a file. This section describes
2897 the fundamental functions that perform this @dfn{format conversion},
2898 namely @code{insert-file-contents} for reading a file into a buffer,
2899 and @code{write-region} for writing a buffer into a file.
2902 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}.
2903 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
2904 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
2907 @node Format Conversion Overview
2908 @subsection Overview
2910 The function @code{insert-file-contents}:
2913 @item initially, inserts bytes from the file into the buffer;
2914 @item decodes bytes to characters as appropriate;
2915 @item processes formats as defined by entries in @code{format-alist}; and
2916 @item calls functions in @code{after-insert-file-functions}.
2920 The function @code{write-region}:
2923 @item initially, calls functions in @code{write-region-annotate-functions};
2924 @item processes formats as defined by entries in @code{format-alist};
2925 @item encodes characters to bytes as appropriate; and
2926 @item modifies the file with the bytes.
2929 This shows the symmetry of the lowest-level operations; reading and
2930 writing handle things in opposite order. The rest of this section
2931 describes the two facilities surrounding the three variables named
2932 above, as well as some related functions. @ref{Coding Systems}, for
2933 details on character encoding and decoding.
2935 @node Format Conversion Round-Trip
2936 @subsection Round-Trip Specification
2938 The most general of the two facilities is controlled by the variable
2939 @code{format-alist}, a list of @dfn{file format} specifications, which
2940 describe textual representations used in files for the data in an Emacs
2941 buffer. The descriptions for reading and writing are paired, which is
2942 why we call this ``round-trip'' specification
2943 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
2945 @defvar format-alist
2946 This list contains one format definition for each defined file format.
2947 Each format definition is a list of this form:
2950 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
2954 @cindex format definition
2956 Here is what the elements in a format definition mean:
2960 The name of this format.
2963 A documentation string for the format.
2966 A regular expression which is used to recognize files represented in
2967 this format. If @code{nil}, the format is never applied automatically.
2970 A shell command or function to decode data in this format (to convert
2971 file data into the usual Emacs data representation).
2973 A shell command is represented as a string; Emacs runs the command as a
2974 filter to perform the conversion.
2976 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2977 and @var{end}, which specify the part of the buffer it should convert.
2978 It should convert the text by editing it in place. Since this can
2979 change the length of the text, @var{from-fn} should return the modified
2982 One responsibility of @var{from-fn} is to make sure that the beginning
2983 of the file no longer matches @var{regexp}. Otherwise it is likely to
2987 A shell command or function to encode data in this format---that is, to
2988 convert the usual Emacs data representation into this format.
2990 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2991 command as a filter to perform the conversion.
2993 If @var{to-fn} is a function, it is called with three arguments:
2994 @var{begin} and @var{end}, which specify the part of the buffer it
2995 should convert, and @var{buffer}, which specifies which buffer. There
2996 are two ways it can do the conversion:
3000 By editing the buffer in place. In this case, @var{to-fn} should
3001 return the end-position of the range of text, as modified.
3004 By returning a list of annotations. This is a list of elements of the
3005 form @code{(@var{position} . @var{string})}, where @var{position} is an
3006 integer specifying the relative position in the text to be written, and
3007 @var{string} is the annotation to add there. The list must be sorted in
3008 order of position when @var{to-fn} returns it.
3010 When @code{write-region} actually writes the text from the buffer to the
3011 file, it intermixes the specified annotations at the corresponding
3012 positions. All this takes place without modifying the buffer.
3016 A flag, @code{t} if the encoding function modifies the buffer, and
3017 @code{nil} if it works by returning a list of annotations.
3020 A minor-mode function to call after visiting a file converted from this
3021 format. The function is called with one argument, the integer 1;
3022 that tells a minor-mode function to enable the mode.
3025 A flag, @code{t} if @code{format-write-file} should not remove this format
3026 from @code{buffer-file-format}.
3029 The function @code{insert-file-contents} automatically recognizes file
3030 formats when it reads the specified file. It checks the text of the
3031 beginning of the file against the regular expressions of the format
3032 definitions, and if it finds a match, it calls the decoding function for
3033 that format. Then it checks all the known formats over again.
3034 It keeps checking them until none of them is applicable.
3036 Visiting a file, with @code{find-file-noselect} or the commands that use
3037 it, performs conversion likewise (because it calls
3038 @code{insert-file-contents}); it also calls the mode function for each
3039 format that it decodes. It stores a list of the format names in the
3040 buffer-local variable @code{buffer-file-format}.
3042 @defvar buffer-file-format
3043 This variable states the format of the visited file. More precisely,
3044 this is a list of the file format names that were decoded in the course
3045 of visiting the current buffer's file. It is always buffer-local in all
3049 When @code{write-region} writes data into a file, it first calls the
3050 encoding functions for the formats listed in @code{buffer-file-format},
3051 in the order of appearance in the list.
3053 @deffn Command format-write-file file format &optional confirm
3054 This command writes the current buffer contents into the file @var{file}
3055 in a format based on @var{format}, which is a list of format names. It
3056 constructs the actual format starting from @var{format}, then appending
3057 any elements from the value of @code{buffer-file-format} with a non-nil
3058 @var{preserve} flag (see above), if they are not already present in
3059 @var{format}. It then updates @code{buffer-file-format} with this
3060 format, making it the default for future saves. Except for the
3061 @var{format} argument, this command is similar to @code{write-file}. In
3062 particular, @var{confirm} has the same meaning and interactive treatment
3063 as the corresponding argument to @code{write-file}. @xref{Definition of
3067 @deffn Command format-find-file file format
3068 This command finds the file @var{file}, converting it according to
3069 format @var{format}. It also makes @var{format} the default if the
3070 buffer is saved later.
3072 The argument @var{format} is a list of format names. If @var{format} is
3073 @code{nil}, no conversion takes place. Interactively, typing just
3074 @key{RET} for @var{format} specifies @code{nil}.
3077 @deffn Command format-insert-file file format &optional beg end
3078 This command inserts the contents of file @var{file}, converting it
3079 according to format @var{format}. If @var{beg} and @var{end} are
3080 non-@code{nil}, they specify which part of the file to read, as in
3081 @code{insert-file-contents} (@pxref{Reading from Files}).
3083 The return value is like what @code{insert-file-contents} returns: a
3084 list of the absolute file name and the length of the data inserted
3087 The argument @var{format} is a list of format names. If @var{format} is
3088 @code{nil}, no conversion takes place. Interactively, typing just
3089 @key{RET} for @var{format} specifies @code{nil}.
3092 @defvar buffer-auto-save-file-format
3093 This variable specifies the format to use for auto-saving. Its value is
3094 a list of format names, just like the value of
3095 @code{buffer-file-format}; however, it is used instead of
3096 @code{buffer-file-format} for writing auto-save files. If the value
3097 is @code{t}, the default, auto-saving uses the same format as a
3098 regular save in the same buffer. This variable is always buffer-local
3102 @node Format Conversion Piecemeal
3103 @subsection Piecemeal Specification
3105 In contrast to the round-trip specification described in the previous
3106 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
3107 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
3108 to separately control the respective reading and writing conversions.
3110 Conversion starts with one representation and produces another
3111 representation. When there is only one conversion to do, there is no
3112 conflict about what to start with. However, when there are multiple
3113 conversions involved, conflict may arise when two conversions need to
3114 start with the same data.
3116 This situation is best understood in the context of converting text
3117 properties during @code{write-region}. For example, the character at
3118 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
3119 the conversion for @code{foo} is done by inserting into the buffer, say,
3120 @samp{FOO:}, then that changes the character at position 42 from
3121 @samp{X} to @samp{F}. The next conversion will start with the wrong
3124 To avoid conflict, cooperative conversions do not modify the buffer,
3125 but instead specify @dfn{annotations}, a list of elements of the form
3126 @code{(@var{position} . @var{string})}, sorted in order of increasing
3129 If there is more than one conversion, @code{write-region} merges their
3130 annotations destructively into one sorted list. Later, when the text
3131 from the buffer is actually written to the file, it intermixes the
3132 specified annotations at the corresponding positions. All this takes
3133 place without modifying the buffer.
3135 @c ??? What about ``overriding'' conversions like those allowed
3136 @c ??? for `write-region-annotate-functions', below? --ttn
3138 In contrast, when reading, the annotations intermixed with the text
3139 are handled immediately. @code{insert-file-contents} sets point to
3140 the beginning of some text to be converted, then calls the conversion
3141 functions with the length of that text. These functions should always
3142 return with point at the beginning of the inserted text. This
3143 approach makes sense for reading because annotations removed by the
3144 first converter can't be mistakenly processed by a later converter.
3145 Each conversion function should scan for the annotations it
3146 recognizes, remove the annotation, modify the buffer text (to set a
3147 text property, for example), and return the updated length of the
3148 text, as it stands after those changes. The value returned by one
3149 function becomes the argument to the next function.
3151 @defvar write-region-annotate-functions
3152 A list of functions for @code{write-region} to call. Each function in
3153 the list is called with two arguments: the start and end of the region
3154 to be written. These functions should not alter the contents of the
3155 buffer. Instead, they should return annotations.
3157 As a special case, a function may return with a different buffer
3158 current. Emacs takes this to mean that the current buffer contains
3159 altered text to be output. It therefore changes the @var{start} and
3160 @var{end} arguments of the @code{write-region} call, giving them the
3161 values of @code{point-min} and @code{point-max} in the new buffer,
3162 respectively. It also discards all previous annotations, because they
3163 should have been dealt with by this function.
3166 @defvar write-region-post-annotation-function
3167 The value of this variable, if non-@code{nil}, should be a function.
3168 This function is called, with no arguments, after @code{write-region}
3171 If any function in @code{write-region-annotate-functions} returns with
3172 a different buffer current, Emacs calls
3173 @code{write-region-post-annotation-function} more than once. Emacs
3174 calls it with the last buffer that was current, and again with the
3175 buffer before that, and so on back to the original buffer.
3177 Thus, a function in @code{write-region-annotate-functions} can create
3178 a buffer, give this variable the local value of @code{kill-buffer} in
3179 that buffer, set up the buffer with altered text, and make the buffer
3180 current. The buffer will be killed after @code{write-region} is done.
3183 @defvar after-insert-file-functions
3184 Each function in this list is called by @code{insert-file-contents}
3185 with one argument, the number of characters inserted, and with point
3186 at the beginning of the inserted text. Each function should leave
3187 point unchanged, and return the new character count describing the
3188 inserted text as modified by the function.
3189 @c ??? The docstring mentions a handler from `file-name-handler-alist'
3190 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
3193 We invite users to write Lisp programs to store and retrieve text
3194 properties in files, using these hooks, and thus to experiment with
3195 various data formats and find good ones. Eventually we hope users
3196 will produce good, general extensions we can install in Emacs.
3198 We suggest not trying to handle arbitrary Lisp objects as text property
3199 names or values---because a program that general is probably difficult
3200 to write, and slow. Instead, choose a set of possible data types that
3201 are reasonably flexible, and not too hard to encode.