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: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
55 Making Certain File Names "Magic"
56 =================================
58 You can implement special handling for certain file names. This is
59 called making those names "magic". You must supply a regular
60 expression to define the class of names (all those that match the
61 regular expression), plus a handler that implements all the primitive
62 XEmacs file operations for file names that do match.
64 The variable `file-name-handler-alist' holds a list of handlers,
65 together with regular expressions that determine when to apply each
66 handler. Each element has this form:
70 All the XEmacs primitives for file access and file name transformation
71 check the given file name against `file-name-handler-alist'. If the
72 file name matches REGEXP, the primitives handle that file by calling
75 The first argument given to HANDLER is the name of the primitive;
76 the remaining arguments are the arguments that were passed to that
77 operation. (The first of these arguments is typically the file name
78 itself.) For example, if you do this:
80 (file-exists-p FILENAME)
82 and FILENAME has handler HANDLER, then HANDLER is called like this:
84 (funcall HANDLER 'file-exists-p FILENAME)
86 Here are the operations that a magic file name handler gets to
89 `add-name-to-file', `copy-file', `delete-directory', `delete-file',
90 `diff-latest-backup-file', `directory-file-name', `directory-files',
91 `dired-compress-file', `dired-uncache', `expand-file-name',
92 `file-accessible-directory-p', `file-attributes', `file-directory-p',
93 `file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
94 `file-name-all-completions', `file-name-as-directory',
95 `file-name-completion', `file-name-directory', `file-name-nondirectory',
96 `file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
97 `file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
98 `get-file-buffer', `insert-directory', `insert-file-contents', `load',
99 `make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
100 `set-visited-file-modtime', `unhandled-file-name-directory',
101 `verify-visited-file-modtime', `write-region'.
103 Handlers for `insert-file-contents' typically need to clear the
104 buffer's modified flag, with `(set-buffer-modified-p nil)', if the
105 VISIT argument is non-`nil'. This also has the effect of unlocking the
106 buffer if it is locked.
108 The handler function must handle all of the above operations, and
109 possibly others to be added in the future. It need not implement all
110 these operations itself--when it has nothing special to do for a
111 certain operation, it can reinvoke the primitive, to handle the
112 operation "in the usual way". It should always reinvoke the primitive
113 for an operation it does not recognize. Here's one way to do this:
115 (defun my-file-handler (operation &rest args)
116 ;; First check for the specific operations
117 ;; that we have special handling for.
118 (cond ((eq operation 'insert-file-contents) ...)
119 ((eq operation 'write-region) ...)
121 ;; Handle any operation we don't know about.
122 (t (let ((inhibit-file-name-handlers
123 (cons 'my-file-handler
124 (and (eq inhibit-file-name-operation operation)
125 inhibit-file-name-handlers)))
126 (inhibit-file-name-operation operation))
127 (apply operation args)))))
129 When a handler function decides to call the ordinary Emacs primitive
130 for the operation at hand, it needs to prevent the primitive from
131 calling the same handler once again, thus leading to an infinite
132 recursion. The example above shows how to do this, with the variables
133 `inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
134 careful to use them exactly as shown above; the details are crucial for
135 proper behavior in the case of multiple handlers, and for operations
136 that have two file names that may each have handlers.
138 - Variable: inhibit-file-name-handlers
139 This variable holds a list of handlers whose use is presently
140 inhibited for a certain operation.
142 - Variable: inhibit-file-name-operation
143 The operation for which certain handlers are presently inhibited.
145 - Function: find-file-name-handler file operation
146 This function returns the handler function for file name FILE, or
147 `nil' if there is none. The argument OPERATION should be the
148 operation to be performed on the file--the value you will pass to
149 the handler as its first argument when you call it. The operation
150 is needed for comparison with `inhibit-file-name-operation'.
152 - Function: file-local-copy filename
153 This function copies file FILENAME to an ordinary non-magic file,
154 if it isn't one already.
156 If FILENAME specifies a "magic" file name, which programs outside
157 Emacs cannot directly read or write, this copies the contents to
158 an ordinary file and returns that file's name.
160 If FILENAME is an ordinary file name, not magic, then this function
161 does nothing and returns `nil'.
163 - Function: unhandled-file-name-directory filename
164 This function returns the name of a directory that is not magic.
165 It uses the directory part of FILENAME if that is not magic.
166 Otherwise, it asks the handler what to do.
168 This is useful for running a subprocess; every subprocess must
169 have a non-magic directory to serve as its current directory, and
170 this function is a good way to come up with one.
173 File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
180 * Intro to Partial Files::
181 * Creating a Partial File::
182 * Detached Partial Files::
185 File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
187 Intro to Partial Files
188 ----------------------
190 A "partial file" is a section of a buffer (called the "master
191 buffer") that is placed in its own buffer and treated as its own file.
192 Changes made to the partial file are not reflected in the master buffer
193 until the partial file is "saved" using the standard buffer save
194 commands. Partial files can be "reverted" (from the master buffer)
195 just like normal files. When a file part is active on a master buffer,
196 that section of the master buffer is marked as read-only. Two file
197 parts on the same master buffer are not allowed to overlap. Partial
198 file buffers are indicated by the words `File Part' in the modeline.
200 The master buffer knows about all the partial files that are active
201 on it, and thus killing or reverting the master buffer will be handled
202 properly. When the master buffer is saved, if there are any unsaved
203 partial files active on it then the user will be given the opportunity
204 to first save these files.
206 When a partial file buffer is first modified, the master buffer is
207 automatically marked as modified so that saving the master buffer will
211 File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
213 Creating a Partial File
214 -----------------------
216 - Function: make-file-part &optional start end name buffer
217 Make a file part on buffer BUFFER out of the region. Call it
218 NAME. This command creates a new buffer containing the contents
219 of the region and marks the buffer as referring to the specified
220 buffer, called the "master buffer". When the file-part buffer is
221 saved, its changes are integrated back into the master buffer.
222 When the master buffer is deleted, all file parts are deleted with
225 When called from a function, expects four arguments, START, END,
226 NAME, and BUFFER, all of which are optional and default to the
227 beginning of BUFFER, the end of BUFFER, a name generated from
228 BUFFER name, and the current buffer, respectively.
231 File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
233 Detached Partial Files
234 ----------------------
236 Every partial file has an extent in the master buffer associated
237 with it (called the "master extent"), marking where in the master
238 buffer the partial file begins and ends. If the text in master buffer
239 that is contained by the extent is deleted, then the extent becomes
240 "detached", meaning that it no longer refers to a specific region of
241 the master buffer. This can happen either when the text is deleted
242 directly or when the master buffer is reverted. Neither of these should
243 happen in normal usage because the master buffer should generally not be
246 Before doing any operation that references a partial file's master
247 extent, XEmacs checks to make sure that the extent is not detached. If
248 this is the case, XEmacs warns the user of this and the master extent is
249 deleted out of the master buffer, disconnecting the file part. The file
250 part's filename is cleared and thus must be explicitly specified if the
251 detached file part is to be saved.
254 File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
256 File Format Conversion
257 ======================
259 The variable `format-alist' defines a list of "file formats", which
260 describe textual representations used in files for the data (text,
261 text-properties, and possibly other information) in an Emacs buffer.
262 Emacs performs format conversion if appropriate when reading and writing
265 - Variable: format-alist
266 This list contains one format definition for each defined file
269 Each format definition is a list of this form:
271 (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
273 Here is what the elements in a format definition mean:
276 The name of this format.
279 A documentation string for the format.
282 A regular expression which is used to recognize files represented
286 A function to call to decode data in this format (to convert file
287 data into the usual Emacs data representation).
289 The FROM-FN is called with two args, BEGIN and END, which specify
290 the part of the buffer it should convert. It should convert the
291 text by editing it in place. Since this can change the length of
292 the text, FROM-FN should return the modified end position.
294 One responsibility of FROM-FN is to make sure that the beginning
295 of the file no longer matches REGEXP. Otherwise it is likely to
299 A function to call to encode data in this format (to convert the
300 usual Emacs data representation into this format).
302 The TO-FN is called with two args, BEGIN and END, which specify
303 the part of the buffer it should convert. There are two ways it
304 can do the conversion:
306 * By editing the buffer in place. In this case, TO-FN should
307 return the end-position of the range of text, as modified.
309 * By returning a list of annotations. This is a list of
310 elements of the form `(POSITION . STRING)', where POSITION is
311 an integer specifying the relative position in the text to be
312 written, and STRING is the annotation to add there. The list
313 must be sorted in order of position when TO-FN returns it.
315 When `write-region' actually writes the text from the buffer
316 to the file, it intermixes the specified annotations at the
317 corresponding positions. All this takes place without
318 modifying the buffer.
321 A flag, `t' if the encoding function modifies the buffer, and
322 `nil' if it works by returning a list of annotations.
325 A mode function to call after visiting a file converted from this
328 The function `insert-file-contents' automatically recognizes file
329 formats when it reads the specified file. It checks the text of the
330 beginning of the file against the regular expressions of the format
331 definitions, and if it finds a match, it calls the decoding function for
332 that format. Then it checks all the known formats over again. It
333 keeps checking them until none of them is applicable.
335 Visiting a file, with `find-file-noselect' or the commands that use
336 it, performs conversion likewise (because it calls
337 `insert-file-contents'); it also calls the mode function for each
338 format that it decodes. It stores a list of the format names in the
339 buffer-local variable `buffer-file-format'.
341 - Variable: buffer-file-format
342 This variable states the format of the visited file. More
343 precisely, this is a list of the file format names that were
344 decoded in the course of visiting the current buffer's file. It
345 is always local in all buffers.
347 When `write-region' writes data into a file, it first calls the
348 encoding functions for the formats listed in `buffer-file-format', in
349 the order of appearance in the list.
351 - Function: format-write-file file format
352 This command writes the current buffer contents into the file FILE
353 in format FORMAT, and makes that format the default for future
354 saves of the buffer. The argument FORMAT is a list of format
357 - Function: format-find-file file format
358 This command finds the file FILE, converting it according to
359 format FORMAT. It also makes FORMAT the default if the buffer is
362 The argument FORMAT is a list of format names. If FORMAT is
363 `nil', no conversion takes place. Interactively, typing just
364 <RET> for FORMAT specifies `nil'.
366 - Function: format-insert-file file format &optional beg end
367 This command inserts the contents of file FILE, converting it
368 according to format FORMAT. If BEG and END are non-`nil', they
369 specify which part of the file to read, as in
370 `insert-file-contents' (*note Reading from Files::).
372 The return value is like what `insert-file-contents' returns: a
373 list of the absolute file name and the length of the data inserted
376 The argument FORMAT is a list of format names. If FORMAT is
377 `nil', no conversion takes place. Interactively, typing just
378 <RET> for FORMAT specifies `nil'.
380 - Function: format-find-file file format
381 This command finds the file FILE, converting it according to
382 format FORMAT. It also makes FORMAT the default if the buffer is
385 The argument FORMAT is a list of format names. If FORMAT is
386 `nil', no conversion takes place. Interactively, typing just
387 <RET> for FORMAT specifies `nil'.
389 - Function: format-insert-file file format &optional beg end
390 This command inserts the contents of file FILE, converting it
391 according to format FORMAT. If BEG and END are non-`nil', they
392 specify which part of the file to read, as in
393 `insert-file-contents' (*note Reading from Files::).
395 The return value is like what `insert-file-contents' returns: a
396 list of the absolute file name and the length of the data inserted
399 The argument FORMAT is a list of format names. If FORMAT is
400 `nil', no conversion takes place. Interactively, typing just
401 <RET> for FORMAT specifies `nil'.
403 - Variable: auto-save-file-format
404 This variable specifies the format to use for auto-saving. Its
405 value is a list of format names, just like the value of
406 `buffer-file-format'; but it is used instead of
407 `buffer-file-format' for writing auto-save files. This variable
408 is always local in all buffers.
411 File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
416 Emacs on MS-DOS makes a distinction between text files and binary
417 files. This is necessary because ordinary text files on MS-DOS use a
418 two character sequence between lines: carriage-return and linefeed
419 (CRLF). Emacs expects just a newline character (a linefeed) between
420 lines. When Emacs reads or writes a text file on MS-DOS, it needs to
421 convert the line separators. This means it needs to know which files
422 are text files and which are binary. It makes this decision when
423 visiting a file, and records the decision in the variable
424 `buffer-file-type' for use when the file is saved.
426 *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
428 - Variable: buffer-file-type
429 This variable, automatically local in each buffer, records the
430 file type of the buffer's visited file. The value is `nil' for
431 text, `t' for binary.
433 - Function: find-buffer-file-type filename
434 This function determines whether file FILENAME is a text file or a
435 binary file. It returns `nil' for text, `t' for binary.
437 - User Option: file-name-buffer-file-type-alist
438 This variable holds an alist for distinguishing text files from
439 binary files. Each element has the form (REGEXP . TYPE), where
440 REGEXP is matched against the file name, and TYPE may be is `nil'
441 for text, `t' for binary, or a function to call to compute which.
442 If it is a function, then it is called with a single argument (the
443 file name) and should return `t' or `nil'.
445 - User Option: default-buffer-file-type
446 This variable specifies the default file type for files whose names
447 don't indicate anything in particular. Its value should be `nil'
448 for text, or `t' for binary.
450 - Command: find-file-text filename
451 Like `find-file', but treat the file as text regardless of its
454 - Command: find-file-binary filename
455 Like `find-file', but treat the file as binary regardless of its
459 File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
461 Backups and Auto-Saving
462 ***********************
464 Backup files and auto-save files are two methods by which XEmacs
465 tries to protect the user from the consequences of crashes or of the
466 user's own errors. Auto-saving preserves the text from earlier in the
467 current editing session; backup files preserve file contents prior to
472 * Backup Files:: How backup files are made; how their names are chosen.
473 * Auto-Saving:: How auto-save files are made; how their names are chosen.
474 * Reverting:: `revert-buffer', and how to customize what it does.
477 File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
482 A "backup file" is a copy of the old contents of a file you are
483 editing. XEmacs makes a backup file the first time you save a buffer
484 into its visited file. Normally, this means that the backup file
485 contains the contents of the file as it was before the current editing
486 session. The contents of the backup file normally remain unchanged once
489 Backups are usually made by renaming the visited file to a new name.
490 Optionally, you can specify that backup files should be made by copying
491 the visited file. This choice makes a difference for files with
492 multiple names; it also can affect whether the edited file remains owned
493 by the original owner or becomes owned by the user editing it.
495 By default, XEmacs makes a single backup file for each file edited.
496 You can alternatively request numbered backups; then each new backup
497 file gets a new name. You can delete old numbered backups when you
498 don't want them any more, or XEmacs can delete them automatically.
502 * Making Backups:: How XEmacs makes backup files, and when.
503 * Rename or Copy:: Two alternatives: renaming the old file or copying it.
504 * Numbered Backups:: Keeping multiple backups for each source file.
505 * Backup Names:: How backup file names are computed; customization.
508 File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
513 - Function: backup-buffer
514 This function makes a backup of the file visited by the current
515 buffer, if appropriate. It is called by `save-buffer' before
516 saving the buffer the first time.
518 - Variable: buffer-backed-up
519 This buffer-local variable indicates whether this buffer's file has
520 been backed up on account of this buffer. If it is non-`nil', then
521 the backup file has been written. Otherwise, the file should be
522 backed up when it is next saved (if backups are enabled). This is
523 a permanent local; `kill-local-variables' does not alter it.
525 - User Option: make-backup-files
526 This variable determines whether or not to make backup files. If
527 it is non-`nil', then XEmacs creates a backup of each file when it
528 is saved for the first time--provided that `backup-inhibited' is
531 The following example shows how to change the `make-backup-files'
532 variable only in the `RMAIL' buffer and not elsewhere. Setting it
533 `nil' stops XEmacs from making backups of the `RMAIL' file, which
534 may save disk space. (You would put this code in your `.emacs'
537 (add-hook 'rmail-mode-hook
541 (setq make-backup-files nil))))
543 - Variable: backup-enable-predicate
544 This variable's value is a function to be called on certain
545 occasions to decide whether a file should have backup files. The
546 function receives one argument, a file name to consider. If the
547 function returns `nil', backups are disabled for that file.
548 Otherwise, the other variables in this section say whether and how
551 The default value is this:
554 (or (< (length name) 5)
555 (not (string-equal "/tmp/"
556 (substring name 0 5)))))
558 - Variable: backup-inhibited
559 If this variable is non-`nil', backups are inhibited. It records
560 the result of testing `backup-enable-predicate' on the visited file
561 name. It can also coherently be used by other mechanisms that
562 inhibit backups based on which file is visited. For example, VC
563 sets this variable non-`nil' to prevent making backups for files
564 managed with a version control system.
566 This is a permanent local, so that changing the major mode does
567 not lose its value. Major modes should not set this
568 variable--they should set `make-backup-files' instead.
571 File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
573 Backup by Renaming or by Copying?
574 ---------------------------------
576 There are two ways that XEmacs can make a backup file:
578 * XEmacs can rename the original file so that it becomes a backup
579 file, and then write the buffer being saved into a new file.
580 After this procedure, any other names (i.e., hard links) of the
581 original file now refer to the backup file. The new file is owned
582 by the user doing the editing, and its group is the default for
583 new files written by the user in that directory.
585 * XEmacs can copy the original file into a backup file, and then
586 overwrite the original file with new contents. After this
587 procedure, any other names (i.e., hard links) of the original file
588 still refer to the current version of the file. The file's owner
589 and group will be unchanged.
591 The first method, renaming, is the default.
593 The variable `backup-by-copying', if non-`nil', says to use the
594 second method, which is to copy the original file and overwrite it with
595 the new buffer contents. The variable `file-precious-flag', if
596 non-`nil', also has this effect (as a sideline of its main
597 significance). *Note Saving Buffers::.
599 - Variable: backup-by-copying
600 If this variable is non-`nil', XEmacs always makes backup files by
603 The following two variables, when non-`nil', cause the second method
604 to be used in certain special cases. They have no effect on the
605 treatment of files that don't fall into the special cases.
607 - Variable: backup-by-copying-when-linked
608 If this variable is non-`nil', XEmacs makes backups by copying for
609 files with multiple names (hard links).
611 This variable is significant only if `backup-by-copying' is `nil',
612 since copying is always used when that variable is non-`nil'.
614 - Variable: backup-by-copying-when-mismatch
615 If this variable is non-`nil', XEmacs makes backups by copying in
616 cases where renaming would change either the owner or the group of
619 The value has no effect when renaming would not alter the owner or
620 group of the file; that is, for files which are owned by the user
621 and whose group matches the default for a new file created there
624 This variable is significant only if `backup-by-copying' is `nil',
625 since copying is always used when that variable is non-`nil'.
628 File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
630 Making and Deleting Numbered Backup Files
631 -----------------------------------------
633 If a file's name is `foo', the names of its numbered backup versions
634 are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
635 `foo.~3~', ..., `foo.~259~', and so on.
637 - User Option: version-control
638 This variable controls whether to make a single non-numbered backup
639 file or multiple numbered backups.
642 Make numbered backups if the visited file already has
643 numbered backups; otherwise, do not.
646 Do not make numbered backups.
649 Make numbered backups.
651 The use of numbered backups ultimately leads to a large number of
652 backup versions, which must then be deleted. XEmacs can do this
653 automatically or it can ask the user whether to delete them.
655 - User Option: kept-new-versions
656 The value of this variable is the number of newest versions to keep
657 when a new numbered backup is made. The newly made backup is
658 included in the count. The default value is 2.
660 - User Option: kept-old-versions
661 The value of this variable is the number of oldest versions to keep
662 when a new numbered backup is made. The default value is 2.
664 If there are backups numbered 1, 2, 3, 5, and 7, and both of these
665 variables have the value 2, then the backups numbered 1 and 2 are kept
666 as old versions and those numbered 5 and 7 are kept as new versions;
667 backup version 3 is excess. The function `find-backup-file-name'
668 (*note Backup Names::) is responsible for determining which backup
669 versions to delete, but does not delete them itself.
671 - User Option: delete-old-versions
672 If this variable is non-`nil', then saving a file deletes excess
673 backup versions silently. Otherwise, it asks the user whether to
676 - User Option: dired-kept-versions
677 This variable specifies how many of the newest backup versions to
678 keep in the Dired command `.' (`dired-clean-directory'). That's
679 the same thing `kept-new-versions' specifies when you make a new
680 backup file. The default value is 2.
683 File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
688 The functions in this section are documented mainly because you can
689 customize the naming conventions for backup files by redefining them.
690 If you change one, you probably need to change the rest.
692 - Function: backup-file-name-p filename
693 This function returns a non-`nil' value if FILENAME is a possible
694 name for a backup file. A file with the name FILENAME need not
695 exist; the function just checks the name.
697 (backup-file-name-p "foo")
699 (backup-file-name-p "foo~")
702 The standard definition of this function is as follows:
704 (defun backup-file-name-p (file)
705 "Return non-nil if FILE is a backup file \
706 name (numeric or not)..."
707 (string-match "~$" file))
709 Thus, the function returns a non-`nil' value if the file name ends
710 with a `~'. (We use a backslash to split the documentation
711 string's first line into two lines in the text, but produce just
712 one line in the string itself.)
714 This simple expression is placed in a separate function to make it
715 easy to redefine for customization.
717 - Function: make-backup-file-name filename
718 This function returns a string that is the name to use for a
719 non-numbered backup file for file FILENAME. On Unix, this is just
720 FILENAME with a tilde appended.
722 The standard definition of this function is as follows:
724 (defun make-backup-file-name (file)
725 "Create the non-numeric backup file name for FILE.
729 You can change the backup-file naming convention by redefining this
730 function. The following example redefines `make-backup-file-name'
731 to prepend a `.' in addition to appending a tilde:
733 (defun make-backup-file-name (filename)
734 (concat "." filename "~"))
736 (make-backup-file-name "backups.texi")
739 - Function: find-backup-file-name filename
740 This function computes the file name for a new backup file for
741 FILENAME. It may also propose certain existing backup files for
742 deletion. `find-backup-file-name' returns a list whose CAR is the
743 name for the new backup file and whose CDR is a list of backup
744 files whose deletion is proposed.
746 Two variables, `kept-old-versions' and `kept-new-versions',
747 determine which backup versions should be kept. This function
748 keeps those versions by excluding them from the CDR of the value.
749 *Note Numbered Backups::.
751 In this example, the value says that `~rms/foo.~5~' is the name to
752 use for the new backup file, and `~rms/foo.~3~' is an "excess"
753 version that the caller should consider deleting now.
755 (find-backup-file-name "~rms/foo")
756 => ("~rms/foo.~5~" "~rms/foo.~3~")
758 - Function: file-newest-backup filename
759 This function returns the name of the most recent backup file for
760 FILENAME, or `nil' if that file has no backup files.
762 Some file comparison commands use this function so that they can
763 automatically compare a file with its most recent backup.
766 File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
771 XEmacs periodically saves all files that you are visiting; this is
772 called "auto-saving". Auto-saving prevents you from losing more than a
773 limited amount of work if the system crashes. By default, auto-saves
774 happen every 300 keystrokes, or after around 30 seconds of idle time.
775 *Note Auto-Save: (emacs)Auto-Save, for information on auto-save for
776 users. Here we describe the functions used to implement auto-saving
777 and the variables that control them.
779 - Variable: buffer-auto-save-file-name
780 This buffer-local variable is the name of the file used for
781 auto-saving the current buffer. It is `nil' if the buffer should
784 buffer-auto-save-file-name
785 => "/xcssun/users/rms/lewis/#files.texi#"
787 - Command: auto-save-mode arg
788 When used interactively without an argument, this command is a
789 toggle switch: it turns on auto-saving of the current buffer if it
790 is off, and vice-versa. With an argument ARG, the command turns
791 auto-saving on if the value of ARG is `t', a nonempty list, or a
792 positive integer. Otherwise, it turns auto-saving off.
794 - Function: auto-save-file-name-p filename
795 This function returns a non-`nil' value if FILENAME is a string
796 that could be the name of an auto-save file. It works based on
797 knowledge of the naming convention for auto-save files: a name that
798 begins and ends with hash marks (`#') is a possible auto-save file
799 name. The argument FILENAME should not contain a directory part.
801 (make-auto-save-file-name)
802 => "/xcssun/users/rms/lewis/#files.texi#"
803 (auto-save-file-name-p "#files.texi#")
805 (auto-save-file-name-p "files.texi")
808 The standard definition of this function is as follows:
810 (defun auto-save-file-name-p (filename)
811 "Return non-nil if FILENAME can be yielded by..."
812 (string-match "^#.*#$" filename))
814 This function exists so that you can customize it if you wish to
815 change the naming convention for auto-save files. If you redefine
816 it, be sure to redefine the function `make-auto-save-file-name'
819 - Function: make-auto-save-file-name
820 This function returns the file name to use for auto-saving the
821 current buffer. This is just the file name with hash marks (`#')
822 appended and prepended to it. This function does not look at the
823 variable `auto-save-visited-file-name' (described below); you
824 should check that before calling this function.
826 (make-auto-save-file-name)
827 => "/xcssun/users/rms/lewis/#backup.texi#"
829 The standard definition of this function is as follows:
831 (defun make-auto-save-file-name ()
832 "Return file name to use for auto-saves \
837 (file-name-directory buffer-file-name)
839 (file-name-nondirectory buffer-file-name)
842 (concat "#%" (buffer-name) "#"))))
844 This exists as a separate function so that you can redefine it to
845 customize the naming convention for auto-save files. Be sure to
846 change `auto-save-file-name-p' in a corresponding way.
848 - Variable: auto-save-visited-file-name
849 If this variable is non-`nil', XEmacs auto-saves buffers in the
850 files they are visiting. That is, the auto-save is done in the
851 same file that you are editing. Normally, this variable is `nil',
852 so auto-save files have distinct names that are created by
853 `make-auto-save-file-name'.
855 When you change the value of this variable, the value does not take
856 effect until the next time auto-save mode is reenabled in any given
857 buffer. If auto-save mode is already enabled, auto-saves continue
858 to go in the same file name until `auto-save-mode' is called again.
860 - Function: recent-auto-save-p
861 This function returns `t' if the current buffer has been
862 auto-saved since the last time it was read in or saved.
864 - Function: set-buffer-auto-saved
865 This function marks the current buffer as auto-saved. The buffer
866 will not be auto-saved again until the buffer text is changed
867 again. The function returns `nil'.
869 - User Option: auto-save-interval
870 The value of this variable is the number of characters that XEmacs
871 reads from the keyboard between auto-saves. Each time this many
872 more characters are read, auto-saving is done for all buffers in
875 - User Option: auto-save-timeout
876 The value of this variable is the number of seconds of idle time
877 that should cause auto-saving. Each time the user pauses for this
878 long, XEmacs auto-saves any buffers that need it. (Actually, the
879 specified timeout is multiplied by a factor depending on the size
880 of the current buffer.)
882 - Variable: auto-save-hook
883 This normal hook is run whenever an auto-save is about to happen.
885 - User Option: auto-save-default
886 If this variable is non-`nil', buffers that are visiting files
887 have auto-saving enabled by default. Otherwise, they do not.
889 - Command: do-auto-save &optional no-message current-only
890 This function auto-saves all buffers that need to be auto-saved.
891 It saves all buffers for which auto-saving is enabled and that
892 have been changed since the previous auto-save.
894 Normally, if any buffers are auto-saved, a message that says
895 `Auto-saving...' is displayed in the echo area while auto-saving is
896 going on. However, if NO-MESSAGE is non-`nil', the message is
899 If CURRENT-ONLY is non-`nil', only the current buffer is
902 - Function: delete-auto-save-file-if-necessary
903 This function deletes the current buffer's auto-save file if
904 `delete-auto-save-files' is non-`nil'. It is called every time a
907 - Variable: delete-auto-save-files
908 This variable is used by the function
909 `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
910 deletes auto-save files when a true save is done (in the visited
911 file). This saves disk space and unclutters your directory.
913 - Function: rename-auto-save-file
914 This function adjusts the current buffer's auto-save file name if
915 the visited file name has changed. It also renames an existing
916 auto-save file. If the visited file name has not changed, this
917 function does nothing.
919 - Variable: buffer-saved-size
920 The value of this buffer-local variable is the length of the
921 current buffer as of the last time it was read in, saved, or
922 auto-saved. This is used to detect a substantial decrease in
923 size, and turn off auto-saving in response.
925 If it is -1, that means auto-saving is temporarily shut off in this
926 buffer due to a substantial deletion. Explicitly saving the buffer
927 stores a positive value in this variable, thus reenabling
928 auto-saving. Turning auto-save mode off or on also alters this
931 - Variable: auto-save-list-file-name
932 This variable (if non-`nil') specifies a file for recording the
933 names of all the auto-save files. Each time XEmacs does
934 auto-saving, it writes two lines into this file for each buffer
935 that has auto-saving enabled. The first line gives the name of
936 the visited file (it's empty if the buffer has none), and the
937 second gives the name of the auto-save file.
939 If XEmacs exits normally, it deletes this file. If XEmacs
940 crashes, you can look in the file to find all the auto-save files
941 that might contain work that was otherwise lost. The
942 `recover-session' command uses these files.
944 The default name for this file is in your home directory and
945 starts with `.saves-'. It also contains the XEmacs process ID and
949 File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
954 If you have made extensive changes to a file and then change your
955 mind about them, you can get rid of them by reading in the previous
956 version of the file with the `revert-buffer' command. *Note Reverting
957 a Buffer: (emacs)Reverting.
959 - Command: revert-buffer &optional check-auto-save noconfirm
960 This command replaces the buffer text with the text of the visited
961 file on disk. This action undoes all changes since the file was
964 If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
965 auto-save file is more recent than the visited file,
966 `revert-buffer' asks the user whether to use that instead.
967 Otherwise, it always uses the text of the visited file itself.
968 Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
971 Normally, `revert-buffer' asks for confirmation before it changes
972 the buffer; but if the argument NOCONFIRM is non-`nil',
973 `revert-buffer' does not ask for confirmation.
975 Reverting tries to preserve marker positions in the buffer by
976 using the replacement feature of `insert-file-contents'. If the
977 buffer contents and the file contents are identical before the
978 revert operation, reverting preserves all the markers. If they
979 are not identical, reverting does change the buffer; then it
980 preserves the markers in the unchanged text (if any) at the
981 beginning and end of the buffer. Preserving any additional
982 markers would be problematical.
984 You can customize how `revert-buffer' does its work by setting these
985 variables--typically, as buffer-local variables.
987 - Variable: revert-buffer-function
988 The value of this variable is the function to use to revert this
989 buffer. If non-`nil', it is called as a function with no
990 arguments to do the work of reverting. If the value is `nil',
991 reverting works the usual way.
993 Modes such as Dired mode, in which the text being edited does not
994 consist of a file's contents but can be regenerated in some other
995 fashion, give this variable a buffer-local value that is a
996 function to regenerate the contents.
998 - Variable: revert-buffer-insert-file-contents-function
999 The value of this variable, if non-`nil', is the function to use to
1000 insert the updated contents when reverting this buffer. The
1001 function receives two arguments: first the file name to use;
1002 second, `t' if the user has asked to read the auto-save file.
1004 - Variable: before-revert-hook
1005 This normal hook is run by `revert-buffer' before actually
1006 inserting the modified contents--but only if
1007 `revert-buffer-function' is `nil'.
1009 Font Lock mode uses this hook to record that the buffer contents
1010 are no longer fontified.
1012 - Variable: after-revert-hook
1013 This normal hook is run by `revert-buffer' after actually inserting
1014 the modified contents--but only if `revert-buffer-function' is
1017 Font Lock mode uses this hook to recompute the fonts for the
1018 updated buffer contents.
1021 File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
1026 A "buffer" is a Lisp object containing text to be edited. Buffers
1027 are used to hold the contents of files that are being visited; there may
1028 also be buffers that are not visiting files. While several buffers may
1029 exist at one time, exactly one buffer is designated the "current
1030 buffer" at any time. Most editing commands act on the contents of the
1031 current buffer. Each buffer, including the current buffer, may or may
1032 not be displayed in any windows.
1036 * Buffer Basics:: What is a buffer?
1037 * Current Buffer:: Designating a buffer as current
1038 so primitives will access its contents.
1039 * Buffer Names:: Accessing and changing buffer names.
1040 * Buffer File Name:: The buffer file name indicates which file is visited.
1041 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
1042 * Modification Time:: Determining whether the visited file was changed
1043 ``behind XEmacs's back''.
1044 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
1045 * The Buffer List:: How to look at all the existing buffers.
1046 * Creating Buffers:: Functions that create buffers.
1047 * Killing Buffers:: Buffers exist until explicitly killed.
1048 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
1051 File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
1056 A "buffer" is a Lisp object containing text to be edited. Buffers
1057 are used to hold the contents of files that are being visited; there may
1058 also be buffers that are not visiting files. While several buffers may
1059 exist at one time, exactly one buffer is designated the "current
1060 buffer" at any time. Most editing commands act on the contents of the
1061 current buffer. Each buffer, including the current buffer, may or may
1062 not be displayed in any windows.
1064 Buffers in Emacs editing are objects that have distinct names and
1065 hold text that can be edited. Buffers appear to Lisp programs as a
1066 special data type. You can think of the contents of a buffer as an
1067 extendable string; insertions and deletions may occur in any part of
1068 the buffer. *Note Text::.
1070 A Lisp buffer object contains numerous pieces of information. Some
1071 of this information is directly accessible to the programmer through
1072 variables, while other information is accessible only through
1073 special-purpose functions. For example, the visited file name is
1074 directly accessible through a variable, while the value of point is
1075 accessible only through a primitive function.
1077 Buffer-specific information that is directly accessible is stored in
1078 "buffer-local" variable bindings, which are variable values that are
1079 effective only in a particular buffer. This feature allows each buffer
1080 to override the values of certain variables. Most major modes override
1081 variables such as `fill-column' or `comment-column' in this way. For
1082 more information about buffer-local variables and functions related to
1083 them, see *Note Buffer-Local Variables::.
1085 For functions and variables related to visiting files in buffers, see
1086 *Note Visiting Files:: and *Note Saving Buffers::. For functions and
1087 variables related to the display of buffers in windows, see *Note
1088 Buffers and Windows::.
1090 - Function: bufferp object
1091 This function returns `t' if OBJECT is a buffer, `nil' otherwise.
projects / chise / xemacs-chise.git- / blob