1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
58 You can copy a file from the disk and insert it into a buffer using
59 the `insert-file-contents' function. Don't use the user-level command
60 `insert-file' in a Lisp program, as that sets the mark.
62 - Function: insert-file-contents filename &optional visit beg end
64 This function inserts the contents of file FILENAME into the
65 current buffer after point. It returns a list of the absolute
66 file name and the length of the data inserted. An error is
67 signaled if FILENAME is not the name of a file that can be read.
69 The function `insert-file-contents' checks the file contents
70 against the defined file formats, and converts the file contents if
71 appropriate. *Note Format Conversion::. It also calls the
72 functions in the list `after-insert-file-functions'; see *Note
75 If VISIT is non-`nil', this function additionally marks the buffer
76 as unmodified and sets up various fields in the buffer so that it
77 is visiting the file FILENAME: these include the buffer's visited
78 file name and its last save file modtime. This feature is used by
79 `find-file-noselect' and you probably should not use it yourself.
81 If BEG and END are non-`nil', they should be integers specifying
82 the portion of the file to insert. In this case, VISIT must be
85 (insert-file-contents filename nil 0 500)
87 inserts the first 500 characters of a file.
89 If the argument REPLACE is non-`nil', it means to replace the
90 contents of the buffer (actually, just the accessible portion)
91 with the contents of the file. This is better than simply
92 deleting the buffer contents and inserting the whole file, because
93 (1) it preserves some marker positions and (2) it puts less data
96 If you want to pass a file name to another process so that another
97 program can read the file, use the function `file-local-copy'; see
98 *Note Magic File Names::.
101 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
106 You can write the contents of a buffer, or part of a buffer, directly
107 to a file on disk using the `append-to-file' and `write-region'
108 functions. Don't use these functions to write to files that are being
109 visited; that could cause confusion in the mechanisms for visiting.
111 - Command: append-to-file start end filename
112 This function appends the contents of the region delimited by
113 START and END in the current buffer to the end of file FILENAME.
114 If that file does not exist, it is created. If that file exists
115 it is overwritten. This function returns `nil'.
117 An error is signaled if FILENAME specifies a nonwritable file, or
118 a nonexistent file in a directory where files cannot be created.
120 - Command: write-region start end filename &optional append visit
121 This function writes the region delimited by START and END in the
122 current buffer into the file specified by FILENAME.
124 If START is a string, then `write-region' writes or appends that
125 string, rather than text from the buffer.
127 If APPEND is non-`nil', then the specified text is appended to the
128 existing file contents (if any).
130 If VISIT is `t', then XEmacs establishes an association between
131 the buffer and the file: the buffer is then visiting that file.
132 It also sets the last file modification time for the current
133 buffer to FILENAME's modtime, and marks the buffer as not
134 modified. This feature is used by `save-buffer', but you probably
135 should not use it yourself.
137 If VISIT is a string, it specifies the file name to visit. This
138 way, you can write the data to one file (FILENAME) while recording
139 the buffer as visiting another file (VISIT). The argument VISIT
140 is used in the echo area message and also for file locking; VISIT
141 is stored in `buffer-file-name'. This feature is used to
142 implement `file-precious-flag'; don't use it yourself unless you
143 really know what you're doing.
145 The function `write-region' converts the data which it writes to
146 the appropriate file formats specified by `buffer-file-format'.
147 *Note Format Conversion::. It also calls the functions in the list
148 `write-region-annotate-functions'; see *Note Saving Properties::.
150 Normally, `write-region' displays a message `Wrote file FILENAME'
151 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
152 then this message is inhibited. This feature is useful for
153 programs that use files for internal purposes, files that the user
154 does not need to know about.
157 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
162 When two users edit the same file at the same time, they are likely
163 to interfere with each other. XEmacs tries to prevent this situation
164 from arising by recording a "file lock" when a file is being modified.
165 XEmacs can then detect the first attempt to modify a buffer visiting a
166 file that is locked by another XEmacs process, and ask the user what to
169 File locks do not work properly when multiple machines can share
170 file systems, such as with NFS. Perhaps a better file locking system
171 will be implemented in the future. When file locks do not work, it is
172 possible for two users to make changes simultaneously, but XEmacs can
173 still warn the user who saves second. Also, the detection of
174 modification of a buffer visiting a file changed on disk catches some
175 cases of simultaneous editing; see *Note Modification Time::.
177 - Function: file-locked-p &optional filename
178 This function returns `nil' if the file FILENAME is not locked by
179 this XEmacs process. It returns `t' if it is locked by this
180 XEmacs, and it returns the name of the user who has locked it if it
181 is locked by someone else.
183 (file-locked-p "foo")
186 - Function: lock-buffer &optional filename
187 This function locks the file FILENAME, if the current buffer is
188 modified. The argument FILENAME defaults to the current buffer's
189 visited file. Nothing is done if the current buffer is not
190 visiting a file, or is not modified.
192 - Function: unlock-buffer
193 This function unlocks the file being visited in the current buffer,
194 if the buffer is modified. If the buffer is not modified, then
195 the file should not be locked, so this function does nothing. It
196 also does nothing if the current buffer is not visiting a file.
198 - Function: ask-user-about-lock file other-user
199 This function is called when the user tries to modify FILE, but it
200 is locked by another user named OTHER-USER. The value it returns
201 determines what happens next:
203 * A value of `t' says to grab the lock on the file. Then this
204 user may edit the file and OTHER-USER loses the lock.
206 * A value of `nil' says to ignore the lock and let this user
207 edit the file anyway.
209 * This function may instead signal a `file-locked' error, in
210 which case the change that the user was about to make does
213 The error message for this error looks like this:
215 error--> File is locked: FILE OTHER-USER
217 where `file' is the name of the file and OTHER-USER is the
218 name of the user who has locked the file.
220 The default definition of this function asks the user to choose
221 what to do. If you wish, you can replace the `ask-user-about-lock'
222 function with your own version that decides in another way. The
223 code for its usual definition is in `userlock.el'.
226 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
228 Information about Files
229 =======================
231 The functions described in this section all operate on strings that
232 designate file names. All the functions have names that begin with the
233 word `file'. These functions all return information about actual files
234 or directories, so their arguments must all exist as actual files or
235 directories unless otherwise noted.
239 * Testing Accessibility:: Is a given file readable? Writable?
240 * Kinds of Files:: Is it a directory? A symbolic link?
241 * Truenames:: Eliminating symbolic links from a file name.
242 * File Attributes:: How large is it? Any other names? Etc.
245 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
247 Testing Accessibility
248 ---------------------
250 These functions test for permission to access a file in specific
253 - Function: file-exists-p filename
254 This function returns `t' if a file named FILENAME appears to
255 exist. This does not mean you can necessarily read the file, only
256 that you can find out its attributes. (On Unix, this is true if
257 the file exists and you have execute permission on the containing
258 directories, regardless of the protection of the file itself.)
260 If the file does not exist, or if fascist access control policies
261 prevent you from finding the attributes of the file, this function
264 - Function: file-readable-p filename
265 This function returns `t' if a file named FILENAME exists and you
266 can read it. It returns `nil' otherwise.
268 (file-readable-p "files.texi")
270 (file-exists-p "/usr/spool/mqueue")
272 (file-readable-p "/usr/spool/mqueue")
275 - Function: file-executable-p filename
276 This function returns `t' if a file named FILENAME exists and you
277 can execute it. It returns `nil' otherwise. If the file is a
278 directory, execute permission means you can check the existence and
279 attributes of files inside the directory, and open those files if
282 - Function: file-writable-p filename
283 This function returns `t' if the file FILENAME can be written or
284 created by you, and `nil' otherwise. A file is writable if the
285 file exists and you can write it. It is creatable if it does not
286 exist, but the specified directory does exist and you can write in
289 In the third example below, `foo' is not writable because the
290 parent directory does not exist, even though the user could create
293 (file-writable-p "~/foo")
295 (file-writable-p "/foo")
297 (file-writable-p "~/no-such-dir/foo")
300 - Function: file-accessible-directory-p dirname
301 This function returns `t' if you have permission to open existing
302 files in the directory whose name as a file is DIRNAME; otherwise
303 (or if there is no such directory), it returns `nil'. The value
304 of DIRNAME may be either a directory name or the file name of a
307 Example: after the following,
309 (file-accessible-directory-p "/foo")
312 we can deduce that any attempt to read a file in `/foo/' will give
315 - Function: file-ownership-preserved-p filename
316 This function returns `t' if deleting the file FILENAME and then
317 creating it anew would keep the file's owner unchanged.
319 - Function: file-newer-than-file-p filename1 filename2
320 This function returns `t' if the file FILENAME1 is newer than file
321 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
322 FILENAME2 does not exist, it returns `t'.
324 In the following example, assume that the file `aug-19' was written
325 on the 19th, `aug-20' was written on the 20th, and the file
326 `no-file' doesn't exist at all.
328 (file-newer-than-file-p "aug-19" "aug-20")
330 (file-newer-than-file-p "aug-20" "aug-19")
332 (file-newer-than-file-p "aug-19" "no-file")
334 (file-newer-than-file-p "no-file" "aug-19")
337 You can use `file-attributes' to get a file's last modification
338 time as a list of two numbers. *Note File Attributes::.
341 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
343 Distinguishing Kinds of Files
344 -----------------------------
346 This section describes how to distinguish various kinds of files,
347 such as directories, symbolic links, and ordinary files.
349 - Function: file-symlink-p filename
350 If the file FILENAME is a symbolic link, the `file-symlink-p'
351 function returns the file name to which it is linked. This may be
352 the name of a text file, a directory, or even another symbolic
353 link, or it may be a nonexistent file name.
355 If the file FILENAME is not a symbolic link (or there is no such
356 file), `file-symlink-p' returns `nil'.
358 (file-symlink-p "foo")
360 (file-symlink-p "sym-link")
362 (file-symlink-p "sym-link2")
364 (file-symlink-p "/bin")
368 - Function: file-directory-p filename
369 This function returns `t' if FILENAME is the name of an existing
370 directory, `nil' otherwise.
372 (file-directory-p "~rms")
374 (file-directory-p "~rms/lewis/files.texi")
376 (file-directory-p "~rms/lewis/no-such-file")
378 (file-directory-p "$HOME")
381 (substitute-in-file-name "$HOME"))
384 - Function: file-regular-p filename
385 This function returns `t' if the file FILENAME exists and is a
386 regular file (not a directory, symbolic link, named pipe,
387 terminal, or other I/O device).
390 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
395 The "truename" of a file is the name that you get by following
396 symbolic links until none remain, then expanding to get rid of `.' and
397 `..' as components. Strictly speaking, a file need not have a unique
398 truename; the number of distinct truenames a file has is equal to the
399 number of hard links to the file. However, truenames are useful
400 because they eliminate symbolic links as a cause of name variation.
402 - Function: file-truename filename &optional default
403 The function `file-truename' returns the true name of the file
404 FILENAME. This is the name that you get by following symbolic
405 links until none remain.
407 If the filename is relative, DEFAULT is the directory to start
408 with. If DEFAULT is `nil' or missing, the current buffer's value
409 of `default-directory' is used.
411 *Note Buffer File Name::, for related information.
414 File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
416 Other Information about Files
417 -----------------------------
419 This section describes the functions for getting detailed information
420 about a file, other than its contents. This information includes the
421 mode bits that control access permission, the owner and group numbers,
422 the number of names, the inode number, the size, and the times of access
425 - Function: file-modes filename
426 This function returns the mode bits of FILENAME, as an integer.
427 The mode bits are also called the file permissions, and they
428 specify access control in the usual Unix fashion. If the
429 low-order bit is 1, then the file is executable by all users, if
430 the second-lowest-order bit is 1, then the file is writable by all
433 The highest value returnable is 4095 (7777 octal), meaning that
434 everyone has read, write, and execute permission, that the SUID bit
435 is set for both others and group, and that the sticky bit is set.
437 (file-modes "~/junk/diffs")
438 => 492 ; Decimal integer.
440 => "754" ; Convert to octal.
442 (set-file-modes "~/junk/diffs" 438)
446 => "666" ; Convert to octal.
449 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
451 - Function: file-nlinks filename
452 This functions returns the number of names (i.e., hard links) that
453 file FILENAME has. If the file does not exist, then this function
454 returns `nil'. Note that symbolic links have no effect on this
455 function, because they are not considered to be names of the files
459 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
460 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
464 (file-nlinks "doesnt-exist")
467 - Function: file-attributes filename
468 This function returns a list of attributes of file FILENAME. If
469 the specified file cannot be opened, it returns `nil'.
471 The elements of the list, in order, are:
473 0. `t' for a directory, a string for a symbolic link (the name
474 linked to), or `nil' for a text file.
476 1. The number of names the file has. Alternate names, also
477 known as hard links, can be created by using the
478 `add-name-to-file' function (*note Changing File
485 4. The time of last access, as a list of two integers. The
486 first integer has the high-order 16 bits of time, the second
487 has the low 16 bits. (This is similar to the value of
488 `current-time'; see *Note Time of Day::.)
490 5. The time of last modification as a list of two integers (as
493 6. The time of last status change as a list of two integers (as
496 7. The size of the file in bytes.
498 8. The file's modes, as a string of ten letters or dashes, as in
501 9. `t' if the file's GID would change if file were deleted and
502 recreated; `nil' otherwise.
504 10. The file's inode number.
506 11. The file system number of the file system that the file is
507 in. This element and the file's inode number together give
508 enough information to distinguish any two files on the
509 system--no two files can have the same values for both of
512 For example, here are the file attributes for `files.texi':
514 (file-attributes "files.texi")
528 and here is how the result is interpreted:
531 is neither a directory nor a symbolic link.
534 has only one name (the name `files.texi' in the current
538 is owned by the user with UID 2235.
541 is in the group with GID 75.
544 was last accessed on Aug 19 00:09. Use `format-time-string' to
545 ! convert this number into a time string. *Note Time
549 was last modified on Aug 19 00:09.
552 last had its inode changed on Aug 19 00:09.
555 is 14906 characters long.
558 has a mode of read and write access for the owner, group, and
562 would retain the same GID if it were recreated.
565 has an inode number of 129500.
568 is on file system number -32252.
571 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
573 Changing File Names and Attributes
574 ==================================
576 The functions in this section rename, copy, delete, link, and set the
579 In the functions that have an argument NEWNAME, if a file by the
580 name of NEWNAME already exists, the actions taken depend on the value
581 of the argument OK-IF-ALREADY-EXISTS:
583 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
586 * Request confirmation if OK-IF-ALREADY-EXISTS is a number.
588 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
591 - Command: add-name-to-file oldname newname &optional
593 This function gives the file named OLDNAME the additional name
594 NEWNAME. This means that NEWNAME becomes a new "hard link" to
597 In the first part of the following example, we list two files,
601 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
602 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
604 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
605 "~/lewis/foo2")'. Again we list the files. This shows two names,
608 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
612 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
613 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
614 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
616 Finally, we evaluate the following:
618 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
620 and list the files again. Now there are three names for one file:
621 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
623 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
627 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
628 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
629 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
631 This function is meaningless on VMS, where multiple names for one
632 file are not allowed.
634 See also `file-nlinks' in *Note File Attributes::.
636 - Command: rename-file filename newname &optional ok-if-already-exists
637 This command renames the file FILENAME as NEWNAME.
639 If FILENAME has additional names aside from FILENAME, it continues
640 to have those names. In fact, adding the name NEWNAME with
641 `add-name-to-file' and then deleting FILENAME has the same effect
642 as renaming, aside from momentary intermediate states.
644 In an interactive call, this function prompts for FILENAME and
645 NEWNAME in the minibuffer; also, it requests confirmation if
646 NEWNAME already exists.
648 - Command: copy-file oldname newname &optional ok-if-exists time
649 This command copies the file OLDNAME to NEWNAME. An error is
650 signaled if OLDNAME does not exist.
652 If TIME is non-`nil', then this functions gives the new file the
653 same last-modified time that the old one has. (This works on only
654 some operating systems.)
656 In an interactive call, this function prompts for FILENAME and
657 NEWNAME in the minibuffer; also, it requests confirmation if
658 NEWNAME already exists.
660 - Command: delete-file filename
661 This command deletes the file FILENAME, like the shell command `rm
662 FILENAME'. If the file has multiple names, it continues to exist
663 under the other names.
665 A suitable kind of `file-error' error is signaled if the file does
666 not exist, or is not deletable. (On Unix, a file is deletable if
667 its directory is writable.)
669 See also `delete-directory' in *Note Create/Delete Dirs::.
671 - Command: make-symbolic-link filename newname &optional ok-if-exists
672 This command makes a symbolic link to FILENAME, named NEWNAME.
673 This is like the shell command `ln -s FILENAME NEWNAME'.
675 In an interactive call, this function prompts for FILENAME and
676 NEWNAME in the minibuffer; also, it requests confirmation if
677 NEWNAME already exists.
679 - Function: define-logical-name varname string
680 This function defines the logical name NAME to have the value
681 STRING. It is available only on VMS.
683 - Function: set-file-modes filename mode
684 This function sets mode bits of FILENAME to MODE (which must be an
685 integer). Only the low 12 bits of MODE are used.
687 - Function: set-default-file-modes mode
688 This function sets the default file protection for new files
689 created by XEmacs and its subprocesses. Every file created with
690 XEmacs initially has this protection. On Unix, the default
691 protection is the bitwise complement of the "umask" value.
693 The argument MODE must be an integer. Only the low 9 bits of MODE
696 Saving a modified version of an existing file does not count as
697 creating the file; it does not change the file's mode, and does
698 not use the default file protection.
700 - Function: default-file-modes
701 This function returns the current default protection value.
703 On MS-DOS, there is no such thing as an "executable" file mode bit.
704 So Emacs considers a file executable if its name ends in `.com', `.bat'
705 or `.exe'. This is reflected in the values returned by `file-modes'
706 and `file-attributes'.
709 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
714 Files are generally referred to by their names, in XEmacs as
715 elsewhere. File names in XEmacs are represented as strings. The
716 functions that operate on a file all expect a file name argument.
718 In addition to operating on files themselves, XEmacs Lisp programs
719 often need to operate on the names; i.e., to take them apart and to use
720 part of a name to construct related file names. This section describes
721 how to manipulate file names.
723 The functions in this section do not actually access files, so they
724 can operate on file names that do not refer to an existing file or
727 On VMS, all these functions understand both VMS file-name syntax and
728 Unix syntax. This is so that all the standard Lisp libraries can
729 specify file names in Unix syntax and work properly on VMS without
730 change. On MS-DOS, these functions understand MS-DOS file-name syntax
731 as well as Unix syntax.
735 * File Name Components:: The directory part of a file name, and the rest.
736 * Directory Names:: A directory's name as a directory
737 is different from its name as a file.
738 * Relative File Names:: Some file names are relative to a current directory.
739 * File Name Expansion:: Converting relative file names to absolute ones.
740 * Unique File Names:: Generating names for temporary files.
741 * File Name Completion:: Finding the completions for a given file name.
742 * User Name Completion:: Finding the completions for a given user name.
745 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
750 The operating system groups files into directories. To specify a
751 file, you must specify the directory and the file's name within that
752 directory. Therefore, XEmacs considers a file name as having two main
753 parts: the "directory name" part, and the "nondirectory" part (or "file
754 name within the directory"). Either part may be empty. Concatenating
755 these two parts reproduces the original file name.
757 On Unix, the directory part is everything up to and including the
758 last slash; the nondirectory part is the rest. The rules in VMS syntax
761 For some purposes, the nondirectory part is further subdivided into
762 the name proper and the "version number". On Unix, only backup files
763 have version numbers in their names; on VMS, every file has a version
764 number, but most of the time the file name actually used in XEmacs
765 omits the version number. Version numbers are found mostly in
768 - Function: file-name-directory filename
769 This function returns the directory part of FILENAME (or `nil' if
770 FILENAME does not include a directory part). On Unix, the
771 function returns a string ending in a slash. On VMS, it returns a
772 string ending in one of the three characters `:', `]', or `>'.
774 (file-name-directory "lewis/foo") ; Unix example
776 (file-name-directory "foo") ; Unix example
778 (file-name-directory "[X]FOO.TMP") ; VMS example
781 - Function: file-name-nondirectory filename
782 This function returns the nondirectory part of FILENAME.
784 (file-name-nondirectory "lewis/foo")
786 (file-name-nondirectory "foo")
788 ;; The following example is accurate only on VMS.
789 (file-name-nondirectory "[X]FOO.TMP")
792 - Function: file-name-sans-versions filename &optional
794 This function returns FILENAME without any file version numbers,
795 backup version numbers, or trailing tildes.
797 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
798 version numbers, only true file version numbers.
800 (file-name-sans-versions "~rms/foo.~1~")
802 (file-name-sans-versions "~rms/foo~")
804 (file-name-sans-versions "~rms/foo")
806 ;; The following example applies to VMS only.
807 (file-name-sans-versions "foo;23")
810 - Function: file-name-sans-extension filename
811 This function returns FILENAME minus its "extension," if any. The
812 extension, in a file name, is the part that starts with the last
813 `.' in the last name component. For example,
815 (file-name-sans-extension "foo.lose.c")
817 (file-name-sans-extension "big.hack/foo")
821 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
826 A "directory name" is the name of a directory. A directory is a
827 kind of file, and it has a file name, which is related to the directory
828 name but not identical to it. (This is not quite the same as the usual
829 Unix terminology.) These two different names for the same entity are
830 related by a syntactic transformation. On Unix, this is simple: a
831 directory name ends in a slash, whereas the directory's name as a file
832 lacks that slash. On VMS, the relationship is more complicated.
834 The difference between a directory name and its name as a file is
835 subtle but crucial. When an XEmacs variable or function argument is
836 described as being a directory name, a file name of a directory is not
839 The following two functions convert between directory names and file
840 names. They do nothing special with environment variable substitutions
841 such as `$HOME', and the constructs `~', and `..'.
843 - Function: file-name-as-directory filename
844 This function returns a string representing FILENAME in a form
845 that the operating system will interpret as the name of a
846 directory. In Unix, this means appending a slash to the string.
847 On VMS, the function converts a string of the form `[X]Y.DIR.1' to
850 (file-name-as-directory "~rms/lewis")
853 - Function: directory-file-name dirname
854 This function returns a string representing DIRNAME in a form that
855 the operating system will interpret as the name of a file. On
856 Unix, this means removing a final slash from the string. On VMS,
857 the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
859 (directory-file-name "~lewis/")
862 Directory name abbreviations are useful for directories that are
863 normally accessed through symbolic links. Sometimes the users recognize
864 primarily the link's name as "the name" of the directory, and find it
865 annoying to see the directory's "real" name. If you define the link
866 name as an abbreviation for the "real" name, XEmacs shows users the
867 abbreviation instead.
869 If you wish to convert a directory name to its abbreviation, use this
872 - Function: abbreviate-file-name dirname &optional hack-homedir
873 This function applies abbreviations from `directory-abbrev-alist'
874 to its argument, and substitutes `~' for the user's home directory.
876 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
877 the user's home directory.
880 - Variable: directory-abbrev-alist
881 The variable `directory-abbrev-alist' contains an alist of
882 abbreviations to use for file directories. Each element has the
883 form `(FROM . TO)', and says to replace FROM with TO when it
884 appears in a directory name. The FROM string is actually a
885 regular expression; it should always start with `^'. The function
886 `abbreviate-file-name' performs these substitutions.
888 You can set this variable in `site-init.el' to describe the
889 abbreviations appropriate for your site.
891 Here's an example, from a system on which file system `/home/fsf'
892 and so on are normally accessed through symbolic links named `/fsf'
895 (("^/home/fsf" . "/fsf")
896 ("^/home/gp" . "/gp")
897 ("^/home/gd" . "/gd"))
900 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
902 Absolute and Relative File Names
903 --------------------------------
905 All the directories in the file system form a tree starting at the
906 root directory. A file name can specify all the directory names
907 starting from the root of the tree; then it is called an "absolute"
908 file name. Or it can specify the position of the file in the tree
909 relative to a default directory; then it is called a "relative" file
910 name. On Unix, an absolute file name starts with a slash or a tilde
911 (`~'), and a relative one does not. The rules on VMS are complicated.
913 - Function: file-name-absolute-p filename
914 This function returns `t' if file FILENAME is an absolute file
915 name, `nil' otherwise. On VMS, this function understands both
916 Unix syntax and VMS syntax.
918 (file-name-absolute-p "~rms/foo")
920 (file-name-absolute-p "rms/foo")
922 (file-name-absolute-p "/user/rms/foo")
926 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
928 Functions that Expand Filenames
929 -------------------------------
931 "Expansion" of a file name means converting a relative file name to
932 an absolute one. Since this is done relative to a default directory,
933 you must specify the default directory name as well as the file name to
934 be expanded. Expansion also simplifies file names by eliminating
935 redundancies such as `./' and `NAME/../'.
937 - Function: expand-file-name filename &optional directory
938 This function converts FILENAME to an absolute file name. If
939 DIRECTORY is supplied, it is the directory to start with if
940 FILENAME is relative. (The value of DIRECTORY should itself be an
941 absolute directory name; it may start with `~'.) Otherwise, the
942 current buffer's value of `default-directory' is used. For
945 (expand-file-name "foo")
946 => "/xcssun/users/rms/lewis/foo"
947 (expand-file-name "../foo")
948 => "/xcssun/users/rms/foo"
949 (expand-file-name "foo" "/usr/spool/")
951 (expand-file-name "$HOME/foo")
952 => "/xcssun/users/rms/lewis/$HOME/foo"
954 Filenames containing `.' or `..' are simplified to their canonical
957 (expand-file-name "bar/../foo")
958 => "/xcssun/users/rms/lewis/foo"
960 `~/' at the beginning is expanded into the user's home directory.
961 A `/' or `~' following a `/'.
963 Note that `expand-file-name' does _not_ expand environment
964 variables; only `substitute-in-file-name' does that.
966 - Function: file-relative-name filename &optional directory
967 This function does the inverse of expansion--it tries to return a
968 relative name that is equivalent to FILENAME when interpreted
969 relative to DIRECTORY.
971 If DIRECTORY is `nil' or omitted, the value of `default-directory'
974 (file-relative-name "/foo/bar" "/foo/")
976 (file-relative-name "/foo/bar" "/hack/")
979 - Variable: default-directory
980 The value of this buffer-local variable is the default directory
981 for the current buffer. It should be an absolute directory name;
982 it may start with `~'. This variable is local in every buffer.
984 `expand-file-name' uses the default directory when its second
987 On Unix systems, the value is always a string ending with a slash.
990 => "/user/lewis/manual/"
992 - Function: substitute-in-file-name filename
993 This function replaces environment variable references in FILENAME
994 with the environment variable values. Following standard Unix
995 shell syntax, `$' is the prefix to substitute an environment
998 The environment variable name is the series of alphanumeric
999 characters (including underscores) that follow the `$'. If the
1000 character following the `$' is a `{', then the variable name is
1001 everything up to the matching `}'.
1003 Here we assume that the environment variable `HOME', which holds
1004 the user's home directory name, has value `/xcssun/users/rms'.
1006 (substitute-in-file-name "$HOME/foo")
1007 => "/xcssun/users/rms/foo"
1009 After substitution, a `/' or `~' following a `/' is taken to be
1010 the start of an absolute file name that overrides what precedes
1011 it, so everything before that `/' or `~' is deleted. For example:
1013 (substitute-in-file-name "bar/~/foo")
1015 (substitute-in-file-name "/usr/local/$HOME/foo")
1016 => "/xcssun/users/rms/foo"
1018 On VMS, `$' substitution is not done, so this function does nothing
1019 on VMS except discard superfluous initial components as shown
1023 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
1025 Generating Unique File Names
1026 ----------------------------
1028 Some programs need to write temporary files. Here is the usual way
1029 to construct a name for such a file:
1031 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
1033 Here we use `(temp-directory)' to specify a directory for temporary
1034 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
1035 `make-temp-name' is to prevent two different users or two different
1036 processes from trying to use the same name.
1038 - Function: temp-directory
1039 This function returns the name of the directory to use for
1040 temporary files. Under Unix, this will be the value of `TMPDIR',
1041 defaulting to `/tmp'. On Windows, this will be obtained from the
1042 `TEMP' or `TMP' environment variables, defaulting to `/'.
1044 Note that the `temp-directory' function does not exist under FSF
1047 - Function: make-temp-name prefix
1048 This function generates a temporary file name starting with
1049 PREFIX. The Emacs process number forms part of the result, so
1050 there is no danger of generating a name being used by another
1053 (make-temp-name "/tmp/foo")
1056 In addition, this function makes an attempt to choose a name that
1057 does not specify an existing file. To make this work, PREFIX
1058 should be an absolute file name.
1060 To avoid confusion, each Lisp application should preferably use a
1061 unique PREFIX to `make-temp-name'.
1064 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
1066 File Name Completion
1067 --------------------
1069 This section describes low-level subroutines for completing a file
1070 name. For other completion functions, see *Note Completion::.
1072 - Function: file-name-all-completions partial-filename directory
1073 This function returns a list of all possible completions for a file
1074 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
1075 The order of the completions is the order of the files in the
1076 directory, which is unpredictable and conveys no useful
1079 The argument PARTIAL-FILENAME must be a file name containing no
1080 directory part and no slash. The current buffer's default
1081 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
1083 In the following example, suppose that the current default
1084 directory, `~rms/lewis', has five files whose names begin with `f':
1085 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
1087 (file-name-all-completions "f" "")
1088 => ("foo" "file~" "file.c.~2~"
1089 "file.c.~1~" "file.c")
1091 (file-name-all-completions "fo" "")
1094 - Function: file-name-completion filename directory
1095 This function completes the file name FILENAME in directory
1096 DIRECTORY. It returns the longest prefix common to all file names
1097 in directory DIRECTORY that start with FILENAME.
1099 If only one match exists and FILENAME matches it exactly, the
1100 function returns `t'. The function returns `nil' if directory
1101 DIRECTORY contains no name starting with FILENAME.
1103 In the following example, suppose that the current default
1104 directory has five files whose names begin with `f': `foo',
1105 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
1107 (file-name-completion "fi" "")
1110 (file-name-completion "file.c.~1" "")
1113 (file-name-completion "file.c.~1~" "")
1116 (file-name-completion "file.c.~3" "")
1119 - User Option: completion-ignored-extensions
1120 `file-name-completion' usually ignores file names that end in any
1121 string in this list. It does not ignore them when all the possible
1122 completions end in one of these suffixes or when a buffer showing
1123 all possible completions is displayed.
1125 A typical value might look like this:
1127 completion-ignored-extensions
1128 => (".o" ".elc" "~" ".dvi")
1131 File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
1133 User Name Completion
1134 --------------------
1136 This section describes low-level subroutines for completing a user
1137 name. For other completion functions, see *Note Completion::.
1139 - Function: user-name-all-completions partial-username
1140 This function returns a list of all possible completions for a user
1141 whose name starts with PARTIAL-USERNAME. The order of the
1142 completions is unpredictable and conveys no useful information.
1144 The argument PARTIAL-USERNAME must be a partial user name
1145 containing no tilde character and no slash.
1147 - Function: user-name-completion username
1148 This function completes the user name USERNAME. It returns the
1149 longest prefix common to all user names that start with USERNAME.
1151 If only one match exists and USERNAME matches it exactly, the
1152 function returns `t'. The function returns `nil' if no user name
1153 starting with USERNAME exists.
1155 - Function: user-name-completion-1 username
1156 This function completes the user name USERNAME, like
1157 `user-name-completion', differing only in the return value. This
1158 function returns the cons of the completion returned by
1159 `user-name-completion', and a boolean indicating whether that
1160 completion was unique.
1163 File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
1165 Contents of Directories
1166 =======================
1168 A directory is a kind of file that contains other files entered under
1169 various names. Directories are a feature of the file system.
1171 XEmacs can list the names of the files in a directory as a Lisp list,
1172 or display the names in a buffer using the `ls' shell command. In the
1173 latter case, it can optionally display information about each file,
1174 depending on the value of switches passed to the `ls' command.
1176 - Function: directory-files directory &optional full-name match-regexp
1178 This function returns a list of the names of the files in the
1179 directory DIRECTORY. By default, the list is in alphabetical
1182 If FULL-NAME is non-`nil', the function returns the files'
1183 absolute file names. Otherwise, it returns just the names
1184 relative to the specified directory.
1186 If MATCH-REGEXP is non-`nil', this function returns only those
1187 file names that contain that regular expression--the other file
1188 names are discarded from the list.
1190 If NOSORT is non-`nil', `directory-files' does not sort the list,
1191 so you get the file names in no particular order. Use this if you
1192 want the utmost possible speed and don't care what order the files
1193 are processed in. If the order of processing is visible to the
1194 user, then the user will probably be happier if you do sort the
1197 If FILES-ONLY is the symbol `t', then only the "files" in the
1198 directory will be returned; subdirectories will be excluded. If
1199 FILES-ONLY is not `nil' and not `t', then only the subdirectories
1200 will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
1201 then both files and subdirectories will be returned.
1203 (directory-files "~lewis")
1204 => ("#foo#" "#foo.el#" "." ".."
1205 "dired-mods.el" "files.texi"
1208 An error is signaled if DIRECTORY is not the name of a directory
1211 - Function: insert-directory file switches &optional wildcard
1213 This function inserts (in the current buffer) a directory listing
1214 for directory FILE, formatted with `ls' according to SWITCHES. It
1215 leaves point after the inserted text.
1217 The argument FILE may be either a directory name or a file
1218 specification including wildcard characters. If WILDCARD is
1219 non-`nil', that means treat FILE as a file specification with
1222 If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
1223 and switches do not contain `-d', so that the listing should show
1224 the full contents of the directory. (The `-d' option to `ls' says
1225 to describe a directory itself rather than its contents.)
1227 This function works by running a directory listing program whose
1228 name is in the variable `insert-directory-program'. If WILDCARD is
1229 non-`nil', it also runs the shell specified by `shell-file-name',
1230 to expand the wildcards.
1232 - Variable: insert-directory-program
1233 This variable's value is the program to run to generate a
1234 directory listing for the function `insert-directory'.
1237 File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
1239 Creating and Deleting Directories
1240 =================================
1242 Most XEmacs Lisp file-manipulation functions get errors when used on
1243 files that are directories. For example, you cannot delete a directory
1244 with `delete-file'. These special functions exist to create and delete
1247 - Command: make-directory dirname &optional parents
1248 This function creates a directory named DIRNAME. Interactively,
1249 the default choice of directory to create is the current default
1250 directory for file names. That is useful when you have visited a
1251 file in a nonexistent directory.
1253 Non-interactively, optional argument PARENTS says whether to
1254 create parent directories if they don't exist. (Interactively, this
1257 - Command: delete-directory dirname
1258 This function deletes the directory named DIRNAME. The function
1259 `delete-file' does not work for files that are directories; you
1260 must use `delete-directory' in that case.