*** empty log message ***
[emacs.git] / lispref / files.texi
blob2e6a5bcee00f8e16c275d0994b5f10cff99fa34c
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
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
9 @chapter Files
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}).
30 @menu
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.
45 @end menu
47 @node Visiting Files
48 @section Visiting Files
49 @cindex finding 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
65 back into the file.
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.
74 @menu
75 * Visiting Functions::         The usual interface functions for visiting.
76 * Subroutines of Visiting::    Lower-level subroutines that they use.
77 @end menu
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:
101 @example
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
103 @end example
105 @noindent
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.
114 @end deffn
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
117 This function is the guts of all the file-visiting functions.  It finds
118 or creates a buffer visiting the file @var{filename}, and returns it.
119 It uses an existing buffer if there is one, and otherwise creates a new
120 buffer and reads the file into it.  You may make the buffer current or
121 display it in a window if you wish, but this function does not do so.
123 If @var{wildcards} is non-@code{nil},
124 then @code{find-file-noselect} expands wildcard
125 characters in @var{filename} and visits all the matching files.
127 When @code{find-file-noselect} uses an existing buffer, it first
128 verifies that the file has not changed since it was last visited or
129 saved in that buffer.  If the file has changed, then this function asks
130 the user whether to reread the changed file.  If the user says
131 @samp{yes}, any changes previously made in the buffer are lost.
133 This function displays warning or advisory messages in various peculiar
134 cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
135 example, if it needs to create a buffer, and there is no file named
136 @var{filename}, it displays the message @samp{(New file)} in the echo
137 area, and leaves the buffer empty.
139 The @code{find-file-noselect} function normally calls
140 @code{after-find-file} after reading the file (@pxref{Subroutines of
141 Visiting}).  That function sets the buffer major mode, parses local
142 variables, warns the user if there exists an auto-save file more recent
143 than the file just visited, and finishes by running the functions in
144 @code{find-file-hook}.
146 If the optional argument @var{rawfile} is non-@code{nil}, then
147 @code{after-find-file} is not called, and the
148 @code{find-file-not-found-functions} are not run in case of failure.  What's
149 more, a non-@code{nil} @var{rawfile} value suppresses coding system
150 conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
151 Conversion}).
153 The @code{find-file-noselect} function usually returns the buffer that
154 is visiting the file @var{filename}.  But, if wildcards are actually
155 used and expanded, it returns a list of buffers that are visiting the
156 various files.
158 @example
159 @group
160 (find-file-noselect "/etc/fstab")
161      @result{} #<buffer fstab>
162 @end group
163 @end example
164 @end defun
166 @deffn Command find-file-other-window filename &optional wildcards
167 This command selects a buffer visiting the file @var{filename}, but
168 does so in a window other than the selected window.  It may use another
169 existing window or split a window; see @ref{Displaying Buffers}.
171 When this command is called interactively, it prompts for
172 @var{filename}.
173 @end deffn
175 @deffn Command find-file-read-only filename &optional wildcards
176 This command selects a buffer visiting the file @var{filename}, like
177 @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
178 Buffers}, for related functions and variables.
180 When this command is called interactively, it prompts for
181 @var{filename}.
182 @end deffn
184 @deffn Command view-file filename
185 This command visits @var{filename} using View mode, returning to the
186 previous buffer when you exit View mode.  View mode is a minor mode that
187 provides commands to skim rapidly through the file, but does not let you
188 modify the text.  Entering View mode runs the normal hook
189 @code{view-mode-hook}.  @xref{Hooks}.
191 When @code{view-file} is called interactively, it prompts for
192 @var{filename}.
193 @end deffn
195 @tindex find-file-wildcards
196 @defopt find-file-wildcards
197 If this variable is non-@code{nil}, then the various @code{find-file}
198 commands check for wildcard characters and visit all the files that
199 match them (when invoked interactively or when their @var{wildcards}
200 argument is non-@code{nil}).  If this option is @code{nil}, then
201 the @code{find-file} commands ignore their @var{wildcards} argument
202 and never treat wildcard characters specially.
203 @end defopt
205 @defvar find-file-hook
206 The value of this variable is a list of functions to be called after a
207 file is visited.  The file's local-variables specification (if any) will
208 have been processed before the hooks are run.  The buffer visiting the
209 file is current when the hook functions are run.
211 This variable is a normal hook.  @xref{Hooks}.
212 @end defvar
214 @defvar find-file-not-found-functions
215 The value of this variable is a list of functions to be called when
216 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
217 file name.  @code{find-file-noselect} calls these functions as soon as
218 it detects a nonexistent file.  It calls them in the order of the list,
219 until one of them returns non-@code{nil}.  @code{buffer-file-name} is
220 already set up.
222 This is not a normal hook because the values of the functions are
223 used, and in many cases only some of the functions are called.
224 @end defvar
226 @node Subroutines of Visiting
227 @comment  node-name,  next,  previous,  up
228 @subsection Subroutines of Visiting
230   The @code{find-file-noselect} function uses two important subroutines
231 which are sometimes useful in user Lisp code: @code{create-file-buffer}
232 and @code{after-find-file}.  This section explains how to use them.
234 @defun create-file-buffer filename
235 This function creates a suitably named buffer for visiting
236 @var{filename}, and returns it.  It uses @var{filename} (sans directory)
237 as the name if that name is free; otherwise, it appends a string such as
238 @samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
240 @strong{Please note:} @code{create-file-buffer} does @emph{not}
241 associate the new buffer with a file and does not select the buffer.
242 It also does not use the default major mode.
244 @example
245 @group
246 (create-file-buffer "foo")
247      @result{} #<buffer foo>
248 @end group
249 @group
250 (create-file-buffer "foo")
251      @result{} #<buffer foo<2>>
252 @end group
253 @group
254 (create-file-buffer "foo")
255      @result{} #<buffer foo<3>>
256 @end group
257 @end example
259 This function is used by @code{find-file-noselect}.
260 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
261 @end defun
263 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
264 This function sets the buffer major mode, and parses local variables
265 (@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
266 and by the default revert function (@pxref{Reverting}).
268 @cindex new file message
269 @cindex file open error
270 If reading the file got an error because the file does not exist, but
271 its directory does exist, the caller should pass a non-@code{nil} value
272 for @var{error}.  In that case, @code{after-find-file} issues a warning:
273 @samp{(New file)}.  For more serious errors, the caller should usually not
274 call @code{after-find-file}.
276 If @var{warn} is non-@code{nil}, then this function issues a warning
277 if an auto-save file exists and is more recent than the visited file.
279 If @var{noauto} is non-@code{nil}, that says not to enable or disable
280 Auto-Save mode.  The mode remains enabled if it was enabled before.
282 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
283 means this call was from @code{revert-buffer}.  This has no direct
284 effect, but some mode functions and hook functions check the value
285 of this variable.
287 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
288 major mode, don't process local variables specifications in the file,
289 and don't run @code{find-file-hook}.  This feature is used by
290 @code{revert-buffer} in some cases.
292 The last thing @code{after-find-file} does is call all the functions
293 in the list @code{find-file-hook}.
294 @end defun
296 @node Saving Buffers
297 @section Saving Buffers
299   When you edit a file in Emacs, you are actually working on a buffer
300 that is visiting that file---that is, the contents of the file are
301 copied into the buffer and the copy is what you edit.  Changes to the
302 buffer do not change the file until you @dfn{save} the buffer, which
303 means copying the contents of the buffer into the file.
305 @deffn Command save-buffer &optional backup-option
306 This function saves the contents of the current buffer in its visited
307 file if the buffer has been modified since it was last visited or saved.
308 Otherwise it does nothing.
310 @code{save-buffer} is responsible for making backup files.  Normally,
311 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
312 file only if this is the first save since visiting the file.  Other
313 values for @var{backup-option} request the making of backup files in
314 other circumstances:
316 @itemize @bullet
317 @item
318 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
319 @code{save-buffer} function marks this version of the file to be
320 backed up when the buffer is next saved.
322 @item
323 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
324 @code{save-buffer} function unconditionally backs up the previous
325 version of the file before saving it.
327 @item
328 With an argument of 0, unconditionally do @emph{not} make any backup file.
329 @end itemize
330 @end deffn
332 @deffn Command save-some-buffers &optional save-silently-p pred
333 @anchor{Definition of save-some-buffers}
334 This command saves some modified file-visiting buffers.  Normally it
335 asks the user about each buffer.  But if @var{save-silently-p} is
336 non-@code{nil}, it saves all the file-visiting buffers without querying
337 the user.
339 The optional @var{pred} argument controls which buffers to ask about
340 (or to save silently if @var{save-silently-p} is non-@code{nil}).
341 If it is @code{nil}, that means to ask only about file-visiting buffers.
342 If it is @code{t}, that means also offer to save certain other non-file
343 buffers---those that have a non-@code{nil} buffer-local value of
344 @code{buffer-offer-save}.  (A user who says @samp{yes} to saving a
345 non-file buffer is asked to specify the file name to use.)  The
346 @code{save-buffers-kill-emacs} function passes the value @code{t} for
347 @var{pred}.
349 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
350 a function of no arguments.  It will be called in each buffer to decide
351 whether to offer to save that buffer.  If it returns a non-@code{nil}
352 value in a certain buffer, that means do offer to save that buffer.
353 @end deffn
355 @deffn Command write-file filename &optional confirm
356 @anchor{Definition of write-file}
357 This function writes the current buffer into file @var{filename}, makes
358 the buffer visit that file, and marks it not modified.  Then it renames
359 the buffer based on @var{filename}, appending a string like @samp{<2>}
360 if necessary to make a unique buffer name.  It does most of this work by
361 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
362 @code{save-buffer}.
364 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
365 before overwriting an existing file.  Interactively, confirmation is
366 required, unless the user supplies a prefix argument.
368 If @var{filename} is an existing directory, or a symbolic link to one,
369 @code{write-file} uses the name of the visited file, in directory
370 @var{filename}.  If the buffer is not visiting a file, it uses the
371 buffer name instead.
372 @end deffn
374   Saving a buffer runs several hooks.  It also performs format
375 conversion (@pxref{Format Conversion}), and may save text properties in
376 ``annotations'' (@pxref{Saving Properties}).
378 @defvar write-file-functions
379 The value of this variable is a list of functions to be called before
380 writing out a buffer to its visited file.  If one of them returns
381 non-@code{nil}, the file is considered already written and the rest of
382 the functions are not called, nor is the usual code for writing the file
383 executed.
385 If a function in @code{write-file-functions} returns non-@code{nil}, it
386 is responsible for making a backup file (if that is appropriate).
387 To do so, execute the following code:
389 @example
390 (or buffer-backed-up (backup-buffer))
391 @end example
393 You might wish to save the file modes value returned by
394 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
395 bits of the file that you write.  This is what @code{save-buffer}
396 normally does. @xref{Making Backups,, Making Backup Files}.
398 The hook functions in @code{write-file-functions} are also responsible for
399 encoding the data (if desired): they must choose a suitable coding
400 system (@pxref{Lisp and Coding Systems}), perform the encoding
401 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
402 the coding system that was used (@pxref{Encoding and I/O}).
404 If you set this hook locally in a buffer, it is assumed to be
405 associated with the file or the way the contents of the buffer were
406 obtained.  Thus the variable is marked as a permanent local, so that
407 changing the major mode does not alter a buffer-local value.  On the
408 other hand, calling @code{set-visited-file-name} will reset it.
409 If this is not what you want, you might like to use
410 @code{write-contents-functions} instead.
412 Even though this is not a normal hook, you can use @code{add-hook} and
413 @code{remove-hook} to manipulate the list.  @xref{Hooks}.
414 @end defvar
416 @c Emacs 19 feature
417 @defvar write-contents-functions
418 This works just like @code{write-file-functions}, but it is intended
419 for hooks that pertain to the buffer's contents, not to the particular
420 visited file or its location.  Such hooks are usually set up by major
421 modes, as buffer-local bindings for this variable.  This variable
422 automatically becomes buffer-local whenever it is set; switching to a
423 new major mode always resets this variable, but calling
424 @code{set-visited-file-name} does not.
426 If any of the functions in this hook returns non-@code{nil}, the file
427 is considered already written and the rest are not called and neither
428 are the functions in @code{write-file-functions}.
429 @end defvar
431 @defopt before-save-hook
432 This normal hook runs before a buffer is saved in its visited file,
433 regardless of whether that is done normally or by one of the hooks
434 described above.  For instance, the @file{copyright.el} program uses
435 this hook to make sure the file you are saving has the current year in
436 its copyright notice.
437 @end defopt
439 @c Emacs 19 feature
440 @defopt after-save-hook
441 This normal hook runs after a buffer has been saved in its visited file.
442 One use of this hook is in Fast Lock mode; it uses this hook to save the
443 highlighting information in a cache file.
444 @end defopt
446 @defopt file-precious-flag
447 If this variable is non-@code{nil}, then @code{save-buffer} protects
448 against I/O errors while saving by writing the new file to a temporary
449 name instead of the name it is supposed to have, and then renaming it to
450 the intended name after it is clear there are no errors.  This procedure
451 prevents problems such as a lack of disk space from resulting in an
452 invalid file.
454 As a side effect, backups are necessarily made by copying.  @xref{Rename
455 or Copy}.  Yet, at the same time, saving a precious file always breaks
456 all hard links between the file you save and other file names.
458 Some modes give this variable a non-@code{nil} buffer-local value
459 in particular buffers.
460 @end defopt
462 @defopt require-final-newline
463 This variable determines whether files may be written out that do
464 @emph{not} end with a newline.  If the value of the variable is
465 @code{t}, then @code{save-buffer} silently adds a newline at the end of
466 the file whenever the buffer being saved does not already end in one.
467 If the value of the variable is non-@code{nil}, but not @code{t}, then
468 @code{save-buffer} asks the user whether to add a newline each time the
469 case arises.
471 If the value of the variable is @code{nil}, then @code{save-buffer}
472 doesn't add newlines at all.  @code{nil} is the default value, but a few
473 major modes set it to @code{t} in particular buffers.
474 @end defopt
476   See also the function @code{set-visited-file-name} (@pxref{Buffer File
477 Name}).
479 @node Reading from Files
480 @comment  node-name,  next,  previous,  up
481 @section Reading from Files
483   You can copy a file from the disk and insert it into a buffer
484 using the @code{insert-file-contents} function.  Don't use the user-level
485 command @code{insert-file} in a Lisp program, as that sets the mark.
487 @defun insert-file-contents filename &optional visit beg end replace
488 This function inserts the contents of file @var{filename} into the
489 current buffer after point.  It returns a list of the absolute file name
490 and the length of the data inserted.  An error is signaled if
491 @var{filename} is not the name of a file that can be read.
493 The function @code{insert-file-contents} checks the file contents
494 against the defined file formats, and converts the file contents if
495 appropriate.  @xref{Format Conversion}.  It also calls the functions in
496 the list @code{after-insert-file-functions}; see @ref{Saving
497 Properties}.  Normally, one of the functions in the
498 @code{after-insert-file-functions} list determines the coding system
499 (@pxref{Coding Systems}) used for decoding the file's contents.
501 If @var{visit} is non-@code{nil}, this function additionally marks the
502 buffer as unmodified and sets up various fields in the buffer so that it
503 is visiting the file @var{filename}: these include the buffer's visited
504 file name and its last save file modtime.  This feature is used by
505 @code{find-file-noselect} and you probably should not use it yourself.
507 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
508 specifying the portion of the file to insert.  In this case, @var{visit}
509 must be @code{nil}.  For example,
511 @example
512 (insert-file-contents filename nil 0 500)
513 @end example
515 @noindent
516 inserts the first 500 characters of a file.
518 If the argument @var{replace} is non-@code{nil}, it means to replace the
519 contents of the buffer (actually, just the accessible portion) with the
520 contents of the file.  This is better than simply deleting the buffer
521 contents and inserting the whole file, because (1) it preserves some
522 marker positions and (2) it puts less data in the undo list.
524 It is possible to read a special file (such as a FIFO or an I/O device)
525 with @code{insert-file-contents}, as long as @var{replace} and
526 @var{visit} are @code{nil}.
527 @end defun
529 @defun insert-file-contents-literally filename &optional visit beg end replace
530 This function works like @code{insert-file-contents} except that it does
531 not do format decoding (@pxref{Format Conversion}), does not do
532 character code conversion (@pxref{Coding Systems}), does not run
533 @code{find-file-hook}, does not perform automatic uncompression, and so
535 @end defun
537 If you want to pass a file name to another process so that another
538 program can read the file, use the function @code{file-local-copy}; see
539 @ref{Magic File Names}.
541 @node Writing to Files
542 @comment  node-name,  next,  previous,  up
543 @section Writing to Files
545   You can write the contents of a buffer, or part of a buffer, directly
546 to a file on disk using the @code{append-to-file} and
547 @code{write-region} functions.  Don't use these functions to write to
548 files that are being visited; that could cause confusion in the
549 mechanisms for visiting.
551 @deffn Command append-to-file start end filename
552 This function appends the contents of the region delimited by
553 @var{start} and @var{end} in the current buffer to the end of file
554 @var{filename}.  If that file does not exist, it is created.  This
555 function returns @code{nil}.
557 An error is signaled if @var{filename} specifies a nonwritable file,
558 or a nonexistent file in a directory where files cannot be created.
560 When called from Lisp, this function is completely equivalent to:
562 @example
563 (write-region start end filename t)
564 @end example
565 @end deffn
567 @deffn Command write-region start end filename &optional append visit lockname mustbenew
568 This function writes the region delimited by @var{start} and @var{end}
569 in the current buffer into the file specified by @var{filename}.
571 If @var{start} is @code{nil}, then the command writes the entire buffer
572 contents (@emph{not} just the accessible portion) to the file and
573 ignores @var{end}.
575 @c Emacs 19 feature
576 If @var{start} is a string, then @code{write-region} writes or appends
577 that string, rather than text from the buffer.  @var{end} is ignored in
578 this case.
580 If @var{append} is non-@code{nil}, then the specified text is appended
581 to the existing file contents (if any).  Starting in Emacs 21, if
582 @var{append} is an integer, then @code{write-region} seeks to that byte
583 offset from the start of the file and writes the data from there.
585 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
586 for confirmation if @var{filename} names an existing file.
587 Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
588 then @code{write-region} does not ask for confirmation, but instead
589 it signals an error @code{file-already-exists} if the file already
590 exists.
592 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
593 a special system feature.  At least for files on a local disk, there is
594 no chance that some other program could create a file of the same name
595 before Emacs does, without Emacs's noticing.
597 If @var{visit} is @code{t}, then Emacs establishes an association
598 between the buffer and the file: the buffer is then visiting that file.
599 It also sets the last file modification time for the current buffer to
600 @var{filename}'s modtime, and marks the buffer as not modified.  This
601 feature is used by @code{save-buffer}, but you probably should not use
602 it yourself.
604 @c Emacs 19 feature
605 If @var{visit} is a string, it specifies the file name to visit.  This
606 way, you can write the data to one file (@var{filename}) while recording
607 the buffer as visiting another file (@var{visit}).  The argument
608 @var{visit} is used in the echo area message and also for file locking;
609 @var{visit} is stored in @code{buffer-file-name}.  This feature is used
610 to implement @code{file-precious-flag}; don't use it yourself unless you
611 really know what you're doing.
613 The optional argument @var{lockname}, if non-@code{nil}, specifies the
614 file name to use for purposes of locking and unlocking, overriding
615 @var{filename} and @var{visit} for that purpose.
617 The function @code{write-region} converts the data which it writes to
618 the appropriate file formats specified by @code{buffer-file-format}.
619 @xref{Format Conversion}.  It also calls the functions in the list
620 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
622 Normally, @code{write-region} displays the message @samp{Wrote
623 @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
624 nor @code{nil} nor a string, then this message is inhibited.  This
625 feature is useful for programs that use files for internal purposes,
626 files that the user does not need to know about.
627 @end deffn
629 @defmac with-temp-file file body...
630 @anchor{Definition of with-temp-file}
631 The @code{with-temp-file} macro evaluates the @var{body} forms with a
632 temporary buffer as the current buffer; then, at the end, it writes the
633 buffer contents into file @var{file}.  It kills the temporary buffer
634 when finished, restoring the buffer that was current before the
635 @code{with-temp-file} form.  Then it returns the value of the last form
636 in @var{body}.
638 The current buffer is restored even in case of an abnormal exit via
639 @code{throw} or error (@pxref{Nonlocal Exits}).
641 See also @code{with-temp-buffer} in @ref{Definition of
642 with-temp-buffer,, The Current Buffer}.
643 @end defmac
645 @node File Locks
646 @section File Locks
647 @cindex file locks
649   When two users edit the same file at the same time, they are likely to
650 interfere with each other.  Emacs tries to prevent this situation from
651 arising by recording a @dfn{file lock} when a file is being modified.
652 Emacs can then detect the first attempt to modify a buffer visiting a
653 file that is locked by another Emacs job, and ask the user what to do.
654 The file lock is really a file, a symbolic link with a special name,
655 stored in the same directory as the file you are editing.
657   When you access files using NFS, there may be a small probability that
658 you and another user will both lock the same file ``simultaneously''.
659 If this happens, it is possible for the two users to make changes
660 simultaneously, but Emacs will still warn the user who saves second.
661 Also, the detection of modification of a buffer visiting a file changed
662 on disk catches some cases of simultaneous editing; see
663 @ref{Modification Time}.
665 @defun file-locked-p filename
666 This function returns @code{nil} if the file @var{filename} is not
667 locked.  It returns @code{t} if it is locked by this Emacs process, and
668 it returns the name of the user who has locked it if it is locked by
669 some other job.
671 @example
672 @group
673 (file-locked-p "foo")
674      @result{} nil
675 @end group
676 @end example
677 @end defun
679 @defun lock-buffer &optional filename
680 This function locks the file @var{filename}, if the current buffer is
681 modified.  The argument @var{filename} defaults to the current buffer's
682 visited file.  Nothing is done if the current buffer is not visiting a
683 file, or is not modified.
684 @end defun
686 @defun unlock-buffer
687 This function unlocks the file being visited in the current buffer,
688 if the buffer is modified.  If the buffer is not modified, then
689 the file should not be locked, so this function does nothing.  It also
690 does nothing if the current buffer is not visiting a file.
691 @end defun
693   File locking is not supported on some systems.  On systems that do not
694 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
695 @code{file-locked-p} do nothing and return @code{nil}.
697 @defun ask-user-about-lock file other-user
698 This function is called when the user tries to modify @var{file}, but it
699 is locked by another user named @var{other-user}.  The default
700 definition of this function asks the user to say what to do.  The value
701 this function returns determines what Emacs does next:
703 @itemize @bullet
704 @item
705 A value of @code{t} says to grab the lock on the file.  Then
706 this user may edit the file and @var{other-user} loses the lock.
708 @item
709 A value of @code{nil} says to ignore the lock and let this
710 user edit the file anyway.
712 @item
713 @kindex file-locked
714 This function may instead signal a @code{file-locked} error, in which
715 case the change that the user was about to make does not take place.
717 The error message for this error looks like this:
719 @example
720 @error{} File is locked: @var{file} @var{other-user}
721 @end example
723 @noindent
724 where @code{file} is the name of the file and @var{other-user} is the
725 name of the user who has locked the file.
726 @end itemize
728 If you wish, you can replace the @code{ask-user-about-lock} function
729 with your own version that makes the decision in another way.  The code
730 for its usual definition is in @file{userlock.el}.
731 @end defun
733 @node Information about Files
734 @section Information about Files
736   The functions described in this section all operate on strings that
737 designate file names.  All the functions have names that begin with the
738 word @samp{file}.  These functions all return information about actual
739 files or directories, so their arguments must all exist as actual files
740 or directories unless otherwise noted.
742 @menu
743 * Testing Accessibility::   Is a given file readable?  Writable?
744 * Kinds of Files::          Is it a directory?  A symbolic link?
745 * Truenames::               Eliminating symbolic links from a file name.
746 * File Attributes::         How large is it?  Any other names?  Etc.
747 @end menu
749 @node Testing Accessibility
750 @comment  node-name,  next,  previous,  up
751 @subsection Testing Accessibility
752 @cindex accessibility of a file
753 @cindex file accessibility
755   These functions test for permission to access a file in specific
756 ways.  Unless explicitly stated otherwise, they recursively follow
757 symbolic links for their file name arguments, at all levels (at the
758 level of the file itself and at all levels of parent directories).
760 @defun file-exists-p filename
761 This function returns @code{t} if a file named @var{filename} appears
762 to exist.  This does not mean you can necessarily read the file, only
763 that you can find out its attributes.  (On Unix and GNU/Linux, this is
764 true if the file exists and you have execute permission on the
765 containing directories, regardless of the protection of the file
766 itself.)
768 If the file does not exist, or if fascist access control policies
769 prevent you from finding the attributes of the file, this function
770 returns @code{nil}.
772 Directories are files, so @code{file-exists-p} returns @code{t} when
773 given a directory name.  However, symbolic links are treated
774 specially; @code{file-exists-p} returns @code{t} for a symbolic link
775 name only if the target file exists.
776 @end defun
778 @defun file-readable-p filename
779 This function returns @code{t} if a file named @var{filename} exists
780 and you can read it.  It returns @code{nil} otherwise.
782 @example
783 @group
784 (file-readable-p "files.texi")
785      @result{} t
786 @end group
787 @group
788 (file-exists-p "/usr/spool/mqueue")
789      @result{} t
790 @end group
791 @group
792 (file-readable-p "/usr/spool/mqueue")
793      @result{} nil
794 @end group
795 @end example
796 @end defun
798 @c Emacs 19 feature
799 @defun file-executable-p filename
800 This function returns @code{t} if a file named @var{filename} exists and
801 you can execute it.  It returns @code{nil} otherwise.  On Unix and
802 GNU/Linux, if the file is a directory, execute permission means you can
803 check the existence and attributes of files inside the directory, and
804 open those files if their modes permit.
805 @end defun
807 @defun file-writable-p filename
808 This function returns @code{t} if the file @var{filename} can be written
809 or created by you, and @code{nil} otherwise.  A file is writable if the
810 file exists and you can write it.  It is creatable if it does not exist,
811 but the specified directory does exist and you can write in that
812 directory.
814 In the third example below, @file{foo} is not writable because the
815 parent directory does not exist, even though the user could create such
816 a directory.
818 @example
819 @group
820 (file-writable-p "~/foo")
821      @result{} t
822 @end group
823 @group
824 (file-writable-p "/foo")
825      @result{} nil
826 @end group
827 @group
828 (file-writable-p "~/no-such-dir/foo")
829      @result{} nil
830 @end group
831 @end example
832 @end defun
834 @c Emacs 19 feature
835 @defun file-accessible-directory-p dirname
836 This function returns @code{t} if you have permission to open existing
837 files in the directory whose name as a file is @var{dirname}; otherwise
838 (or if there is no such directory), it returns @code{nil}.  The value
839 of @var{dirname} may be either a directory name or the file name of a
840 file which is a directory.
842 Example: after the following,
844 @example
845 (file-accessible-directory-p "/foo")
846      @result{} nil
847 @end example
849 @noindent
850 we can deduce that any attempt to read a file in @file{/foo/} will
851 give an error.
852 @end defun
854 @defun access-file filename string
855 This function opens file @var{filename} for reading, then closes it and
856 returns @code{nil}.  However, if the open fails, it signals an error
857 using @var{string} as the error message text.
858 @end defun
860 @defun file-ownership-preserved-p filename
861 This function returns @code{t} if deleting the file @var{filename} and
862 then creating it anew would keep the file's owner unchanged.  It also
863 returns @code{t} for nonexistent files.
865 If @var{filename} is a symbolic link, then, unlike the other functions
866 discussed here, @code{file-ownership-preserved-p} does @emph{not}
867 replace @var{filename} with its target.  However, it does recursively
868 follow symbolic links at all levels of parent directories.
869 @end defun
871 @defun file-newer-than-file-p filename1 filename2
872 @cindex file age
873 @cindex file modification time
874 This function returns @code{t} if the file @var{filename1} is
875 newer than file @var{filename2}.  If @var{filename1} does not
876 exist, it returns @code{nil}.  If @var{filename1} does exist, but
877 @var{filename2} does not, it returns @code{t}.
879 In the following example, assume that the file @file{aug-19} was written
880 on the 19th, @file{aug-20} was written on the 20th, and the file
881 @file{no-file} doesn't exist at all.
883 @example
884 @group
885 (file-newer-than-file-p "aug-19" "aug-20")
886      @result{} nil
887 @end group
888 @group
889 (file-newer-than-file-p "aug-20" "aug-19")
890      @result{} t
891 @end group
892 @group
893 (file-newer-than-file-p "aug-19" "no-file")
894      @result{} t
895 @end group
896 @group
897 (file-newer-than-file-p "no-file" "aug-19")
898      @result{} nil
899 @end group
900 @end example
902 You can use @code{file-attributes} to get a file's last modification
903 time as a list of two numbers.  @xref{File Attributes}.
904 @end defun
906 @node Kinds of Files
907 @comment  node-name,  next,  previous,  up
908 @subsection Distinguishing Kinds of Files
910   This section describes how to distinguish various kinds of files, such
911 as directories, symbolic links, and ordinary files.
913 @defun file-symlink-p filename
914 @cindex file symbolic links
915 If the file @var{filename} is a symbolic link, the
916 @code{file-symlink-p} function returns the (non-recursive) link target
917 as a string.  (Determining the file name that the link points to from
918 the target is nontrivial.)  First, this function recursively follows
919 symbolic links at all levels of parent directories.
921 If the file @var{filename} is not a symbolic link (or there is no such file),
922 @code{file-symlink-p} returns @code{nil}.
924 @example
925 @group
926 (file-symlink-p "foo")
927      @result{} nil
928 @end group
929 @group
930 (file-symlink-p "sym-link")
931      @result{} "foo"
932 @end group
933 @group
934 (file-symlink-p "sym-link2")
935      @result{} "sym-link"
936 @end group
937 @group
938 (file-symlink-p "/bin")
939      @result{} "/pub/bin"
940 @end group
941 @end example
943 @c !!! file-symlink-p: should show output of ls -l for comparison
944 @end defun
946 The next two functions recursively follow symbolic links at
947 all levels for @var{filename}.
949 @defun file-directory-p filename
950 This function returns @code{t} if @var{filename} is the name of an
951 existing directory, @code{nil} otherwise.
953 @example
954 @group
955 (file-directory-p "~rms")
956      @result{} t
957 @end group
958 @group
959 (file-directory-p "~rms/lewis/files.texi")
960      @result{} nil
961 @end group
962 @group
963 (file-directory-p "~rms/lewis/no-such-file")
964      @result{} nil
965 @end group
966 @group
967 (file-directory-p "$HOME")
968      @result{} nil
969 @end group
970 @group
971 (file-directory-p
972  (substitute-in-file-name "$HOME"))
973      @result{} t
974 @end group
975 @end example
976 @end defun
978 @defun file-regular-p filename
979 This function returns @code{t} if the file @var{filename} exists and is
980 a regular file (not a directory, named pipe, terminal, or
981 other I/O device).
982 @end defun
984 @node Truenames
985 @subsection Truenames
986 @cindex truename (of file)
988 @c Emacs 19 features
989   The @dfn{truename} of a file is the name that you get by following
990 symbolic links at all levels until none remain, then simplifying away
991 @samp{.}@: and @samp{..}@: appearing as name components.  This results
992 in a sort of canonical name for the file.  A file does not always have a
993 unique truename; the number of distinct truenames a file has is equal to
994 the number of hard links to the file.  However, truenames are useful
995 because they eliminate symbolic links as a cause of name variation.
997 @defun file-truename filename
998 The function @code{file-truename} returns the truename of the file
999 @var{filename}.  The argument must be an absolute file name.
1001 This function does not expand environment variables.  Only
1002 @code{substitute-in-file-name} does that.  @xref{Definition of
1003 substitute-in-file-name}.
1005 If you may need to follow symbolic links preceding @samp{..}@:
1006 appearing as a name component, you should make sure to call
1007 @code{file-truename} without prior direct or indirect calls to
1008 @code{expand-file-name}, as otherwise the file name component
1009 immediately preceding @samp{..} will be ``simplified away'' before
1010 @code{file-truename} is called.  To eliminate the need for a call to
1011 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
1012 same way that @code{expand-file-name} does.  @xref{File Name
1013 Expansion,, Functions that Expand Filenames}.
1014 @end defun
1016 @defun file-chase-links filename &optional limit
1017 This function follows symbolic links, starting with @var{filename},
1018 until it finds a file name which is not the name of a symbolic link.
1019 Then it returns that file name.  This function does @emph{not} follow
1020 symbolic links at the level of parent directories.
1022 If you specify a number for @var{limit}, then after chasing through
1023 that many links, the function just returns what it has even if that is
1024 still a symbolic link.
1025 @end defun
1027   To illustrate the difference between @code{file-chase-links} and
1028 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
1029 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
1030 ordinary file (or at least, not a symbolic link) or nonexistent.  Then
1031 we would have:
1033 @example
1034 (file-chase-links "/usr/foo/hello")
1035      ;; @r{This does not follow the links in the parent directories.}
1036      @result{} "/usr/foo/hello"
1037 (file-truename "/usr/foo/hello")
1038      ;; @r{Assuming that @file{/home} is not a symbolic link.}
1039      @result{} "/home/foo/hello"
1040 @end example
1042   @xref{Buffer File Name}, for related information.
1044 @node File Attributes
1045 @comment  node-name,  next,  previous,  up
1046 @subsection Other Information about Files
1048   This section describes the functions for getting detailed information
1049 about a file, other than its contents.  This information includes the
1050 mode bits that control access permission, the owner and group numbers,
1051 the number of names, the inode number, the size, and the times of access
1052 and modification.
1054 @defun file-modes filename
1055 @cindex permission
1056 @cindex file attributes
1057 This function returns the mode bits of @var{filename}, as an integer.
1058 The mode bits are also called the file permissions, and they specify
1059 access control in the usual Unix fashion.  If the low-order bit is 1,
1060 then the file is executable by all users, if the second-lowest-order bit
1061 is 1, then the file is writable by all users, etc.
1063 The highest value returnable is 4095 (7777 octal), meaning that
1064 everyone has read, write, and execute permission, that the @acronym{SUID} bit
1065 is set for both others and group, and that the sticky bit is set.
1067 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
1069 This function recursively follows symbolic links at all levels.
1071 @example
1072 @group
1073 (file-modes "~/junk/diffs")
1074      @result{} 492               ; @r{Decimal integer.}
1075 @end group
1076 @group
1077 (format "%o" 492)
1078      @result{} "754"             ; @r{Convert to octal.}
1079 @end group
1081 @group
1082 (set-file-modes "~/junk/diffs" 438)
1083      @result{} nil
1084 @end group
1086 @group
1087 (format "%o" 438)
1088      @result{} "666"             ; @r{Convert to octal.}
1089 @end group
1091 @group
1092 % ls -l diffs
1093   -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
1094 @end group
1095 @end example
1096 @end defun
1098 If the @var{filename} argument to the next two functions is a symbolic
1099 link, then these function do @emph{not} replace it with its target.
1100 However, they both recursively follow symbolic links at all levels of
1101 parent directories.
1103 @defun file-nlinks filename
1104 This functions returns the number of names (i.e., hard links) that
1105 file @var{filename} has.  If the file does not exist, then this function
1106 returns @code{nil}.  Note that symbolic links have no effect on this
1107 function, because they are not considered to be names of the files they
1108 link to.
1110 @example
1111 @group
1112 % ls -l foo*
1113 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
1114 -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
1115 @end group
1117 @group
1118 (file-nlinks "foo")
1119      @result{} 2
1120 @end group
1121 @group
1122 (file-nlinks "doesnt-exist")
1123      @result{} nil
1124 @end group
1125 @end example
1126 @end defun
1128 @defun file-attributes filename &optional id-format
1129 @anchor{Definition of file-attributes}
1130 This function returns a list of attributes of file @var{filename}.  If
1131 the specified file cannot be opened, it returns @code{nil}.
1132 The optional parameter @var{id-format} specifies the preferred format
1133 of attributes @acronym{UID} and @acronym{GID} (see below)---the
1134 valid values are @code{'string} and @code{'integer}.  The latter is
1135 the default, but we plan to change that, so you should specify a
1136 non-@code{nil} value for @var{id-format} if you use the returned
1137 @acronym{UID} or @acronym{GID}.
1139 The elements of the list, in order, are:
1141 @enumerate 0
1142 @item
1143 @code{t} for a directory, a string for a symbolic link (the name
1144 linked to), or @code{nil} for a text file.
1146 @c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
1147 @item
1148 The number of names the file has.  Alternate names, also known as hard
1149 links, can be created by using the @code{add-name-to-file} function
1150 (@pxref{Changing Files}).
1152 @item
1153 The file's @acronym{UID} as a string or an integer.  If a string
1154 value cannot be looked up, the integer value is returned.
1156 @item
1157 The file's @acronym{GID} likewise.
1159 @item
1160 The time of last access, as a list of two integers.
1161 The first integer has the high-order 16 bits of time,
1162 the second has the low 16 bits.  (This is similar to the
1163 value of @code{current-time}; see @ref{Time of Day}.)
1165 @item
1166 The time of last modification as a list of two integers (as above).
1168 @item
1169 The time of last status change as a list of two integers (as above).
1171 @item
1172 The size of the file in bytes.  If the size is too large to fit in a
1173 Lisp integer, this is a floating point number.
1175 @item
1176 The file's modes, as a string of ten letters or dashes,
1177 as in @samp{ls -l}.
1179 @item
1180 @code{t} if the file's @acronym{GID} would change if file were
1181 deleted and recreated; @code{nil} otherwise.
1183 @item
1184 The file's inode number.  If possible, this is an integer.  If the inode
1185 number is too large to be represented as an integer in Emacs Lisp, then
1186 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
1187 holds the low 16 bits.
1189 @item
1190 The file system number of the file system that the file is in.
1191 Depending on the magnitude of the value, this can be either an integer
1192 or a cons cell, in the same manner as the inode number.  This element
1193 and the file's inode number together give enough information to
1194 distinguish any two files on the system---no two files can have the same
1195 values for both of these numbers.
1196 @end enumerate
1198 For example, here are the file attributes for @file{files.texi}:
1200 @example
1201 @group
1202 (file-attributes "files.texi" 'string)
1203      @result{}  (nil 1 "lh" "users"
1204           (8489 20284)
1205           (8489 20284)
1206           (8489 20285)
1207           14906 "-rw-rw-rw-"
1208           nil 129500 -32252)
1209 @end group
1210 @end example
1212 @noindent
1213 and here is how the result is interpreted:
1215 @table @code
1216 @item nil
1217 is neither a directory nor a symbolic link.
1219 @item 1
1220 has only one name (the name @file{files.texi} in the current default
1221 directory).
1223 @item "lh"
1224 is owned by the user with name "lh".
1226 @item "users"
1227 is in the group with name "users".
1229 @item (8489 20284)
1230 was last accessed on Aug 19 00:09.
1232 @item (8489 20284)
1233 was last modified on Aug 19 00:09.
1235 @item (8489 20285)
1236 last had its inode changed on Aug 19 00:09.
1238 @item 14906
1239 is 14906 bytes long.  (It may not contain 14906 characters, though,
1240 if some of the bytes belong to multibyte sequences.)
1242 @item "-rw-rw-rw-"
1243 has a mode of read and write access for the owner, group, and world.
1245 @item nil
1246 would retain the same @acronym{GID} if it were recreated.
1248 @item 129500
1249 has an inode number of 129500.
1250 @item -32252
1251 is on file system number -32252.
1252 @end table
1253 @end defun
1255 @node Changing Files
1256 @section Changing File Names and Attributes
1257 @cindex renaming files
1258 @cindex copying files
1259 @cindex deleting files
1260 @cindex linking files
1261 @cindex setting modes of files
1263   The functions in this section rename, copy, delete, link, and set the
1264 modes of files.
1266   In the functions that have an argument @var{newname}, if a file by the
1267 name of @var{newname} already exists, the actions taken depend on the
1268 value of the argument @var{ok-if-already-exists}:
1270 @itemize @bullet
1271 @item
1272 Signal a @code{file-already-exists} error if
1273 @var{ok-if-already-exists} is @code{nil}.
1275 @item
1276 Request confirmation if @var{ok-if-already-exists} is a number.
1278 @item
1279 Replace the old file without confirmation if @var{ok-if-already-exists}
1280 is any other value.
1281 @end itemize
1283 The next four commands all recursively follow symbolic links at all
1284 levels of parent directories for their first argument, but, if that
1285 argument is itself a symbolic link, then only @code{copy-file}
1286 replaces it with its (recursive) target.
1288 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
1289 @cindex file with multiple names
1290 @cindex file hard link
1291 This function gives the file named @var{oldname} the additional name
1292 @var{newname}.  This means that @var{newname} becomes a new ``hard
1293 link'' to @var{oldname}.
1295 In the first part of the following example, we list two files,
1296 @file{foo} and @file{foo3}.
1298 @example
1299 @group
1300 % ls -li fo*
1301 81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
1302 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1303 @end group
1304 @end example
1306 Now we create a hard link, by calling @code{add-name-to-file}, then list
1307 the files again.  This shows two names for one file, @file{foo} and
1308 @file{foo2}.
1310 @example
1311 @group
1312 (add-name-to-file "foo" "foo2")
1313      @result{} nil
1314 @end group
1316 @group
1317 % ls -li fo*
1318 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
1319 81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
1320 84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
1321 @end group
1322 @end example
1324 Finally, we evaluate the following:
1326 @example
1327 (add-name-to-file "foo" "foo3" t)
1328 @end example
1330 @noindent
1331 and list the files again.  Now there are three names
1332 for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
1333 contents of @file{foo3} are lost.
1335 @example
1336 @group
1337 (add-name-to-file "foo1" "foo3")
1338      @result{} nil
1339 @end group
1341 @group
1342 % ls -li fo*
1343 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
1344 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
1345 81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
1346 @end group
1347 @end example
1349 This function is meaningless on operating systems where multiple names
1350 for one file are not allowed.  Some systems implement multiple names
1351 by copying the file instead.
1353 See also @code{file-nlinks} in @ref{File Attributes}.
1354 @end deffn
1356 @deffn Command rename-file filename newname &optional ok-if-already-exists
1357 This command renames the file @var{filename} as @var{newname}.
1359 If @var{filename} has additional names aside from @var{filename}, it
1360 continues to have those names.  In fact, adding the name @var{newname}
1361 with @code{add-name-to-file} and then deleting @var{filename} has the
1362 same effect as renaming, aside from momentary intermediate states.
1363 @end deffn
1365 @deffn Command copy-file oldname newname &optional ok-if-exists time
1366 This command copies the file @var{oldname} to @var{newname}.  An
1367 error is signaled if @var{oldname} does not exist.  If @var{newname}
1368 names a directory, it copies @var{oldname} into that directory,
1369 preserving its final name component.
1371 If @var{time} is non-@code{nil}, then this function gives the new file
1372 the same last-modified time that the old one has.  (This works on only
1373 some operating systems.)  If setting the time gets an error,
1374 @code{copy-file} signals a @code{file-date-error} error.
1376 This function copies the file modes, too.
1378 In an interactive call, a prefix argument specifies a non-@code{nil}
1379 value for @var{time}.
1380 @end deffn
1382 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
1383 @pindex ln
1384 @kindex file-already-exists
1385 This command makes a symbolic link to @var{filename}, named
1386 @var{newname}.  This is like the shell command @samp{ln -s
1387 @var{filename} @var{newname}}.
1389 This function is not available on systems that don't support symbolic
1390 links.
1391 @end deffn
1393 @deffn Command delete-file filename
1394 @pindex rm
1395 This command deletes the file @var{filename}, like the shell command
1396 @samp{rm @var{filename}}.  If the file has multiple names, it continues
1397 to exist under the other names.
1399 A suitable kind of @code{file-error} error is signaled if the file does
1400 not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
1401 deletable if its directory is writable.)
1403 If @var{filename} is a symbolic link, @code{delete-file} does not
1404 replace it with its target, but it does follow symbolic links at all
1405 levels of parent directories.
1407 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1408 @end deffn
1410 @defun define-logical-name varname string
1411 This function defines the logical name @var{varname} to have the value
1412 @var{string}.  It is available only on VMS.
1413 @end defun
1415 @defun set-file-modes filename mode
1416 This function sets mode bits of @var{filename} to @var{mode} (which
1417 must be an integer).  Only the low 12 bits of @var{mode} are used.
1418 This function recursively follows symbolic links at all levels for
1419 @var{filename}.
1420 @end defun
1422 @c Emacs 19 feature
1423 @defun set-default-file-modes mode
1424 @cindex umask
1425 This function sets the default file protection for new files created by
1426 Emacs and its subprocesses.  Every file created with Emacs initially has
1427 this protection, or a subset of it (@code{write-region} will not give a
1428 file execute permission even if the default file protection allows
1429 execute permission).  On Unix and GNU/Linux, the default protection is
1430 the bitwise complement of the ``umask'' value.
1432 The argument @var{mode} must be an integer.  On most systems, only the
1433 low 9 bits of @var{mode} are meaningful.  You can use the Lisp construct
1434 for octal character codes to enter @var{mode}; for example,
1436 @example
1437 (set-default-file-modes ?\644)
1438 @end example
1440 Saving a modified version of an existing file does not count as creating
1441 the file; it preserves the existing file's mode, whatever that is.  So
1442 the default file protection has no effect.
1443 @end defun
1445 @defun default-file-modes
1446 This function returns the current default protection value.
1447 @end defun
1449 @defun set-file-times filename &optional time
1450 This function sets the access and modification times of @var{filename}
1451 to @var{time}.  The return value is @code{t} if the times are successfully
1452 set, otherwise it is @code{nil}.  @var{time} defaults to the current
1453 time and must be in the format returned by @code{current-time}
1454 (@pxref{Time of Day}).
1455 @end defun
1457 @cindex MS-DOS and file modes
1458 @cindex file modes and MS-DOS
1459   On MS-DOS, there is no such thing as an ``executable'' file mode bit.
1460 So Emacs considers a file executable if its name ends in one of the
1461 standard executable extensions, such as @file{.com}, @file{.bat},
1462 @file{.exe}, and some others.  Files that begin with the Unix-standard
1463 @samp{#!} signature, such as shell and Perl scripts, are also considered
1464 as executable files.  This is reflected in the values returned by
1465 @code{file-modes} and @code{file-attributes}.  Directories are also
1466 reported with executable bit set, for compatibility with Unix.
1468 @node File Names
1469 @section File Names
1470 @cindex file names
1472   Files are generally referred to by their names, in Emacs as elsewhere.
1473 File names in Emacs are represented as strings.  The functions that
1474 operate on a file all expect a file name argument.
1476   In addition to operating on files themselves, Emacs Lisp programs
1477 often need to operate on file names; i.e., to take them apart and to use
1478 part of a name to construct related file names.  This section describes
1479 how to manipulate file names.
1481   The functions in this section do not actually access files, so they
1482 can operate on file names that do not refer to an existing file or
1483 directory.
1485   On MS-DOS and MS-Windows, these functions (like the function that
1486 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
1487 where backslashes separate the components, as well as Unix syntax; but
1488 they always return Unix syntax.  On VMS, these functions (and the ones
1489 that operate on files) understand both VMS file-name syntax and Unix
1490 syntax.  This enables Lisp programs to specify file names in Unix syntax
1491 and work properly on all systems without change.
1493 @menu
1494 * File Name Components::  The directory part of a file name, and the rest.
1495 * Relative File Names::   Some file names are relative to a current directory.
1496 * Directory Names::       A directory's name as a directory
1497                             is different from its name as a file.
1498 * File Name Expansion::   Converting relative file names to absolute ones.
1499 * Unique File Names::     Generating names for temporary files.
1500 * File Name Completion::  Finding the completions for a given file name.
1501 * Standard File Names::   If your package uses a fixed file name,
1502                             how to handle various operating systems simply.
1503 @end menu
1505 @node File Name Components
1506 @subsection File Name Components
1507 @cindex directory part (of file name)
1508 @cindex nondirectory part (of file name)
1509 @cindex version number (in file name)
1511   The operating system groups files into directories.  To specify a
1512 file, you must specify the directory and the file's name within that
1513 directory.  Therefore, Emacs considers a file name as having two main
1514 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1515 (or @dfn{file name within the directory}).  Either part may be empty.
1516 Concatenating these two parts reproduces the original file name.
1518   On most systems, the directory part is everything up to and including
1519 the last slash (backslash is also allowed in input on MS-DOS or
1520 MS-Windows); the nondirectory part is the rest.  The rules in VMS syntax
1521 are complicated.
1523   For some purposes, the nondirectory part is further subdivided into
1524 the name proper and the @dfn{version number}.  On most systems, only
1525 backup files have version numbers in their names.  On VMS, every file
1526 has a version number, but most of the time the file name actually used
1527 in Emacs omits the version number, so that version numbers in Emacs are
1528 found mostly in directory lists.
1530 @defun file-name-directory filename
1531 This function returns the directory part of @var{filename}, as a
1532 directory name (@pxref{Directory Names}), or @code{nil} if
1533 @var{filename} does not include a directory part.
1535 On GNU and Unix systems, a string returned by this function always
1536 ends in a slash.  On MSDOS it can also end in a colon.  On VMS, it
1537 returns a string ending in one of the three characters @samp{:},
1538 @samp{]}, or @samp{>}.
1540 @example
1541 @group
1542 (file-name-directory "lewis/foo")  ; @r{Unix example}
1543      @result{} "lewis/"
1544 @end group
1545 @group
1546 (file-name-directory "foo")        ; @r{Unix example}
1547      @result{} nil
1548 @end group
1549 @group
1550 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
1551      @result{} "[X]"
1552 @end group
1553 @end example
1554 @end defun
1556 @defun file-name-nondirectory filename
1557 This function returns the nondirectory part of @var{filename}.
1559 @example
1560 @group
1561 (file-name-nondirectory "lewis/foo")
1562      @result{} "foo"
1563 @end group
1564 @group
1565 (file-name-nondirectory "foo")
1566      @result{} "foo"
1567 @end group
1568 @group
1569 (file-name-nondirectory "lewis/")
1570      @result{} ""
1571 @end group
1572 @group
1573 ;; @r{The following example is accurate only on VMS.}
1574 (file-name-nondirectory "[X]FOO.TMP")
1575      @result{} "FOO.TMP"
1576 @end group
1577 @end example
1578 @end defun
1580 @defun file-name-sans-versions filename &optional keep-backup-version
1581 This function returns @var{filename} with any file version numbers,
1582 backup version numbers, or trailing tildes discarded.
1584 If @var{keep-backup-version} is non-@code{nil}, then true file version
1585 numbers understood as such by the file system are discarded from the
1586 return value, but backup version numbers are kept.
1588 @example
1589 @group
1590 (file-name-sans-versions "~rms/foo.~1~")
1591      @result{} "~rms/foo"
1592 @end group
1593 @group
1594 (file-name-sans-versions "~rms/foo~")
1595      @result{} "~rms/foo"
1596 @end group
1597 @group
1598 (file-name-sans-versions "~rms/foo")
1599      @result{} "~rms/foo"
1600 @end group
1601 @group
1602 ;; @r{The following example applies to VMS only.}
1603 (file-name-sans-versions "foo;23")
1604      @result{} "foo"
1605 @end group
1606 @end example
1607 @end defun
1609 @defun file-name-extension filename &optional period
1610 This function returns @var{filename}'s final ``extension'', if any,
1611 after applying @code{file-name-sans-versions} to remove any
1612 version/backup part.  The extension, in a file name, is the part that
1613 starts with the last @samp{.} in the last name component (minus
1614 any version/backup part).
1616 This function returns @code{nil} for extensionless file names such as
1617 @file{foo}.  It returns @code{""} for null extensions, as in
1618 @file{foo.}.  If the last component of a file name begins with a
1619 @samp{.}, that @samp{.}  doesn't count as the beginning of an
1620 extension.  Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
1621 @samp{.emacs}.
1623 If @var{period} is non-@code{nil}, then the returned value includes
1624 the period that delimits the extension, and if @var{filename} has no
1625 extension, the value is @code{""}.
1626 @end defun
1628 @defun file-name-sans-extension filename
1629 This function returns @var{filename} minus its extension, if any.  The
1630 version/backup part, if present, is only removed if the file has an
1631 extension.  For example,
1633 @example
1634 (file-name-sans-extension "foo.lose.c")
1635      @result{} "foo.lose"
1636 (file-name-sans-extension "big.hack/foo")
1637      @result{} "big.hack/foo"
1638 (file-name-sans-extension "/my/home/.emacs")
1639      @result{} "/my/home/.emacs"
1640 (file-name-sans-extension "/my/home/.emacs.el")
1641      @result{} "/my/home/.emacs"
1642 (file-name-sans-extension "~/foo.el.~3~")
1643      @result{} "~/foo"
1644 (file-name-sans-extension "~/foo.~3~")
1645      @result{} "~/foo.~3~"
1646 @end example
1648 Note that the @samp{.~3~} in the two last examples is the backup part,
1649 not an extension.
1650 @end defun
1652 @ignore
1653 Andrew Innes says that this
1655 @c @defvar directory-sep-char
1656 @c @tindex directory-sep-char
1657 This variable holds the character that Emacs normally uses to separate
1658 file name components.  The default value is @code{?/}, but on MS-Windows
1659 you can set it to @code{?\\}; then the functions that transform file names
1660 use backslashes in their output.
1662 File names using backslashes work as input to Lisp primitives even on
1663 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
1664 value of @code{?/}.
1665 @end defvar
1666 @end ignore
1668 @node Relative File Names
1669 @subsection Absolute and Relative File Names
1670 @cindex absolute file name
1671 @cindex relative file name
1673   All the directories in the file system form a tree starting at the
1674 root directory.  A file name can specify all the directory names
1675 starting from the root of the tree; then it is called an @dfn{absolute}
1676 file name.  Or it can specify the position of the file in the tree
1677 relative to a default directory; then it is called a @dfn{relative} file
1678 name.  On Unix and GNU/Linux, an absolute file name starts with a slash
1679 or a tilde (@samp{~}), and a relative one does not.  On MS-DOS and
1680 MS-Windows, an absolute file name starts with a slash or a backslash, or
1681 with a drive specification @samp{@var{x}:/}, where @var{x} is the
1682 @dfn{drive letter}.  The rules on VMS are complicated.
1684 @defun file-name-absolute-p filename
1685 This function returns @code{t} if file @var{filename} is an absolute
1686 file name, @code{nil} otherwise.  On VMS, this function understands both
1687 Unix syntax and VMS syntax.
1689 @example
1690 @group
1691 (file-name-absolute-p "~rms/foo")
1692      @result{} t
1693 @end group
1694 @group
1695 (file-name-absolute-p "rms/foo")
1696      @result{} nil
1697 @end group
1698 @group
1699 (file-name-absolute-p "/user/rms/foo")
1700      @result{} t
1701 @end group
1702 @end example
1703 @end defun
1705 @node Directory Names
1706 @comment  node-name,  next,  previous,  up
1707 @subsection Directory Names
1708 @cindex directory name
1709 @cindex file name of directory
1711   A @dfn{directory name} is the name of a directory.  A directory is
1712 actually a kind of file, so it has a file name, which is related to
1713 the directory name but not identical to it.  (This is not quite the
1714 same as the usual Unix terminology.)  These two different names for
1715 the same entity are related by a syntactic transformation.  On GNU and
1716 Unix systems, this is simple: a directory name ends in a slash,
1717 whereas the directory's name as a file lacks that slash.  On MSDOS and
1718 VMS, the relationship is more complicated.
1720   The difference between a directory name and its name as a file is
1721 subtle but crucial.  When an Emacs variable or function argument is
1722 described as being a directory name, a file name of a directory is not
1723 acceptable.  When @code{file-name-directory} returns a string, that is
1724 always a directory name.
1726   The following two functions convert between directory names and file
1727 names.  They do nothing special with environment variable substitutions
1728 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
1730 @defun file-name-as-directory filename
1731 This function returns a string representing @var{filename} in a form
1732 that the operating system will interpret as the name of a directory.  On
1733 most systems, this means appending a slash to the string (if it does not
1734 already end in one).  On VMS, the function converts a string of the form
1735 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
1737 @example
1738 @group
1739 (file-name-as-directory "~rms/lewis")
1740      @result{} "~rms/lewis/"
1741 @end group
1742 @end example
1743 @end defun
1745 @defun directory-file-name dirname
1746 This function returns a string representing @var{dirname} in a form that
1747 the operating system will interpret as the name of a file.  On most
1748 systems, this means removing the final slash (or backslash) from the
1749 string.  On VMS, the function converts a string of the form @file{[X.Y]}
1750 to @file{[X]Y.DIR.1}.
1752 @example
1753 @group
1754 (directory-file-name "~lewis/")
1755      @result{} "~lewis"
1756 @end group
1757 @end example
1758 @end defun
1760   Given a directory name, you can combine it with a relative file name
1761 using @code{concat}:
1763 @example
1764 (concat @var{dirname} @var{relfile})
1765 @end example
1767 @noindent
1768 Be sure to verify that the file name is relative before doing that.
1769 If you use an absolute file name, the results could be syntactically
1770 invalid or refer to the wrong file.
1772   If you want to use a directory file name in making such a
1773 combination, you must first convert it to a directory name using
1774 @code{file-name-as-directory}:
1776 @example
1777 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
1778 @end example
1780 @noindent
1781 Don't try concatenating a slash by hand, as in
1783 @example
1784 ;;; @r{Wrong!}
1785 (concat @var{dirfile} "/" @var{relfile})
1786 @end example
1788 @noindent
1789 because this is not portable.  Always use
1790 @code{file-name-as-directory}.
1792 @cindex directory name abbreviation
1793   Directory name abbreviations are useful for directories that are
1794 normally accessed through symbolic links.  Sometimes the users recognize
1795 primarily the link's name as ``the name'' of the directory, and find it
1796 annoying to see the directory's ``real'' name.  If you define the link
1797 name as an abbreviation for the ``real'' name, Emacs shows users the
1798 abbreviation instead.
1800 @defvar directory-abbrev-alist
1801 The variable @code{directory-abbrev-alist} contains an alist of
1802 abbreviations to use for file directories.  Each element has the form
1803 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1804 @var{to} when it appears in a directory name.  The @var{from} string is
1805 actually a regular expression; it should always start with @samp{^}.
1806 The @var{to} string should be an ordinary absolute directory name.  Do
1807 not use @samp{~} to stand for a home directory in that string.  The
1808 function @code{abbreviate-file-name} performs these substitutions.
1810 You can set this variable in @file{site-init.el} to describe the
1811 abbreviations appropriate for your site.
1813 Here's an example, from a system on which file system @file{/home/fsf}
1814 and so on are normally accessed through symbolic links named @file{/fsf}
1815 and so on.
1817 @example
1818 (("^/home/fsf" . "/fsf")
1819  ("^/home/gp" . "/gp")
1820  ("^/home/gd" . "/gd"))
1821 @end example
1822 @end defvar
1824   To convert a directory name to its abbreviation, use this
1825 function:
1827 @defun abbreviate-file-name filename
1828 @anchor{Definition of abbreviate-file-name}
1829 This function applies abbreviations from @code{directory-abbrev-alist}
1830 to its argument, and substitutes @samp{~} for the user's home
1831 directory.  You can use it for directory names and for file names,
1832 because it recognizes abbreviations even as part of the name.
1833 @end defun
1835 @node File Name Expansion
1836 @subsection Functions that Expand Filenames
1837 @cindex expansion of file names
1839   @dfn{Expansion} of a file name means converting a relative file name
1840 to an absolute one.  Since this is done relative to a default directory,
1841 you must specify the default directory name as well as the file name to
1842 be expanded.  Expansion also simplifies file names by eliminating
1843 redundancies such as @file{./} and @file{@var{name}/../}.
1845 In the next two functions, the @var{directory} argument can be either
1846 a directory name or a directory file name.  @xref{Directory Names}.
1848 @defun expand-file-name filename &optional directory
1849 This function converts @var{filename} to an absolute file name.  If
1850 @var{directory} is supplied, it is the default directory to start with
1851 if @var{filename} is relative.  (The value of @var{directory} should
1852 itself be an absolute directory name; it may start with @samp{~}.)
1853 Otherwise, the current buffer's value of @code{default-directory} is
1854 used.  For example:
1856 @example
1857 @group
1858 (expand-file-name "foo")
1859      @result{} "/xcssun/users/rms/lewis/foo"
1860 @end group
1861 @group
1862 (expand-file-name "../foo")
1863      @result{} "/xcssun/users/rms/foo"
1864 @end group
1865 @group
1866 (expand-file-name "foo" "/usr/spool/")
1867      @result{} "/usr/spool/foo"
1868 @end group
1869 @group
1870 (expand-file-name "$HOME/foo")
1871      @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1872 @end group
1873 @end example
1875 If the part of the combined file name before the first slash is
1876 @samp{~}, it expands to the value of the @env{HOME} environment
1877 variable (usually your home directory).  If the part before the first
1878 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
1879 it expands to @var{user}'s home directory.
1881 Filenames containing @samp{.} or @samp{..} are simplified to their
1882 canonical form:
1884 @example
1885 @group
1886 (expand-file-name "bar/../foo")
1887      @result{} "/xcssun/users/rms/lewis/foo"
1888 @end group
1889 @end example
1891 Note that @code{expand-file-name} does @emph{not} expand environment
1892 variables; only @code{substitute-in-file-name} does that.
1894 Note also that @code{expand-file-name} does not follow symbolic links
1895 at any level.  This results in a difference between the way
1896 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
1897 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
1898 @samp{/tmp/foo/bar} we get:
1900 @example
1901 @group
1902 (file-truename "/tmp/bar/../myfile")
1903      @result{} "/tmp/foo/myfile"
1904 @end group
1905 @group
1906 (expand-file-name "/tmp/bar/../myfile")
1907      @result{} "/tmp/myfile"
1908 @end group
1909 @end example
1911 If you may need to follow symbolic links preceding @samp{..}, you
1912 should make sure to call @code{file-truename} without prior direct or
1913 indirect calls to @code{expand-file-name}.  @xref{Truenames}.
1914 @end defun
1916 @c Emacs 19 feature
1917 @defun file-relative-name filename &optional directory
1918 This function does the inverse of expansion---it tries to return a
1919 relative name that is equivalent to @var{filename} when interpreted
1920 relative to @var{directory}.  If @var{directory} is omitted or
1921 @code{nil}, it defaults to the current buffer's default directory.
1923 On some operating systems, an absolute file name begins with a device
1924 name.  On such systems, @var{filename} has no relative equivalent based
1925 on @var{directory} if they start with two different device names.  In
1926 this case, @code{file-relative-name} returns @var{filename} in absolute
1927 form.
1929 @example
1930 (file-relative-name "/foo/bar" "/foo/")
1931      @result{} "bar"
1932 (file-relative-name "/foo/bar" "/hack/")
1933      @result{} "../foo/bar"
1934 @end example
1935 @end defun
1937 @defvar default-directory
1938 The value of this buffer-local variable is the default directory for the
1939 current buffer.  It should be an absolute directory name; it may start
1940 with @samp{~}.  This variable is buffer-local in every buffer.
1942 @code{expand-file-name} uses the default directory when its second
1943 argument is @code{nil}.
1945 Aside from VMS, the value is always a string ending with a slash.
1947 @example
1948 @group
1949 default-directory
1950      @result{} "/user/lewis/manual/"
1951 @end group
1952 @end example
1953 @end defvar
1955 @defun substitute-in-file-name filename
1956 @anchor{Definition of substitute-in-file-name}
1957 This function replaces environment variable references in
1958 @var{filename} with the environment variable values.  Following
1959 standard Unix shell syntax, @samp{$} is the prefix to substitute an
1960 environment variable value.  If the input contains @samp{$$}, that is
1961 converted to @samp{$}; this gives the user a way to ``quote'' a
1962 @samp{$}.
1964 The environment variable name is the series of alphanumeric characters
1965 (including underscores) that follow the @samp{$}.  If the character following
1966 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
1967 matching @samp{@}}.
1969 Calling @code{substitute-in-file-name} on output produced by
1970 @code{substitute-in-file-name} tends to give incorrect results.  For
1971 instance, use of @samp{$$} to quote a single @samp{$} won't work
1972 properly, and @samp{$} in an environment variable's value could lead
1973 to repeated substitution.  Therefore, programs that call this function
1974 and put the output where it will be passed to this function need to
1975 double all @samp{$} characters to prevent subsequent incorrect
1976 results.
1978 @c Wordy to avoid overfull hbox.  --rjc 15mar92
1979 Here we assume that the environment variable @code{HOME}, which holds
1980 the user's home directory name, has value @samp{/xcssun/users/rms}.
1982 @example
1983 @group
1984 (substitute-in-file-name "$HOME/foo")
1985      @result{} "/xcssun/users/rms/foo"
1986 @end group
1987 @end example
1989 After substitution, if a @samp{~} or a @samp{/} appears immediately
1990 after another @samp{/}, the function discards everything before it (up
1991 through the immediately preceding @samp{/}).
1993 @example
1994 @group
1995 (substitute-in-file-name "bar/~/foo")
1996      @result{} "~/foo"
1997 @end group
1998 @group
1999 (substitute-in-file-name "/usr/local/$HOME/foo")
2000      @result{} "/xcssun/users/rms/foo"
2001      ;; @r{@file{/usr/local/} has been discarded.}
2002 @end group
2003 @end example
2005 On VMS, @samp{$} substitution is not done, so this function does nothing
2006 on VMS except discard superfluous initial components as shown above.
2007 @end defun
2009 @node Unique File Names
2010 @subsection Generating Unique File Names
2012   Some programs need to write temporary files.  Here is the usual way to
2013 construct a name for such a file, starting in Emacs 21:
2015 @example
2016 (make-temp-file @var{name-of-application})
2017 @end example
2019 @noindent
2020 The job of @code{make-temp-file} is to prevent two different users or
2021 two different jobs from trying to use the exact same file name.
2023 @defun make-temp-file prefix &optional dir-flag suffix
2024 @tindex make-temp-file
2025 This function creates a temporary file and returns its name.
2026 The name starts with @var{prefix}; it also contains a number that is
2027 different in each Emacs job.  If @var{prefix} is a relative file name,
2028 it is expanded against @code{temporary-file-directory}.
2030 @example
2031 @group
2032 (make-temp-file "foo")
2033      @result{} "/tmp/foo232J6v"
2034 @end group
2035 @end example
2037 When @code{make-temp-file} returns, the file has been created and is
2038 empty.  At that point, you should write the intended contents into the
2039 file.
2041 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
2042 empty directory instead of an empty file.  It returns the file name,
2043 not the directory name, of that directory.  @xref{Directory Names}.
2045 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
2046 the end of the file name.
2048 To prevent conflicts among different libraries running in the same
2049 Emacs, each Lisp program that uses @code{make-temp-file} should have its
2050 own @var{prefix}.  The number added to the end of @var{prefix}
2051 distinguishes between the same application running in different Emacs
2052 jobs.  Additional added characters permit a large number of distinct
2053 names even in one Emacs job.
2054 @end defun
2056   The default directory for temporary files is controlled by the
2057 variable @code{temporary-file-directory}.  This variable gives the user
2058 a uniform way to specify the directory for all temporary files.  Some
2059 programs use @code{small-temporary-file-directory} instead, if that is
2060 non-@code{nil}.  To use it, you should expand the prefix against
2061 the proper directory before calling @code{make-temp-file}.
2063   In older Emacs versions where @code{make-temp-file} does not exist,
2064 you should use @code{make-temp-name} instead:
2066 @example
2067 (make-temp-name
2068  (expand-file-name @var{name-of-application}
2069                    temporary-file-directory))
2070 @end example
2072 @defun make-temp-name string
2073 This function generates a string that can be used as a unique file name.
2074 The name starts with @var{string}, and contains a number that is
2075 different in each Emacs job.  It is like @code{make-temp-file} except
2076 that it just constructs a name, and does not create a file.  Another
2077 difference is that @var{string} should be an absolute file name.  On
2078 MS-DOS, this function can truncate the @var{string} prefix to fit into
2079 the 8+3 file-name limits.
2080 @end defun
2082 @defvar temporary-file-directory
2083 @cindex @code{TMPDIR} environment variable
2084 @cindex @code{TMP} environment variable
2085 @cindex @code{TEMP} environment variable
2086 This variable specifies the directory name for creating temporary files.
2087 Its value should be a directory name (@pxref{Directory Names}), but it
2088 is good for Lisp programs to cope if the value is a directory's file
2089 name instead.  Using the value as the second argument to
2090 @code{expand-file-name} is a good way to achieve that.
2092 The default value is determined in a reasonable way for your operating
2093 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
2094 environment variables, with a fall-back to a system-dependent name if
2095 none of these variables is defined.
2097 Even if you do not use @code{make-temp-file} to create the temporary
2098 file, you should still use this variable to decide which directory to
2099 put the file in.  However, if you expect the file to be small, you
2100 should use @code{small-temporary-file-directory} first if that is
2101 non-@code{nil}.
2102 @end defvar
2104 @tindex small-temporary-file-directory
2105 @defvar small-temporary-file-directory
2106 This variable (new in Emacs 21) specifies the directory name for
2107 creating certain temporary files, which are likely to be small.
2109 If you want to write a temporary file which is likely to be small, you
2110 should compute the directory like this:
2112 @example
2113 (make-temp-file
2114   (expand-file-name @var{prefix}
2115                     (or small-temporary-file-directory
2116                         temporary-file-directory)))
2117 @end example
2118 @end defvar
2120 @node File Name Completion
2121 @subsection File Name Completion
2122 @cindex file name completion subroutines
2123 @cindex completion, file name
2125   This section describes low-level subroutines for completing a file
2126 name.  For other completion functions, see @ref{Completion}.
2128 @defun file-name-all-completions partial-filename directory
2129 This function returns a list of all possible completions for a file
2130 whose name starts with @var{partial-filename} in directory
2131 @var{directory}.  The order of the completions is the order of the files
2132 in the directory, which is unpredictable and conveys no useful
2133 information.
2135 The argument @var{partial-filename} must be a file name containing no
2136 directory part and no slash (or backslash on some systems).  The current
2137 buffer's default directory is prepended to @var{directory}, if
2138 @var{directory} is not absolute.
2140 In the following example, suppose that @file{~rms/lewis} is the current
2141 default directory, and has five files whose names begin with @samp{f}:
2142 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2143 @file{file.c.~2~}.@refill
2145 @example
2146 @group
2147 (file-name-all-completions "f" "")
2148      @result{} ("foo" "file~" "file.c.~2~"
2149                 "file.c.~1~" "file.c")
2150 @end group
2152 @group
2153 (file-name-all-completions "fo" "")
2154      @result{} ("foo")
2155 @end group
2156 @end example
2157 @end defun
2159 @defun file-name-completion filename directory
2160 This function completes the file name @var{filename} in directory
2161 @var{directory}.  It returns the longest prefix common to all file names
2162 in directory @var{directory} that start with @var{filename}.
2164 If only one match exists and @var{filename} matches it exactly, the
2165 function returns @code{t}.  The function returns @code{nil} if directory
2166 @var{directory} contains no name starting with @var{filename}.
2168 In the following example, suppose that the current default directory
2169 has five files whose names begin with @samp{f}: @file{foo},
2170 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
2171 @file{file.c.~2~}.@refill
2173 @example
2174 @group
2175 (file-name-completion "fi" "")
2176      @result{} "file"
2177 @end group
2179 @group
2180 (file-name-completion "file.c.~1" "")
2181      @result{} "file.c.~1~"
2182 @end group
2184 @group
2185 (file-name-completion "file.c.~1~" "")
2186      @result{} t
2187 @end group
2189 @group
2190 (file-name-completion "file.c.~3" "")
2191      @result{} nil
2192 @end group
2193 @end example
2194 @end defun
2196 @defopt completion-ignored-extensions
2197 @code{file-name-completion} usually ignores file names that end in any
2198 string in this list.  It does not ignore them when all the possible
2199 completions end in one of these suffixes.  This variable has no effect
2200 on @code{file-name-all-completions}.@refill
2202 A typical value might look like this:
2204 @example
2205 @group
2206 completion-ignored-extensions
2207      @result{} (".o" ".elc" "~" ".dvi")
2208 @end group
2209 @end example
2211 If an element of @code{completion-ignored-extensions} ends in a slash
2212 @samp{/}, it signals a directory.  The elements which do @emph{not} end
2213 in a slash will never match a directory; thus, the above value will not
2214 filter out a directory named @file{foo.elc}.
2215 @end defopt
2217 @node Standard File Names
2218 @subsection Standard File Names
2220   Most of the file names used in Lisp programs are entered by the user.
2221 But occasionally a Lisp program needs to specify a standard file name
2222 for a particular use---typically, to hold customization information
2223 about each user.  For example, abbrev definitions are stored (by
2224 default) in the file @file{~/.abbrev_defs}; the @code{completion}
2225 package stores completions in the file @file{~/.completions}.  These are
2226 two of the many standard file names used by parts of Emacs for certain
2227 purposes.
2229   Various operating systems have their own conventions for valid file
2230 names and for which file names to use for user profile data.  A Lisp
2231 program which reads a file using a standard file name ought to use, on
2232 each type of system, a file name suitable for that system.  The function
2233 @code{convert-standard-filename} makes this easy to do.
2235 @defun convert-standard-filename filename
2236 This function alters the file name @var{filename} to fit the conventions
2237 of the operating system in use, and returns the result as a new string.
2238 @end defun
2240   The recommended way to specify a standard file name in a Lisp program
2241 is to choose a name which fits the conventions of GNU and Unix systems,
2242 usually with a nondirectory part that starts with a period, and pass it
2243 to @code{convert-standard-filename} instead of using it directly.  Here
2244 is an example from the @code{completion} package:
2246 @example
2247 (defvar save-completions-file-name
2248         (convert-standard-filename "~/.completions")
2249   "*The file name to save completions to.")
2250 @end example
2252   On GNU and Unix systems, and on some other systems as well,
2253 @code{convert-standard-filename} returns its argument unchanged.  On
2254 some other systems, it alters the name to fit the system's conventions.
2256   For example, on MS-DOS the alterations made by this function include
2257 converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
2258 middle of the name to @samp{.} if there is no other @samp{.}, inserting
2259 a @samp{.} after eight characters if there is none, and truncating to
2260 three characters after the @samp{.}.  (It makes other changes as well.)
2261 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
2262 @file{.completions} becomes @file{_complet.ion}.
2264 @node Contents of Directories
2265 @section Contents of Directories
2266 @cindex directory-oriented functions
2267 @cindex file names in directory
2269   A directory is a kind of file that contains other files entered under
2270 various names.  Directories are a feature of the file system.
2272   Emacs can list the names of the files in a directory as a Lisp list,
2273 or display the names in a buffer using the @code{ls} shell command.  In
2274 the latter case, it can optionally display information about each file,
2275 depending on the options passed to the @code{ls} command.
2277 @defun directory-files directory &optional full-name match-regexp nosort
2278 This function returns a list of the names of the files in the directory
2279 @var{directory}.  By default, the list is in alphabetical order.
2281 If @var{full-name} is non-@code{nil}, the function returns the files'
2282 absolute file names.  Otherwise, it returns the names relative to
2283 the specified directory.
2285 If @var{match-regexp} is non-@code{nil}, this function returns only
2286 those file names that contain a match for that regular expression---the
2287 other file names are excluded from the list.
2289 @c Emacs 19 feature
2290 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
2291 the list, so you get the file names in no particular order.  Use this if
2292 you want the utmost possible speed and don't care what order the files
2293 are processed in.  If the order of processing is visible to the user,
2294 then the user will probably be happier if you do sort the names.
2296 @example
2297 @group
2298 (directory-files "~lewis")
2299      @result{} ("#foo#" "#foo.el#" "." ".."
2300          "dired-mods.el" "files.texi"
2301          "files.texi.~1~")
2302 @end group
2303 @end example
2305 An error is signaled if @var{directory} is not the name of a directory
2306 that can be read.
2307 @end defun
2309 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
2310 This is similar to @code{directory-files} in deciding which files
2311 to report on and how to report their names.  However, instead
2312 of returning a list of file names, it returns for each file a
2313 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
2314 is what @code{file-attributes} would return for that file.
2315 The optional argument @var{id-format} has the same meaning as the
2316 corresponding argument to @code{file-attributes} (@pxref{Definition
2317 of file-attributes}).
2318 @end defun
2320 @defun file-name-all-versions file dirname
2321 This function returns a list of all versions of the file named
2322 @var{file} in directory @var{dirname}.  It is only available on VMS.
2323 @end defun
2325 @tindex file-expand-wildcards
2326 @defun file-expand-wildcards pattern &optional full
2327 This function expands the wildcard pattern @var{pattern}, returning
2328 a list of file names that match it.
2330 If @var{pattern} is written as an absolute file name,
2331 the values are absolute also.
2333 If @var{pattern} is written as a relative file name, it is interpreted
2334 relative to the current default directory.  The file names returned are
2335 normally also relative to the current default directory.  However, if
2336 @var{full} is non-@code{nil}, they are absolute.
2337 @end defun
2339 @defun insert-directory file switches &optional wildcard full-directory-p
2340 This function inserts (in the current buffer) a directory listing for
2341 directory @var{file}, formatted with @code{ls} according to
2342 @var{switches}.  It leaves point after the inserted text.
2343 @var{switches} may be a string of options, or a list of strings
2344 representing individual options.
2346 The argument @var{file} may be either a directory name or a file
2347 specification including wildcard characters.  If @var{wildcard} is
2348 non-@code{nil}, that means treat @var{file} as a file specification with
2349 wildcards.
2351 If @var{full-directory-p} is non-@code{nil}, that means the directory
2352 listing is expected to show the full contents of a directory.  You
2353 should specify @code{t} when @var{file} is a directory and switches do
2354 not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
2355 describe a directory itself as a file, rather than showing its
2356 contents.)
2358 On most systems, this function works by running a directory listing
2359 program whose name is in the variable @code{insert-directory-program}.
2360 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
2361 @code{shell-file-name}, to expand the wildcards.
2363 MS-DOS and MS-Windows systems usually lack the standard Unix program
2364 @code{ls}, so this function emulates the standard Unix program @code{ls}
2365 with Lisp code.
2367 As a technical detail, when @var{switches} contains the long
2368 @samp{--dired} option, @code{insert-directory} treats it specially,
2369 for the sake of dired.  However, the normally equivalent short
2370 @samp{-D} option is just passed on to @code{insert-directory-program},
2371 as any other option.
2372 @end defun
2374 @defvar insert-directory-program
2375 This variable's value is the program to run to generate a directory listing
2376 for the function @code{insert-directory}.  It is ignored on systems
2377 which generate the listing with Lisp code.
2378 @end defvar
2380 @node Create/Delete Dirs
2381 @section Creating and Deleting Directories
2382 @c Emacs 19 features
2384   Most Emacs Lisp file-manipulation functions get errors when used on
2385 files that are directories.  For example, you cannot delete a directory
2386 with @code{delete-file}.  These special functions exist to create and
2387 delete directories.
2389 @defun make-directory dirname &optional parents
2390 This function creates a directory named @var{dirname}.
2391 If @var{parents} is non-@code{nil}, as is always the case in an
2392 interactive call, that means to create the parent directories first,
2393 if they don't already exist.
2394 @end defun
2396 @defun delete-directory dirname
2397 This function deletes the directory named @var{dirname}.  The function
2398 @code{delete-file} does not work for files that are directories; you
2399 must use @code{delete-directory} for them.  If the directory contains
2400 any files, @code{delete-directory} signals an error.
2402 This function only follows symbolic links at the level of parent
2403 directories.
2404 @end defun
2406 @node Magic File Names
2407 @section Making Certain File Names ``Magic''
2408 @cindex magic file names
2410 @c Emacs 19 feature
2411   You can implement special handling for certain file names.  This is
2412 called making those names @dfn{magic}.  The principal use for this
2413 feature is in implementing remote file names (@pxref{Remote Files,,
2414 Remote Files, emacs, The GNU Emacs Manual}).
2416   To define a kind of magic file name, you must supply a regular
2417 expression to define the class of names (all those that match the
2418 regular expression), plus a handler that implements all the primitive
2419 Emacs file operations for file names that do match.
2421   The variable @code{file-name-handler-alist} holds a list of handlers,
2422 together with regular expressions that determine when to apply each
2423 handler.  Each element has this form:
2425 @example
2426 (@var{regexp} . @var{handler})
2427 @end example
2429 @noindent
2430 All the Emacs primitives for file access and file name transformation
2431 check the given file name against @code{file-name-handler-alist}.  If
2432 the file name matches @var{regexp}, the primitives handle that file by
2433 calling @var{handler}.
2435 The first argument given to @var{handler} is the name of the
2436 primitive, as a symbol; the remaining arguments are the arguments that
2437 were passed to that primitive.  (The first of these arguments is most
2438 often the file name itself.)  For example, if you do this:
2440 @example
2441 (file-exists-p @var{filename})
2442 @end example
2444 @noindent
2445 and @var{filename} has handler @var{handler}, then @var{handler} is
2446 called like this:
2448 @example
2449 (funcall @var{handler} 'file-exists-p @var{filename})
2450 @end example
2452 When a function takes two or more arguments that must be file names,
2453 it checks each of those names for a handler.  For example, if you do
2454 this:
2456 @example
2457 (expand-file-name @var{filename} @var{dirname})
2458 @end example
2460 @noindent
2461 then it checks for a handler for @var{filename} and then for a handler
2462 for @var{dirname}.  In either case, the @var{handler} is called like
2463 this:
2465 @example
2466 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
2467 @end example
2469 @noindent
2470 The @var{handler} then needs to figure out whether to handle
2471 @var{filename} or @var{dirname}.
2473 If the specified file name matches more than one handler, the one
2474 whose match starts last in the file name gets precedence.  This rule
2475 is chosen so that handlers for jobs such as uncompression are handled
2476 first, before handlers for jobs such as remote file access.
2478 Here are the operations that a magic file name handler gets to handle:
2480 @ifnottex
2481 @noindent
2482 @code{access-file}, @code{add-name-to-file},
2483 @code{byte-compiler-base-file-name},@*
2484 @code{copy-file}, @code{delete-directory},
2485 @code{delete-file},
2486 @code{diff-latest-backup-file},
2487 @code{directory-file-name},
2488 @code{directory-files},
2489 @code{directory-files-and-attributes},
2490 @code{dired-call-process},
2491 @code{dired-compress-file}, @code{dired-uncache},@*
2492 @code{expand-file-name},
2493 @code{file-accessible-directory-p},
2494 @code{file-attributes},
2495 @code{file-directory-p},
2496 @code{file-executable-p}, @code{file-exists-p},
2497 @code{file-local-copy}, @code{file-remote-p},
2498 @code{file-modes}, @code{file-name-all-completions},
2499 @code{file-name-as-directory},
2500 @code{file-name-completion},
2501 @code{file-name-directory},
2502 @code{file-name-nondirectory},
2503 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2504 @code{file-ownership-preserved-p},
2505 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2506 @code{file-truename}, @code{file-writable-p},
2507 @code{find-backup-file-name},
2508 @code{find-file-noselect},@*
2509 @code{get-file-buffer},
2510 @code{insert-directory},
2511 @code{insert-file-contents},@*
2512 @code{load}, @code{make-directory},
2513 @code{make-directory-internal},
2514 @code{make-symbolic-link},@*
2515 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
2516 @code{set-visited-file-modtime}, @code{shell-command},
2517 @code{substitute-in-file-name},@*
2518 @code{unhandled-file-name-directory},
2519 @code{vc-registered},
2520 @code{verify-visited-file-modtime},@*
2521 @code{write-region}.
2522 @end ifnottex
2523 @iftex
2524 @noindent
2525 @flushleft
2526 @code{access-file}, @code{add-name-to-file},
2527 @code{byte-com@discretionary{}{}{}piler-base-file-name},
2528 @code{copy-file}, @code{delete-directory},
2529 @code{delete-file},
2530 @code{diff-latest-backup-file},
2531 @code{directory-file-name},
2532 @code{directory-files},
2533 @code{directory-files-and-at@discretionary{}{}{}tributes},
2534 @code{dired-call-process},
2535 @code{dired-compress-file}, @code{dired-uncache},
2536 @code{expand-file-name},
2537 @code{file-accessible-direc@discretionary{}{}{}tory-p},
2538 @code{file-attributes},
2539 @code{file-direct@discretionary{}{}{}ory-p},
2540 @code{file-executable-p}, @code{file-exists-p},
2541 @code{file-local-copy}, @code{file-remote-p},
2542 @code{file-modes}, @code{file-name-all-completions},
2543 @code{file-name-as-directory},
2544 @code{file-name-completion},
2545 @code{file-name-directory},
2546 @code{file-name-nondirec@discretionary{}{}{}tory},
2547 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2548 @code{file-ownership-pre@discretionary{}{}{}served-p},
2549 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2550 @code{file-truename}, @code{file-writable-p},
2551 @code{find-backup-file-name},
2552 @code{find-file-noselect},
2553 @code{get-file-buffer},
2554 @code{insert-directory},
2555 @code{insert-file-contents},
2556 @code{load}, @code{make-direc@discretionary{}{}{}tory},
2557 @code{make-direc@discretionary{}{}{}tory-internal},
2558 @code{make-symbolic-link},
2559 @code{rename-file}, @code{set-file-modes},
2560 @code{set-visited-file-modtime}, @code{shell-command},
2561 @code{substitute-in-file-name},
2562 @code{unhandled-file-name-directory},
2563 @code{vc-regis@discretionary{}{}{}tered},
2564 @code{verify-visited-file-modtime},
2565 @code{write-region}.
2566 @end flushleft
2567 @end iftex
2569 Handlers for @code{insert-file-contents} typically need to clear the
2570 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2571 @var{visit} argument is non-@code{nil}.  This also has the effect of
2572 unlocking the buffer if it is locked.
2574 The handler function must handle all of the above operations, and
2575 possibly others to be added in the future.  It need not implement all
2576 these operations itself---when it has nothing special to do for a
2577 certain operation, it can reinvoke the primitive, to handle the
2578 operation ``in the usual way''.  It should always reinvoke the primitive
2579 for an operation it does not recognize.  Here's one way to do this:
2581 @smallexample
2582 (defun my-file-handler (operation &rest args)
2583   ;; @r{First check for the specific operations}
2584   ;; @r{that we have special handling for.}
2585   (cond ((eq operation 'insert-file-contents) @dots{})
2586         ((eq operation 'write-region) @dots{})
2587         @dots{}
2588         ;; @r{Handle any operation we don't know about.}
2589         (t (let ((inhibit-file-name-handlers
2590                   (cons 'my-file-handler
2591                         (and (eq inhibit-file-name-operation operation)
2592                              inhibit-file-name-handlers)))
2593                  (inhibit-file-name-operation operation))
2594              (apply operation args)))))
2595 @end smallexample
2597 When a handler function decides to call the ordinary Emacs primitive for
2598 the operation at hand, it needs to prevent the primitive from calling
2599 the same handler once again, thus leading to an infinite recursion.  The
2600 example above shows how to do this, with the variables
2601 @code{inhibit-file-name-handlers} and
2602 @code{inhibit-file-name-operation}.  Be careful to use them exactly as
2603 shown above; the details are crucial for proper behavior in the case of
2604 multiple handlers, and for operations that have two file names that may
2605 each have handlers.
2607 @kindex safe-magic (@r{property})
2608 Handlers that don't really do anything special for actual access to the
2609 file---such as the ones that implement completion of host names for
2610 remote file names---should have a non-@code{nil} @code{safe-magic}
2611 property.  For instance, Emacs normally ``protects'' directory names
2612 it finds in @code{PATH} from becoming magic, if they look like magic
2613 file names, by prefixing them with @samp{/:}.  But if the handler that
2614 would be used for them has a non-@code{nil} @code{safe-magic}
2615 property, the @samp{/:} is not added.
2617 @defvar inhibit-file-name-handlers
2618 This variable holds a list of handlers whose use is presently inhibited
2619 for a certain operation.
2620 @end defvar
2622 @defvar inhibit-file-name-operation
2623 The operation for which certain handlers are presently inhibited.
2624 @end defvar
2626 @defun find-file-name-handler file operation
2627 This function returns the handler function for file name @var{file}, or
2628 @code{nil} if there is none.  The argument @var{operation} should be the
2629 operation to be performed on the file---the value you will pass to the
2630 handler as its first argument when you call it.  The operation is needed
2631 for comparison with @code{inhibit-file-name-operation}.
2632 @end defun
2634 @defun file-local-copy filename
2635 This function copies file @var{filename} to an ordinary non-magic file
2636 on the local machine, if it isn't on the local machine already.  Magic
2637 file names should handle the @code{file-local-copy} operation if they
2638 refer to files on other machines.  A magic file name that is used for
2639 other purposes than remote file access should not handle
2640 @code{file-local-copy}; then this function will treat the file as
2641 local.
2643 If @var{filename} is local, whether magic or not, this function does
2644 nothing and returns @code{nil}.  Otherwise it returns the file name
2645 of the local copy file.
2646 @end defun
2648 @defun file-remote-p filename
2649 This function tests whether @var{filename} is a remote file.  If
2650 @var{filename} is local (not remote), the return value is @code{nil}.
2651 If @var{filename} is indeed remote, the return value is a string that
2652 identifies the remote system.
2654 This identifier string may include a host name, a user name, and
2655 characters designating the method used to access the remote system.
2656 For example, the remote identifier string for the filename
2657 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
2659 If @code{file-remote-p} returns the same identifier for two different
2660 filenames, that means they are stored on the same file system and can
2661 be accessed locally with respect to each other.  This means, for
2662 example, that it is possible to start a remote process accessing both
2663 files at the same time.  Implementors of file handlers need to ensure
2664 this principle is valid.
2665 @end defun
2667 @defun unhandled-file-name-directory filename
2668 This function returns the name of a directory that is not magic.  It
2669 uses the directory part of @var{filename} if that is not magic.  For a
2670 magic file name, it invokes the file name handler, which therefore
2671 decides what value to return.
2673 This is useful for running a subprocess; every subprocess must have a
2674 non-magic directory to serve as its current directory, and this function
2675 is a good way to come up with one.
2676 @end defun
2678 @node Format Conversion
2679 @section File Format Conversion
2681 @cindex file format conversion
2682 @cindex encoding file formats
2683 @cindex decoding file formats
2684   The variable @code{format-alist} defines a list of @dfn{file formats},
2685 which describe textual representations used in files for the data (text,
2686 text-properties, and possibly other information) in an Emacs buffer.
2687 Emacs performs format conversion if appropriate when reading and writing
2688 files.
2690 @defvar format-alist
2691 This list contains one format definition for each defined file format.
2692 @end defvar
2694 @cindex format definition
2695 Each format definition is a list of this form:
2697 @example
2698 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2699 @end example
2701 Here is what the elements in a format definition mean:
2703 @table @var
2704 @item name
2705 The name of this format.
2707 @item doc-string
2708 A documentation string for the format.
2710 @item regexp
2711 A regular expression which is used to recognize files represented in
2712 this format.
2714 @item from-fn
2715 A shell command or function to decode data in this format (to convert
2716 file data into the usual Emacs data representation).
2718 A shell command is represented as a string; Emacs runs the command as a
2719 filter to perform the conversion.
2721 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
2722 and @var{end}, which specify the part of the buffer it should convert.
2723 It should convert the text by editing it in place.  Since this can
2724 change the length of the text, @var{from-fn} should return the modified
2725 end position.
2727 One responsibility of @var{from-fn} is to make sure that the beginning
2728 of the file no longer matches @var{regexp}.  Otherwise it is likely to
2729 get called again.
2731 @item to-fn
2732 A shell command or function to encode data in this format---that is, to
2733 convert the usual Emacs data representation into this format.
2735 If @var{to-fn} is a string, it is a shell command; Emacs runs the
2736 command as a filter to perform the conversion.
2738 If @var{to-fn} is a function, it is called with two arguments, @var{begin}
2739 and @var{end}, which specify the part of the buffer it should convert.
2740 There are two ways it can do the conversion:
2742 @itemize @bullet
2743 @item
2744 By editing the buffer in place.  In this case, @var{to-fn} should
2745 return the end-position of the range of text, as modified.
2747 @item
2748 By returning a list of annotations.  This is a list of elements of the
2749 form @code{(@var{position} . @var{string})}, where @var{position} is an
2750 integer specifying the relative position in the text to be written, and
2751 @var{string} is the annotation to add there.  The list must be sorted in
2752 order of position when @var{to-fn} returns it.
2754 When @code{write-region} actually writes the text from the buffer to the
2755 file, it intermixes the specified annotations at the corresponding
2756 positions.  All this takes place without modifying the buffer.
2757 @end itemize
2759 @item modify
2760 A flag, @code{t} if the encoding function modifies the buffer, and
2761 @code{nil} if it works by returning a list of annotations.
2763 @item mode-fn
2764 A minor-mode function to call after visiting a file converted from this
2765 format.  The function is called with one argument, the integer 1;
2766 that tells a minor-mode function to enable the mode.
2767 @end table
2769 The function @code{insert-file-contents} automatically recognizes file
2770 formats when it reads the specified file.  It checks the text of the
2771 beginning of the file against the regular expressions of the format
2772 definitions, and if it finds a match, it calls the decoding function for
2773 that format.  Then it checks all the known formats over again.
2774 It keeps checking them until none of them is applicable.
2776 Visiting a file, with @code{find-file-noselect} or the commands that use
2777 it, performs conversion likewise (because it calls
2778 @code{insert-file-contents}); it also calls the mode function for each
2779 format that it decodes.  It stores a list of the format names in the
2780 buffer-local variable @code{buffer-file-format}.
2782 @defvar buffer-file-format
2783 This variable states the format of the visited file.  More precisely,
2784 this is a list of the file format names that were decoded in the course
2785 of visiting the current buffer's file.  It is always buffer-local in all
2786 buffers.
2787 @end defvar
2789 When @code{write-region} writes data into a file, it first calls the
2790 encoding functions for the formats listed in @code{buffer-file-format},
2791 in the order of appearance in the list.
2793 @deffn Command format-write-file file format &optional confirm
2794 This command writes the current buffer contents into the file
2795 @var{file} in format @var{format}, and makes that format the default
2796 for future saves of the buffer.  The argument @var{format} is a list
2797 of format names.  Except for the @var{format} argument, this command
2798 is similar to @code{write-file}.  In particular, @var{confirm} has the
2799 same meaning and interactive treatment as the corresponding argument
2800 to @code{write-file}.  @xref{Definition of write-file}.
2801 @end deffn
2803 @deffn Command format-find-file file format
2804 This command finds the file @var{file}, converting it according to
2805 format @var{format}.  It also makes @var{format} the default if the
2806 buffer is saved later.
2808 The argument @var{format} is a list of format names.  If @var{format} is
2809 @code{nil}, no conversion takes place.  Interactively, typing just
2810 @key{RET} for @var{format} specifies @code{nil}.
2811 @end deffn
2813 @deffn Command format-insert-file file format &optional beg end
2814 This command inserts the contents of file @var{file}, converting it
2815 according to format @var{format}.  If @var{beg} and @var{end} are
2816 non-@code{nil}, they specify which part of the file to read, as in
2817 @code{insert-file-contents} (@pxref{Reading from Files}).
2819 The return value is like what @code{insert-file-contents} returns: a
2820 list of the absolute file name and the length of the data inserted
2821 (after conversion).
2823 The argument @var{format} is a list of format names.  If @var{format} is
2824 @code{nil}, no conversion takes place.  Interactively, typing just
2825 @key{RET} for @var{format} specifies @code{nil}.
2826 @end deffn
2828 @defvar buffer-auto-save-file-format
2829 This variable specifies the format to use for auto-saving.  Its value is
2830 a list of format names, just like the value of
2831 @code{buffer-file-format}; however, it is used instead of
2832 @code{buffer-file-format} for writing auto-save files.  If the value
2833 is @code{t}, the default, auto-saving uses the same format as a
2834 regular save in the same buffer.  This variable is always buffer-local
2835 in all buffers.
2836 @end defvar
2838 @ignore
2839    arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
2840 @end ignore