1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
55 Changing File Names and Attributes
56 ==================================
58 The functions in this section rename, copy, delete, link, and set the
61 In the functions that have arguments NEWNAME and
62 OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
63 the actions taken depend on the value of OK-IF-ALREADY-EXISTS:
65 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
68 * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is
69 what happens when the function is invoked interactively.
71 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
74 - Command: add-name-to-file filename newname &optional
76 This function gives the file named FILENAME the additional name
77 NEWNAME. This means that NEWNAME becomes a new "hard link" to
78 FILENAME. Both these arguments must be strings.
80 In the first part of the following example, we list two files,
84 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
85 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
87 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
88 "~/lewis/foo2")'. Again we list the files. This shows two names,
91 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
95 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
96 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
97 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
99 Finally, we evaluate the following:
101 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
103 and list the files again. Now there are three names for one file:
104 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
106 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
110 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
111 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
112 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
114 This function is meaningless on non-Unix systems, where multiple
115 names for one file are not allowed.
117 See also `file-nlinks' in *Note File Attributes::.
119 - Command: rename-file filename newname &optional ok-if-already-exists
120 This command renames the file FILENAME as NEWNAME.
122 If FILENAME has additional names aside from FILENAME, it continues
123 to have those names. In fact, adding the name NEWNAME with
124 `add-name-to-file' and then deleting FILENAME has the same effect
125 as renaming, aside from momentary intermediate states.
127 In an interactive call, this function prompts for FILENAME and
128 NEWNAME in the minibuffer; also, it requests confirmation if
129 NEWNAME already exists.
131 - Command: copy-file filename newname &optional ok-if-already-exists
133 This command copies the file FILENAME to NEWNAME. An error is
134 signaled if FILENAME does not exist.
136 If TIME is non-`nil', then this functions gives the new file the
137 same last-modified time that the old one has. (This works on only
138 some operating systems.)
140 In an interactive call, this function prompts for FILENAME and
141 NEWNAME in the minibuffer; also, it requests confirmation if
142 NEWNAME already exists.
144 - Command: delete-file filename
145 This command deletes the file FILENAME, like the shell command `rm
146 FILENAME'. If the file has multiple names, it continues to exist
147 under the other names.
149 A suitable kind of `file-error' error is signaled if the file does
150 not exist, or is not deletable. (On Unix, a file is deletable if
151 its directory is writable.)
153 See also `delete-directory' in *Note Create/Delete Dirs::.
155 - Command: make-symbolic-link filename newname &optional
157 This command makes a symbolic link to FILENAME, named NEWNAME.
158 This is like the shell command `ln -s FILENAME NEWNAME'.
160 In an interactive call, this function prompts for FILENAME and
161 NEWNAME in the minibuffer; also, it requests confirmation if
162 NEWNAME already exists.
164 - Function: set-file-modes filename mode
165 This function sets mode bits of FILENAME to MODE (which must be an
166 integer). Only the low 12 bits of MODE are used.
168 - Function: set-default-file-modes mode
169 This function sets the default file protection for new files
170 created by XEmacs and its subprocesses. Every file created with
171 XEmacs initially has this protection. On Unix, the default
172 protection is the bitwise complement of the "umask" value.
174 The argument MODE must be an integer. Only the low 9 bits of MODE
177 Saving a modified version of an existing file does not count as
178 creating the file; it does not change the file's mode, and does
179 not use the default file protection.
181 - Function: default-file-modes
182 This function returns the current default protection value.
184 On MS-DOS, there is no such thing as an "executable" file mode bit.
185 So Emacs considers a file executable if its name ends in `.com', `.bat'
186 or `.exe'. This is reflected in the values returned by `file-modes'
187 and `file-attributes'.
190 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
195 Files are generally referred to by their names, in XEmacs as
196 elsewhere. File names in XEmacs are represented as strings. The
197 functions that operate on a file all expect a file name argument.
199 In addition to operating on files themselves, XEmacs Lisp programs
200 often need to operate on the names; i.e., to take them apart and to use
201 part of a name to construct related file names. This section describes
202 how to manipulate file names.
204 The functions in this section do not actually access files, so they
205 can operate on file names that do not refer to an existing file or
208 On MS-DOS, these functions understand MS-DOS file-name syntax as
209 well as Unix syntax. This is so that all the standard Lisp libraries
210 can specify file names in Unix syntax and work properly on all systems
211 without change. Similarly for other operating systems.
215 * File Name Components:: The directory part of a file name, and the rest.
216 * Directory Names:: A directory's name as a directory
217 is different from its name as a file.
218 * Relative File Names:: Some file names are relative to a current directory.
219 * File Name Expansion:: Converting relative file names to absolute ones.
220 * Unique File Names:: Generating names for temporary files.
221 * File Name Completion:: Finding the completions for a given file name.
222 * User Name Completion:: Finding the completions for a given user name.
225 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
230 The operating system groups files into directories. To specify a
231 file, you must specify the directory and the file's name within that
232 directory. Therefore, XEmacs considers a file name as having two main
233 parts: the "directory name" part, and the "nondirectory" part (or "file
234 name within the directory"). Either part may be empty. Concatenating
235 these two parts reproduces the original file name.
237 On Unix, the directory part is everything up to and including the
238 last slash; the nondirectory part is the rest.
240 For some purposes, the nondirectory part is further subdivided into
241 the name proper and the "version number". On Unix, only backup files
242 have version numbers in their names.
244 - Function: file-name-directory filename
245 This function returns the directory part of FILENAME (or `nil' if
246 FILENAME does not include a directory part). On Unix, the
247 function returns a string ending in a slash.
249 (file-name-directory "lewis/foo") ; Unix example
251 (file-name-directory "foo") ; Unix example
254 - Function: file-name-nondirectory filename
255 This function returns the nondirectory part of FILENAME.
257 (file-name-nondirectory "lewis/foo")
259 (file-name-nondirectory "foo")
262 - Function: file-name-sans-versions filename &optional
264 This function returns FILENAME without any file version numbers,
265 backup version numbers, or trailing tildes.
267 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
268 version numbers, only true file version numbers.
270 (file-name-sans-versions "~rms/foo.~1~")
272 (file-name-sans-versions "~rms/foo~")
274 (file-name-sans-versions "~rms/foo")
277 - Function: file-name-sans-extension filename
278 This function returns FILENAME minus its "extension," if any. The
279 extension, in a file name, is the part that starts with the last
280 `.' in the last name component. For example,
282 (file-name-sans-extension "foo.lose.c")
284 (file-name-sans-extension "big.hack/foo")
288 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
293 A "directory name" is the name of a directory. A directory is a
294 kind of file, and it has a file name, which is related to the directory
295 name but not identical to it. (This is not quite the same as the usual
296 Unix terminology.) These two different names for the same entity are
297 related by a syntactic transformation. On Unix, this is simple: a
298 directory name ends in a slash, whereas the directory's name as a file
301 The difference between a directory name and its name as a file is
302 subtle but crucial. When an XEmacs variable or function argument is
303 described as being a directory name, a file name of a directory is not
306 The following two functions convert between directory names and file
307 names. They do nothing special with environment variable substitutions
308 such as `$HOME', and the constructs `~', and `..'.
310 - Function: file-name-as-directory filename
311 This function returns a string representing FILENAME in a form
312 that the operating system will interpret as the name of a
313 directory. In Unix, this means appending a slash to the string.
315 (file-name-as-directory "~rms/lewis")
318 - Function: directory-file-name dirname
319 This function returns a string representing DIRNAME in a form that
320 the operating system will interpret as the name of a file. On
321 Unix, this means removing a final slash from the string.
323 (directory-file-name "~lewis/")
326 Directory name abbreviations are useful for directories that are
327 normally accessed through symbolic links. Sometimes the users recognize
328 primarily the link's name as "the name" of the directory, and find it
329 annoying to see the directory's "real" name. If you define the link
330 name as an abbreviation for the "real" name, XEmacs shows users the
331 abbreviation instead.
333 If you wish to convert a directory name to its abbreviation, use this
336 - Function: abbreviate-file-name filename &optional hack-homedir
337 This function applies abbreviations from `directory-abbrev-alist'
338 to its argument, and substitutes `~' for the user's home directory.
340 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
341 the user's home directory.
344 - Variable: directory-abbrev-alist
345 The variable `directory-abbrev-alist' contains an alist of
346 abbreviations to use for file directories. Each element has the
347 form `(FROM . TO)', and says to replace FROM with TO when it
348 appears in a directory name. The FROM string is actually a
349 regular expression; it should always start with `^'. The function
350 `abbreviate-file-name' performs these substitutions.
352 You can set this variable in `site-init.el' to describe the
353 abbreviations appropriate for your site.
355 Here's an example, from a system on which file system `/home/fsf'
356 and so on are normally accessed through symbolic links named `/fsf'
359 (("^/home/fsf" . "/fsf")
360 ("^/home/gp" . "/gp")
361 ("^/home/gd" . "/gd"))
364 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
366 Absolute and Relative File Names
367 --------------------------------
369 All the directories in the file system form a tree starting at the
370 root directory. A file name can specify all the directory names
371 starting from the root of the tree; then it is called an "absolute"
372 file name. Or it can specify the position of the file in the tree
373 relative to a default directory; then it is called a "relative" file
374 name. On Unix, an absolute file name starts with a slash or a tilde
375 (`~'), and a relative one does not.
377 - Function: file-name-absolute-p filename
378 This function returns `t' if file FILENAME is an absolute file
379 name, `nil' otherwise.
381 (file-name-absolute-p "~rms/foo")
383 (file-name-absolute-p "rms/foo")
385 (file-name-absolute-p "/user/rms/foo")
389 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
391 Functions that Expand Filenames
392 -------------------------------
394 "Expansion" of a file name means converting a relative file name to
395 an absolute one. Since this is done relative to a default directory,
396 you must specify the default directory name as well as the file name to
397 be expanded. Expansion also simplifies file names by eliminating
398 redundancies such as `./' and `NAME/../'.
400 - Function: expand-file-name filename &optional directory
401 This function converts FILENAME to an absolute file name. If
402 DIRECTORY is supplied, it is the directory to start with if
403 FILENAME is relative. (The value of DIRECTORY should itself be an
404 absolute directory name; it may start with `~'.) Otherwise, the
405 current buffer's value of `default-directory' is used. For
408 (expand-file-name "foo")
409 => "/xcssun/users/rms/lewis/foo"
410 (expand-file-name "../foo")
411 => "/xcssun/users/rms/foo"
412 (expand-file-name "foo" "/usr/spool/")
414 (expand-file-name "$HOME/foo")
415 => "/xcssun/users/rms/lewis/$HOME/foo"
417 Filenames containing `.' or `..' are simplified to their canonical
420 (expand-file-name "bar/../foo")
421 => "/xcssun/users/rms/lewis/foo"
423 `~/' at the beginning is expanded into the user's home directory.
424 A `/' or `~' following a `/'.
426 Note that `expand-file-name' does _not_ expand environment
427 variables; only `substitute-in-file-name' does that.
429 - Function: file-relative-name filename &optional directory
430 This function does the inverse of expansion--it tries to return a
431 relative name that is equivalent to FILENAME when interpreted
432 relative to DIRECTORY.
434 If DIRECTORY is `nil' or omitted, the value of `default-directory'
437 (file-relative-name "/foo/bar" "/foo/")
439 (file-relative-name "/foo/bar" "/hack/")
442 - Variable: default-directory
443 The value of this buffer-local variable is the default directory
444 for the current buffer. It should be an absolute directory name;
445 it may start with `~'. This variable is local in every buffer.
447 `expand-file-name' uses the default directory when its second
450 On Unix systems, the value is always a string ending with a slash.
453 => "/user/lewis/manual/"
455 - Function: substitute-in-file-name filename
456 This function replaces environment variable references in FILENAME
457 with the environment variable values. Following standard Unix
458 shell syntax, `$' is the prefix to substitute an environment
461 The environment variable name is the series of alphanumeric
462 characters (including underscores) that follow the `$'. If the
463 character following the `$' is a `{', then the variable name is
464 everything up to the matching `}'.
466 Here we assume that the environment variable `HOME', which holds
467 the user's home directory name, has value `/xcssun/users/rms'.
469 (substitute-in-file-name "$HOME/foo")
470 => "/xcssun/users/rms/foo"
472 After substitution, a `/' or `~' following a `/' is taken to be
473 the start of an absolute file name that overrides what precedes
474 it, so everything before that `/' or `~' is deleted. For example:
476 (substitute-in-file-name "bar/~/foo")
478 (substitute-in-file-name "/usr/local/$HOME/foo")
479 => "/xcssun/users/rms/foo"
482 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
484 Generating Unique File Names
485 ----------------------------
487 Some programs need to write temporary files. Here is the usual way
488 to construct a name for such a file:
490 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
492 Here we use `(temp-directory)' to specify a directory for temporary
493 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
494 `make-temp-name' is to prevent two different users or two different
495 processes from trying to use the same name.
497 - Function: temp-directory
498 This function returns the name of the directory to use for
499 temporary files. Under Unix, this will be the value of `TMPDIR',
500 defaulting to `/tmp'. On Windows, this will be obtained from the
501 `TEMP' or `TMP' environment variables, defaulting to `/'.
503 Note that the `temp-directory' function does not exist under FSF
506 - Function: make-temp-name prefix
507 This function generates a temporary file name starting with
508 PREFIX. The Emacs process number forms part of the result, so
509 there is no danger of generating a name being used by another
512 (make-temp-name "/tmp/foo")
515 In addition, this function makes an attempt to choose a name that
516 does not specify an existing file. To make this work, PREFIX
517 should be an absolute file name.
519 To avoid confusion, each Lisp application should preferably use a
520 unique PREFIX to `make-temp-name'.
523 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
528 This section describes low-level subroutines for completing a file
529 name. For other completion functions, see *Note Completion::.
531 - Function: file-name-all-completions partial-filename directory
532 This function returns a list of all possible completions for files
533 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
534 The order of the completions is the order of the files in the
535 directory, which is unpredictable and conveys no useful
538 The argument PARTIAL-FILENAME must be a file name containing no
539 directory part and no slash. The current buffer's default
540 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
542 File names which end with any member of
543 `completion-ignored-extensions' are not considered as possible
544 completions for PARTIAL-FILENAME unless there is no other possible
545 completion. `completion-ignored-extensions' is not applied to the
546 names of directories.
548 In the following example, suppose that the current default
549 directory, `~rms/lewis', has five files whose names begin with `f':
550 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
552 (file-name-all-completions "f" "")
553 => ("foo" "file~" "file.c.~2~"
554 "file.c.~1~" "file.c")
556 (file-name-all-completions "fo" "")
559 - Function: file-name-completion partial-filename directory
560 This function completes the file name PARTIAL-FILENAME in directory
561 DIRECTORY. It returns the longest prefix common to all file names
562 in directory DIRECTORY that start with PARTIAL-FILENAME.
564 If only one match exists and PARTIAL-FILENAME matches it exactly,
565 the function returns `t'. The function returns `nil' if directory
566 DIRECTORY contains no name starting with PARTIAL-FILENAME.
568 File names which end with any member of
569 `completion-ignored-extensions' are not considered as possible
570 completions for PARTIAL-FILENAME unless there is no other possible
571 completion. `completion-ignored-extensions' is not applied to the
572 names of directories.
574 In the following example, suppose that the current default
575 directory has five files whose names begin with `f': `foo',
576 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
578 (file-name-completion "fi" "")
581 (file-name-completion "file.c.~1" "")
584 (file-name-completion "file.c.~1~" "")
587 (file-name-completion "file.c.~3" "")
590 - User Option: completion-ignored-extensions
591 `file-name-completion' usually ignores file names that end in any
592 string in this list. It does not ignore them when all the possible
593 completions end in one of these suffixes or when a buffer showing
594 all possible completions is displayed.
596 A typical value might look like this:
598 completion-ignored-extensions
599 => (".o" ".elc" "~" ".dvi")
602 File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
607 This section describes low-level subroutines for completing a user
608 name. For other completion functions, see *Note Completion::.
610 - Function: user-name-all-completions partial-username
611 This function returns a list of all possible completions for a
612 user name starting with PARTIAL-USERNAME. The order of the
613 completions is unpredictable and conveys no useful information.
615 The argument PARTIAL-USERNAME must be a partial user name
616 containing no tilde character and no slash.
618 - Function: user-name-completion partial-username
619 This function completes a user name from PARTIAL-USERNAME. It
620 returns the longest prefix common to all user names that start with
623 If only one match exists and PARTIAL-USERNAME matches it exactly,
624 the function returns `t'. The function returns `nil' if no user
625 name starting with PARTIAL-USERNAME exists.
627 - Function: user-name-completion-1 partial-username
628 This function completes the partial user name PARTIAL-USERNAME,
629 like `user-name-completion', differing only in the return value.
630 This function returns the cons of the completion returned by
631 `user-name-completion', and a boolean indicating whether that
632 completion was unique.
635 File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
637 Contents of Directories
638 =======================
640 A directory is a kind of file that contains other files entered under
641 various names. Directories are a feature of the file system.
643 XEmacs can list the names of the files in a directory as a Lisp list,
644 or display the names in a buffer using the `ls' shell command. In the
645 latter case, it can optionally display information about each file,
646 depending on the value of switches passed to the `ls' command.
648 - Function: directory-files directory &optional full-name match-regexp
650 This function returns a list of the names of the files in the
651 directory DIRECTORY. By default, the list is in alphabetical
654 If FULL-NAME is non-`nil', the function returns the files'
655 absolute file names. Otherwise, it returns just the names
656 relative to the specified directory.
658 If MATCH-REGEXP is non-`nil', this function returns only those
659 file names that contain that regular expression--the other file
660 names are discarded from the list.
662 If NOSORT is non-`nil', `directory-files' does not sort the list,
663 so you get the file names in no particular order. Use this if you
664 want the utmost possible speed and don't care what order the files
665 are processed in. If the order of processing is visible to the
666 user, then the user will probably be happier if you do sort the
669 If FILES-ONLY is the symbol `t', then only the "files" in the
670 directory will be returned; subdirectories will be excluded. If
671 FILES-ONLY is not `nil' and not `t', then only the subdirectories
672 will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
673 then both files and subdirectories will be returned.
675 (directory-files "~lewis")
676 => ("#foo#" "#foo.el#" "." ".."
677 "dired-mods.el" "files.texi"
680 An error is signaled if DIRECTORY is not the name of a directory
683 - Function: insert-directory file switches &optional wildcard
685 This function inserts (in the current buffer) a directory listing
686 for directory FILE, formatted with `ls' according to SWITCHES. It
687 leaves point after the inserted text.
689 The argument FILE may be either a directory name or a file
690 specification including wildcard characters. If WILDCARD is
691 non-`nil', that means treat FILE as a file specification with
694 If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
695 and switches do not contain `-d', so that the listing should show
696 the full contents of the directory. (The `-d' option to `ls' says
697 to describe a directory itself rather than its contents.)
699 This function works by running a directory listing program whose
700 name is in the variable `insert-directory-program'. If WILDCARD is
701 non-`nil', it also runs the shell specified by `shell-file-name',
702 to expand the wildcards.
704 - Variable: insert-directory-program
705 This variable's value is the program to run to generate a
706 directory listing for the function `insert-directory'.
709 File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
711 Creating and Deleting Directories
712 =================================
714 Most XEmacs Lisp file-manipulation functions get errors when used on
715 files that are directories. For example, you cannot delete a directory
716 with `delete-file'. These special functions exist to create and delete
719 - Command: make-directory dirname &optional parents
720 This function creates a directory named DIRNAME. Interactively,
721 the default choice of directory to create is the current default
722 directory for file names. That is useful when you have visited a
723 file in a nonexistent directory.
725 Non-interactively, optional argument PARENTS says whether to
726 create parent directories if they don't exist. (Interactively, this
729 - Command: delete-directory dirname
730 This function deletes the directory named DIRNAME. The function
731 `delete-file' does not work for files that are directories; you
732 must use `delete-directory' in that case.
735 File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
737 Making Certain File Names "Magic"
738 =================================
740 You can implement special handling for certain file names. This is
741 called making those names "magic". You must supply a regular
742 expression to define the class of names (all those that match the
743 regular expression), plus a handler that implements all the primitive
744 XEmacs file operations for file names that do match.
746 The variable `file-name-handler-alist' holds a list of handlers,
747 together with regular expressions that determine when to apply each
748 handler. Each element has this form:
752 All the XEmacs primitives for file access and file name transformation
753 check the given file name against `file-name-handler-alist'. If the
754 file name matches REGEXP, the primitives handle that file by calling
757 The first argument given to HANDLER is the name of the primitive;
758 the remaining arguments are the arguments that were passed to that
759 operation. (The first of these arguments is typically the file name
760 itself.) For example, if you do this:
762 (file-exists-p FILENAME)
764 and FILENAME has handler HANDLER, then HANDLER is called like this:
766 (funcall HANDLER 'file-exists-p FILENAME)
768 Here are the operations that a magic file name handler gets to
771 `add-name-to-file', `copy-file', `delete-directory', `delete-file',
772 `diff-latest-backup-file', `directory-file-name', `directory-files',
773 `dired-compress-file', `dired-uncache', `expand-file-name',
774 `file-accessible-directory-p', `file-attributes', `file-directory-p',
775 `file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
776 `file-name-all-completions', `file-name-as-directory',
777 `file-name-completion', `file-name-directory', `file-name-nondirectory',
778 `file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
779 `file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
780 `get-file-buffer', `insert-directory', `insert-file-contents', `load',
781 `make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
782 `set-visited-file-modtime', `unhandled-file-name-directory',
783 `verify-visited-file-modtime', `write-region'.
785 Handlers for `insert-file-contents' typically need to clear the
786 buffer's modified flag, with `(set-buffer-modified-p nil)', if the
787 VISIT argument is non-`nil'. This also has the effect of unlocking the
788 buffer if it is locked.
790 The handler function must handle all of the above operations, and
791 possibly others to be added in the future. It need not implement all
792 these operations itself--when it has nothing special to do for a
793 certain operation, it can reinvoke the primitive, to handle the
794 operation "in the usual way". It should always reinvoke the primitive
795 for an operation it does not recognize. Here's one way to do this:
797 (defun my-file-handler (operation &rest args)
798 ;; First check for the specific operations
799 ;; that we have special handling for.
800 (cond ((eq operation 'insert-file-contents) ...)
801 ((eq operation 'write-region) ...)
803 ;; Handle any operation we don't know about.
804 (t (let ((inhibit-file-name-handlers
805 (cons 'my-file-handler
806 (and (eq inhibit-file-name-operation operation)
807 inhibit-file-name-handlers)))
808 (inhibit-file-name-operation operation))
809 (apply operation args)))))
811 When a handler function decides to call the ordinary Emacs primitive
812 for the operation at hand, it needs to prevent the primitive from
813 calling the same handler once again, thus leading to an infinite
814 recursion. The example above shows how to do this, with the variables
815 `inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
816 careful to use them exactly as shown above; the details are crucial for
817 proper behavior in the case of multiple handlers, and for operations
818 that have two file names that may each have handlers.
820 - Variable: inhibit-file-name-handlers
821 This variable holds a list of handlers whose use is presently
822 inhibited for a certain operation.
824 - Variable: inhibit-file-name-operation
825 The operation for which certain handlers are presently inhibited.
827 - Function: find-file-name-handler filename &optional operation
828 This function returns the handler function for file name FILENAME,
829 or `nil' if there is none. The argument OPERATION should be the
830 operation to be performed on the file--the value you will pass to
831 the handler as its first argument when you call it. The operation
832 is needed for comparison with `inhibit-file-name-operation'.
834 - Function: file-local-copy filename
835 This function copies file FILENAME to an ordinary non-magic file,
836 if it isn't one already.
838 If FILENAME specifies a "magic" file name, which programs outside
839 Emacs cannot directly read or write, this copies the contents to
840 an ordinary file and returns that file's name.
842 If FILENAME is an ordinary file name, not magic, then this function
843 does nothing and returns `nil'.
845 - Function: unhandled-file-name-directory filename
846 This function returns the name of a directory that is not magic.
847 It uses the directory part of FILENAME if that is not magic.
848 Otherwise, it asks the handler what to do.
850 This is useful for running a subprocess; every subprocess must
851 have a non-magic directory to serve as its current directory, and
852 this function is a good way to come up with one.
855 File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
862 * Intro to Partial Files::
863 * Creating a Partial File::
864 * Detached Partial Files::
867 File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
869 Intro to Partial Files
870 ----------------------
872 A "partial file" is a section of a buffer (called the "master
873 buffer") that is placed in its own buffer and treated as its own file.
874 Changes made to the partial file are not reflected in the master buffer
875 until the partial file is "saved" using the standard buffer save
876 commands. Partial files can be "reverted" (from the master buffer)
877 just like normal files. When a file part is active on a master buffer,
878 that section of the master buffer is marked as read-only. Two file
879 parts on the same master buffer are not allowed to overlap. Partial
880 file buffers are indicated by the words `File Part' in the modeline.
882 The master buffer knows about all the partial files that are active
883 on it, and thus killing or reverting the master buffer will be handled
884 properly. When the master buffer is saved, if there are any unsaved
885 partial files active on it then the user will be given the opportunity
886 to first save these files.
888 When a partial file buffer is first modified, the master buffer is
889 automatically marked as modified so that saving the master buffer will
893 File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
895 Creating a Partial File
896 -----------------------
898 - Command: make-file-part &optional start end name buffer
899 Make a file part on buffer BUFFER out of the region. Call it
900 NAME. This command creates a new buffer containing the contents
901 of the region and marks the buffer as referring to the specified
902 buffer, called the "master buffer". When the file-part buffer is
903 saved, its changes are integrated back into the master buffer.
904 When the master buffer is deleted, all file parts are deleted with
907 When called from a function, expects four arguments, START, END,
908 NAME, and BUFFER, all of which are optional and default to the
909 beginning of BUFFER, the end of BUFFER, a name generated from
910 BUFFER's name, and the current buffer, respectively.
913 File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
915 Detached Partial Files
916 ----------------------
918 Every partial file has an extent in the master buffer associated
919 with it (called the "master extent"), marking where in the master
920 buffer the partial file begins and ends. If the text in master buffer
921 that is contained by the extent is deleted, then the extent becomes
922 "detached", meaning that it no longer refers to a specific region of
923 the master buffer. This can happen either when the text is deleted
924 directly or when the master buffer is reverted. Neither of these should
925 happen in normal usage because the master buffer should generally not be
928 Before doing any operation that references a partial file's master
929 extent, XEmacs checks to make sure that the extent is not detached. If
930 this is the case, XEmacs warns the user of this and the master extent is
931 deleted out of the master buffer, disconnecting the file part. The file
932 part's filename is cleared and thus must be explicitly specified if the
933 detached file part is to be saved.
936 File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
938 File Format Conversion
939 ======================
941 The variable `format-alist' defines a list of "file formats", which
942 describe textual representations used in files for the data (text,
943 text-properties, and possibly other information) in an Emacs buffer.
944 Emacs performs format conversion if appropriate when reading and writing
947 - Variable: format-alist
948 This list contains one format definition for each defined file
951 Each format definition is a list of this form:
953 (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
955 Here is what the elements in a format definition mean:
958 The name of this format.
961 A documentation string for the format.
964 A regular expression which is used to recognize files represented
968 A function to call to decode data in this format (to convert file
969 data into the usual Emacs data representation).
971 The FROM-FN is called with two args, BEGIN and END, which specify
972 the part of the buffer it should convert. It should convert the
973 text by editing it in place. Since this can change the length of
974 the text, FROM-FN should return the modified end position.
976 One responsibility of FROM-FN is to make sure that the beginning
977 of the file no longer matches REGEXP. Otherwise it is likely to
981 A function to call to encode data in this format (to convert the
982 usual Emacs data representation into this format).
984 The TO-FN is called with two args, BEGIN and END, which specify
985 the part of the buffer it should convert. There are two ways it
986 can do the conversion:
988 * By editing the buffer in place. In this case, TO-FN should
989 return the end-position of the range of text, as modified.
991 * By returning a list of annotations. This is a list of
992 elements of the form `(POSITION . STRING)', where POSITION is
993 an integer specifying the relative position in the text to be
994 written, and STRING is the annotation to add there. The list
995 must be sorted in order of position when TO-FN returns it.
997 When `write-region' actually writes the text from the buffer
998 to the file, it intermixes the specified annotations at the
999 corresponding positions. All this takes place without
1000 modifying the buffer.
1003 A flag, `t' if the encoding function modifies the buffer, and
1004 `nil' if it works by returning a list of annotations.
1007 A mode function to call after visiting a file converted from this
1010 The function `insert-file-contents' automatically recognizes file
1011 formats when it reads the specified file. It checks the text of the
1012 beginning of the file against the regular expressions of the format
1013 definitions, and if it finds a match, it calls the decoding function for
1014 that format. Then it checks all the known formats over again. It
1015 keeps checking them until none of them is applicable.
1017 Visiting a file, with `find-file-noselect' or the commands that use
1018 it, performs conversion likewise (because it calls
1019 `insert-file-contents'); it also calls the mode function for each
1020 format that it decodes. It stores a list of the format names in the
1021 buffer-local variable `buffer-file-format'.
1023 - Variable: buffer-file-format
1024 This variable states the format of the visited file. More
1025 precisely, this is a list of the file format names that were
1026 decoded in the course of visiting the current buffer's file. It
1027 is always local in all buffers.
1029 When `write-region' writes data into a file, it first calls the
1030 encoding functions for the formats listed in `buffer-file-format', in
1031 the order of appearance in the list.
1033 - Command: format-write-file file format
1034 This command writes the current buffer contents into the file FILE
1035 in format FORMAT, and makes that format the default for future
1036 saves of the buffer. The argument FORMAT is a list of format
1039 - Command: format-find-file file format
1040 This command finds the file FILE, converting it according to
1041 format FORMAT. It also makes FORMAT the default if the buffer is
1044 The argument FORMAT is a list of format names. If FORMAT is
1045 `nil', no conversion takes place. Interactively, typing just
1046 <RET> for FORMAT specifies `nil'.
1048 - Command: format-insert-file file format &optional start end
1049 This command inserts the contents of file FILE, converting it
1050 according to format FORMAT. If START and END are non-`nil', they
1051 specify which part of the file to read, as in
1052 `insert-file-contents' (*note Reading from Files::).
1054 The return value is like what `insert-file-contents' returns: a
1055 list of the absolute file name and the length of the data inserted
1058 The argument FORMAT is a list of format names. If FORMAT is
1059 `nil', no conversion takes place. Interactively, typing just
1060 <RET> for FORMAT specifies `nil'.
1062 - Variable: auto-save-file-format
1063 This variable specifies the format to use for auto-saving. Its
1064 value is a list of format names, just like the value of
1065 `buffer-file-format'; but it is used instead of
1066 `buffer-file-format' for writing auto-save files. This variable
1067 is always local in all buffers.
1070 File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
1075 Emacs on MS-DOS makes a distinction between text files and binary
1076 files. This is necessary because ordinary text files on MS-DOS use a
1077 two character sequence between lines: carriage-return and linefeed
1078 (CRLF). Emacs expects just a newline character (a linefeed) between
1079 lines. When Emacs reads or writes a text file on MS-DOS, it needs to
1080 convert the line separators. This means it needs to know which files
1081 are text files and which are binary. It makes this decision when
1082 visiting a file, and records the decision in the variable
1083 `buffer-file-type' for use when the file is saved.
1085 *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
1087 - Variable: buffer-file-type
1088 This variable, automatically local in each buffer, records the
1089 file type of the buffer's visited file. The value is `nil' for
1090 text, `t' for binary.
1092 - Function: find-buffer-file-type filename
1093 This function determines whether file FILENAME is a text file or a
1094 binary file. It returns `nil' for text, `t' for binary.
1096 - User Option: file-name-buffer-file-type-alist
1097 This variable holds an alist for distinguishing text files from
1098 binary files. Each element has the form (REGEXP . TYPE), where
1099 REGEXP is matched against the file name, and TYPE may be is `nil'
1100 for text, `t' for binary, or a function to call to compute which.
1101 If it is a function, then it is called with a single argument (the
1102 file name) and should return `t' or `nil'.
1104 - User Option: default-buffer-file-type
1105 This variable specifies the default file type for files whose names
1106 don't indicate anything in particular. Its value should be `nil'
1107 for text, or `t' for binary.
1109 - Command: find-file-text filename
1110 Like `find-file', but treat the file as text regardless of its
1113 - Command: find-file-binary filename
1114 Like `find-file', but treat the file as binary regardless of its
1118 File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
1120 Backups and Auto-Saving
1121 ***********************
1123 Backup files and auto-save files are two methods by which XEmacs
1124 tries to protect the user from the consequences of crashes or of the
1125 user's own errors. Auto-saving preserves the text from earlier in the
1126 current editing session; backup files preserve file contents prior to
1127 the current session.
1131 * Backup Files:: How backup files are made; how their names are chosen.
1132 * Auto-Saving:: How auto-save files are made; how their names are chosen.
1133 * Reverting:: `revert-buffer', and how to customize what it does.
1136 File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
1141 A "backup file" is a copy of the old contents of a file you are
1142 editing. XEmacs makes a backup file the first time you save a buffer
1143 into its visited file. Normally, this means that the backup file
1144 contains the contents of the file as it was before the current editing
1145 session. The contents of the backup file normally remain unchanged once
1148 Backups are usually made by renaming the visited file to a new name.
1149 Optionally, you can specify that backup files should be made by copying
1150 the visited file. This choice makes a difference for files with
1151 multiple names; it also can affect whether the edited file remains owned
1152 by the original owner or becomes owned by the user editing it.
1154 By default, XEmacs makes a single backup file for each file edited.
1155 You can alternatively request numbered backups; then each new backup
1156 file gets a new name. You can delete old numbered backups when you
1157 don't want them any more, or XEmacs can delete them automatically.
1161 * Making Backups:: How XEmacs makes backup files, and when.
1162 * Rename or Copy:: Two alternatives: renaming the old file or copying it.
1163 * Numbered Backups:: Keeping multiple backups for each source file.
1164 * Backup Names:: How backup file names are computed; customization.
1167 File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
1172 - Function: backup-buffer
1173 This function makes a backup of the file visited by the current
1174 buffer, if appropriate. It is called by `save-buffer' before
1175 saving the buffer the first time.
1177 - Variable: buffer-backed-up
1178 This buffer-local variable indicates whether this buffer's file has
1179 been backed up on account of this buffer. If it is non-`nil', then
1180 the backup file has been written. Otherwise, the file should be
1181 backed up when it is next saved (if backups are enabled). This is
1182 a permanent local; `kill-local-variables' does not alter it.
1184 - User Option: make-backup-files
1185 This variable determines whether or not to make backup files. If
1186 it is non-`nil', then XEmacs creates a backup of each file when it
1187 is saved for the first time--provided that `backup-inhibited' is
1190 The following example shows how to change the `make-backup-files'
1191 variable only in the `RMAIL' buffer and not elsewhere. Setting it
1192 `nil' stops XEmacs from making backups of the `RMAIL' file, which
1193 may save disk space. (You would put this code in your `.emacs'
1196 (add-hook 'rmail-mode-hook
1197 (function (lambda ()
1198 (make-local-variable
1200 (setq make-backup-files nil))))
1202 - Variable: backup-enable-predicate
1203 This variable's value is a function to be called on certain
1204 occasions to decide whether a file should have backup files. The
1205 function receives one argument, a file name to consider. If the
1206 function returns `nil', backups are disabled for that file.
1207 Otherwise, the other variables in this section say whether and how
1210 The default value is this:
1213 (or (< (length name) 5)
1214 (not (string-equal "/tmp/"
1215 (substring name 0 5)))))
1217 - Variable: backup-inhibited
1218 If this variable is non-`nil', backups are inhibited. It records
1219 the result of testing `backup-enable-predicate' on the visited file
1220 name. It can also coherently be used by other mechanisms that
1221 inhibit backups based on which file is visited. For example, VC
1222 sets this variable non-`nil' to prevent making backups for files
1223 managed with a version control system.
1225 This is a permanent local, so that changing the major mode does
1226 not lose its value. Major modes should not set this
1227 variable--they should set `make-backup-files' instead.