1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
55 Substituting Key Bindings in Documentation
56 ==========================================
58 When documentation strings refer to key sequences, they should use
59 the current, actual key bindings. They can do so using certain special
60 text sequences described below. Accessing documentation strings in the
61 usual way substitutes current key binding information for these special
62 sequences. This works by calling `substitute-command-keys'. You can
63 also call that function yourself.
65 Here is a list of the special sequences and what they mean:
68 stands for a key sequence that will invoke COMMAND, or `M-x
69 COMMAND' if COMMAND has no key bindings.
72 stands for a summary of the value of MAPVAR, which should be a
73 keymap. The summary is made by `describe-bindings'.
76 stands for no text itself. It is used for a side effect: it
77 specifies MAPVAR as the keymap for any following `\[COMMAND]'
78 sequences in this documentation string.
81 quotes the following character and is discarded; this `\=\=' puts
82 `\=' into the output, and `\=\[' puts `\[' into the output.
84 *Please note:* Each `\' must be doubled when written in a string in
87 - Function: substitute-command-keys STRING
88 This function scans STRING for the above special sequences and
89 replaces them by what they stand for, returning the result as a
90 string. This permits display of documentation that refers
91 accurately to the user's own customized key bindings.
93 Here are examples of the special sequences:
95 (substitute-command-keys
96 "To abort recursive edit, type: \\[abort-recursive-edit]")
97 => "To abort recursive edit, type: C-]"
99 (substitute-command-keys
100 "The keys that are defined for the minibuffer here are:
101 \\{minibuffer-local-must-match-map}")
102 => "The keys that are defined for the minibuffer here are:
104 ? minibuffer-completion-help
105 SPC minibuffer-complete-word
106 TAB minibuffer-complete
107 LFD minibuffer-complete-and-exit
108 RET minibuffer-complete-and-exit
109 C-g abort-recursive-edit
111 (substitute-command-keys
112 "To abort a recursive edit from the minibuffer, type\
113 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
114 => "To abort a recursive edit from the minibuffer, type C-g."
116 (substitute-command-keys
117 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
118 \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
119 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
120 as the keymap for future \\=\\[COMMAND] substrings.
121 \\=\\= quotes the following character and is discarded;
122 thus, \\=\\=\\=\\= puts \\=\\= into the output,
123 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
124 => "Substrings of the form \{MAPVAR} are replaced by summaries
125 (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
126 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
127 as the keymap for future \[COMMAND] substrings.
128 \= quotes the following character and is discarded;
129 thus, \=\= puts \= into the output,
130 and \=\[ puts \[ into the output."
133 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
135 Describing Characters for Help Messages
136 =======================================
138 These functions convert events, key sequences or characters to
139 textual descriptions. These descriptions are useful for including
140 arbitrary text characters or key sequences in messages, because they
141 convert non-printing and whitespace characters to sequences of printing
142 characters. The description of a non-whitespace printing character is
143 the character itself.
145 - Function: key-description SEQUENCE
146 This function returns a string containing the XEmacs standard
147 notation for the input events in SEQUENCE. The argument SEQUENCE
148 may be a string, vector or list. *Note Events::, for more
149 information about valid events. See also the examples for
150 `single-key-description', below.
152 - Function: single-key-description KEY
153 This function returns a string describing KEY in the standard
154 XEmacs notation for keyboard input. A normal printing character
155 appears as itself, but a control character turns into a string
156 starting with `C-', a meta character turns into a string starting
157 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
158 A symbol appears as the name of the symbol. An event that is a
159 list appears as the name of the symbol in the CAR of the list.
161 (single-key-description ?\C-x)
164 (key-description "\C-x \M-y \n \t \r \f123")
165 => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
167 (single-key-description 'kp_next)
170 (single-key-description '(shift button1))
173 - Function: text-char-description CHARACTER
174 This function returns a string describing CHARACTER in the
175 standard XEmacs notation for characters that appear in text--like
176 `single-key-description', except that control characters are
177 represented with a leading caret (which is how control characters
178 in XEmacs buffers are usually displayed).
180 (text-char-description ?\C-c)
183 (text-char-description ?\M-m)
186 (text-char-description ?\C-\M-m)
190 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
195 XEmacs provides a variety of on-line help functions, all accessible
196 to the user as subcommands of the prefix `C-h', or on some keyboards,
197 `help'. For more information about them, see *Note Help: (emacs)Help.
198 Here we describe some program-level interfaces to the same information.
200 - Command: apropos REGEXP &optional DO-ALL PREDICATE
201 This function finds all symbols whose names contain a match for the
202 regular expression REGEXP, and returns a list of them (*note
203 Regular Expressions::.). It also displays the symbols in a buffer
204 named `*Help*', each with a one-line description.
206 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
207 the functions that are found.
209 If PREDICATE is non-`nil', it should be a function to be called on
210 each symbol that has matched REGEXP. Only symbols for which
211 PREDICATE returns a non-`nil' value are listed or displayed.
213 In the first of the following examples, `apropos' finds all the
214 symbols with names containing `exec'. In the second example, it
215 finds and returns only those symbols that are also commands. (We
216 don't show the output that results in the `*Help*' buffer.)
219 => (Buffer-menu-execute command-execute exec-directory
220 exec-path execute-extended-command execute-kbd-macro
221 executing-kbd-macro executing-macro)
223 (apropos "exec" nil 'commandp)
224 => (Buffer-menu-execute execute-extended-command)
226 `apropos' is used by various user-level commands, such as `C-h a'
227 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
228 (`command-apropos'), which does an apropos over only those
229 functions which are user commands. `command-apropos' calls
230 `apropos', specifying a PREDICATE to restrict the output to
231 symbols that are commands. The call to `apropos' looks like this:
233 (apropos string t 'commandp)
236 The value of this variable is a local keymap for characters
237 following the Help key, `C-h'.
239 - Prefix Command: help-command
240 This symbol is not a function; its function definition is actually
241 the keymap known as `help-map'. It is defined in `help.el' as
244 (define-key global-map "\C-h" 'help-command)
245 (fset 'help-command help-map)
247 - Function: print-help-return-message &optional FUNCTION
248 This function builds a string that explains how to restore the
249 previous state of the windows after a help command. After
250 building the message, it applies FUNCTION to it if FUNCTION is
251 non-`nil'. Otherwise it calls `message' to display it in the echo
254 This function expects to be called inside a
255 `with-output-to-temp-buffer' special form, and expects
256 `standard-output' to have the value bound by that special form.
257 For an example of its use, see the long example in *Note Accessing
260 - Variable: help-char
261 The value of this variable is the help character--the character
262 that XEmacs recognizes as meaning Help. By default, it is the
263 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
264 character, if `help-form' is non-`nil' Lisp expression, it
265 evaluates that expression, and displays the result in a window if
268 `help-char' can be a character or a key description such as `help'
271 Usually the value of `help-form''s value is `nil'. Then the help
272 character has no special meaning at the level of command input, and
273 it becomes part of a key sequence in the normal way. The standard
274 key binding of `C-h' is a prefix key for several general-purpose
277 The help character is special after prefix keys, too. If it has no
278 binding as a subcommand of the prefix key, it runs
279 `describe-prefix-bindings', which displays a list of all the
280 subcommands of the prefix key.
282 - Variable: help-form
283 If this variable is non-`nil', its value is a form to evaluate
284 whenever the character `help-char' is read. If evaluating the form
285 produces a string, that string is displayed.
287 A command that calls `next-command-event' or `next-event' probably
288 should bind `help-form' to a non-`nil' expression while it does
289 input. (The exception is when `C-h' is meaningful input.)
290 Evaluating this expression should result in a string that explains
291 what the input is for and how to enter it properly.
293 Entry to the minibuffer binds this variable to the value of
294 `minibuffer-help-form' (*note Minibuffer Misc::.).
296 - Variable: prefix-help-command
297 This variable holds a function to print help for a prefix
298 character. The function is called when the user types a prefix
299 key followed by the help character, and the help character has no
300 binding after that prefix. The variable's default value is
301 `describe-prefix-bindings'.
303 - Function: describe-prefix-bindings
304 This function calls `describe-bindings' to display a list of all
305 the subcommands of the prefix key of the most recent key sequence.
306 The prefix described consists of all but the last event of that
307 key sequence. (The last event is, presumably, the help character.)
309 The following two functions are found in the library `helper'. They
310 are for modes that want to provide help without relinquishing control,
311 such as the "electric" modes. You must load that library with
312 `(require 'helper)' in order to use them. Their names begin with
313 `Helper' to distinguish them from the ordinary help functions.
315 - Command: Helper-describe-bindings
316 This command pops up a window displaying a help buffer containing a
317 listing of all of the key bindings from both the local and global
318 keymaps. It works by calling `describe-bindings'.
320 - Command: Helper-help
321 This command provides help for the current mode. It prompts the
322 user in the minibuffer with the message `Help (Type ? for further
323 options)', and then provides assistance in finding out what the key
324 bindings are, and what the mode is intended for. It returns `nil'.
326 This can be customized by changing the map `Helper-help-map'.
329 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
334 As you add functionality to a package, you may at times want to
335 replace an older function with a new one. To preserve compatibility
336 with existing code, the older function needs to still exist; but users
337 of that function should be told to use the newer one instead. XEmacs
338 Lisp lets you mark a function or variable as "obsolete", and indicate
339 what should be used instead.
341 - Function: make-obsolete FUNCTION NEW
342 This function indicates that FUNCTION is an obsolete function, and
343 the function NEW should be used instead. The byte compiler will
344 issue a warning to this effect when it encounters a usage of the
345 older function, and the help system will also note this in the
346 function's documentation. NEW can also be a string (if there is
347 not a single function with the same functionality any more), and
348 should be a descriptive statement, such as "use FOO or BAR
349 instead" or "this function is unnecessary".
351 - Function: make-obsolete-variable VARIABLE NEW
352 This is like `make-obsolete' but is for variables instead of
355 - Function: define-obsolete-function-alias OLDFUN NEWFUN
356 This function combines `make-obsolete' and `define-function',
357 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
358 OLDFUN as an alias for NEWFUN.
360 - Function: define-obsolete-variable-alias OLDVAR NEWVAR
361 This is like `define-obsolete-function-alias' but for variables.
363 Note that you should not normally put obsoleteness information
364 explicitly in a function or variable's doc string. The obsoleteness
365 information that you specify using the above functions will be displayed
366 whenever the doc string is displayed, and by adding it explicitly the
367 result is redundancy.
369 Also, if an obsolete function is substantially the same as a newer
370 one but is not actually an alias, you should consider omitting the doc
371 string entirely (use a null string `""' as the doc string). That way,
372 the user is told about the obsoleteness and is forced to look at the
373 documentation of the new function, making it more likely that he will
374 use the new function.
376 - Function: function-obsoleteness-doc FUNCTION
377 If FUNCTION is obsolete, this function returns a string describing
378 this. This is the message that is printed out during byte
379 compilation or in the function's documentation. If FUNCTION is
380 not obsolete, `nil' is returned.
382 - Function: variable-obsoleteness-doc VARIABLE
383 This is like `function-obsoleteness-doc' but for variables.
385 The obsoleteness information is stored internally by putting a
386 property `byte-obsolete-info' (for functions) or
387 `byte-obsolete-variable' (for variables) on the symbol that specifies
388 the obsolete function or variable. For more information, see the
389 implementation of `make-obsolete' and `make-obsolete-variable' in
390 `lisp/bytecomp/bytecomp-runtime.el'.
393 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
398 In XEmacs, you can find, create, view, save, and otherwise work with
399 files and file directories. This chapter describes most of the
400 file-related functions of XEmacs Lisp, but a few others are described in
401 *Note Buffers::, and those related to backups and auto-saving are
402 described in *Note Backups and Auto-Saving::.
404 Many of the file functions take one or more arguments that are file
405 names. A file name is actually a string. Most of these functions
406 expand file name arguments using `expand-file-name', so that `~' is
407 handled correctly, as are relative file names (including `../'). These
408 functions don't recognize environment variable substitutions such as
409 `$HOME'. *Note File Name Expansion::.
413 * Visiting Files:: Reading files into Emacs buffers for editing.
414 * Saving Buffers:: Writing changed buffers back into files.
415 * Reading from Files:: Reading files into buffers without visiting.
416 * Writing to Files:: Writing new files from parts of buffers.
417 * File Locks:: Locking and unlocking files, to prevent
418 simultaneous editing by two people.
419 * Information about Files:: Testing existence, accessibility, size of files.
420 * Changing File Attributes:: Renaming files, changing protection, etc.
421 * File Names:: Decomposing and expanding file names.
422 * Contents of Directories:: Getting a list of the files in a directory.
423 * Create/Delete Dirs:: Creating and Deleting Directories.
424 * Magic File Names:: Defining "magic" special handling
425 for certain file names.
426 * Partial Files:: Treating a section of a buffer as a file.
427 * Format Conversion:: Conversion to and from various file formats.
428 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
431 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
436 Visiting a file means reading a file into a buffer. Once this is
437 done, we say that the buffer is "visiting" that file, and call the file
438 "the visited file" of the buffer.
440 A file and a buffer are two different things. A file is information
441 recorded permanently in the computer (unless you delete it). A buffer,
442 on the other hand, is information inside of XEmacs that will vanish at
443 the end of the editing session (or when you kill the buffer). Usually,
444 a buffer contains information that you have copied from a file; then we
445 say the buffer is visiting that file. The copy in the buffer is what
446 you modify with editing commands. Such changes to the buffer do not
447 change the file; therefore, to make the changes permanent, you must
448 "save" the buffer, which means copying the altered buffer contents back
451 In spite of the distinction between files and buffers, people often
452 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
453 "I am editing a file," rather than, "I am editing a buffer that I will
454 soon save as a file of the same name." Humans do not usually need to
455 make the distinction explicit. When dealing with a computer program,
456 however, it is good to keep the distinction in mind.
460 * Visiting Functions:: The usual interface functions for visiting.
461 * Subroutines of Visiting:: Lower-level subroutines that they use.
464 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
466 Functions for Visiting Files
467 ----------------------------
469 This section describes the functions normally used to visit files.
470 For historical reasons, these functions have names starting with
471 `find-' rather than `visit-'. *Note Buffer File Name::, for functions
472 and variables that access the visited file name of a buffer or that
473 find an existing buffer by its visited file name.
475 In a Lisp program, if you want to look at the contents of a file but
476 not alter it, the fastest way is to use `insert-file-contents' in a
477 temporary buffer. Visiting the file is not necessary and takes longer.
478 *Note Reading from Files::.
480 - Command: find-file FILENAME
481 This command selects a buffer visiting the file FILENAME, using an
482 existing buffer if there is one, and otherwise creating a new
483 buffer and reading the file into it. It also returns that buffer.
485 The body of the `find-file' function is very simple and looks like
488 (switch-to-buffer (find-file-noselect filename))
490 (See `switch-to-buffer' in *Note Displaying Buffers::.)
492 When `find-file' is called interactively, it prompts for FILENAME
495 - Function: find-file-noselect FILENAME &optional NOWARN
496 This function is the guts of all the file-visiting functions. It
497 finds or creates a buffer visiting the file FILENAME, and returns
498 it. It uses an existing buffer if there is one, and otherwise
499 creates a new buffer and reads the file into it. You may make the
500 buffer current or display it in a window if you wish, but this
501 function does not do so.
503 When `find-file-noselect' uses an existing buffer, it first
504 verifies that the file has not changed since it was last visited or
505 saved in that buffer. If the file has changed, then this function
506 asks the user whether to reread the changed file. If the user says
507 `yes', any changes previously made in the buffer are lost.
509 If `find-file-noselect' needs to create a buffer, and there is no
510 file named FILENAME, it displays the message `New file' in the
511 echo area, and leaves the buffer empty.
513 If NO-WARN is non-`nil', various warnings that XEmacs normally
514 gives (e.g. if another buffer is already visiting FILENAME but
515 FILENAME has been removed from disk since that buffer was created)
518 The `find-file-noselect' function calls `after-find-file' after
519 reading the file (*note Subroutines of Visiting::.). That function
520 sets the buffer major mode, parses local variables, warns the user
521 if there exists an auto-save file more recent than the file just
522 visited, and finishes by running the functions in
525 The `find-file-noselect' function returns the buffer that is
526 visiting the file FILENAME.
528 (find-file-noselect "/etc/fstab")
531 - Command: find-file-other-window FILENAME
532 This command selects a buffer visiting the file FILENAME, but does
533 so in a window other than the selected window. It may use another
534 existing window or split a window; see *Note Displaying Buffers::.
536 When this command is called interactively, it prompts for FILENAME.
538 - Command: find-file-read-only FILENAME
539 This command selects a buffer visiting the file FILENAME, like
540 `find-file', but it marks the buffer as read-only. *Note Read
541 Only Buffers::, for related functions and variables.
543 When this command is called interactively, it prompts for FILENAME.
545 - Command: view-file FILENAME
546 This command visits FILENAME in View mode, and displays it in a
547 recursive edit, returning to the previous buffer when done. View
548 mode is a mode that allows you to skim rapidly through the file
549 but does not let you modify it. Entering View mode runs the
550 normal hook `view-mode-hook'. *Note Hooks::.
552 When `view-file' is called interactively, it prompts for FILENAME.
554 - Variable: find-file-hooks
555 The value of this variable is a list of functions to be called
556 after a file is visited. The file's local-variables specification
557 (if any) will have been processed before the hooks are run. The
558 buffer visiting the file is current when the hook functions are
561 This variable works just like a normal hook, but we think that
562 renaming it would not be advisable.
564 - Variable: find-file-not-found-hooks
565 The value of this variable is a list of functions to be called when
566 `find-file' or `find-file-noselect' is passed a nonexistent file
567 name. `find-file-noselect' calls these functions as soon as it
568 detects a nonexistent file. It calls them in the order of the
569 list, until one of them returns non-`nil'. `buffer-file-name' is
572 This is not a normal hook because the values of the functions are
573 used and they may not all be called.
576 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
578 Subroutines of Visiting
579 -----------------------
581 The `find-file-noselect' function uses the `create-file-buffer' and
582 `after-find-file' functions as subroutines. Sometimes it is useful to
585 - Function: create-file-buffer FILENAME
586 This function creates a suitably named buffer for visiting
587 FILENAME, and returns it. It uses FILENAME (sans directory) as
588 the name if that name is free; otherwise, it appends a string such
589 as `<2>' to get an unused name. See also *Note Creating Buffers::.
591 *Please note:* `create-file-buffer' does *not* associate the new
592 buffer with a file and does not select the buffer. It also does
593 not use the default major mode.
595 (create-file-buffer "foo")
597 (create-file-buffer "foo")
599 (create-file-buffer "foo")
602 This function is used by `find-file-noselect'. It uses
603 `generate-new-buffer' (*note Creating Buffers::.).
605 - Function: after-find-file &optional ERROR WARN NOAUTO
606 This function sets the buffer major mode, and parses local
607 variables (*note Auto Major Mode::.). It is called by
608 `find-file-noselect' and by the default revert function (*note
611 If reading the file got an error because the file does not exist,
612 but its directory does exist, the caller should pass a non-`nil'
613 value for ERROR. In that case, `after-find-file' issues a warning:
614 `(New File)'. For more serious errors, the caller should usually
615 not call `after-find-file'.
617 If WARN is non-`nil', then this function issues a warning if an
618 auto-save file exists and is more recent than the visited file.
620 If NOAUTO is non-`nil', then this function does not turn on
621 auto-save mode; otherwise, it does.
623 The last thing `after-find-file' does is call all the functions in
627 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
632 When you edit a file in XEmacs, you are actually working on a buffer
633 that is visiting that file--that is, the contents of the file are
634 copied into the buffer and the copy is what you edit. Changes to the
635 buffer do not change the file until you "save" the buffer, which means
636 copying the contents of the buffer into the file.
638 - Command: save-buffer &optional BACKUP-OPTION
639 This function saves the contents of the current buffer in its
640 visited file if the buffer has been modified since it was last
641 visited or saved. Otherwise it does nothing.
643 `save-buffer' is responsible for making backup files. Normally,
644 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
645 if this is the first save since visiting the file. Other values
646 for BACKUP-OPTION request the making of backup files in other
649 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
650 `save-buffer' function marks this version of the file to be
651 backed up when the buffer is next saved.
653 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
654 `save-buffer' function unconditionally backs up the previous
655 version of the file before saving it.
657 - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
658 This command saves some modified file-visiting buffers. Normally
659 it asks the user about each buffer. But if SAVE-SILENTLY-P is
660 non-`nil', it saves all the file-visiting buffers without querying
663 The optional EXITING argument, if non-`nil', requests this
664 function to offer also to save certain other buffers that are not
665 visiting files. These are buffers that have a non-`nil' local
666 value of `buffer-offer-save'. (A user who says yes to saving one
667 of these is asked to specify a file name to use.) The
668 `save-buffers-kill-emacs' function passes a non-`nil' value for
671 - Variable: buffer-offer-save
672 When this variable is non-`nil' in a buffer, XEmacs offers to save
673 the buffer on exit even if the buffer is not visiting a file. The
674 variable is automatically local in all buffers. Normally, Mail
675 mode (used for editing outgoing mail) sets this to `t'.
677 - Command: write-file FILENAME
678 This function writes the current buffer into file FILENAME, makes
679 the buffer visit that file, and marks it not modified. Then it
680 renames the buffer based on FILENAME, appending a string like `<2>'
681 if necessary to make a unique buffer name. It does most of this
682 work by calling `set-visited-file-name' and `save-buffer'.
684 - Variable: write-file-hooks
685 The value of this variable is a list of functions to be called
686 before writing out a buffer to its visited file. If one of them
687 returns non-`nil', the file is considered already written and the
688 rest of the functions are not called, nor is the usual code for
689 writing the file executed.
691 If a function in `write-file-hooks' returns non-`nil', it is
692 responsible for making a backup file (if that is appropriate). To
693 do so, execute the following code:
695 (or buffer-backed-up (backup-buffer))
697 You might wish to save the file modes value returned by
698 `backup-buffer' and use that to set the mode bits of the file that
699 you write. This is what `save-buffer' normally does.
701 Even though this is not a normal hook, you can use `add-hook' and
702 `remove-hook' to manipulate the list. *Note Hooks::.
704 - Variable: local-write-file-hooks
705 This works just like `write-file-hooks', but it is intended to be
706 made local to particular buffers. It's not a good idea to make
707 `write-file-hooks' local to a buffer--use this variable instead.
709 The variable is marked as a permanent local, so that changing the
710 major mode does not alter a buffer-local value. This is
711 convenient for packages that read "file" contents in special ways,
712 and set up hooks to save the data in a corresponding way.
714 - Variable: write-contents-hooks
715 This works just like `write-file-hooks', but it is intended for
716 hooks that pertain to the contents of the file, as opposed to
717 hooks that pertain to where the file came from. Such hooks are
718 usually set up by major modes, as buffer-local bindings for this
719 variable. Switching to a new major mode always resets this
722 - Variable: after-save-hook
723 This normal hook runs after a buffer has been saved in its visited
726 - Variable: file-precious-flag
727 If this variable is non-`nil', then `save-buffer' protects against
728 I/O errors while saving by writing the new file to a temporary
729 name instead of the name it is supposed to have, and then renaming
730 it to the intended name after it is clear there are no errors.
731 This procedure prevents problems such as a lack of disk space from
732 resulting in an invalid file.
734 As a side effect, backups are necessarily made by copying. *Note
735 Rename or Copy::. Yet, at the same time, saving a precious file
736 always breaks all hard links between the file you save and other
739 Some modes set this variable non-`nil' locally in particular
742 - User Option: require-final-newline
743 This variable determines whether files may be written out that do
744 *not* end with a newline. If the value of the variable is `t',
745 then `save-buffer' silently adds a newline at the end of the file
746 whenever the buffer being saved does not already end in one. If
747 the value of the variable is non-`nil', but not `t', then
748 `save-buffer' asks the user whether to add a newline each time the
751 If the value of the variable is `nil', then `save-buffer' doesn't
752 add newlines at all. `nil' is the default value, but a few major
753 modes set it to `t' in particular buffers.
756 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
761 You can copy a file from the disk and insert it into a buffer using
762 the `insert-file-contents' function. Don't use the user-level command
763 `insert-file' in a Lisp program, as that sets the mark.
765 - Function: insert-file-contents FILENAME &optional VISIT BEG END
767 This function inserts the contents of file FILENAME into the
768 current buffer after point. It returns a list of the absolute
769 file name and the length of the data inserted. An error is
770 signaled if FILENAME is not the name of a file that can be read.
772 The function `insert-file-contents' checks the file contents
773 against the defined file formats, and converts the file contents if
774 appropriate. *Note Format Conversion::. It also calls the
775 functions in the list `after-insert-file-functions'; see *Note
778 If VISIT is non-`nil', this function additionally marks the buffer
779 as unmodified and sets up various fields in the buffer so that it
780 is visiting the file FILENAME: these include the buffer's visited
781 file name and its last save file modtime. This feature is used by
782 `find-file-noselect' and you probably should not use it yourself.
784 If BEG and END are non-`nil', they should be integers specifying
785 the portion of the file to insert. In this case, VISIT must be
788 (insert-file-contents filename nil 0 500)
790 inserts the first 500 characters of a file.
792 If the argument REPLACE is non-`nil', it means to replace the
793 contents of the buffer (actually, just the accessible portion)
794 with the contents of the file. This is better than simply
795 deleting the buffer contents and inserting the whole file, because
796 (1) it preserves some marker positions and (2) it puts less data
799 If you want to pass a file name to another process so that another
800 program can read the file, use the function `file-local-copy'; see
801 *Note Magic File Names::.
804 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
809 You can write the contents of a buffer, or part of a buffer, directly
810 to a file on disk using the `append-to-file' and `write-region'
811 functions. Don't use these functions to write to files that are being
812 visited; that could cause confusion in the mechanisms for visiting.
814 - Command: append-to-file START END FILENAME
815 This function appends the contents of the region delimited by
816 START and END in the current buffer to the end of file FILENAME.
817 If that file does not exist, it is created. If that file exists
818 it is overwritten. This function returns `nil'.
820 An error is signaled if FILENAME specifies a nonwritable file, or
821 a nonexistent file in a directory where files cannot be created.
823 - Command: write-region START END FILENAME &optional APPEND VISIT
824 This function writes the region delimited by START and END in the
825 current buffer into the file specified by FILENAME.
827 If START is a string, then `write-region' writes or appends that
828 string, rather than text from the buffer.
830 If APPEND is non-`nil', then the specified text is appended to the
831 existing file contents (if any).
833 If VISIT is `t', then XEmacs establishes an association between
834 the buffer and the file: the buffer is then visiting that file.
835 It also sets the last file modification time for the current
836 buffer to FILENAME's modtime, and marks the buffer as not
837 modified. This feature is used by `save-buffer', but you probably
838 should not use it yourself.
840 If VISIT is a string, it specifies the file name to visit. This
841 way, you can write the data to one file (FILENAME) while recording
842 the buffer as visiting another file (VISIT). The argument VISIT
843 is used in the echo area message and also for file locking; VISIT
844 is stored in `buffer-file-name'. This feature is used to
845 implement `file-precious-flag'; don't use it yourself unless you
846 really know what you're doing.
848 The function `write-region' converts the data which it writes to
849 the appropriate file formats specified by `buffer-file-format'.
850 *Note Format Conversion::. It also calls the functions in the list
851 `write-region-annotate-functions'; see *Note Saving Properties::.
853 Normally, `write-region' displays a message `Wrote file FILENAME'
854 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
855 then this message is inhibited. This feature is useful for
856 programs that use files for internal purposes, files that the user
857 does not need to know about.
860 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
865 When two users edit the same file at the same time, they are likely
866 to interfere with each other. XEmacs tries to prevent this situation
867 from arising by recording a "file lock" when a file is being modified.
868 XEmacs can then detect the first attempt to modify a buffer visiting a
869 file that is locked by another XEmacs process, and ask the user what to
872 File locks do not work properly when multiple machines can share
873 file systems, such as with NFS. Perhaps a better file locking system
874 will be implemented in the future. When file locks do not work, it is
875 possible for two users to make changes simultaneously, but XEmacs can
876 still warn the user who saves second. Also, the detection of
877 modification of a buffer visiting a file changed on disk catches some
878 cases of simultaneous editing; see *Note Modification Time::.
880 - Function: file-locked-p &optional FILENAME
881 This function returns `nil' if the file FILENAME is not locked by
882 this XEmacs process. It returns `t' if it is locked by this
883 XEmacs, and it returns the name of the user who has locked it if it
884 is locked by someone else.
886 (file-locked-p "foo")
889 - Function: lock-buffer &optional FILENAME
890 This function locks the file FILENAME, if the current buffer is
891 modified. The argument FILENAME defaults to the current buffer's
892 visited file. Nothing is done if the current buffer is not
893 visiting a file, or is not modified.
895 - Function: unlock-buffer
896 This function unlocks the file being visited in the current buffer,
897 if the buffer is modified. If the buffer is not modified, then
898 the file should not be locked, so this function does nothing. It
899 also does nothing if the current buffer is not visiting a file.
901 - Function: ask-user-about-lock FILE OTHER-USER
902 This function is called when the user tries to modify FILE, but it
903 is locked by another user named OTHER-USER. The value it returns
904 determines what happens next:
906 * A value of `t' says to grab the lock on the file. Then this
907 user may edit the file and OTHER-USER loses the lock.
909 * A value of `nil' says to ignore the lock and let this user
910 edit the file anyway.
912 * This function may instead signal a `file-locked' error, in
913 which case the change that the user was about to make does
916 The error message for this error looks like this:
918 error--> File is locked: FILE OTHER-USER
920 where `file' is the name of the file and OTHER-USER is the
921 name of the user who has locked the file.
923 The default definition of this function asks the user to choose
924 what to do. If you wish, you can replace the `ask-user-about-lock'
925 function with your own version that decides in another way. The
926 code for its usual definition is in `userlock.el'.
929 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
931 Information about Files
932 =======================
934 The functions described in this section all operate on strings that
935 designate file names. All the functions have names that begin with the
936 word `file'. These functions all return information about actual files
937 or directories, so their arguments must all exist as actual files or
938 directories unless otherwise noted.
942 * Testing Accessibility:: Is a given file readable? Writable?
943 * Kinds of Files:: Is it a directory? A symbolic link?
944 * Truenames:: Eliminating symbolic links from a file name.
945 * File Attributes:: How large is it? Any other names? Etc.
948 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
950 Testing Accessibility
951 ---------------------
953 These functions test for permission to access a file in specific
956 - Function: file-exists-p FILENAME
957 This function returns `t' if a file named FILENAME appears to
958 exist. This does not mean you can necessarily read the file, only
959 that you can find out its attributes. (On Unix, this is true if
960 the file exists and you have execute permission on the containing
961 directories, regardless of the protection of the file itself.)
963 If the file does not exist, or if fascist access control policies
964 prevent you from finding the attributes of the file, this function
967 - Function: file-readable-p FILENAME
968 This function returns `t' if a file named FILENAME exists and you
969 can read it. It returns `nil' otherwise.
971 (file-readable-p "files.texi")
973 (file-exists-p "/usr/spool/mqueue")
975 (file-readable-p "/usr/spool/mqueue")
978 - Function: file-executable-p FILENAME
979 This function returns `t' if a file named FILENAME exists and you
980 can execute it. It returns `nil' otherwise. If the file is a
981 directory, execute permission means you can check the existence and
982 attributes of files inside the directory, and open those files if
985 - Function: file-writable-p FILENAME
986 This function returns `t' if the file FILENAME can be written or
987 created by you, and `nil' otherwise. A file is writable if the
988 file exists and you can write it. It is creatable if it does not
989 exist, but the specified directory does exist and you can write in
992 In the third example below, `foo' is not writable because the
993 parent directory does not exist, even though the user could create
996 (file-writable-p "~/foo")
998 (file-writable-p "/foo")
1000 (file-writable-p "~/no-such-dir/foo")
1003 - Function: file-accessible-directory-p DIRNAME
1004 This function returns `t' if you have permission to open existing
1005 files in the directory whose name as a file is DIRNAME; otherwise
1006 (or if there is no such directory), it returns `nil'. The value
1007 of DIRNAME may be either a directory name or the file name of a
1010 Example: after the following,
1012 (file-accessible-directory-p "/foo")
1015 we can deduce that any attempt to read a file in `/foo/' will give
1018 - Function: file-ownership-preserved-p FILENAME
1019 This function returns `t' if deleting the file FILENAME and then
1020 creating it anew would keep the file's owner unchanged.
1022 - Function: file-newer-than-file-p FILENAME1 FILENAME2
1023 This function returns `t' if the file FILENAME1 is newer than file
1024 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
1025 FILENAME2 does not exist, it returns `t'.
1027 In the following example, assume that the file `aug-19' was written
1028 on the 19th, `aug-20' was written on the 20th, and the file
1029 `no-file' doesn't exist at all.
1031 (file-newer-than-file-p "aug-19" "aug-20")
1033 (file-newer-than-file-p "aug-20" "aug-19")
1035 (file-newer-than-file-p "aug-19" "no-file")
1037 (file-newer-than-file-p "no-file" "aug-19")
1040 You can use `file-attributes' to get a file's last modification
1041 time as a list of two numbers. *Note File Attributes::.
1044 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
1046 Distinguishing Kinds of Files
1047 -----------------------------
1049 This section describes how to distinguish various kinds of files,
1050 such as directories, symbolic links, and ordinary files.
1052 - Function: file-symlink-p FILENAME
1053 If the file FILENAME is a symbolic link, the `file-symlink-p'
1054 function returns the file name to which it is linked. This may be
1055 the name of a text file, a directory, or even another symbolic
1056 link, or it may be a nonexistent file name.
1058 If the file FILENAME is not a symbolic link (or there is no such
1059 file), `file-symlink-p' returns `nil'.
1061 (file-symlink-p "foo")
1063 (file-symlink-p "sym-link")
1065 (file-symlink-p "sym-link2")
1067 (file-symlink-p "/bin")
1071 - Function: file-directory-p FILENAME
1072 This function returns `t' if FILENAME is the name of an existing
1073 directory, `nil' otherwise.
1075 (file-directory-p "~rms")
1077 (file-directory-p "~rms/lewis/files.texi")
1079 (file-directory-p "~rms/lewis/no-such-file")
1081 (file-directory-p "$HOME")
1084 (substitute-in-file-name "$HOME"))
1087 - Function: file-regular-p FILENAME
1088 This function returns `t' if the file FILENAME exists and is a
1089 regular file (not a directory, symbolic link, named pipe,
1090 terminal, or other I/O device).
1093 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
1098 The "truename" of a file is the name that you get by following
1099 symbolic links until none remain, then expanding to get rid of `.' and
1100 `..' as components. Strictly speaking, a file need not have a unique
1101 truename; the number of distinct truenames a file has is equal to the
1102 number of hard links to the file. However, truenames are useful
1103 because they eliminate symbolic links as a cause of name variation.
1105 - Function: file-truename FILENAME &optional DEFAULT
1106 The function `file-truename' returns the true name of the file
1107 FILENAME. This is the name that you get by following symbolic
1108 links until none remain.
1110 If the filename is relative, DEFAULT is the directory to start
1111 with. If DEFAULT is `nil' or missing, the current buffer's value
1112 of `default-directory' is used.
1114 *Note Buffer File Name::, for related information.
projects / chise / xemacs-chise.git.1 / blob