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: 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
112 (substitute-command-keys
113 "To abort a recursive edit from the minibuffer, type\
114 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
115 => "To abort a recursive edit from the minibuffer, type C-g."
117 (substitute-command-keys
118 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
119 \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
120 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
121 as the keymap for future \\=\\[COMMAND] substrings.
122 \\=\\= quotes the following character and is discarded;
123 thus, \\=\\=\\=\\= puts \\=\\= into the output,
124 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
125 => "Substrings of the form \{MAPVAR} are replaced by summaries
126 (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
127 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
128 as the keymap for future \[COMMAND] substrings.
129 \= quotes the following character and is discarded;
130 thus, \=\= puts \= into the output,
131 and \=\[ puts \[ into the output."
134 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
136 Describing Characters for Help Messages
137 =======================================
139 These functions convert events, key sequences or characters to
140 textual descriptions. These descriptions are useful for including
141 arbitrary text characters or key sequences in messages, because they
142 convert non-printing and whitespace characters to sequences of printing
143 characters. The description of a non-whitespace printing character is
144 the character itself.
146 - Function: key-description sequence
147 This function returns a string containing the XEmacs standard
148 notation for the input events in SEQUENCE. The argument SEQUENCE
149 may be a string, vector or list. *Note Events::, for more
150 information about valid events. See also the examples for
151 `single-key-description', below.
153 - Function: single-key-description key
154 This function returns a string describing KEY in the standard
155 XEmacs notation for keyboard input. A normal printing character
156 appears as itself, but a control character turns into a string
157 starting with `C-', a meta character turns into a string starting
158 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
159 A symbol appears as the name of the symbol. An event that is a
160 list appears as the name of the symbol in the CAR of the list.
162 (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"
166 (single-key-description 'kp_next)
168 (single-key-description '(shift button1))
171 - Function: text-char-description character
172 This function returns a string describing CHARACTER in the
173 standard XEmacs notation for characters that appear in text--like
174 `single-key-description', except that control characters are
175 represented with a leading caret (which is how control characters
176 in XEmacs buffers are usually displayed).
178 (text-char-description ?\C-c)
180 (text-char-description ?\M-m)
182 (text-char-description ?\C-\M-m)
186 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
191 XEmacs provides a variety of on-line help functions, all accessible
192 to the user as subcommands of the prefix `C-h', or on some keyboards,
193 `help'. For more information about them, see *Note Help: (emacs)Help.
194 Here we describe some program-level interfaces to the same information.
196 - Command: apropos regexp &optional do-all predicate
197 This function finds all symbols whose names contain a match for the
198 regular expression REGEXP, and returns a list of them (*note
199 Regular Expressions::). It also displays the symbols in a buffer
200 named `*Help*', each with a one-line description.
202 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
203 the functions that are found.
205 If PREDICATE is non-`nil', it should be a function to be called on
206 each symbol that has matched REGEXP. Only symbols for which
207 PREDICATE returns a non-`nil' value are listed or displayed.
209 In the first of the following examples, `apropos' finds all the
210 symbols with names containing `exec'. In the second example, it
211 finds and returns only those symbols that are also commands. (We
212 don't show the output that results in the `*Help*' buffer.)
215 => (Buffer-menu-execute command-execute exec-directory
216 exec-path execute-extended-command execute-kbd-macro
217 executing-kbd-macro executing-macro)
219 (apropos "exec" nil 'commandp)
220 => (Buffer-menu-execute execute-extended-command)
222 `apropos' is used by various user-level commands, such as `C-h a'
223 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
224 (`command-apropos'), which does an apropos over only those
225 functions which are user commands. `command-apropos' calls
226 `apropos', specifying a PREDICATE to restrict the output to
227 symbols that are commands. The call to `apropos' looks like this:
229 (apropos string t 'commandp)
232 The value of this variable is a local keymap for characters
233 following the Help key, `C-h'.
235 - Prefix Command: help-command
236 This symbol is not a function; its function definition is actually
237 the keymap known as `help-map'. It is defined in `help.el' as
240 (define-key global-map "\C-h" 'help-command)
241 (fset 'help-command help-map)
243 - Function: print-help-return-message &optional function
244 This function builds a string that explains how to restore the
245 previous state of the windows after a help command. After
246 building the message, it applies FUNCTION to it if FUNCTION is
247 non-`nil'. Otherwise it calls `message' to display it in the echo
250 This function expects to be called inside a
251 `with-output-to-temp-buffer' special form, and expects
252 `standard-output' to have the value bound by that special form.
253 For an example of its use, see the long example in *Note Accessing
256 - Variable: help-char
257 The value of this variable is the help character--the character
258 that XEmacs recognizes as meaning Help. By default, it is the
259 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
260 character, if `help-form' is non-`nil' Lisp expression, it
261 evaluates that expression, and displays the result in a window if
264 `help-char' can be a character or a key description such as `help'
267 Usually the value of `help-form''s value is `nil'. Then the help
268 character has no special meaning at the level of command input, and
269 it becomes part of a key sequence in the normal way. The standard
270 key binding of `C-h' is a prefix key for several general-purpose
273 The help character is special after prefix keys, too. If it has no
274 binding as a subcommand of the prefix key, it runs
275 `describe-prefix-bindings', which displays a list of all the
276 subcommands of the prefix key.
278 - Variable: help-form
279 If this variable is non-`nil', its value is a form to evaluate
280 whenever the character `help-char' is read. If evaluating the form
281 produces a string, that string is displayed.
283 A command that calls `next-command-event' or `next-event' probably
284 should bind `help-form' to a non-`nil' expression while it does
285 input. (The exception is when `C-h' is meaningful input.)
286 Evaluating this expression should result in a string that explains
287 what the input is for and how to enter it properly.
289 Entry to the minibuffer binds this variable to the value of
290 `minibuffer-help-form' (*note Minibuffer Misc::).
292 - Variable: prefix-help-command
293 This variable holds a function to print help for a prefix
294 character. The function is called when the user types a prefix
295 key followed by the help character, and the help character has no
296 binding after that prefix. The variable's default value is
297 `describe-prefix-bindings'.
299 - Function: describe-prefix-bindings
300 This function calls `describe-bindings' to display a list of all
301 the subcommands of the prefix key of the most recent key sequence.
302 The prefix described consists of all but the last event of that
303 key sequence. (The last event is, presumably, the help character.)
305 The following two functions are found in the library `helper'. They
306 are for modes that want to provide help without relinquishing control,
307 such as the "electric" modes. You must load that library with
308 `(require 'helper)' in order to use them. Their names begin with
309 `Helper' to distinguish them from the ordinary help functions.
311 - Command: Helper-describe-bindings
312 This command pops up a window displaying a help buffer containing a
313 listing of all of the key bindings from both the local and global
314 keymaps. It works by calling `describe-bindings'.
316 - Command: Helper-help
317 This command provides help for the current mode. It prompts the
318 user in the minibuffer with the message `Help (Type ? for further
319 options)', and then provides assistance in finding out what the key
320 bindings are, and what the mode is intended for. It returns `nil'.
322 This can be customized by changing the map `Helper-help-map'.
325 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
330 As you add functionality to a package, you may at times want to
331 replace an older function with a new one. To preserve compatibility
332 with existing code, the older function needs to still exist; but users
333 of that function should be told to use the newer one instead. XEmacs
334 Lisp lets you mark a function or variable as "obsolete", and indicate
335 what should be used instead.
337 - Function: make-obsolete function new
338 This function indicates that FUNCTION is an obsolete function, and
339 the function NEW should be used instead. The byte compiler will
340 issue a warning to this effect when it encounters a usage of the
341 older function, and the help system will also note this in the
342 function's documentation. NEW can also be a string (if there is
343 not a single function with the same functionality any more), and
344 should be a descriptive statement, such as "use FOO or BAR
345 instead" or "this function is unnecessary".
347 - Function: make-obsolete-variable variable new
348 This is like `make-obsolete' but is for variables instead of
351 - Function: define-obsolete-function-alias oldfun newfun
352 This function combines `make-obsolete' and `define-function',
353 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
354 OLDFUN as an alias for NEWFUN.
356 - Function: define-obsolete-variable-alias oldvar newvar
357 This is like `define-obsolete-function-alias' but for variables.
359 Note that you should not normally put obsoleteness information
360 explicitly in a function or variable's doc string. The obsoleteness
361 information that you specify using the above functions will be displayed
362 whenever the doc string is displayed, and by adding it explicitly the
363 result is redundancy.
365 Also, if an obsolete function is substantially the same as a newer
366 one but is not actually an alias, you should consider omitting the doc
367 string entirely (use a null string `""' as the doc string). That way,
368 the user is told about the obsoleteness and is forced to look at the
369 documentation of the new function, making it more likely that he will
370 use the new function.
372 - Function: function-obsoleteness-doc function
373 If FUNCTION is obsolete, this function returns a string describing
374 this. This is the message that is printed out during byte
375 compilation or in the function's documentation. If FUNCTION is
376 not obsolete, `nil' is returned.
378 - Function: variable-obsoleteness-doc variable
379 This is like `function-obsoleteness-doc' but for variables.
381 The obsoleteness information is stored internally by putting a
382 property `byte-obsolete-info' (for functions) or
383 `byte-obsolete-variable' (for variables) on the symbol that specifies
384 the obsolete function or variable. For more information, see the
385 implementation of `make-obsolete' and `make-obsolete-variable' in
386 `lisp/bytecomp/bytecomp-runtime.el'.
389 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
394 In XEmacs, you can find, create, view, save, and otherwise work with
395 files and file directories. This chapter describes most of the
396 file-related functions of XEmacs Lisp, but a few others are described in
397 *Note Buffers::, and those related to backups and auto-saving are
398 described in *Note Backups and Auto-Saving::.
400 Many of the file functions take one or more arguments that are file
401 names. A file name is actually a string. Most of these functions
402 expand file name arguments using `expand-file-name', so that `~' is
403 handled correctly, as are relative file names (including `../'). These
404 functions don't recognize environment variable substitutions such as
405 `$HOME'. *Note File Name Expansion::.
409 * Visiting Files:: Reading files into Emacs buffers for editing.
410 * Saving Buffers:: Writing changed buffers back into files.
411 * Reading from Files:: Reading files into buffers without visiting.
412 * Writing to Files:: Writing new files from parts of buffers.
413 * File Locks:: Locking and unlocking files, to prevent
414 simultaneous editing by two people.
415 * Information about Files:: Testing existence, accessibility, size of files.
416 * Changing File Attributes:: Renaming files, changing protection, etc.
417 * File Names:: Decomposing and expanding file names.
418 * Contents of Directories:: Getting a list of the files in a directory.
419 * Create/Delete Dirs:: Creating and Deleting Directories.
420 * Magic File Names:: Defining "magic" special handling
421 for certain file names.
422 * Partial Files:: Treating a section of a buffer as a file.
423 * Format Conversion:: Conversion to and from various file formats.
424 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
427 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
432 Visiting a file means reading a file into a buffer. Once this is
433 done, we say that the buffer is "visiting" that file, and call the file
434 "the visited file" of the buffer.
436 A file and a buffer are two different things. A file is information
437 recorded permanently in the computer (unless you delete it). A buffer,
438 on the other hand, is information inside of XEmacs that will vanish at
439 the end of the editing session (or when you kill the buffer). Usually,
440 a buffer contains information that you have copied from a file; then we
441 say the buffer is visiting that file. The copy in the buffer is what
442 you modify with editing commands. Such changes to the buffer do not
443 change the file; therefore, to make the changes permanent, you must
444 "save" the buffer, which means copying the altered buffer contents back
447 In spite of the distinction between files and buffers, people often
448 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
449 "I am editing a file," rather than, "I am editing a buffer that I will
450 soon save as a file of the same name." Humans do not usually need to
451 make the distinction explicit. When dealing with a computer program,
452 however, it is good to keep the distinction in mind.
456 * Visiting Functions:: The usual interface functions for visiting.
457 * Subroutines of Visiting:: Lower-level subroutines that they use.
460 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
462 Functions for Visiting Files
463 ----------------------------
465 This section describes the functions normally used to visit files.
466 For historical reasons, these functions have names starting with
467 `find-' rather than `visit-'. *Note Buffer File Name::, for functions
468 and variables that access the visited file name of a buffer or that
469 find an existing buffer by its visited file name.
471 In a Lisp program, if you want to look at the contents of a file but
472 not alter it, the fastest way is to use `insert-file-contents' in a
473 temporary buffer. Visiting the file is not necessary and takes longer.
474 *Note Reading from Files::.
476 - Command: find-file filename
477 This command selects a buffer visiting the file FILENAME, using an
478 existing buffer if there is one, and otherwise creating a new
479 buffer and reading the file into it. It also returns that buffer.
481 The body of the `find-file' function is very simple and looks like
484 (switch-to-buffer (find-file-noselect filename))
486 (See `switch-to-buffer' in *Note Displaying Buffers::.)
488 When `find-file' is called interactively, it prompts for FILENAME
491 - Function: find-file-noselect filename &optional nowarn
492 This function is the guts of all the file-visiting functions. It
493 finds or creates a buffer visiting the file FILENAME, and returns
494 it. It uses an existing buffer if there is one, and otherwise
495 creates a new buffer and reads the file into it. You may make the
496 buffer current or display it in a window if you wish, but this
497 function does not do so.
499 When `find-file-noselect' uses an existing buffer, it first
500 verifies that the file has not changed since it was last visited or
501 saved in that buffer. If the file has changed, then this function
502 asks the user whether to reread the changed file. If the user says
503 `yes', any changes previously made in the buffer are lost.
505 If `find-file-noselect' needs to create a buffer, and there is no
506 file named FILENAME, it displays the message `New file' in the
507 echo area, and leaves the buffer empty.
509 If NO-WARN is non-`nil', various warnings that XEmacs normally
510 gives (e.g. if another buffer is already visiting FILENAME but
511 FILENAME has been removed from disk since that buffer was created)
514 The `find-file-noselect' function calls `after-find-file' after
515 reading the file (*note Subroutines of Visiting::). That function
516 sets the buffer major mode, parses local variables, warns the user
517 if there exists an auto-save file more recent than the file just
518 visited, and finishes by running the functions in
521 The `find-file-noselect' function returns the buffer that is
522 visiting the file FILENAME.
524 (find-file-noselect "/etc/fstab")
527 - Command: find-file-other-window filename
528 This command selects a buffer visiting the file FILENAME, but does
529 so in a window other than the selected window. It may use another
530 existing window or split a window; see *Note Displaying Buffers::.
532 When this command is called interactively, it prompts for FILENAME.
534 - Command: find-file-read-only filename
535 This command selects a buffer visiting the file FILENAME, like
536 `find-file', but it marks the buffer as read-only. *Note Read
537 Only Buffers::, for related functions and variables.
539 When this command is called interactively, it prompts for FILENAME.
541 - Command: view-file filename
542 This command visits FILENAME in View mode, and displays it in a
543 recursive edit, returning to the previous buffer when done. View
544 mode is a mode that allows you to skim rapidly through the file
545 but does not let you modify it. Entering View mode runs the
546 normal hook `view-mode-hook'. *Note Hooks::.
548 When `view-file' is called interactively, it prompts for FILENAME.
550 - Variable: find-file-hooks
551 The value of this variable is a list of functions to be called
552 after a file is visited. The file's local-variables specification
553 (if any) will have been processed before the hooks are run. The
554 buffer visiting the file is current when the hook functions are
557 This variable works just like a normal hook, but we think that
558 renaming it would not be advisable.
560 - Variable: find-file-not-found-hooks
561 The value of this variable is a list of functions to be called when
562 `find-file' or `find-file-noselect' is passed a nonexistent file
563 name. `find-file-noselect' calls these functions as soon as it
564 detects a nonexistent file. It calls them in the order of the
565 list, until one of them returns non-`nil'. `buffer-file-name' is
568 This is not a normal hook because the values of the functions are
569 used and they may not all be called.
572 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
574 Subroutines of Visiting
575 -----------------------
577 The `find-file-noselect' function uses the `create-file-buffer' and
578 `after-find-file' functions as subroutines. Sometimes it is useful to
581 - Function: create-file-buffer filename
582 This function creates a suitably named buffer for visiting
583 FILENAME, and returns it. It uses FILENAME (sans directory) as
584 the name if that name is free; otherwise, it appends a string such
585 as `<2>' to get an unused name. See also *Note Creating Buffers::.
587 *Please note:* `create-file-buffer' does _not_ associate the new
588 buffer with a file and does not select the buffer. It also does
589 not use the default major mode.
591 (create-file-buffer "foo")
593 (create-file-buffer "foo")
595 (create-file-buffer "foo")
598 This function is used by `find-file-noselect'. It uses
599 `generate-new-buffer' (*note Creating Buffers::).
601 - Function: after-find-file &optional error warn noauto
602 This function sets the buffer major mode, and parses local
603 variables (*note Auto Major Mode::). It is called by
604 `find-file-noselect' and by the default revert function (*note
607 If reading the file got an error because the file does not exist,
608 but its directory does exist, the caller should pass a non-`nil'
609 value for ERROR. In that case, `after-find-file' issues a warning:
610 `(New File)'. For more serious errors, the caller should usually
611 not call `after-find-file'.
613 If WARN is non-`nil', then this function issues a warning if an
614 auto-save file exists and is more recent than the visited file.
616 If NOAUTO is non-`nil', then this function does not turn on
617 auto-save mode; otherwise, it does.
619 The last thing `after-find-file' does is call all the functions in
623 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
628 When you edit a file in XEmacs, you are actually working on a buffer
629 that is visiting that file--that is, the contents of the file are
630 copied into the buffer and the copy is what you edit. Changes to the
631 buffer do not change the file until you "save" the buffer, which means
632 copying the contents of the buffer into the file.
634 - Command: save-buffer &optional backup-option
635 This function saves the contents of the current buffer in its
636 visited file if the buffer has been modified since it was last
637 visited or saved. Otherwise it does nothing.
639 `save-buffer' is responsible for making backup files. Normally,
640 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
641 if this is the first save since visiting the file. Other values
642 for BACKUP-OPTION request the making of backup files in other
645 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
646 `save-buffer' function marks this version of the file to be
647 backed up when the buffer is next saved.
649 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
650 `save-buffer' function unconditionally backs up the previous
651 version of the file before saving it.
653 - Command: save-some-buffers &optional save-silently-p exiting
654 This command saves some modified file-visiting buffers. Normally
655 it asks the user about each buffer. But if SAVE-SILENTLY-P is
656 non-`nil', it saves all the file-visiting buffers without querying
659 The optional EXITING argument, if non-`nil', requests this
660 function to offer also to save certain other buffers that are not
661 visiting files. These are buffers that have a non-`nil' local
662 value of `buffer-offer-save'. (A user who says yes to saving one
663 of these is asked to specify a file name to use.) The
664 `save-buffers-kill-emacs' function passes a non-`nil' value for
667 - Variable: buffer-offer-save
668 When this variable is non-`nil' in a buffer, XEmacs offers to save
669 the buffer on exit even if the buffer is not visiting a file. The
670 variable is automatically local in all buffers. Normally, Mail
671 mode (used for editing outgoing mail) sets this to `t'.
673 - Command: write-file filename
674 This function writes the current buffer into file FILENAME, makes
675 the buffer visit that file, and marks it not modified. Then it
676 renames the buffer based on FILENAME, appending a string like `<2>'
677 if necessary to make a unique buffer name. It does most of this
678 work by calling `set-visited-file-name' and `save-buffer'.
680 - Variable: write-file-hooks
681 The value of this variable is a list of functions to be called
682 before writing out a buffer to its visited file. If one of them
683 returns non-`nil', the file is considered already written and the
684 rest of the functions are not called, nor is the usual code for
685 writing the file executed.
687 If a function in `write-file-hooks' returns non-`nil', it is
688 responsible for making a backup file (if that is appropriate). To
689 do so, execute the following code:
691 (or buffer-backed-up (backup-buffer))
693 You might wish to save the file modes value returned by
694 `backup-buffer' and use that to set the mode bits of the file that
695 you write. This is what `save-buffer' normally does.
697 Even though this is not a normal hook, you can use `add-hook' and
698 `remove-hook' to manipulate the list. *Note Hooks::.
700 - Variable: local-write-file-hooks
701 This works just like `write-file-hooks', but it is intended to be
702 made local to particular buffers. It's not a good idea to make
703 `write-file-hooks' local to a buffer--use this variable instead.
705 The variable is marked as a permanent local, so that changing the
706 major mode does not alter a buffer-local value. This is
707 convenient for packages that read "file" contents in special ways,
708 and set up hooks to save the data in a corresponding way.
710 - Variable: write-contents-hooks
711 This works just like `write-file-hooks', but it is intended for
712 hooks that pertain to the contents of the file, as opposed to
713 hooks that pertain to where the file came from. Such hooks are
714 usually set up by major modes, as buffer-local bindings for this
715 variable. Switching to a new major mode always resets this
718 - Variable: after-save-hook
719 This normal hook runs after a buffer has been saved in its visited
722 - Variable: file-precious-flag
723 If this variable is non-`nil', then `save-buffer' protects against
724 I/O errors while saving by writing the new file to a temporary
725 name instead of the name it is supposed to have, and then renaming
726 it to the intended name after it is clear there are no errors.
727 This procedure prevents problems such as a lack of disk space from
728 resulting in an invalid file.
730 As a side effect, backups are necessarily made by copying. *Note
731 Rename or Copy::. Yet, at the same time, saving a precious file
732 always breaks all hard links between the file you save and other
735 Some modes set this variable non-`nil' locally in particular
738 - User Option: require-final-newline
739 This variable determines whether files may be written out that do
740 _not_ end with a newline. If the value of the variable is `t',
741 then `save-buffer' silently adds a newline at the end of the file
742 whenever the buffer being saved does not already end in one. If
743 the value of the variable is non-`nil', but not `t', then
744 `save-buffer' asks the user whether to add a newline each time the
747 If the value of the variable is `nil', then `save-buffer' doesn't
748 add newlines at all. `nil' is the default value, but a few major
749 modes set it to `t' in particular buffers.
752 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
757 You can copy a file from the disk and insert it into a buffer using
758 the `insert-file-contents' function. Don't use the user-level command
759 `insert-file' in a Lisp program, as that sets the mark.
761 - Function: insert-file-contents filename &optional visit beg end
763 This function inserts the contents of file FILENAME into the
764 current buffer after point. It returns a list of the absolute
765 file name and the length of the data inserted. An error is
766 signaled if FILENAME is not the name of a file that can be read.
768 The function `insert-file-contents' checks the file contents
769 against the defined file formats, and converts the file contents if
770 appropriate. *Note Format Conversion::. It also calls the
771 functions in the list `after-insert-file-functions'; see *Note
774 If VISIT is non-`nil', this function additionally marks the buffer
775 as unmodified and sets up various fields in the buffer so that it
776 is visiting the file FILENAME: these include the buffer's visited
777 file name and its last save file modtime. This feature is used by
778 `find-file-noselect' and you probably should not use it yourself.
780 If BEG and END are non-`nil', they should be integers specifying
781 the portion of the file to insert. In this case, VISIT must be
784 (insert-file-contents filename nil 0 500)
786 inserts the first 500 characters of a file.
788 If the argument REPLACE is non-`nil', it means to replace the
789 contents of the buffer (actually, just the accessible portion)
790 with the contents of the file. This is better than simply
791 deleting the buffer contents and inserting the whole file, because
792 (1) it preserves some marker positions and (2) it puts less data
795 If you want to pass a file name to another process so that another
796 program can read the file, use the function `file-local-copy'; see
797 *Note Magic File Names::.
800 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
805 You can write the contents of a buffer, or part of a buffer, directly
806 to a file on disk using the `append-to-file' and `write-region'
807 functions. Don't use these functions to write to files that are being
808 visited; that could cause confusion in the mechanisms for visiting.
810 - Command: append-to-file start end filename
811 This function appends the contents of the region delimited by
812 START and END in the current buffer to the end of file FILENAME.
813 If that file does not exist, it is created. If that file exists
814 it is overwritten. This function returns `nil'.
816 An error is signaled if FILENAME specifies a nonwritable file, or
817 a nonexistent file in a directory where files cannot be created.
819 - Command: write-region start end filename &optional append visit
820 This function writes the region delimited by START and END in the
821 current buffer into the file specified by FILENAME.
823 If START is a string, then `write-region' writes or appends that
824 string, rather than text from the buffer.
826 If APPEND is non-`nil', then the specified text is appended to the
827 existing file contents (if any).
829 If VISIT is `t', then XEmacs establishes an association between
830 the buffer and the file: the buffer is then visiting that file.
831 It also sets the last file modification time for the current
832 buffer to FILENAME's modtime, and marks the buffer as not
833 modified. This feature is used by `save-buffer', but you probably
834 should not use it yourself.
836 If VISIT is a string, it specifies the file name to visit. This
837 way, you can write the data to one file (FILENAME) while recording
838 the buffer as visiting another file (VISIT). The argument VISIT
839 is used in the echo area message and also for file locking; VISIT
840 is stored in `buffer-file-name'. This feature is used to
841 implement `file-precious-flag'; don't use it yourself unless you
842 really know what you're doing.
844 The function `write-region' converts the data which it writes to
845 the appropriate file formats specified by `buffer-file-format'.
846 *Note Format Conversion::. It also calls the functions in the list
847 `write-region-annotate-functions'; see *Note Saving Properties::.
849 Normally, `write-region' displays a message `Wrote file FILENAME'
850 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
851 then this message is inhibited. This feature is useful for
852 programs that use files for internal purposes, files that the user
853 does not need to know about.
856 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
861 When two users edit the same file at the same time, they are likely
862 to interfere with each other. XEmacs tries to prevent this situation
863 from arising by recording a "file lock" when a file is being modified.
864 XEmacs can then detect the first attempt to modify a buffer visiting a
865 file that is locked by another XEmacs process, and ask the user what to
868 File locks do not work properly when multiple machines can share
869 file systems, such as with NFS. Perhaps a better file locking system
870 will be implemented in the future. When file locks do not work, it is
871 possible for two users to make changes simultaneously, but XEmacs can
872 still warn the user who saves second. Also, the detection of
873 modification of a buffer visiting a file changed on disk catches some
874 cases of simultaneous editing; see *Note Modification Time::.
876 - Function: file-locked-p &optional filename
877 This function returns `nil' if the file FILENAME is not locked by
878 this XEmacs process. It returns `t' if it is locked by this
879 XEmacs, and it returns the name of the user who has locked it if it
880 is locked by someone else.
882 (file-locked-p "foo")
885 - Function: lock-buffer &optional filename
886 This function locks the file FILENAME, if the current buffer is
887 modified. The argument FILENAME defaults to the current buffer's
888 visited file. Nothing is done if the current buffer is not
889 visiting a file, or is not modified.
891 - Function: unlock-buffer
892 This function unlocks the file being visited in the current buffer,
893 if the buffer is modified. If the buffer is not modified, then
894 the file should not be locked, so this function does nothing. It
895 also does nothing if the current buffer is not visiting a file.
897 - Function: ask-user-about-lock file other-user
898 This function is called when the user tries to modify FILE, but it
899 is locked by another user named OTHER-USER. The value it returns
900 determines what happens next:
902 * A value of `t' says to grab the lock on the file. Then this
903 user may edit the file and OTHER-USER loses the lock.
905 * A value of `nil' says to ignore the lock and let this user
906 edit the file anyway.
908 * This function may instead signal a `file-locked' error, in
909 which case the change that the user was about to make does
912 The error message for this error looks like this:
914 error--> File is locked: FILE OTHER-USER
916 where `file' is the name of the file and OTHER-USER is the
917 name of the user who has locked the file.
919 The default definition of this function asks the user to choose
920 what to do. If you wish, you can replace the `ask-user-about-lock'
921 function with your own version that decides in another way. The
922 code for its usual definition is in `userlock.el'.
925 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
927 Information about Files
928 =======================
930 The functions described in this section all operate on strings that
931 designate file names. All the functions have names that begin with the
932 word `file'. These functions all return information about actual files
933 or directories, so their arguments must all exist as actual files or
934 directories unless otherwise noted.
938 * Testing Accessibility:: Is a given file readable? Writable?
939 * Kinds of Files:: Is it a directory? A symbolic link?
940 * Truenames:: Eliminating symbolic links from a file name.
941 * File Attributes:: How large is it? Any other names? Etc.
944 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
946 Testing Accessibility
947 ---------------------
949 These functions test for permission to access a file in specific
952 - Function: file-exists-p filename
953 This function returns `t' if a file named FILENAME appears to
954 exist. This does not mean you can necessarily read the file, only
955 that you can find out its attributes. (On Unix, this is true if
956 the file exists and you have execute permission on the containing
957 directories, regardless of the protection of the file itself.)
959 If the file does not exist, or if fascist access control policies
960 prevent you from finding the attributes of the file, this function
963 - Function: file-readable-p filename
964 This function returns `t' if a file named FILENAME exists and you
965 can read it. It returns `nil' otherwise.
967 (file-readable-p "files.texi")
969 (file-exists-p "/usr/spool/mqueue")
971 (file-readable-p "/usr/spool/mqueue")
974 - Function: file-executable-p filename
975 This function returns `t' if a file named FILENAME exists and you
976 can execute it. It returns `nil' otherwise. If the file is a
977 directory, execute permission means you can check the existence and
978 attributes of files inside the directory, and open those files if
981 - Function: file-writable-p filename
982 This function returns `t' if the file FILENAME can be written or
983 created by you, and `nil' otherwise. A file is writable if the
984 file exists and you can write it. It is creatable if it does not
985 exist, but the specified directory does exist and you can write in
988 In the third example below, `foo' is not writable because the
989 parent directory does not exist, even though the user could create
992 (file-writable-p "~/foo")
994 (file-writable-p "/foo")
996 (file-writable-p "~/no-such-dir/foo")
999 - Function: file-accessible-directory-p dirname
1000 This function returns `t' if you have permission to open existing
1001 files in the directory whose name as a file is DIRNAME; otherwise
1002 (or if there is no such directory), it returns `nil'. The value
1003 of DIRNAME may be either a directory name or the file name of a
1006 Example: after the following,
1008 (file-accessible-directory-p "/foo")
1011 we can deduce that any attempt to read a file in `/foo/' will give
1014 - Function: file-ownership-preserved-p filename
1015 This function returns `t' if deleting the file FILENAME and then
1016 creating it anew would keep the file's owner unchanged.
1018 - Function: file-newer-than-file-p filename1 filename2
1019 This function returns `t' if the file FILENAME1 is newer than file
1020 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
1021 FILENAME2 does not exist, it returns `t'.
1023 In the following example, assume that the file `aug-19' was written
1024 on the 19th, `aug-20' was written on the 20th, and the file
1025 `no-file' doesn't exist at all.
1027 (file-newer-than-file-p "aug-19" "aug-20")
1029 (file-newer-than-file-p "aug-20" "aug-19")
1031 (file-newer-than-file-p "aug-19" "no-file")
1033 (file-newer-than-file-p "no-file" "aug-19")
1036 You can use `file-attributes' to get a file's last modification
1037 time as a list of two numbers. *Note File Attributes::.
1040 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
1042 Distinguishing Kinds of Files
1043 -----------------------------
1045 This section describes how to distinguish various kinds of files,
1046 such as directories, symbolic links, and ordinary files.
1048 - Function: file-symlink-p filename
1049 If the file FILENAME is a symbolic link, the `file-symlink-p'
1050 function returns the file name to which it is linked. This may be
1051 the name of a text file, a directory, or even another symbolic
1052 link, or it may be a nonexistent file name.
1054 If the file FILENAME is not a symbolic link (or there is no such
1055 file), `file-symlink-p' returns `nil'.
1057 (file-symlink-p "foo")
1059 (file-symlink-p "sym-link")
1061 (file-symlink-p "sym-link2")
1063 (file-symlink-p "/bin")
1067 - Function: file-directory-p filename
1068 This function returns `t' if FILENAME is the name of an existing
1069 directory, `nil' otherwise.
1071 (file-directory-p "~rms")
1073 (file-directory-p "~rms/lewis/files.texi")
1075 (file-directory-p "~rms/lewis/no-such-file")
1077 (file-directory-p "$HOME")
1080 (substitute-in-file-name "$HOME"))
1083 - Function: file-regular-p filename
1084 This function returns `t' if the file FILENAME exists and is a
1085 regular file (not a directory, symbolic link, named pipe,
1086 terminal, or other I/O device).
1089 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
1094 The "truename" of a file is the name that you get by following
1095 symbolic links until none remain, then expanding to get rid of `.' and
1096 `..' as components. Strictly speaking, a file need not have a unique
1097 truename; the number of distinct truenames a file has is equal to the
1098 number of hard links to the file. However, truenames are useful
1099 because they eliminate symbolic links as a cause of name variation.
1101 - Function: file-truename filename &optional default
1102 The function `file-truename' returns the true name of the file
1103 FILENAME. This is the name that you get by following symbolic
1104 links until none remain.
1106 If the filename is relative, DEFAULT is the directory to start
1107 with. If DEFAULT is `nil' or missing, the current buffer's value
1108 of `default-directory' is used.
1110 *Note Buffer File Name::, for related information.
projects / chise / xemacs-chise.git- / blob