1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: File Attributes, Prev: Truenames, Up: Information about Files
55 Other Information about Files
56 -----------------------------
58 This section describes the functions for getting detailed information
59 about a file, other than its contents. This information includes the
60 mode bits that control access permission, the owner and group numbers,
61 the number of names, the inode number, the size, and the times of access
64 - Function: file-modes FILENAME
65 This function returns the mode bits of FILENAME, as an integer.
66 The mode bits are also called the file permissions, and they
67 specify access control in the usual Unix fashion. If the
68 low-order bit is 1, then the file is executable by all users, if
69 the second-lowest-order bit is 1, then the file is writable by all
72 The highest value returnable is 4095 (7777 octal), meaning that
73 everyone has read, write, and execute permission, that the SUID bit
74 is set for both others and group, and that the sticky bit is set.
76 (file-modes "~/junk/diffs")
77 => 492 ; Decimal integer.
79 => "754" ; Convert to octal.
81 (set-file-modes "~/junk/diffs" 438)
85 => "666" ; Convert to octal.
88 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
90 - Function: file-nlinks FILENAME
91 This functions returns the number of names (i.e., hard links) that
92 file FILENAME has. If the file does not exist, then this function
93 returns `nil'. Note that symbolic links have no effect on this
94 function, because they are not considered to be names of the files
98 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
99 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
103 (file-nlinks "doesnt-exist")
106 - Function: file-attributes FILENAME
107 This function returns a list of attributes of file FILENAME. If
108 the specified file cannot be opened, it returns `nil'.
110 The elements of the list, in order, are:
112 0. `t' for a directory, a string for a symbolic link (the name
113 linked to), or `nil' for a text file.
115 1. The number of names the file has. Alternate names, also
116 known as hard links, can be created by using the
117 `add-name-to-file' function (*note Changing File
124 4. The time of last access, as a list of two integers. The
125 first integer has the high-order 16 bits of time, the second
126 has the low 16 bits. (This is similar to the value of
127 `current-time'; see *Note Time of Day::.)
129 5. The time of last modification as a list of two integers (as
132 6. The time of last status change as a list of two integers (as
135 7. The size of the file in bytes.
137 8. The file's modes, as a string of ten letters or dashes, as in
140 9. `t' if the file's GID would change if file were deleted and
141 recreated; `nil' otherwise.
143 10. The file's inode number.
145 11. The file system number of the file system that the file is
146 in. This element and the file's inode number together give
147 enough information to distinguish any two files on the
148 system--no two files can have the same values for both of
151 For example, here are the file attributes for `files.texi':
153 (file-attributes "files.texi")
167 and here is how the result is interpreted:
170 is neither a directory nor a symbolic link.
173 has only one name (the name `files.texi' in the current
177 is owned by the user with UID 2235.
180 is in the group with GID 75.
183 was last accessed on Aug 19 00:09. Use `format-time-string' to
184 ! convert this number into a time string. *Note Time
188 was last modified on Aug 19 00:09.
191 last had its inode changed on Aug 19 00:09.
194 is 14906 characters long.
197 has a mode of read and write access for the owner, group, and
201 would retain the same GID if it were recreated.
204 has an inode number of 129500.
207 is on file system number -32252.
210 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
212 Changing File Names and Attributes
213 ==================================
215 The functions in this section rename, copy, delete, link, and set the
218 In the functions that have an argument NEWNAME, if a file by the
219 name of NEWNAME already exists, the actions taken depend on the value
220 of the argument OK-IF-ALREADY-EXISTS:
222 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
225 * Request confirmation if OK-IF-ALREADY-EXISTS is a number.
227 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
230 - Command: add-name-to-file OLDNAME NEWNAME &optional
232 This function gives the file named OLDNAME the additional name
233 NEWNAME. This means that NEWNAME becomes a new "hard link" to
236 In the first part of the following example, we list two files,
240 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
241 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
243 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
244 "~/lewis/foo2")'. Again we list the files. This shows two names,
247 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
251 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
252 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
253 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
255 Finally, we evaluate the following:
257 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
259 and list the files again. Now there are three names for one file:
260 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
262 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
266 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
267 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
268 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
270 This function is meaningless on VMS, where multiple names for one
271 file are not allowed.
273 See also `file-nlinks' in *Note File Attributes::.
275 - Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
276 This command renames the file FILENAME as NEWNAME.
278 If FILENAME has additional names aside from FILENAME, it continues
279 to have those names. In fact, adding the name NEWNAME with
280 `add-name-to-file' and then deleting FILENAME has the same effect
281 as renaming, aside from momentary intermediate states.
283 In an interactive call, this function prompts for FILENAME and
284 NEWNAME in the minibuffer; also, it requests confirmation if
285 NEWNAME already exists.
287 - Command: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
288 This command copies the file OLDNAME to NEWNAME. An error is
289 signaled if OLDNAME does not exist.
291 If TIME is non-`nil', then this functions gives the new file the
292 same last-modified time that the old one has. (This works on only
293 some operating systems.)
295 In an interactive call, this function prompts for FILENAME and
296 NEWNAME in the minibuffer; also, it requests confirmation if
297 NEWNAME already exists.
299 - Command: delete-file FILENAME
300 This command deletes the file FILENAME, like the shell command `rm
301 FILENAME'. If the file has multiple names, it continues to exist
302 under the other names.
304 A suitable kind of `file-error' error is signaled if the file does
305 not exist, or is not deletable. (On Unix, a file is deletable if
306 its directory is writable.)
308 See also `delete-directory' in *Note Create/Delete Dirs::.
310 - Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
311 This command makes a symbolic link to FILENAME, named NEWNAME.
312 This is like the shell command `ln -s FILENAME NEWNAME'.
314 In an interactive call, this function prompts for FILENAME and
315 NEWNAME in the minibuffer; also, it requests confirmation if
316 NEWNAME already exists.
318 - Function: define-logical-name VARNAME STRING
319 This function defines the logical name NAME to have the value
320 STRING. It is available only on VMS.
322 - Function: set-file-modes FILENAME MODE
323 This function sets mode bits of FILENAME to MODE (which must be an
324 integer). Only the low 12 bits of MODE are used.
326 - Function: set-default-file-modes MODE
327 This function sets the default file protection for new files
328 created by XEmacs and its subprocesses. Every file created with
329 XEmacs initially has this protection. On Unix, the default
330 protection is the bitwise complement of the "umask" value.
332 The argument MODE must be an integer. Only the low 9 bits of MODE
335 Saving a modified version of an existing file does not count as
336 creating the file; it does not change the file's mode, and does
337 not use the default file protection.
339 - Function: default-file-modes
340 This function returns the current default protection value.
342 On MS-DOS, there is no such thing as an "executable" file mode bit.
343 So Emacs considers a file executable if its name ends in `.com', `.bat'
344 or `.exe'. This is reflected in the values returned by `file-modes'
345 and `file-attributes'.
348 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
353 Files are generally referred to by their names, in XEmacs as
354 elsewhere. File names in XEmacs are represented as strings. The
355 functions that operate on a file all expect a file name argument.
357 In addition to operating on files themselves, XEmacs Lisp programs
358 often need to operate on the names; i.e., to take them apart and to use
359 part of a name to construct related file names. This section describes
360 how to manipulate file names.
362 The functions in this section do not actually access files, so they
363 can operate on file names that do not refer to an existing file or
366 On VMS, all these functions understand both VMS file-name syntax and
367 Unix syntax. This is so that all the standard Lisp libraries can
368 specify file names in Unix syntax and work properly on VMS without
369 change. On MS-DOS, these functions understand MS-DOS file-name syntax
370 as well as Unix syntax.
374 * File Name Components:: The directory part of a file name, and the rest.
375 * Directory Names:: A directory's name as a directory
376 is different from its name as a file.
377 * Relative File Names:: Some file names are relative to a current directory.
378 * File Name Expansion:: Converting relative file names to absolute ones.
379 * Unique File Names:: Generating names for temporary files.
380 * File Name Completion:: Finding the completions for a given file name.
381 * User Name Completion:: Finding the completions for a given user name.
384 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
389 The operating system groups files into directories. To specify a
390 file, you must specify the directory and the file's name within that
391 directory. Therefore, XEmacs considers a file name as having two main
392 parts: the "directory name" part, and the "nondirectory" part (or "file
393 name within the directory"). Either part may be empty. Concatenating
394 these two parts reproduces the original file name.
396 On Unix, the directory part is everything up to and including the
397 last slash; the nondirectory part is the rest. The rules in VMS syntax
400 For some purposes, the nondirectory part is further subdivided into
401 the name proper and the "version number". On Unix, only backup files
402 have version numbers in their names; on VMS, every file has a version
403 number, but most of the time the file name actually used in XEmacs
404 omits the version number. Version numbers are found mostly in
407 - Function: file-name-directory FILENAME
408 This function returns the directory part of FILENAME (or `nil' if
409 FILENAME does not include a directory part). On Unix, the
410 function returns a string ending in a slash. On VMS, it returns a
411 string ending in one of the three characters `:', `]', or `>'.
413 (file-name-directory "lewis/foo") ; Unix example
415 (file-name-directory "foo") ; Unix example
417 (file-name-directory "[X]FOO.TMP") ; VMS example
420 - Function: file-name-nondirectory FILENAME
421 This function returns the nondirectory part of FILENAME.
423 (file-name-nondirectory "lewis/foo")
425 (file-name-nondirectory "foo")
427 ;; The following example is accurate only on VMS.
428 (file-name-nondirectory "[X]FOO.TMP")
431 - Function: file-name-sans-versions FILENAME &optional
433 This function returns FILENAME without any file version numbers,
434 backup version numbers, or trailing tildes.
436 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
437 version numbers, only true file version numbers.
439 (file-name-sans-versions "~rms/foo.~1~")
441 (file-name-sans-versions "~rms/foo~")
443 (file-name-sans-versions "~rms/foo")
445 ;; The following example applies to VMS only.
446 (file-name-sans-versions "foo;23")
449 - Function: file-name-sans-extension FILENAME
450 This function returns FILENAME minus its "extension," if any. The
451 extension, in a file name, is the part that starts with the last
452 `.' in the last name component. For example,
454 (file-name-sans-extension "foo.lose.c")
456 (file-name-sans-extension "big.hack/foo")
460 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
465 A "directory name" is the name of a directory. A directory is a
466 kind of file, and it has a file name, which is related to the directory
467 name but not identical to it. (This is not quite the same as the usual
468 Unix terminology.) These two different names for the same entity are
469 related by a syntactic transformation. On Unix, this is simple: a
470 directory name ends in a slash, whereas the directory's name as a file
471 lacks that slash. On VMS, the relationship is more complicated.
473 The difference between a directory name and its name as a file is
474 subtle but crucial. When an XEmacs variable or function argument is
475 described as being a directory name, a file name of a directory is not
478 The following two functions convert between directory names and file
479 names. They do nothing special with environment variable substitutions
480 such as `$HOME', and the constructs `~', and `..'.
482 - Function: file-name-as-directory FILENAME
483 This function returns a string representing FILENAME in a form
484 that the operating system will interpret as the name of a
485 directory. In Unix, this means appending a slash to the string.
486 On VMS, the function converts a string of the form `[X]Y.DIR.1' to
489 (file-name-as-directory "~rms/lewis")
492 - Function: directory-file-name DIRNAME
493 This function returns a string representing DIRNAME in a form that
494 the operating system will interpret as the name of a file. On
495 Unix, this means removing a final slash from the string. On VMS,
496 the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
498 (directory-file-name "~lewis/")
501 Directory name abbreviations are useful for directories that are
502 normally accessed through symbolic links. Sometimes the users recognize
503 primarily the link's name as "the name" of the directory, and find it
504 annoying to see the directory's "real" name. If you define the link
505 name as an abbreviation for the "real" name, XEmacs shows users the
506 abbreviation instead.
508 If you wish to convert a directory name to its abbreviation, use this
511 - Function: abbreviate-file-name DIRNAME &optional HACK-HOMEDIR
512 This function applies abbreviations from `directory-abbrev-alist'
513 to its argument, and substitutes `~' for the user's home directory.
515 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
516 the user's home directory.
519 - Variable: directory-abbrev-alist
520 The variable `directory-abbrev-alist' contains an alist of
521 abbreviations to use for file directories. Each element has the
522 form `(FROM . TO)', and says to replace FROM with TO when it
523 appears in a directory name. The FROM string is actually a
524 regular expression; it should always start with `^'. The function
525 `abbreviate-file-name' performs these substitutions.
527 You can set this variable in `site-init.el' to describe the
528 abbreviations appropriate for your site.
530 Here's an example, from a system on which file system `/home/fsf'
531 and so on are normally accessed through symbolic links named `/fsf'
534 (("^/home/fsf" . "/fsf")
535 ("^/home/gp" . "/gp")
536 ("^/home/gd" . "/gd"))
539 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
541 Absolute and Relative File Names
542 --------------------------------
544 All the directories in the file system form a tree starting at the
545 root directory. A file name can specify all the directory names
546 starting from the root of the tree; then it is called an "absolute"
547 file name. Or it can specify the position of the file in the tree
548 relative to a default directory; then it is called a "relative" file
549 name. On Unix, an absolute file name starts with a slash or a tilde
550 (`~'), and a relative one does not. The rules on VMS are complicated.
552 - Function: file-name-absolute-p FILENAME
553 This function returns `t' if file FILENAME is an absolute file
554 name, `nil' otherwise. On VMS, this function understands both
555 Unix syntax and VMS syntax.
557 (file-name-absolute-p "~rms/foo")
559 (file-name-absolute-p "rms/foo")
561 (file-name-absolute-p "/user/rms/foo")
565 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
567 Functions that Expand Filenames
568 -------------------------------
570 "Expansion" of a file name means converting a relative file name to
571 an absolute one. Since this is done relative to a default directory,
572 you must specify the default directory name as well as the file name to
573 be expanded. Expansion also simplifies file names by eliminating
574 redundancies such as `./' and `NAME/../'.
576 - Function: expand-file-name FILENAME &optional DIRECTORY
577 This function converts FILENAME to an absolute file name. If
578 DIRECTORY is supplied, it is the directory to start with if
579 FILENAME is relative. (The value of DIRECTORY should itself be an
580 absolute directory name; it may start with `~'.) Otherwise, the
581 current buffer's value of `default-directory' is used. For
584 (expand-file-name "foo")
585 => "/xcssun/users/rms/lewis/foo"
586 (expand-file-name "../foo")
587 => "/xcssun/users/rms/foo"
588 (expand-file-name "foo" "/usr/spool/")
590 (expand-file-name "$HOME/foo")
591 => "/xcssun/users/rms/lewis/$HOME/foo"
593 Filenames containing `.' or `..' are simplified to their canonical
596 (expand-file-name "bar/../foo")
597 => "/xcssun/users/rms/lewis/foo"
599 `~/' at the beginning is expanded into the user's home directory.
600 A `/' or `~' following a `/'.
602 Note that `expand-file-name' does *not* expand environment
603 variables; only `substitute-in-file-name' does that.
605 - Function: file-relative-name FILENAME &optional DIRECTORY
606 This function does the inverse of expansion--it tries to return a
607 relative name that is equivalent to FILENAME when interpreted
608 relative to DIRECTORY.
610 If DIRECTORY is `nil' or omitted, the value of `default-directory'
613 (file-relative-name "/foo/bar" "/foo/")
615 (file-relative-name "/foo/bar" "/hack/")
618 - Variable: default-directory
619 The value of this buffer-local variable is the default directory
620 for the current buffer. It should be an absolute directory name;
621 it may start with `~'. This variable is local in every buffer.
623 `expand-file-name' uses the default directory when its second
626 On Unix systems, the value is always a string ending with a slash.
629 => "/user/lewis/manual/"
631 - Function: substitute-in-file-name FILENAME
632 This function replaces environment variable references in FILENAME
633 with the environment variable values. Following standard Unix
634 shell syntax, `$' is the prefix to substitute an environment
637 The environment variable name is the series of alphanumeric
638 characters (including underscores) that follow the `$'. If the
639 character following the `$' is a `{', then the variable name is
640 everything up to the matching `}'.
642 Here we assume that the environment variable `HOME', which holds
643 the user's home directory name, has value `/xcssun/users/rms'.
645 (substitute-in-file-name "$HOME/foo")
646 => "/xcssun/users/rms/foo"
648 After substitution, a `/' or `~' following a `/' is taken to be
649 the start of an absolute file name that overrides what precedes
650 it, so everything before that `/' or `~' is deleted. For example:
652 (substitute-in-file-name "bar/~/foo")
654 (substitute-in-file-name "/usr/local/$HOME/foo")
655 => "/xcssun/users/rms/foo"
657 On VMS, `$' substitution is not done, so this function does nothing
658 on VMS except discard superfluous initial components as shown
662 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
664 Generating Unique File Names
665 ----------------------------
667 Some programs need to write temporary files. Here is the usual way
668 to construct a name for such a file:
670 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
672 Here we use `(temp-directory)' to specify a directory for temporary
673 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
674 `make-temp-name' is to prevent two different users or two different
675 processes from trying to use the same name.
677 - Function: temp-directory
678 This function returns the name of the directory to use for
679 temporary files. Under Unix, this will be the value of `TMPDIR',
680 defaulting to `/tmp'. On Windows, this will be obtained from the
681 `TEMP' or `TMP' environment variables, defaulting to `/'.
683 Note that the `temp-directory' function does not exist under FSF
686 - Function: make-temp-name PREFIX
687 This function generates a temporary file name starting with
688 PREFIX. The Emacs process number forms part of the result, so
689 there is no danger of generating a name being used by another
692 (make-temp-name "/tmp/foo")
695 In addition, this function makes an attempt to choose a name that
696 does not specify an existing file. To make this work, PREFIX
697 should be an absolute file name.
699 To avoid confusion, each Lisp application should preferably use a
700 unique PREFIX to `make-temp-name'.
703 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
708 This section describes low-level subroutines for completing a file
709 name. For other completion functions, see *Note Completion::.
711 - Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
712 This function returns a list of all possible completions for a file
713 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
714 The order of the completions is the order of the files in the
715 directory, which is unpredictable and conveys no useful
718 The argument PARTIAL-FILENAME must be a file name containing no
719 directory part and no slash. The current buffer's default
720 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
722 In the following example, suppose that the current default
723 directory, `~rms/lewis', has five files whose names begin with `f':
724 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
726 (file-name-all-completions "f" "")
727 => ("foo" "file~" "file.c.~2~"
728 "file.c.~1~" "file.c")
730 (file-name-all-completions "fo" "")
733 - Function: file-name-completion FILENAME DIRECTORY
734 This function completes the file name FILENAME in directory
735 DIRECTORY. It returns the longest prefix common to all file names
736 in directory DIRECTORY that start with FILENAME.
738 If only one match exists and FILENAME matches it exactly, the
739 function returns `t'. The function returns `nil' if directory
740 DIRECTORY contains no name starting with FILENAME.
742 In the following example, suppose that the current default
743 directory has five files whose names begin with `f': `foo',
744 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
746 (file-name-completion "fi" "")
749 (file-name-completion "file.c.~1" "")
752 (file-name-completion "file.c.~1~" "")
755 (file-name-completion "file.c.~3" "")
758 - User Option: completion-ignored-extensions
759 `file-name-completion' usually ignores file names that end in any
760 string in this list. It does not ignore them when all the possible
761 completions end in one of these suffixes or when a buffer showing
762 all possible completions is displayed.
764 A typical value might look like this:
766 completion-ignored-extensions
767 => (".o" ".elc" "~" ".dvi")
770 File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
775 This section describes low-level subroutines for completing a user
776 name. For other completion functions, see *Note Completion::.
778 - Function: user-name-all-completions PARTIAL-USERNAME
779 This function returns a list of all possible completions for a user
780 whose name starts with PARTIAL-USERNAME. The order of the
781 completions is unpredictable and conveys no useful information.
783 The argument PARTIAL-USERNAME must be a partial user name
784 containing no tilde character and no slash.
786 - Function: user-name-completion USERNAME
787 This function completes the user name USERNAME. It returns the
788 longest prefix common to all user names that start with USERNAME.
790 If only one match exists and USERNAME matches it exactly, the
791 function returns `t'. The function returns `nil' if no user name
792 starting with USERNAME exists.
794 - Function: user-name-completion-1 USERNAME
795 This function completes the user name USERNAME, like
796 `user-name-completion', differing only in the return value. This
797 function returns the cons of the completion returned by
798 `user-name-completion', and a boolean indicating whether that
799 completion was unique.
802 File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
804 Contents of Directories
805 =======================
807 A directory is a kind of file that contains other files entered under
808 various names. Directories are a feature of the file system.
810 XEmacs can list the names of the files in a directory as a Lisp list,
811 or display the names in a buffer using the `ls' shell command. In the
812 latter case, it can optionally display information about each file,
813 depending on the value of switches passed to the `ls' command.
815 - Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
817 This function returns a list of the names of the files in the
818 directory DIRECTORY. By default, the list is in alphabetical
821 If FULL-NAME is non-`nil', the function returns the files'
822 absolute file names. Otherwise, it returns just the names
823 relative to the specified directory.
825 If MATCH-REGEXP is non-`nil', this function returns only those
826 file names that contain that regular expression--the other file
827 names are discarded from the list.
829 If NOSORT is non-`nil', `directory-files' does not sort the list,
830 so you get the file names in no particular order. Use this if you
831 want the utmost possible speed and don't care what order the files
832 are processed in. If the order of processing is visible to the
833 user, then the user will probably be happier if you do sort the
836 If FILES-ONLY is the symbol `t', then only the "files" in the
837 directory will be returned; subdirectories will be excluded. If
838 FILES-ONLY is not `nil' and not `t', then only the subdirectories
839 will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
840 then both files and subdirectories will be returned.
842 (directory-files "~lewis")
843 => ("#foo#" "#foo.el#" "." ".."
844 "dired-mods.el" "files.texi"
847 An error is signaled if DIRECTORY is not the name of a directory
850 - Function: insert-directory FILE SWITCHES &optional WILDCARD
852 This function inserts (in the current buffer) a directory listing
853 for directory FILE, formatted with `ls' according to SWITCHES. It
854 leaves point after the inserted text.
856 The argument FILE may be either a directory name or a file
857 specification including wildcard characters. If WILDCARD is
858 non-`nil', that means treat FILE as a file specification with
861 If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
862 and switches do not contain `-d', so that the listing should show
863 the full contents of the directory. (The `-d' option to `ls' says
864 to describe a directory itself rather than its contents.)
866 This function works by running a directory listing program whose
867 name is in the variable `insert-directory-program'. If WILDCARD is
868 non-`nil', it also runs the shell specified by `shell-file-name',
869 to expand the wildcards.
871 - Variable: insert-directory-program
872 This variable's value is the program to run to generate a
873 directory listing for the function `insert-directory'.
876 File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
878 Creating and Deleting Directories
879 =================================
881 Most XEmacs Lisp file-manipulation functions get errors when used on
882 files that are directories. For example, you cannot delete a directory
883 with `delete-file'. These special functions exist to create and delete
886 - Command: make-directory DIRNAME &optional PARENTS
887 This function creates a directory named DIRNAME. Interactively,
888 the default choice of directory to create is the current default
889 directory for file names. That is useful when you have visited a
890 file in a nonexistent directory.
892 Non-interactively, optional argument PARENTS says whether to
893 create parent directories if they don't exist. (Interactively, this
896 - Command: delete-directory DIRNAME
897 This function deletes the directory named DIRNAME. The function
898 `delete-file' does not work for files that are directories; you
899 must use `delete-directory' in that case.
902 File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
904 Making Certain File Names "Magic"
905 =================================
907 You can implement special handling for certain file names. This is
908 called making those names "magic". You must supply a regular
909 expression to define the class of names (all those that match the
910 regular expression), plus a handler that implements all the primitive
911 XEmacs file operations for file names that do match.
913 The variable `file-name-handler-alist' holds a list of handlers,
914 together with regular expressions that determine when to apply each
915 handler. Each element has this form:
919 All the XEmacs primitives for file access and file name transformation
920 check the given file name against `file-name-handler-alist'. If the
921 file name matches REGEXP, the primitives handle that file by calling
924 The first argument given to HANDLER is the name of the primitive;
925 the remaining arguments are the arguments that were passed to that
926 operation. (The first of these arguments is typically the file name
927 itself.) For example, if you do this:
929 (file-exists-p FILENAME)
931 and FILENAME has handler HANDLER, then HANDLER is called like this:
933 (funcall HANDLER 'file-exists-p FILENAME)
935 Here are the operations that a magic file name handler gets to
938 `add-name-to-file', `copy-file', `delete-directory', `delete-file',
939 `diff-latest-backup-file', `directory-file-name', `directory-files',
940 `dired-compress-file', `dired-uncache', `expand-file-name',
941 `file-accessible-directory-p', `file-attributes', `file-directory-p',
942 `file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
943 `file-name-all-completions', `file-name-as-directory',
944 `file-name-completion', `file-name-directory', `file-name-nondirectory',
945 `file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
946 `file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
947 `get-file-buffer', `insert-directory', `insert-file-contents', `load',
948 `make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
949 `set-visited-file-modtime', `unhandled-file-name-directory',
950 `verify-visited-file-modtime', `write-region'.
952 Handlers for `insert-file-contents' typically need to clear the
953 buffer's modified flag, with `(set-buffer-modified-p nil)', if the
954 VISIT argument is non-`nil'. This also has the effect of unlocking the
955 buffer if it is locked.
957 The handler function must handle all of the above operations, and
958 possibly others to be added in the future. It need not implement all
959 these operations itself--when it has nothing special to do for a
960 certain operation, it can reinvoke the primitive, to handle the
961 operation "in the usual way". It should always reinvoke the primitive
962 for an operation it does not recognize. Here's one way to do this:
964 (defun my-file-handler (operation &rest args)
965 ;; First check for the specific operations
966 ;; that we have special handling for.
967 (cond ((eq operation 'insert-file-contents) ...)
968 ((eq operation 'write-region) ...)
970 ;; Handle any operation we don't know about.
971 (t (let ((inhibit-file-name-handlers
972 (cons 'my-file-handler
973 (and (eq inhibit-file-name-operation operation)
974 inhibit-file-name-handlers)))
975 (inhibit-file-name-operation operation))
976 (apply operation args)))))
978 When a handler function decides to call the ordinary Emacs primitive
979 for the operation at hand, it needs to prevent the primitive from
980 calling the same handler once again, thus leading to an infinite
981 recursion. The example above shows how to do this, with the variables
982 `inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
983 careful to use them exactly as shown above; the details are crucial for
984 proper behavior in the case of multiple handlers, and for operations
985 that have two file names that may each have handlers.
987 - Variable: inhibit-file-name-handlers
988 This variable holds a list of handlers whose use is presently
989 inhibited for a certain operation.
991 - Variable: inhibit-file-name-operation
992 The operation for which certain handlers are presently inhibited.
994 - Function: find-file-name-handler FILE OPERATION
995 This function returns the handler function for file name FILE, or
996 `nil' if there is none. The argument OPERATION should be the
997 operation to be performed on the file--the value you will pass to
998 the handler as its first argument when you call it. The operation
999 is needed for comparison with `inhibit-file-name-operation'.
1001 - Function: file-local-copy FILENAME
1002 This function copies file FILENAME to an ordinary non-magic file,
1003 if it isn't one already.
1005 If FILENAME specifies a "magic" file name, which programs outside
1006 Emacs cannot directly read or write, this copies the contents to
1007 an ordinary file and returns that file's name.
1009 If FILENAME is an ordinary file name, not magic, then this function
1010 does nothing and returns `nil'.
1012 - Function: unhandled-file-name-directory FILENAME
1013 This function returns the name of a directory that is not magic.
1014 It uses the directory part of FILENAME if that is not magic.
1015 Otherwise, it asks the handler what to do.
1017 This is useful for running a subprocess; every subprocess must
1018 have a non-magic directory to serve as its current directory, and
1019 this function is a good way to come up with one.
1022 File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
1029 * Intro to Partial Files::
1030 * Creating a Partial File::
1031 * Detached Partial Files::
1034 File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
1036 Intro to Partial Files
1037 ----------------------
1039 A "partial file" is a section of a buffer (called the "master
1040 buffer") that is placed in its own buffer and treated as its own file.
1041 Changes made to the partial file are not reflected in the master buffer
1042 until the partial file is "saved" using the standard buffer save
1043 commands. Partial files can be "reverted" (from the master buffer)
1044 just like normal files. When a file part is active on a master buffer,
1045 that section of the master buffer is marked as read-only. Two file
1046 parts on the same master buffer are not allowed to overlap. Partial
1047 file buffers are indicated by the words `File Part' in the modeline.
1049 The master buffer knows about all the partial files that are active
1050 on it, and thus killing or reverting the master buffer will be handled
1051 properly. When the master buffer is saved, if there are any unsaved
1052 partial files active on it then the user will be given the opportunity
1053 to first save these files.
1055 When a partial file buffer is first modified, the master buffer is
1056 automatically marked as modified so that saving the master buffer will
1060 File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
1062 Creating a Partial File
1063 -----------------------
1065 - Function: make-file-part &optional START END NAME BUFFER
1066 Make a file part on buffer BUFFER out of the region. Call it
1067 NAME. This command creates a new buffer containing the contents
1068 of the region and marks the buffer as referring to the specified
1069 buffer, called the "master buffer". When the file-part buffer is
1070 saved, its changes are integrated back into the master buffer.
1071 When the master buffer is deleted, all file parts are deleted with
1074 When called from a function, expects four arguments, START, END,
1075 NAME, and BUFFER, all of which are optional and default to the
1076 beginning of BUFFER, the end of BUFFER, a name generated from
1077 BUFFER name, and the current buffer, respectively.
1080 File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
1082 Detached Partial Files
1083 ----------------------
1085 Every partial file has an extent in the master buffer associated
1086 with it (called the "master extent"), marking where in the master
1087 buffer the partial file begins and ends. If the text in master buffer
1088 that is contained by the extent is deleted, then the extent becomes
1089 "detached", meaning that it no longer refers to a specific region of
1090 the master buffer. This can happen either when the text is deleted
1091 directly or when the master buffer is reverted. Neither of these should
1092 happen in normal usage because the master buffer should generally not be
1095 Before doing any operation that references a partial file's master
1096 extent, XEmacs checks to make sure that the extent is not detached. If
1097 this is the case, XEmacs warns the user of this and the master extent is
1098 deleted out of the master buffer, disconnecting the file part. The file
1099 part's filename is cleared and thus must be explicitly specified if the
1100 detached file part is to be saved.
1103 File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
1105 File Format Conversion
1106 ======================
1108 The variable `format-alist' defines a list of "file formats", which
1109 describe textual representations used in files for the data (text,
1110 text-properties, and possibly other information) in an Emacs buffer.
1111 Emacs performs format conversion if appropriate when reading and writing
1114 - Variable: format-alist
1115 This list contains one format definition for each defined file
1118 Each format definition is a list of this form:
1120 (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
1122 Here is what the elements in a format definition mean:
1125 The name of this format.
1128 A documentation string for the format.
1131 A regular expression which is used to recognize files represented
1135 A function to call to decode data in this format (to convert file
1136 data into the usual Emacs data representation).
1138 The FROM-FN is called with two args, BEGIN and END, which specify
1139 the part of the buffer it should convert. It should convert the
1140 text by editing it in place. Since this can change the length of
1141 the text, FROM-FN should return the modified end position.
1143 One responsibility of FROM-FN is to make sure that the beginning
1144 of the file no longer matches REGEXP. Otherwise it is likely to
1148 A function to call to encode data in this format (to convert the
1149 usual Emacs data representation into this format).
1151 The TO-FN is called with two args, BEGIN and END, which specify
1152 the part of the buffer it should convert. There are two ways it
1153 can do the conversion:
1155 * By editing the buffer in place. In this case, TO-FN should
1156 return the end-position of the range of text, as modified.
1158 * By returning a list of annotations. This is a list of
1159 elements of the form `(POSITION . STRING)', where POSITION is
1160 an integer specifying the relative position in the text to be
1161 written, and STRING is the annotation to add there. The list
1162 must be sorted in order of position when TO-FN returns it.
1164 When `write-region' actually writes the text from the buffer
1165 to the file, it intermixes the specified annotations at the
1166 corresponding positions. All this takes place without
1167 modifying the buffer.
1170 A flag, `t' if the encoding function modifies the buffer, and
1171 `nil' if it works by returning a list of annotations.
1174 A mode function to call after visiting a file converted from this
1177 The function `insert-file-contents' automatically recognizes file
1178 formats when it reads the specified file. It checks the text of the
1179 beginning of the file against the regular expressions of the format
1180 definitions, and if it finds a match, it calls the decoding function for
1181 that format. Then it checks all the known formats over again. It
1182 keeps checking them until none of them is applicable.
1184 Visiting a file, with `find-file-noselect' or the commands that use
1185 it, performs conversion likewise (because it calls
1186 `insert-file-contents'); it also calls the mode function for each
1187 format that it decodes. It stores a list of the format names in the
1188 buffer-local variable `buffer-file-format'.
1190 - Variable: buffer-file-format
1191 This variable states the format of the visited file. More
1192 precisely, this is a list of the file format names that were
1193 decoded in the course of visiting the current buffer's file. It
1194 is always local in all buffers.
1196 When `write-region' writes data into a file, it first calls the
1197 encoding functions for the formats listed in `buffer-file-format', in
1198 the order of appearance in the list.
1200 - Function: format-write-file FILE FORMAT
1201 This command writes the current buffer contents into the file FILE
1202 in format FORMAT, and makes that format the default for future
1203 saves of the buffer. The argument FORMAT is a list of format
1206 - Function: format-find-file FILE FORMAT
1207 This command finds the file FILE, converting it according to
1208 format FORMAT. It also makes FORMAT the default if the buffer is
1211 The argument FORMAT is a list of format names. If FORMAT is
1212 `nil', no conversion takes place. Interactively, typing just
1213 <RET> for FORMAT specifies `nil'.
1215 - Function: format-insert-file FILE FORMAT &optional BEG END
1216 This command inserts the contents of file FILE, converting it
1217 according to format FORMAT. If BEG and END are non-`nil', they
1218 specify which part of the file to read, as in
1219 `insert-file-contents' (*note Reading from Files::.).
1221 The return value is like what `insert-file-contents' returns: a
1222 list of the absolute file name and the length of the data inserted
1225 The argument FORMAT is a list of format names. If FORMAT is
1226 `nil', no conversion takes place. Interactively, typing just
1227 <RET> for FORMAT specifies `nil'.
1229 - Function: format-find-file FILE FORMAT
1230 This command finds the file FILE, converting it according to
1231 format FORMAT. It also makes FORMAT the default if the buffer is
1234 The argument FORMAT is a list of format names. If FORMAT is
1235 `nil', no conversion takes place. Interactively, typing just
1236 <RET> for FORMAT specifies `nil'.
1238 - Function: format-insert-file FILE FORMAT &optional BEG END
1239 This command inserts the contents of file FILE, converting it
1240 according to format FORMAT. If BEG and END are non-`nil', they
1241 specify which part of the file to read, as in
1242 `insert-file-contents' (*note Reading from Files::.).
1244 The return value is like what `insert-file-contents' returns: a
1245 list of the absolute file name and the length of the data inserted
1248 The argument FORMAT is a list of format names. If FORMAT is
1249 `nil', no conversion takes place. Interactively, typing just
1250 <RET> for FORMAT specifies `nil'.
1252 - Variable: auto-save-file-format
1253 This variable specifies the format to use for auto-saving. Its
1254 value is a list of format names, just like the value of
1255 `buffer-file-format'; but it is used instead of
1256 `buffer-file-format' for writing auto-save files. This variable
1257 is always local in all buffers.