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: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
58 When you edit a file in XEmacs, you are actually working on a buffer
59 that is visiting that file--that is, the contents of the file are
60 copied into the buffer and the copy is what you edit. Changes to the
61 buffer do not change the file until you "save" the buffer, which means
62 copying the contents of the buffer into the file.
64 - Command: save-buffer &optional backup-option
65 This function saves the contents of the current buffer in its
66 visited file if the buffer has been modified since it was last
67 visited or saved. Otherwise it does nothing.
69 `save-buffer' is responsible for making backup files. Normally,
70 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
71 if this is the first save since visiting the file. Other values
72 for BACKUP-OPTION request the making of backup files in other
75 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
76 `save-buffer' function marks this version of the file to be
77 backed up when the buffer is next saved.
79 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
80 `save-buffer' function unconditionally backs up the previous
81 version of the file before saving it.
83 - Command: save-some-buffers &optional save-silently-p exiting
84 This command saves some modified file-visiting buffers. Normally
85 it asks the user about each buffer. But if SAVE-SILENTLY-P is
86 non-`nil', it saves all the file-visiting buffers without querying
89 The optional EXITING argument, if non-`nil', requests this
90 function to offer also to save certain other buffers that are not
91 visiting files. These are buffers that have a non-`nil' local
92 value of `buffer-offer-save'. (A user who says yes to saving one
93 of these is asked to specify a file name to use.) The
94 `save-buffers-kill-emacs' function passes a non-`nil' value for
97 - Variable: buffer-offer-save
98 When this variable is non-`nil' in a buffer, XEmacs offers to save
99 the buffer on exit even if the buffer is not visiting a file. The
100 variable is automatically local in all buffers. Normally, Mail
101 mode (used for editing outgoing mail) sets this to `t'.
103 - Command: write-file filename
104 This function writes the current buffer into file FILENAME, makes
105 the buffer visit that file, and marks it not modified. Then it
106 renames the buffer based on FILENAME, appending a string like `<2>'
107 if necessary to make a unique buffer name. It does most of this
108 work by calling `set-visited-file-name' and `save-buffer'.
110 - Variable: write-file-hooks
111 The value of this variable is a list of functions to be called
112 before writing out a buffer to its visited file. If one of them
113 returns non-`nil', the file is considered already written and the
114 rest of the functions are not called, nor is the usual code for
115 writing the file executed.
117 If a function in `write-file-hooks' returns non-`nil', it is
118 responsible for making a backup file (if that is appropriate). To
119 do so, execute the following code:
121 (or buffer-backed-up (backup-buffer))
123 You might wish to save the file modes value returned by
124 `backup-buffer' and use that to set the mode bits of the file that
125 you write. This is what `save-buffer' normally does.
127 Even though this is not a normal hook, you can use `add-hook' and
128 `remove-hook' to manipulate the list. *Note Hooks::.
130 - Variable: local-write-file-hooks
131 This works just like `write-file-hooks', but it is intended to be
132 made local to particular buffers. It's not a good idea to make
133 `write-file-hooks' local to a buffer--use this variable instead.
135 The variable is marked as a permanent local, so that changing the
136 major mode does not alter a buffer-local value. This is
137 convenient for packages that read "file" contents in special ways,
138 and set up hooks to save the data in a corresponding way.
140 - Variable: write-contents-hooks
141 This works just like `write-file-hooks', but it is intended for
142 hooks that pertain to the contents of the file, as opposed to
143 hooks that pertain to where the file came from. Such hooks are
144 usually set up by major modes, as buffer-local bindings for this
145 variable. Switching to a new major mode always resets this
148 - Variable: after-save-hook
149 This normal hook runs after a buffer has been saved in its visited
152 - Variable: file-precious-flag
153 If this variable is non-`nil', then `save-buffer' protects against
154 I/O errors while saving by writing the new file to a temporary
155 name instead of the name it is supposed to have, and then renaming
156 it to the intended name after it is clear there are no errors.
157 This procedure prevents problems such as a lack of disk space from
158 resulting in an invalid file.
160 As a side effect, backups are necessarily made by copying. *Note
161 Rename or Copy::. Yet, at the same time, saving a precious file
162 always breaks all hard links between the file you save and other
165 Some modes set this variable non-`nil' locally in particular
168 - User Option: require-final-newline
169 This variable determines whether files may be written out that do
170 _not_ end with a newline. If the value of the variable is `t',
171 then `save-buffer' silently adds a newline at the end of the file
172 whenever the buffer being saved does not already end in one. If
173 the value of the variable is non-`nil', but not `t', then
174 `save-buffer' asks the user whether to add a newline each time the
177 If the value of the variable is `nil', then `save-buffer' doesn't
178 add newlines at all. `nil' is the default value, but a few major
179 modes set it to `t' in particular buffers.
182 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
187 You can copy a file from the disk and insert it into a buffer using
188 the `insert-file-contents' function. Don't use the user-level command
189 `insert-file' in a Lisp program, as that sets the mark.
191 - Function: insert-file-contents filename &optional visit beg end
193 This function inserts the contents of file FILENAME into the
194 current buffer after point. It returns a list of the absolute
195 file name and the length of the data inserted. An error is
196 signaled if FILENAME is not the name of a file that can be read.
198 The function `insert-file-contents' checks the file contents
199 against the defined file formats, and converts the file contents if
200 appropriate. *Note Format Conversion::. It also calls the
201 functions in the list `after-insert-file-functions'; see *Note
204 If VISIT is non-`nil', this function additionally marks the buffer
205 as unmodified and sets up various fields in the buffer so that it
206 is visiting the file FILENAME: these include the buffer's visited
207 file name and its last save file modtime. This feature is used by
208 `find-file-noselect' and you probably should not use it yourself.
210 If BEG and END are non-`nil', they should be integers specifying
211 the portion of the file to insert. In this case, VISIT must be
214 (insert-file-contents filename nil 0 500)
216 inserts the first 500 characters of a file.
218 If the argument REPLACE is non-`nil', it means to replace the
219 contents of the buffer (actually, just the accessible portion)
220 with the contents of the file. This is better than simply
221 deleting the buffer contents and inserting the whole file, because
222 (1) it preserves some marker positions and (2) it puts less data
225 If you want to pass a file name to another process so that another
226 program can read the file, use the function `file-local-copy'; see
227 *Note Magic File Names::.
230 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
235 You can write the contents of a buffer, or part of a buffer, directly
236 to a file on disk using the `append-to-file' and `write-region'
237 functions. Don't use these functions to write to files that are being
238 visited; that could cause confusion in the mechanisms for visiting.
240 - Command: append-to-file start end filename
241 This function appends the contents of the region delimited by
242 START and END in the current buffer to the end of file FILENAME.
243 If that file does not exist, it is created. If that file exists
244 it is overwritten. This function returns `nil'.
246 An error is signaled if FILENAME specifies a nonwritable file, or
247 a nonexistent file in a directory where files cannot be created.
249 - Command: write-region start end filename &optional append visit
250 This function writes the region delimited by START and END in the
251 current buffer into the file specified by FILENAME.
253 If START is a string, then `write-region' writes or appends that
254 string, rather than text from the buffer.
256 If APPEND is non-`nil', then the specified text is appended to the
257 existing file contents (if any).
259 If VISIT is `t', then XEmacs establishes an association between
260 the buffer and the file: the buffer is then visiting that file.
261 It also sets the last file modification time for the current
262 buffer to FILENAME's modtime, and marks the buffer as not
263 modified. This feature is used by `save-buffer', but you probably
264 should not use it yourself.
266 If VISIT is a string, it specifies the file name to visit. This
267 way, you can write the data to one file (FILENAME) while recording
268 the buffer as visiting another file (VISIT). The argument VISIT
269 is used in the echo area message and also for file locking; VISIT
270 is stored in `buffer-file-name'. This feature is used to
271 implement `file-precious-flag'; don't use it yourself unless you
272 really know what you're doing.
274 The function `write-region' converts the data which it writes to
275 the appropriate file formats specified by `buffer-file-format'.
276 *Note Format Conversion::. It also calls the functions in the list
277 `write-region-annotate-functions'; see *Note Saving Properties::.
279 Normally, `write-region' displays a message `Wrote file FILENAME'
280 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
281 then this message is inhibited. This feature is useful for
282 programs that use files for internal purposes, files that the user
283 does not need to know about.
286 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
291 When two users edit the same file at the same time, they are likely
292 to interfere with each other. XEmacs tries to prevent this situation
293 from arising by recording a "file lock" when a file is being modified.
294 XEmacs can then detect the first attempt to modify a buffer visiting a
295 file that is locked by another XEmacs process, and ask the user what to
298 File locks do not work properly when multiple machines can share
299 file systems, such as with NFS. Perhaps a better file locking system
300 will be implemented in the future. When file locks do not work, it is
301 possible for two users to make changes simultaneously, but XEmacs can
302 still warn the user who saves second. Also, the detection of
303 modification of a buffer visiting a file changed on disk catches some
304 cases of simultaneous editing; see *Note Modification Time::.
306 - Function: file-locked-p &optional filename
307 This function returns `nil' if the file FILENAME is not locked by
308 this XEmacs process. It returns `t' if it is locked by this
309 XEmacs, and it returns the name of the user who has locked it if it
310 is locked by someone else.
312 (file-locked-p "foo")
315 - Function: lock-buffer &optional filename
316 This function locks the file FILENAME, if the current buffer is
317 modified. The argument FILENAME defaults to the current buffer's
318 visited file. Nothing is done if the current buffer is not
319 visiting a file, or is not modified.
321 - Function: unlock-buffer
322 This function unlocks the file being visited in the current buffer,
323 if the buffer is modified. If the buffer is not modified, then
324 the file should not be locked, so this function does nothing. It
325 also does nothing if the current buffer is not visiting a file.
327 - Function: ask-user-about-lock file other-user
328 This function is called when the user tries to modify FILE, but it
329 is locked by another user named OTHER-USER. The value it returns
330 determines what happens next:
332 * A value of `t' says to grab the lock on the file. Then this
333 user may edit the file and OTHER-USER loses the lock.
335 * A value of `nil' says to ignore the lock and let this user
336 edit the file anyway.
338 * This function may instead signal a `file-locked' error, in
339 which case the change that the user was about to make does
342 The error message for this error looks like this:
344 error--> File is locked: FILE OTHER-USER
346 where `file' is the name of the file and OTHER-USER is the
347 name of the user who has locked the file.
349 The default definition of this function asks the user to choose
350 what to do. If you wish, you can replace the `ask-user-about-lock'
351 function with your own version that decides in another way. The
352 code for its usual definition is in `userlock.el'.
355 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
357 Information about Files
358 =======================
360 The functions described in this section all operate on strings that
361 designate file names. All the functions have names that begin with the
362 word `file'. These functions all return information about actual files
363 or directories, so their arguments must all exist as actual files or
364 directories unless otherwise noted.
368 * Testing Accessibility:: Is a given file readable? Writable?
369 * Kinds of Files:: Is it a directory? A symbolic link?
370 * Truenames:: Eliminating symbolic links from a file name.
371 * File Attributes:: How large is it? Any other names? Etc.
374 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
376 Testing Accessibility
377 ---------------------
379 These functions test for permission to access a file in specific
382 - Function: file-exists-p filename
383 This function returns `t' if a file named FILENAME appears to
384 exist. This does not mean you can necessarily read the file, only
385 that you can find out its attributes. (On Unix, this is true if
386 the file exists and you have execute permission on the containing
387 directories, regardless of the protection of the file itself.)
389 If the file does not exist, or if fascist access control policies
390 prevent you from finding the attributes of the file, this function
393 - Function: file-readable-p filename
394 This function returns `t' if a file named FILENAME exists and you
395 can read it. It returns `nil' otherwise.
397 (file-readable-p "files.texi")
399 (file-exists-p "/usr/spool/mqueue")
401 (file-readable-p "/usr/spool/mqueue")
404 - Function: file-executable-p filename
405 This function returns `t' if a file named FILENAME exists and you
406 can execute it. It returns `nil' otherwise. If the file is a
407 directory, execute permission means you can check the existence and
408 attributes of files inside the directory, and open those files if
411 - Function: file-writable-p filename
412 This function returns `t' if the file FILENAME can be written or
413 created by you, and `nil' otherwise. A file is writable if the
414 file exists and you can write it. It is creatable if it does not
415 exist, but the specified directory does exist and you can write in
418 In the third example below, `foo' is not writable because the
419 parent directory does not exist, even though the user could create
422 (file-writable-p "~/foo")
424 (file-writable-p "/foo")
426 (file-writable-p "~/no-such-dir/foo")
429 - Function: file-accessible-directory-p dirname
430 This function returns `t' if you have permission to open existing
431 files in the directory whose name as a file is DIRNAME; otherwise
432 (or if there is no such directory), it returns `nil'. The value
433 of DIRNAME may be either a directory name or the file name of a
436 Example: after the following,
438 (file-accessible-directory-p "/foo")
441 we can deduce that any attempt to read a file in `/foo/' will give
444 - Function: file-ownership-preserved-p filename
445 This function returns `t' if deleting the file FILENAME and then
446 creating it anew would keep the file's owner unchanged.
448 - Function: file-newer-than-file-p filename1 filename2
449 This function returns `t' if the file FILENAME1 is newer than file
450 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
451 FILENAME2 does not exist, it returns `t'.
453 In the following example, assume that the file `aug-19' was written
454 on the 19th, `aug-20' was written on the 20th, and the file
455 `no-file' doesn't exist at all.
457 (file-newer-than-file-p "aug-19" "aug-20")
459 (file-newer-than-file-p "aug-20" "aug-19")
461 (file-newer-than-file-p "aug-19" "no-file")
463 (file-newer-than-file-p "no-file" "aug-19")
466 You can use `file-attributes' to get a file's last modification
467 time as a list of two numbers. *Note File Attributes::.
470 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
472 Distinguishing Kinds of Files
473 -----------------------------
475 This section describes how to distinguish various kinds of files,
476 such as directories, symbolic links, and ordinary files.
478 - Function: file-symlink-p filename
479 If the file FILENAME is a symbolic link, the `file-symlink-p'
480 function returns the file name to which it is linked. This may be
481 the name of a text file, a directory, or even another symbolic
482 link, or it may be a nonexistent file name.
484 If the file FILENAME is not a symbolic link (or there is no such
485 file), `file-symlink-p' returns `nil'.
487 (file-symlink-p "foo")
489 (file-symlink-p "sym-link")
491 (file-symlink-p "sym-link2")
493 (file-symlink-p "/bin")
497 - Function: file-directory-p filename
498 This function returns `t' if FILENAME is the name of an existing
499 directory, `nil' otherwise.
501 (file-directory-p "~rms")
503 (file-directory-p "~rms/lewis/files.texi")
505 (file-directory-p "~rms/lewis/no-such-file")
507 (file-directory-p "$HOME")
510 (substitute-in-file-name "$HOME"))
513 - Function: file-regular-p filename
514 This function returns `t' if the file FILENAME exists and is a
515 regular file (not a directory, symbolic link, named pipe,
516 terminal, or other I/O device).
519 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
524 The "truename" of a file is the name that you get by following
525 symbolic links until none remain, then expanding to get rid of `.' and
526 `..' as components. Strictly speaking, a file need not have a unique
527 truename; the number of distinct truenames a file has is equal to the
528 number of hard links to the file. However, truenames are useful
529 because they eliminate symbolic links as a cause of name variation.
531 - Function: file-truename filename &optional default
532 The function `file-truename' returns the true name of the file
533 FILENAME. This is the name that you get by following symbolic
534 links until none remain.
536 If the filename is relative, DEFAULT is the directory to start
537 with. If DEFAULT is `nil' or missing, the current buffer's value
538 of `default-directory' is used.
540 *Note Buffer File Name::, for related information.
543 File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
545 Other Information about Files
546 -----------------------------
548 This section describes the functions for getting detailed information
549 about a file, other than its contents. This information includes the
550 mode bits that control access permission, the owner and group numbers,
551 the number of names, the inode number, the size, and the times of access
554 - Function: file-modes filename
555 This function returns the mode bits of FILENAME, as an integer.
556 The mode bits are also called the file permissions, and they
557 specify access control in the usual Unix fashion. If the
558 low-order bit is 1, then the file is executable by all users, if
559 the second-lowest-order bit is 1, then the file is writable by all
562 The highest value returnable is 4095 (7777 octal), meaning that
563 everyone has read, write, and execute permission, that the SUID bit
564 is set for both others and group, and that the sticky bit is set.
566 (file-modes "~/junk/diffs")
567 => 492 ; Decimal integer.
569 => "754" ; Convert to octal.
571 (set-file-modes "~/junk/diffs" 438)
575 => "666" ; Convert to octal.
578 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
580 - Function: file-nlinks filename
581 This functions returns the number of names (i.e., hard links) that
582 file FILENAME has. If the file does not exist, then this function
583 returns `nil'. Note that symbolic links have no effect on this
584 function, because they are not considered to be names of the files
588 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
589 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
593 (file-nlinks "doesnt-exist")
596 - Function: file-attributes filename
597 This function returns a list of attributes of file FILENAME. If
598 the specified file cannot be opened, it returns `nil'.
600 The elements of the list, in order, are:
602 0. `t' for a directory, a string for a symbolic link (the name
603 linked to), or `nil' for a text file.
605 1. The number of names the file has. Alternate names, also
606 known as hard links, can be created by using the
607 `add-name-to-file' function (*note Changing File
614 4. The time of last access, as a list of two integers. The
615 first integer has the high-order 16 bits of time, the second
616 has the low 16 bits. (This is similar to the value of
617 `current-time'; see *Note Time of Day::.)
619 5. The time of last modification as a list of two integers (as
622 6. The time of last status change as a list of two integers (as
625 7. The size of the file in bytes.
627 8. The file's modes, as a string of ten letters or dashes, as in
630 9. `t' if the file's GID would change if file were deleted and
631 recreated; `nil' otherwise.
633 10. The file's inode number.
635 11. The file system number of the file system that the file is
636 in. This element and the file's inode number together give
637 enough information to distinguish any two files on the
638 system--no two files can have the same values for both of
641 For example, here are the file attributes for `files.texi':
643 (file-attributes "files.texi")
657 and here is how the result is interpreted:
660 is neither a directory nor a symbolic link.
663 has only one name (the name `files.texi' in the current
667 is owned by the user with UID 2235.
670 is in the group with GID 75.
673 was last accessed on Aug 19 00:09. Use `format-time-string' to
674 ! convert this number into a time string. *Note Time
678 was last modified on Aug 19 00:09.
681 last had its inode changed on Aug 19 00:09.
684 is 14906 characters long.
687 has a mode of read and write access for the owner, group, and
691 would retain the same GID if it were recreated.
694 has an inode number of 129500.
697 is on file system number -32252.
700 File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
702 Changing File Names and Attributes
703 ==================================
705 The functions in this section rename, copy, delete, link, and set the
708 In the functions that have an argument NEWNAME, if a file by the
709 name of NEWNAME already exists, the actions taken depend on the value
710 of the argument OK-IF-ALREADY-EXISTS:
712 * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
715 * Request confirmation if OK-IF-ALREADY-EXISTS is a number.
717 * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
720 - Command: add-name-to-file oldname newname &optional
722 This function gives the file named OLDNAME the additional name
723 NEWNAME. This means that NEWNAME becomes a new "hard link" to
726 In the first part of the following example, we list two files,
730 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
731 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
733 Then we evaluate the form `(add-name-to-file "~/lewis/foo"
734 "~/lewis/foo2")'. Again we list the files. This shows two names,
737 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
741 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
742 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
743 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
745 Finally, we evaluate the following:
747 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
749 and list the files again. Now there are three names for one file:
750 `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
752 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
756 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
757 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
758 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
760 This function is meaningless on VMS, where multiple names for one
761 file are not allowed.
763 See also `file-nlinks' in *Note File Attributes::.
765 - Command: rename-file filename newname &optional ok-if-already-exists
766 This command renames the file FILENAME as NEWNAME.
768 If FILENAME has additional names aside from FILENAME, it continues
769 to have those names. In fact, adding the name NEWNAME with
770 `add-name-to-file' and then deleting FILENAME has the same effect
771 as renaming, aside from momentary intermediate states.
773 In an interactive call, this function prompts for FILENAME and
774 NEWNAME in the minibuffer; also, it requests confirmation if
775 NEWNAME already exists.
777 - Command: copy-file oldname newname &optional ok-if-exists time
778 This command copies the file OLDNAME to NEWNAME. An error is
779 signaled if OLDNAME does not exist.
781 If TIME is non-`nil', then this functions gives the new file the
782 same last-modified time that the old one has. (This works on only
783 some operating systems.)
785 In an interactive call, this function prompts for FILENAME and
786 NEWNAME in the minibuffer; also, it requests confirmation if
787 NEWNAME already exists.
789 - Command: delete-file filename
790 This command deletes the file FILENAME, like the shell command `rm
791 FILENAME'. If the file has multiple names, it continues to exist
792 under the other names.
794 A suitable kind of `file-error' error is signaled if the file does
795 not exist, or is not deletable. (On Unix, a file is deletable if
796 its directory is writable.)
798 See also `delete-directory' in *Note Create/Delete Dirs::.
800 - Command: make-symbolic-link filename newname &optional ok-if-exists
801 This command makes a symbolic link to FILENAME, named NEWNAME.
802 This is like the shell command `ln -s FILENAME NEWNAME'.
804 In an interactive call, this function prompts for FILENAME and
805 NEWNAME in the minibuffer; also, it requests confirmation if
806 NEWNAME already exists.
808 - Function: define-logical-name varname string
809 This function defines the logical name NAME to have the value
810 STRING. It is available only on VMS.
812 - Function: set-file-modes filename mode
813 This function sets mode bits of FILENAME to MODE (which must be an
814 integer). Only the low 12 bits of MODE are used.
816 - Function: set-default-file-modes mode
817 This function sets the default file protection for new files
818 created by XEmacs and its subprocesses. Every file created with
819 XEmacs initially has this protection. On Unix, the default
820 protection is the bitwise complement of the "umask" value.
822 The argument MODE must be an integer. Only the low 9 bits of MODE
825 Saving a modified version of an existing file does not count as
826 creating the file; it does not change the file's mode, and does
827 not use the default file protection.
829 - Function: default-file-modes
830 This function returns the current default protection value.
832 On MS-DOS, there is no such thing as an "executable" file mode bit.
833 So Emacs considers a file executable if its name ends in `.com', `.bat'
834 or `.exe'. This is reflected in the values returned by `file-modes'
835 and `file-attributes'.
838 File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
843 Files are generally referred to by their names, in XEmacs as
844 elsewhere. File names in XEmacs are represented as strings. The
845 functions that operate on a file all expect a file name argument.
847 In addition to operating on files themselves, XEmacs Lisp programs
848 often need to operate on the names; i.e., to take them apart and to use
849 part of a name to construct related file names. This section describes
850 how to manipulate file names.
852 The functions in this section do not actually access files, so they
853 can operate on file names that do not refer to an existing file or
856 On VMS, all these functions understand both VMS file-name syntax and
857 Unix syntax. This is so that all the standard Lisp libraries can
858 specify file names in Unix syntax and work properly on VMS without
859 change. On MS-DOS, these functions understand MS-DOS file-name syntax
860 as well as Unix syntax.
864 * File Name Components:: The directory part of a file name, and the rest.
865 * Directory Names:: A directory's name as a directory
866 is different from its name as a file.
867 * Relative File Names:: Some file names are relative to a current directory.
868 * File Name Expansion:: Converting relative file names to absolute ones.
869 * Unique File Names:: Generating names for temporary files.
870 * File Name Completion:: Finding the completions for a given file name.
871 * User Name Completion:: Finding the completions for a given user name.
874 File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
879 The operating system groups files into directories. To specify a
880 file, you must specify the directory and the file's name within that
881 directory. Therefore, XEmacs considers a file name as having two main
882 parts: the "directory name" part, and the "nondirectory" part (or "file
883 name within the directory"). Either part may be empty. Concatenating
884 these two parts reproduces the original file name.
886 On Unix, the directory part is everything up to and including the
887 last slash; the nondirectory part is the rest. The rules in VMS syntax
890 For some purposes, the nondirectory part is further subdivided into
891 the name proper and the "version number". On Unix, only backup files
892 have version numbers in their names; on VMS, every file has a version
893 number, but most of the time the file name actually used in XEmacs
894 omits the version number. Version numbers are found mostly in
897 - Function: file-name-directory filename
898 This function returns the directory part of FILENAME (or `nil' if
899 FILENAME does not include a directory part). On Unix, the
900 function returns a string ending in a slash. On VMS, it returns a
901 string ending in one of the three characters `:', `]', or `>'.
903 (file-name-directory "lewis/foo") ; Unix example
905 (file-name-directory "foo") ; Unix example
907 (file-name-directory "[X]FOO.TMP") ; VMS example
910 - Function: file-name-nondirectory filename
911 This function returns the nondirectory part of FILENAME.
913 (file-name-nondirectory "lewis/foo")
915 (file-name-nondirectory "foo")
917 ;; The following example is accurate only on VMS.
918 (file-name-nondirectory "[X]FOO.TMP")
921 - Function: file-name-sans-versions filename &optional
923 This function returns FILENAME without any file version numbers,
924 backup version numbers, or trailing tildes.
926 If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
927 version numbers, only true file version numbers.
929 (file-name-sans-versions "~rms/foo.~1~")
931 (file-name-sans-versions "~rms/foo~")
933 (file-name-sans-versions "~rms/foo")
935 ;; The following example applies to VMS only.
936 (file-name-sans-versions "foo;23")
939 - Function: file-name-sans-extension filename
940 This function returns FILENAME minus its "extension," if any. The
941 extension, in a file name, is the part that starts with the last
942 `.' in the last name component. For example,
944 (file-name-sans-extension "foo.lose.c")
946 (file-name-sans-extension "big.hack/foo")
950 File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
955 A "directory name" is the name of a directory. A directory is a
956 kind of file, and it has a file name, which is related to the directory
957 name but not identical to it. (This is not quite the same as the usual
958 Unix terminology.) These two different names for the same entity are
959 related by a syntactic transformation. On Unix, this is simple: a
960 directory name ends in a slash, whereas the directory's name as a file
961 lacks that slash. On VMS, the relationship is more complicated.
963 The difference between a directory name and its name as a file is
964 subtle but crucial. When an XEmacs variable or function argument is
965 described as being a directory name, a file name of a directory is not
968 The following two functions convert between directory names and file
969 names. They do nothing special with environment variable substitutions
970 such as `$HOME', and the constructs `~', and `..'.
972 - Function: file-name-as-directory filename
973 This function returns a string representing FILENAME in a form
974 that the operating system will interpret as the name of a
975 directory. In Unix, this means appending a slash to the string.
976 On VMS, the function converts a string of the form `[X]Y.DIR.1' to
979 (file-name-as-directory "~rms/lewis")
982 - Function: directory-file-name dirname
983 This function returns a string representing DIRNAME in a form that
984 the operating system will interpret as the name of a file. On
985 Unix, this means removing a final slash from the string. On VMS,
986 the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
988 (directory-file-name "~lewis/")
991 Directory name abbreviations are useful for directories that are
992 normally accessed through symbolic links. Sometimes the users recognize
993 primarily the link's name as "the name" of the directory, and find it
994 annoying to see the directory's "real" name. If you define the link
995 name as an abbreviation for the "real" name, XEmacs shows users the
996 abbreviation instead.
998 If you wish to convert a directory name to its abbreviation, use this
1001 - Function: abbreviate-file-name dirname &optional hack-homedir
1002 This function applies abbreviations from `directory-abbrev-alist'
1003 to its argument, and substitutes `~' for the user's home directory.
1005 If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
1006 the user's home directory.
1009 - Variable: directory-abbrev-alist
1010 The variable `directory-abbrev-alist' contains an alist of
1011 abbreviations to use for file directories. Each element has the
1012 form `(FROM . TO)', and says to replace FROM with TO when it
1013 appears in a directory name. The FROM string is actually a
1014 regular expression; it should always start with `^'. The function
1015 `abbreviate-file-name' performs these substitutions.
1017 You can set this variable in `site-init.el' to describe the
1018 abbreviations appropriate for your site.
1020 Here's an example, from a system on which file system `/home/fsf'
1021 and so on are normally accessed through symbolic links named `/fsf'
1024 (("^/home/fsf" . "/fsf")
1025 ("^/home/gp" . "/gp")
1026 ("^/home/gd" . "/gd"))
1029 File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
1031 Absolute and Relative File Names
1032 --------------------------------
1034 All the directories in the file system form a tree starting at the
1035 root directory. A file name can specify all the directory names
1036 starting from the root of the tree; then it is called an "absolute"
1037 file name. Or it can specify the position of the file in the tree
1038 relative to a default directory; then it is called a "relative" file
1039 name. On Unix, an absolute file name starts with a slash or a tilde
1040 (`~'), and a relative one does not. The rules on VMS are complicated.
1042 - Function: file-name-absolute-p filename
1043 This function returns `t' if file FILENAME is an absolute file
1044 name, `nil' otherwise. On VMS, this function understands both
1045 Unix syntax and VMS syntax.
1047 (file-name-absolute-p "~rms/foo")
1049 (file-name-absolute-p "rms/foo")
1051 (file-name-absolute-p "/user/rms/foo")
1055 File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
1057 Functions that Expand Filenames
1058 -------------------------------
1060 "Expansion" of a file name means converting a relative file name to
1061 an absolute one. Since this is done relative to a default directory,
1062 you must specify the default directory name as well as the file name to
1063 be expanded. Expansion also simplifies file names by eliminating
1064 redundancies such as `./' and `NAME/../'.
1066 - Function: expand-file-name filename &optional directory
1067 This function converts FILENAME to an absolute file name. If
1068 DIRECTORY is supplied, it is the directory to start with if
1069 FILENAME is relative. (The value of DIRECTORY should itself be an
1070 absolute directory name; it may start with `~'.) Otherwise, the
1071 current buffer's value of `default-directory' is used. For
1074 (expand-file-name "foo")
1075 => "/xcssun/users/rms/lewis/foo"
1076 (expand-file-name "../foo")
1077 => "/xcssun/users/rms/foo"
1078 (expand-file-name "foo" "/usr/spool/")
1080 (expand-file-name "$HOME/foo")
1081 => "/xcssun/users/rms/lewis/$HOME/foo"
1083 Filenames containing `.' or `..' are simplified to their canonical
1086 (expand-file-name "bar/../foo")
1087 => "/xcssun/users/rms/lewis/foo"
1089 `~/' at the beginning is expanded into the user's home directory.
1090 A `/' or `~' following a `/'.
1092 Note that `expand-file-name' does _not_ expand environment
1093 variables; only `substitute-in-file-name' does that.
1095 - Function: file-relative-name filename &optional directory
1096 This function does the inverse of expansion--it tries to return a
1097 relative name that is equivalent to FILENAME when interpreted
1098 relative to DIRECTORY.
1100 If DIRECTORY is `nil' or omitted, the value of `default-directory'
1103 (file-relative-name "/foo/bar" "/foo/")
1105 (file-relative-name "/foo/bar" "/hack/")
1108 - Variable: default-directory
1109 The value of this buffer-local variable is the default directory
1110 for the current buffer. It should be an absolute directory name;
1111 it may start with `~'. This variable is local in every buffer.
1113 `expand-file-name' uses the default directory when its second
1116 On Unix systems, the value is always a string ending with a slash.
1119 => "/user/lewis/manual/"
1121 - Function: substitute-in-file-name filename
1122 This function replaces environment variable references in FILENAME
1123 with the environment variable values. Following standard Unix
1124 shell syntax, `$' is the prefix to substitute an environment
1127 The environment variable name is the series of alphanumeric
1128 characters (including underscores) that follow the `$'. If the
1129 character following the `$' is a `{', then the variable name is
1130 everything up to the matching `}'.
1132 Here we assume that the environment variable `HOME', which holds
1133 the user's home directory name, has value `/xcssun/users/rms'.
1135 (substitute-in-file-name "$HOME/foo")
1136 => "/xcssun/users/rms/foo"
1138 After substitution, a `/' or `~' following a `/' is taken to be
1139 the start of an absolute file name that overrides what precedes
1140 it, so everything before that `/' or `~' is deleted. For example:
1142 (substitute-in-file-name "bar/~/foo")
1144 (substitute-in-file-name "/usr/local/$HOME/foo")
1145 => "/xcssun/users/rms/foo"
1147 On VMS, `$' substitution is not done, so this function does nothing
1148 on VMS except discard superfluous initial components as shown
1152 File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
1154 Generating Unique File Names
1155 ----------------------------
1157 Some programs need to write temporary files. Here is the usual way
1158 to construct a name for such a file:
1160 (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
1162 Here we use `(temp-directory)' to specify a directory for temporary
1163 files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
1164 `make-temp-name' is to prevent two different users or two different
1165 processes from trying to use the same name.
1167 - Function: temp-directory
1168 This function returns the name of the directory to use for
1169 temporary files. Under Unix, this will be the value of `TMPDIR',
1170 defaulting to `/tmp'. On Windows, this will be obtained from the
1171 `TEMP' or `TMP' environment variables, defaulting to `/'.
1173 Note that the `temp-directory' function does not exist under FSF
1176 - Function: make-temp-name prefix
1177 This function generates a temporary file name starting with
1178 PREFIX. The Emacs process number forms part of the result, so
1179 there is no danger of generating a name being used by another
1182 (make-temp-name "/tmp/foo")
1185 In addition, this function makes an attempt to choose a name that
1186 does not specify an existing file. To make this work, PREFIX
1187 should be an absolute file name.
1189 To avoid confusion, each Lisp application should preferably use a
1190 unique PREFIX to `make-temp-name'.
1193 File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
1195 File Name Completion
1196 --------------------
1198 This section describes low-level subroutines for completing a file
1199 name. For other completion functions, see *Note Completion::.
1201 - Function: file-name-all-completions partial-filename directory
1202 This function returns a list of all possible completions for a file
1203 whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
1204 The order of the completions is the order of the files in the
1205 directory, which is unpredictable and conveys no useful
1208 The argument PARTIAL-FILENAME must be a file name containing no
1209 directory part and no slash. The current buffer's default
1210 directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
1212 In the following example, suppose that the current default
1213 directory, `~rms/lewis', has five files whose names begin with `f':
1214 `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
1216 (file-name-all-completions "f" "")
1217 => ("foo" "file~" "file.c.~2~"
1218 "file.c.~1~" "file.c")
1220 (file-name-all-completions "fo" "")
1223 - Function: file-name-completion filename directory
1224 This function completes the file name FILENAME in directory
1225 DIRECTORY. It returns the longest prefix common to all file names
1226 in directory DIRECTORY that start with FILENAME.
1228 If only one match exists and FILENAME matches it exactly, the
1229 function returns `t'. The function returns `nil' if directory
1230 DIRECTORY contains no name starting with FILENAME.
1232 In the following example, suppose that the current default
1233 directory has five files whose names begin with `f': `foo',
1234 `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
1236 (file-name-completion "fi" "")
1239 (file-name-completion "file.c.~1" "")
1242 (file-name-completion "file.c.~1~" "")
1245 (file-name-completion "file.c.~3" "")
1248 - User Option: completion-ignored-extensions
1249 `file-name-completion' usually ignores file names that end in any
1250 string in this list. It does not ignore them when all the possible
1251 completions end in one of these suffixes or when a buffer showing
1252 all possible completions is displayed.
1254 A typical value might look like this:
1256 completion-ignored-extensions
1257 => (".o" ".elc" "~" ".dvi")
projects / chise / xemacs-chise.git- / blob