1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
58 Emacs on MS-DOS makes a distinction between text files and binary
59 files. This is necessary because ordinary text files on MS-DOS use a
60 two character sequence between lines: carriage-return and linefeed
61 (CRLF). Emacs expects just a newline character (a linefeed) between
62 lines. When Emacs reads or writes a text file on MS-DOS, it needs to
63 convert the line separators. This means it needs to know which files
64 are text files and which are binary. It makes this decision when
65 visiting a file, and records the decision in the variable
66 `buffer-file-type' for use when the file is saved.
68 *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
70 - Variable: buffer-file-type
71 This variable, automatically local in each buffer, records the
72 file type of the buffer's visited file. The value is `nil' for
75 - Function: find-buffer-file-type FILENAME
76 This function determines whether file FILENAME is a text file or a
77 binary file. It returns `nil' for text, `t' for binary.
79 - User Option: file-name-buffer-file-type-alist
80 This variable holds an alist for distinguishing text files from
81 binary files. Each element has the form (REGEXP . TYPE), where
82 REGEXP is matched against the file name, and TYPE may be is `nil'
83 for text, `t' for binary, or a function to call to compute which.
84 If it is a function, then it is called with a single argument (the
85 file name) and should return `t' or `nil'.
87 - User Option: default-buffer-file-type
88 This variable specifies the default file type for files whose names
89 don't indicate anything in particular. Its value should be `nil'
90 for text, or `t' for binary.
92 - Command: find-file-text FILENAME
93 Like `find-file', but treat the file as text regardless of its
96 - Command: find-file-binary FILENAME
97 Like `find-file', but treat the file as binary regardless of its
101 File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
103 Backups and Auto-Saving
104 ***********************
106 Backup files and auto-save files are two methods by which XEmacs
107 tries to protect the user from the consequences of crashes or of the
108 user's own errors. Auto-saving preserves the text from earlier in the
109 current editing session; backup files preserve file contents prior to
114 * Backup Files:: How backup files are made; how their names are chosen.
115 * Auto-Saving:: How auto-save files are made; how their names are chosen.
116 * Reverting:: `revert-buffer', and how to customize what it does.
119 File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
124 A "backup file" is a copy of the old contents of a file you are
125 editing. XEmacs makes a backup file the first time you save a buffer
126 into its visited file. Normally, this means that the backup file
127 contains the contents of the file as it was before the current editing
128 session. The contents of the backup file normally remain unchanged once
131 Backups are usually made by renaming the visited file to a new name.
132 Optionally, you can specify that backup files should be made by copying
133 the visited file. This choice makes a difference for files with
134 multiple names; it also can affect whether the edited file remains owned
135 by the original owner or becomes owned by the user editing it.
137 By default, XEmacs makes a single backup file for each file edited.
138 You can alternatively request numbered backups; then each new backup
139 file gets a new name. You can delete old numbered backups when you
140 don't want them any more, or XEmacs can delete them automatically.
144 * Making Backups:: How XEmacs makes backup files, and when.
145 * Rename or Copy:: Two alternatives: renaming the old file or copying it.
146 * Numbered Backups:: Keeping multiple backups for each source file.
147 * Backup Names:: How backup file names are computed; customization.
150 File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
155 - Function: backup-buffer
156 This function makes a backup of the file visited by the current
157 buffer, if appropriate. It is called by `save-buffer' before
158 saving the buffer the first time.
160 - Variable: buffer-backed-up
161 This buffer-local variable indicates whether this buffer's file has
162 been backed up on account of this buffer. If it is non-`nil', then
163 the backup file has been written. Otherwise, the file should be
164 backed up when it is next saved (if backups are enabled). This is
165 a permanent local; `kill-local-variables' does not alter it.
167 - User Option: make-backup-files
168 This variable determines whether or not to make backup files. If
169 it is non-`nil', then XEmacs creates a backup of each file when it
170 is saved for the first time--provided that `backup-inhibited' is
173 The following example shows how to change the `make-backup-files'
174 variable only in the `RMAIL' buffer and not elsewhere. Setting it
175 `nil' stops XEmacs from making backups of the `RMAIL' file, which
176 may save disk space. (You would put this code in your `.emacs'
179 (add-hook 'rmail-mode-hook
183 (setq make-backup-files nil))))
185 - Variable: backup-enable-predicate
186 This variable's value is a function to be called on certain
187 occasions to decide whether a file should have backup files. The
188 function receives one argument, a file name to consider. If the
189 function returns `nil', backups are disabled for that file.
190 Otherwise, the other variables in this section say whether and how
193 The default value is this:
196 (or (< (length name) 5)
197 (not (string-equal "/tmp/"
198 (substring name 0 5)))))
200 - Variable: backup-inhibited
201 If this variable is non-`nil', backups are inhibited. It records
202 the result of testing `backup-enable-predicate' on the visited file
203 name. It can also coherently be used by other mechanisms that
204 inhibit backups based on which file is visited. For example, VC
205 sets this variable non-`nil' to prevent making backups for files
206 managed with a version control system.
208 This is a permanent local, so that changing the major mode does
209 not lose its value. Major modes should not set this
210 variable--they should set `make-backup-files' instead.
213 File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
215 Backup by Renaming or by Copying?
216 ---------------------------------
218 There are two ways that XEmacs can make a backup file:
220 * XEmacs can rename the original file so that it becomes a backup
221 file, and then write the buffer being saved into a new file.
222 After this procedure, any other names (i.e., hard links) of the
223 original file now refer to the backup file. The new file is owned
224 by the user doing the editing, and its group is the default for
225 new files written by the user in that directory.
227 * XEmacs can copy the original file into a backup file, and then
228 overwrite the original file with new contents. After this
229 procedure, any other names (i.e., hard links) of the original file
230 still refer to the current version of the file. The file's owner
231 and group will be unchanged.
233 The first method, renaming, is the default.
235 The variable `backup-by-copying', if non-`nil', says to use the
236 second method, which is to copy the original file and overwrite it with
237 the new buffer contents. The variable `file-precious-flag', if
238 non-`nil', also has this effect (as a sideline of its main
239 significance). *Note Saving Buffers::.
241 - Variable: backup-by-copying
242 If this variable is non-`nil', XEmacs always makes backup files by
245 The following two variables, when non-`nil', cause the second method
246 to be used in certain special cases. They have no effect on the
247 treatment of files that don't fall into the special cases.
249 - Variable: backup-by-copying-when-linked
250 If this variable is non-`nil', XEmacs makes backups by copying for
251 files with multiple names (hard links).
253 This variable is significant only if `backup-by-copying' is `nil',
254 since copying is always used when that variable is non-`nil'.
256 - Variable: backup-by-copying-when-mismatch
257 If this variable is non-`nil', XEmacs makes backups by copying in
258 cases where renaming would change either the owner or the group of
261 The value has no effect when renaming would not alter the owner or
262 group of the file; that is, for files which are owned by the user
263 and whose group matches the default for a new file created there
266 This variable is significant only if `backup-by-copying' is `nil',
267 since copying is always used when that variable is non-`nil'.
270 File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
272 Making and Deleting Numbered Backup Files
273 -----------------------------------------
275 If a file's name is `foo', the names of its numbered backup versions
276 are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
277 `foo.~3~', ..., `foo.~259~', and so on.
279 - User Option: version-control
280 This variable controls whether to make a single non-numbered backup
281 file or multiple numbered backups.
284 Make numbered backups if the visited file already has
285 numbered backups; otherwise, do not.
288 Do not make numbered backups.
291 Make numbered backups.
293 The use of numbered backups ultimately leads to a large number of
294 backup versions, which must then be deleted. XEmacs can do this
295 automatically or it can ask the user whether to delete them.
297 - User Option: kept-new-versions
298 The value of this variable is the number of newest versions to keep
299 when a new numbered backup is made. The newly made backup is
300 included in the count. The default value is 2.
302 - User Option: kept-old-versions
303 The value of this variable is the number of oldest versions to keep
304 when a new numbered backup is made. The default value is 2.
306 If there are backups numbered 1, 2, 3, 5, and 7, and both of these
307 variables have the value 2, then the backups numbered 1 and 2 are kept
308 as old versions and those numbered 5 and 7 are kept as new versions;
309 backup version 3 is excess. The function `find-backup-file-name'
310 (*note Backup Names::.) is responsible for determining which backup
311 versions to delete, but does not delete them itself.
313 - User Option: trim-versions-without-asking
314 If this variable is non-`nil', then saving a file deletes excess
315 backup versions silently. Otherwise, it asks the user whether to
318 - User Option: dired-kept-versions
319 This variable specifies how many of the newest backup versions to
320 keep in the Dired command `.' (`dired-clean-directory'). That's
321 the same thing `kept-new-versions' specifies when you make a new
322 backup file. The default value is 2.
325 File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
330 The functions in this section are documented mainly because you can
331 customize the naming conventions for backup files by redefining them.
332 If you change one, you probably need to change the rest.
334 - Function: backup-file-name-p FILENAME
335 This function returns a non-`nil' value if FILENAME is a possible
336 name for a backup file. A file with the name FILENAME need not
337 exist; the function just checks the name.
339 (backup-file-name-p "foo")
342 (backup-file-name-p "foo~")
345 The standard definition of this function is as follows:
347 (defun backup-file-name-p (file)
348 "Return non-nil if FILE is a backup file \
349 name (numeric or not)..."
350 (string-match "~$" file))
352 Thus, the function returns a non-`nil' value if the file name ends
353 with a `~'. (We use a backslash to split the documentation
354 string's first line into two lines in the text, but produce just
355 one line in the string itself.)
357 This simple expression is placed in a separate function to make it
358 easy to redefine for customization.
360 - Function: make-backup-file-name FILENAME
361 This function returns a string that is the name to use for a
362 non-numbered backup file for file FILENAME. On Unix, this is just
363 FILENAME with a tilde appended.
365 The standard definition of this function is as follows:
367 (defun make-backup-file-name (file)
368 "Create the non-numeric backup file name for FILE.
372 You can change the backup-file naming convention by redefining this
373 function. The following example redefines `make-backup-file-name'
374 to prepend a `.' in addition to appending a tilde:
376 (defun make-backup-file-name (filename)
377 (concat "." filename "~"))
379 (make-backup-file-name "backups.texi")
382 - Function: find-backup-file-name FILENAME
383 This function computes the file name for a new backup file for
384 FILENAME. It may also propose certain existing backup files for
385 deletion. `find-backup-file-name' returns a list whose CAR is the
386 name for the new backup file and whose CDR is a list of backup
387 files whose deletion is proposed.
389 Two variables, `kept-old-versions' and `kept-new-versions',
390 determine which backup versions should be kept. This function
391 keeps those versions by excluding them from the CDR of the value.
392 *Note Numbered Backups::.
394 In this example, the value says that `~rms/foo.~5~' is the name to
395 use for the new backup file, and `~rms/foo.~3~' is an "excess"
396 version that the caller should consider deleting now.
398 (find-backup-file-name "~rms/foo")
399 => ("~rms/foo.~5~" "~rms/foo.~3~")
401 - Function: file-newest-backup FILENAME
402 This function returns the name of the most recent backup file for
403 FILENAME, or `nil' if that file has no backup files.
405 Some file comparison commands use this function so that they can
406 automatically compare a file with its most recent backup.
409 File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
414 XEmacs periodically saves all files that you are visiting; this is
415 called "auto-saving". Auto-saving prevents you from losing more than a
416 limited amount of work if the system crashes. By default, auto-saves
417 happen every 300 keystrokes, or after around 30 seconds of idle time.
418 *Note Auto-Save: (emacs)Auto-Save, for information on auto-save for
419 users. Here we describe the functions used to implement auto-saving
420 and the variables that control them.
422 - Variable: buffer-auto-save-file-name
423 This buffer-local variable is the name of the file used for
424 auto-saving the current buffer. It is `nil' if the buffer should
427 buffer-auto-save-file-name
428 => "/xcssun/users/rms/lewis/#files.texi#"
430 - Command: auto-save-mode ARG
431 When used interactively without an argument, this command is a
432 toggle switch: it turns on auto-saving of the current buffer if it
433 is off, and vice-versa. With an argument ARG, the command turns
434 auto-saving on if the value of ARG is `t', a nonempty list, or a
435 positive integer. Otherwise, it turns auto-saving off.
437 - Function: auto-save-file-name-p FILENAME
438 This function returns a non-`nil' value if FILENAME is a string
439 that could be the name of an auto-save file. It works based on
440 knowledge of the naming convention for auto-save files: a name that
441 begins and ends with hash marks (`#') is a possible auto-save file
442 name. The argument FILENAME should not contain a directory part.
444 (make-auto-save-file-name)
445 => "/xcssun/users/rms/lewis/#files.texi#"
446 (auto-save-file-name-p "#files.texi#")
448 (auto-save-file-name-p "files.texi")
451 The standard definition of this function is as follows:
453 (defun auto-save-file-name-p (filename)
454 "Return non-nil if FILENAME can be yielded by..."
455 (string-match "^#.*#$" filename))
457 This function exists so that you can customize it if you wish to
458 change the naming convention for auto-save files. If you redefine
459 it, be sure to redefine the function `make-auto-save-file-name'
462 - Function: make-auto-save-file-name
463 This function returns the file name to use for auto-saving the
464 current buffer. This is just the file name with hash marks (`#')
465 appended and prepended to it. This function does not look at the
466 variable `auto-save-visited-file-name' (described below); you
467 should check that before calling this function.
469 (make-auto-save-file-name)
470 => "/xcssun/users/rms/lewis/#backup.texi#"
472 The standard definition of this function is as follows:
474 (defun make-auto-save-file-name ()
475 "Return file name to use for auto-saves \
480 (file-name-directory buffer-file-name)
482 (file-name-nondirectory buffer-file-name)
485 (concat "#%" (buffer-name) "#"))))
487 This exists as a separate function so that you can redefine it to
488 customize the naming convention for auto-save files. Be sure to
489 change `auto-save-file-name-p' in a corresponding way.
491 - Variable: auto-save-visited-file-name
492 If this variable is non-`nil', XEmacs auto-saves buffers in the
493 files they are visiting. That is, the auto-save is done in the
494 same file that you are editing. Normally, this variable is `nil',
495 so auto-save files have distinct names that are created by
496 `make-auto-save-file-name'.
498 When you change the value of this variable, the value does not take
499 effect until the next time auto-save mode is reenabled in any given
500 buffer. If auto-save mode is already enabled, auto-saves continue
501 to go in the same file name until `auto-save-mode' is called again.
503 - Function: recent-auto-save-p
504 This function returns `t' if the current buffer has been
505 auto-saved since the last time it was read in or saved.
507 - Function: set-buffer-auto-saved
508 This function marks the current buffer as auto-saved. The buffer
509 will not be auto-saved again until the buffer text is changed
510 again. The function returns `nil'.
512 - User Option: auto-save-interval
513 The value of this variable is the number of characters that XEmacs
514 reads from the keyboard between auto-saves. Each time this many
515 more characters are read, auto-saving is done for all buffers in
518 - User Option: auto-save-timeout
519 The value of this variable is the number of seconds of idle time
520 that should cause auto-saving. Each time the user pauses for this
521 long, XEmacs auto-saves any buffers that need it. (Actually, the
522 specified timeout is multiplied by a factor depending on the size
523 of the current buffer.)
525 - Variable: auto-save-hook
526 This normal hook is run whenever an auto-save is about to happen.
528 - User Option: auto-save-default
529 If this variable is non-`nil', buffers that are visiting files
530 have auto-saving enabled by default. Otherwise, they do not.
532 - Command: do-auto-save &optional NO-MESSAGE CURRENT-ONLY
533 This function auto-saves all buffers that need to be auto-saved.
534 It saves all buffers for which auto-saving is enabled and that
535 have been changed since the previous auto-save.
537 Normally, if any buffers are auto-saved, a message that says
538 `Auto-saving...' is displayed in the echo area while auto-saving is
539 going on. However, if NO-MESSAGE is non-`nil', the message is
542 If CURRENT-ONLY is non-`nil', only the current buffer is
545 - Function: delete-auto-save-file-if-necessary
546 This function deletes the current buffer's auto-save file if
547 `delete-auto-save-files' is non-`nil'. It is called every time a
550 - Variable: delete-auto-save-files
551 This variable is used by the function
552 `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
553 deletes auto-save files when a true save is done (in the visited
554 file). This saves disk space and unclutters your directory.
556 - Function: rename-auto-save-file
557 This function adjusts the current buffer's auto-save file name if
558 the visited file name has changed. It also renames an existing
559 auto-save file. If the visited file name has not changed, this
560 function does nothing.
562 - Variable: buffer-saved-size
563 The value of this buffer-local variable is the length of the
564 current buffer as of the last time it was read in, saved, or
565 auto-saved. This is used to detect a substantial decrease in
566 size, and turn off auto-saving in response.
568 If it is -1, that means auto-saving is temporarily shut off in this
569 buffer due to a substantial deletion. Explicitly saving the buffer
570 stores a positive value in this variable, thus reenabling
571 auto-saving. Turning auto-save mode off or on also alters this
574 - Variable: auto-save-list-file-name
575 This variable (if non-`nil') specifies a file for recording the
576 names of all the auto-save files. Each time XEmacs does
577 auto-saving, it writes two lines into this file for each buffer
578 that has auto-saving enabled. The first line gives the name of
579 the visited file (it's empty if the buffer has none), and the
580 second gives the name of the auto-save file.
582 If XEmacs exits normally, it deletes this file. If XEmacs
583 crashes, you can look in the file to find all the auto-save files
584 that might contain work that was otherwise lost. The
585 `recover-session' command uses these files.
587 The default name for this file is in your home directory and
588 starts with `.saves-'. It also contains the XEmacs process ID and
592 File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
597 If you have made extensive changes to a file and then change your
598 mind about them, you can get rid of them by reading in the previous
599 version of the file with the `revert-buffer' command. *Note Reverting
600 a Buffer: (emacs)Reverting.
602 - Command: revert-buffer &optional CHECK-AUTO-SAVE NOCONFIRM
603 This command replaces the buffer text with the text of the visited
604 file on disk. This action undoes all changes since the file was
607 If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
608 auto-save file is more recent than the visited file,
609 `revert-buffer' asks the user whether to use that instead.
610 Otherwise, it always uses the text of the visited file itself.
611 Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
614 Normally, `revert-buffer' asks for confirmation before it changes
615 the buffer; but if the argument NOCONFIRM is non-`nil',
616 `revert-buffer' does not ask for confirmation.
618 Reverting tries to preserve marker positions in the buffer by
619 using the replacement feature of `insert-file-contents'. If the
620 buffer contents and the file contents are identical before the
621 revert operation, reverting preserves all the markers. If they
622 are not identical, reverting does change the buffer; then it
623 preserves the markers in the unchanged text (if any) at the
624 beginning and end of the buffer. Preserving any additional
625 markers would be problematical.
627 You can customize how `revert-buffer' does its work by setting these
628 variables--typically, as buffer-local variables.
630 - Variable: revert-buffer-function
631 The value of this variable is the function to use to revert this
632 buffer. If non-`nil', it is called as a function with no
633 arguments to do the work of reverting. If the value is `nil',
634 reverting works the usual way.
636 Modes such as Dired mode, in which the text being edited does not
637 consist of a file's contents but can be regenerated in some other
638 fashion, give this variable a buffer-local value that is a
639 function to regenerate the contents.
641 - Variable: revert-buffer-insert-file-contents-function
642 The value of this variable, if non-`nil', is the function to use to
643 insert the updated contents when reverting this buffer. The
644 function receives two arguments: first the file name to use;
645 second, `t' if the user has asked to read the auto-save file.
647 - Variable: before-revert-hook
648 This normal hook is run by `revert-buffer' before actually
649 inserting the modified contents--but only if
650 `revert-buffer-function' is `nil'.
652 Font Lock mode uses this hook to record that the buffer contents
653 are no longer fontified.
655 - Variable: after-revert-hook
656 This normal hook is run by `revert-buffer' after actually inserting
657 the modified contents--but only if `revert-buffer-function' is
660 Font Lock mode uses this hook to recompute the fonts for the
661 updated buffer contents.
664 File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
669 A "buffer" is a Lisp object containing text to be edited. Buffers
670 are used to hold the contents of files that are being visited; there may
671 also be buffers that are not visiting files. While several buffers may
672 exist at one time, exactly one buffer is designated the "current
673 buffer" at any time. Most editing commands act on the contents of the
674 current buffer. Each buffer, including the current buffer, may or may
675 not be displayed in any windows.
679 * Buffer Basics:: What is a buffer?
680 * Current Buffer:: Designating a buffer as current
681 so primitives will access its contents.
682 * Buffer Names:: Accessing and changing buffer names.
683 * Buffer File Name:: The buffer file name indicates which file is visited.
684 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
685 * Modification Time:: Determining whether the visited file was changed
686 "behind XEmacs's back".
687 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
688 * The Buffer List:: How to look at all the existing buffers.
689 * Creating Buffers:: Functions that create buffers.
690 * Killing Buffers:: Buffers exist until explicitly killed.
691 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
694 File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
699 A "buffer" is a Lisp object containing text to be edited. Buffers
700 are used to hold the contents of files that are being visited; there may
701 also be buffers that are not visiting files. While several buffers may
702 exist at one time, exactly one buffer is designated the "current
703 buffer" at any time. Most editing commands act on the contents of the
704 current buffer. Each buffer, including the current buffer, may or may
705 not be displayed in any windows.
707 Buffers in Emacs editing are objects that have distinct names and
708 hold text that can be edited. Buffers appear to Lisp programs as a
709 special data type. You can think of the contents of a buffer as an
710 extendable string; insertions and deletions may occur in any part of
711 the buffer. *Note Text::.
713 A Lisp buffer object contains numerous pieces of information. Some
714 of this information is directly accessible to the programmer through
715 variables, while other information is accessible only through
716 special-purpose functions. For example, the visited file name is
717 directly accessible through a variable, while the value of point is
718 accessible only through a primitive function.
720 Buffer-specific information that is directly accessible is stored in
721 "buffer-local" variable bindings, which are variable values that are
722 effective only in a particular buffer. This feature allows each buffer
723 to override the values of certain variables. Most major modes override
724 variables such as `fill-column' or `comment-column' in this way. For
725 more information about buffer-local variables and functions related to
726 them, see *Note Buffer-Local Variables::.
728 For functions and variables related to visiting files in buffers, see
729 *Note Visiting Files:: and *Note Saving Buffers::. For functions and
730 variables related to the display of buffers in windows, see *Note
731 Buffers and Windows::.
733 - Function: bufferp OBJECT
734 This function returns `t' if OBJECT is a buffer, `nil' otherwise.
737 File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
742 There are, in general, many buffers in an Emacs session. At any
743 time, one of them is designated as the "current buffer". This is the
744 buffer in which most editing takes place, because most of the primitives
745 for examining or changing text in a buffer operate implicitly on the
746 current buffer (*note Text::.). Normally the buffer that is displayed
747 on the screen in the selected window is the current buffer, but this is
748 not always so: a Lisp program can designate any buffer as current
749 temporarily in order to operate on its contents, without changing what
750 is displayed on the screen.
752 The way to designate a current buffer in a Lisp program is by calling
753 `set-buffer'. The specified buffer remains current until a new one is
756 When an editing command returns to the editor command loop, the
757 command loop designates the buffer displayed in the selected window as
758 current, to prevent confusion: the buffer that the cursor is in when
759 Emacs reads a command is the buffer that the command will apply to.
760 (*Note Command Loop::.) Therefore, `set-buffer' is not the way to
761 switch visibly to a different buffer so that the user can edit it. For
762 this, you must use the functions described in *Note Displaying
765 However, Lisp functions that change to a different current buffer
766 should not depend on the command loop to set it back afterwards.
767 Editing commands written in XEmacs Lisp can be called from other
768 programs as well as from the command loop. It is convenient for the
769 caller if the subroutine does not change which buffer is current
770 (unless, of course, that is the subroutine's purpose). Therefore, you
771 should normally use `set-buffer' within a `save-excursion' that will
772 restore the current buffer when your function is done (*note
773 Excursions::.). Here is an example, the code for the command
774 `append-to-buffer' (with the documentation string abridged):
776 (defun append-to-buffer (buffer start end)
777 "Append to specified buffer the text of the region.
779 (interactive "BAppend to buffer: \nr")
780 (let ((oldbuf (current-buffer)))
782 (set-buffer (get-buffer-create buffer))
783 (insert-buffer-substring oldbuf start end))))
785 This function binds a local variable to the current buffer, and then
786 `save-excursion' records the values of point, the mark, and the
787 original buffer. Next, `set-buffer' makes another buffer current.
788 Finally, `insert-buffer-substring' copies the string from the original
789 current buffer to the new current buffer.
791 If the buffer appended to happens to be displayed in some window,
792 the next redisplay will show how its text has changed. Otherwise, you
793 will not see the change immediately on the screen. The buffer becomes
794 current temporarily during the execution of the command, but this does
795 not cause it to be displayed.
797 If you make local bindings (with `let' or function arguments) for a
798 variable that may also have buffer-local bindings, make sure that the
799 same buffer is current at the beginning and at the end of the local
800 binding's scope. Otherwise you might bind it in one buffer and unbind
801 it in another! There are two ways to do this. In simple cases, you may
802 see that nothing ever changes the current buffer within the scope of the
803 binding. Otherwise, use `save-excursion' to make sure that the buffer
804 current at the beginning is current again whenever the variable is
807 It is not reliable to change the current buffer back with
808 `set-buffer', because that won't do the job if a quit happens while the
809 wrong buffer is current. Here is what *not* to do:
811 (let (buffer-read-only
812 (obuf (current-buffer)))
817 Using `save-excursion', as shown below, handles quitting, errors, and
818 `throw', as well as ordinary evaluation.
820 (let (buffer-read-only)
825 - Function: current-buffer
826 This function returns the current buffer.
829 => #<buffer buffers.texi>
831 - Function: set-buffer BUFFER-OR-NAME
832 This function makes BUFFER-OR-NAME the current buffer. It does
833 not display the buffer in the currently selected window or in any
834 other window, so the user cannot necessarily see the buffer. But
835 Lisp programs can in any case work on it.
837 This function returns the buffer identified by BUFFER-OR-NAME. An
838 error is signaled if BUFFER-OR-NAME does not identify an existing
842 File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
847 Each buffer has a unique name, which is a string. Many of the
848 functions that work on buffers accept either a buffer or a buffer name
849 as an argument. Any argument called BUFFER-OR-NAME is of this sort,
850 and an error is signaled if it is neither a string nor a buffer. Any
851 argument called BUFFER must be an actual buffer object, not a name.
853 Buffers that are ephemeral and generally uninteresting to the user
854 have names starting with a space, so that the `list-buffers' and
855 `buffer-menu' commands don't mention them. A name starting with space
856 also initially disables recording undo information; see *Note Undo::.
858 - Function: buffer-name &optional BUFFER
859 This function returns the name of BUFFER as a string. If BUFFER
860 is not supplied, it defaults to the current buffer.
862 If `buffer-name' returns `nil', it means that BUFFER has been
863 killed. *Note Killing Buffers::.
868 (setq foo (get-buffer "temp"))
877 - Command: rename-buffer NEWNAME &optional UNIQUE
878 This function renames the current buffer to NEWNAME. An error is
879 signaled if NEWNAME is not a string, or if there is already a
880 buffer with that name. The function returns `nil'.
882 Ordinarily, `rename-buffer' signals an error if NEWNAME is already
883 in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
884 make a name that is not in use. Interactively, you can make
885 UNIQUE non-`nil' with a numeric prefix argument.
887 One application of this command is to rename the `*shell*' buffer
888 to some other name, thus making it possible to create a second
889 shell buffer under the name `*shell*'.
891 - Function: get-buffer BUFFER-OR-NAME
892 This function returns the buffer specified by BUFFER-OR-NAME. If
893 BUFFER-OR-NAME is a string and there is no buffer with that name,
894 the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
895 as given. (That is not very useful, so the argument is usually a
898 (setq b (get-buffer "lewis"))
902 (get-buffer "Frazzle-nots")
905 See also the function `get-buffer-create' in *Note Creating
908 - Function: generate-new-buffer-name STARTING-NAME &optional IGNORE
909 This function returns a name that would be unique for a new
910 buffer--but does not create the buffer. It starts with
911 STARTING-NAME, and produces a name not currently in use for any
912 buffer by appending a number inside of `<...>'.
914 If IGNORE is given, it specifies a name that is okay to use (if it
915 is in the sequence to be tried), even if a buffer with that name
918 See the related function `generate-new-buffer' in *Note Creating
922 File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
927 The "buffer file name" is the name of the file that is visited in
928 that buffer. When a buffer is not visiting a file, its buffer file name
929 is `nil'. Most of the time, the buffer name is the same as the
930 nondirectory part of the buffer file name, but the buffer file name and
931 the buffer name are distinct and can be set independently. *Note
934 - Function: buffer-file-name &optional BUFFER
935 This function returns the absolute file name of the file that
936 BUFFER is visiting. If BUFFER is not visiting any file,
937 `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
938 defaults to the current buffer.
940 (buffer-file-name (other-buffer))
941 => "/usr/user/lewis/manual/files.texi"
943 - Variable: buffer-file-name
944 This buffer-local variable contains the name of the file being
945 visited in the current buffer, or `nil' if it is not visiting a
946 file. It is a permanent local, unaffected by
947 `kill-local-variables'.
950 => "/usr/user/lewis/manual/buffers.texi"
952 It is risky to change this variable's value without doing various
953 other things. See the definition of `set-visited-file-name' in
954 `files.el'; some of the things done there, such as changing the
955 buffer name, are not strictly necessary, but others are essential
956 to avoid confusing XEmacs.
958 - Variable: buffer-file-truename
959 This buffer-local variable holds the truename of the file visited
960 in the current buffer, or `nil' if no file is visited. It is a
961 permanent local, unaffected by `kill-local-variables'. *Note
964 - Variable: buffer-file-number
965 This buffer-local variable holds the file number and directory
966 device number of the file visited in the current buffer, or `nil'
967 if no file or a nonexistent file is visited. It is a permanent
968 local, unaffected by `kill-local-variables'. *Note Truenames::.
970 The value is normally a list of the form `(FILENUM DEVNUM)'. This
971 pair of numbers uniquely identifies the file among all files
972 accessible on the system. See the function `file-attributes', in
973 *Note File Attributes::, for more information about them.
975 - Function: get-file-buffer FILENAME
976 This function returns the buffer visiting file FILENAME. If there
977 is no such buffer, it returns `nil'. The argument FILENAME, which
978 must be a string, is expanded (*note File Name Expansion::.), then
979 compared against the visited file names of all live buffers.
981 (get-file-buffer "buffers.texi")
982 => #<buffer buffers.texi>
984 In unusual circumstances, there can be more than one buffer
985 visiting the same file name. In such cases, this function returns
986 the first such buffer in the buffer list.
988 - Command: set-visited-file-name FILENAME
989 If FILENAME is a non-empty string, this function changes the name
990 of the file visited in current buffer to FILENAME. (If the buffer
991 had no visited file, this gives it one.) The *next time* the
992 buffer is saved it will go in the newly-specified file. This
993 command marks the buffer as modified, since it does not (as far as
994 XEmacs knows) match the contents of FILENAME, even if it matched
995 the former visited file.
997 If FILENAME is `nil' or the empty string, that stands for "no
998 visited file". In this case, `set-visited-file-name' marks the
999 buffer as having no visited file.
1001 When the function `set-visited-file-name' is called interactively,
1002 it prompts for FILENAME in the minibuffer.
1004 See also `clear-visited-file-modtime' and
1005 `verify-visited-file-modtime' in *Note Buffer Modification::.
1007 - Variable: list-buffers-directory
1008 This buffer-local variable records a string to display in a buffer
1009 listing in place of the visited file name, for buffers that don't
1010 have a visited file name. Dired buffers use this variable.
1013 File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
1018 XEmacs keeps a flag called the "modified flag" for each buffer, to
1019 record whether you have changed the text of the buffer. This flag is
1020 set to `t' whenever you alter the contents of the buffer, and cleared
1021 to `nil' when you save it. Thus, the flag shows whether there are
1022 unsaved changes. The flag value is normally shown in the modeline
1023 (*note Modeline Variables::.), and controls saving (*note Saving
1024 Buffers::.) and auto-saving (*note Auto-Saving::.).
1026 Some Lisp programs set the flag explicitly. For example, the
1027 function `set-visited-file-name' sets the flag to `t', because the text
1028 does not match the newly-visited file, even if it is unchanged from the
1029 file formerly visited.
1031 The functions that modify the contents of buffers are described in
1034 - Function: buffer-modified-p &optional BUFFER
1035 This function returns `t' if the buffer BUFFER has been modified
1036 since it was last read in from a file or saved, or `nil'
1037 otherwise. If BUFFER is not supplied, the current buffer is
1040 - Function: set-buffer-modified-p FLAG
1041 This function marks the current buffer as modified if FLAG is
1042 non-`nil', or as unmodified if the flag is `nil'.
1044 Another effect of calling this function is to cause unconditional
1045 redisplay of the modeline for the current buffer. In fact, the
1046 function `redraw-modeline' works by doing this:
1048 (set-buffer-modified-p (buffer-modified-p))
1050 - Command: not-modified &optional ARG
1051 This command marks the current buffer as unmodified, and not
1052 needing to be saved. (If ARG is non-`nil', the buffer is instead
1053 marked as modified.) Don't use this function in programs, since it
1054 prints a message in the echo area; use `set-buffer-modified-p'
1057 - Function: buffer-modified-tick &optional BUFFER
1058 This function returns BUFFER`s modification-count. This is a
1059 counter that increments every time the buffer is modified. If
1060 BUFFER is `nil' (or omitted), the current buffer is used.
1063 File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
1065 Comparison of Modification Time
1066 ===============================
1068 Suppose that you visit a file and make changes in its buffer, and
1069 meanwhile the file itself is changed on disk. At this point, saving the
1070 buffer would overwrite the changes in the file. Occasionally this may
1071 be what you want, but usually it would lose valuable information.
1072 XEmacs therefore checks the file's modification time using the functions
1073 described below before saving the file.
1075 - Function: verify-visited-file-modtime BUFFER
1076 This function compares what BUFFER has recorded for the
1077 modification time of its visited file against the actual
1078 modification time of the file as recorded by the operating system.
1079 The two should be the same unless some other process has written
1080 the file since XEmacs visited or saved it.
1082 The function returns `t' if the last actual modification time and
1083 XEmacs's recorded modification time are the same, `nil' otherwise.
1085 - Function: clear-visited-file-modtime
1086 This function clears out the record of the last modification time
1087 of the file being visited by the current buffer. As a result, the
1088 next attempt to save this buffer will not complain of a
1089 discrepancy in file modification times.
1091 This function is called in `set-visited-file-name' and other
1092 exceptional places where the usual test to avoid overwriting a
1093 changed file should not be done.
1095 - Function: visited-file-modtime
1096 This function returns the buffer's recorded last file modification
1097 time, as a list of the form `(HIGH . LOW)'. (This is the same
1098 format that `file-attributes' uses to return time values; see
1099 *Note File Attributes::.)
1101 - Function: set-visited-file-modtime &optional TIME
1102 This function updates the buffer's record of the last modification
1103 time of the visited file, to the value specified by TIME if TIME
1104 is not `nil', and otherwise to the last modification time of the
1107 If TIME is not `nil', it should have the form `(HIGH . LOW)' or
1108 `(HIGH LOW)', in either case containing two integers, each of
1109 which holds 16 bits of the time.
1111 This function is useful if the buffer was not read from the file
1112 normally, or if the file itself has been changed for some known
1115 - Function: ask-user-about-supersession-threat FILENAME
1116 This function is used to ask a user how to proceed after an
1117 attempt to modify an obsolete buffer visiting file FILENAME. An
1118 "obsolete buffer" is an unmodified buffer for which the associated
1119 file on disk is newer than the last save-time of the buffer. This
1120 means some other program has probably altered the file.
1122 Depending on the user's answer, the function may return normally,
1123 in which case the modification of the buffer proceeds, or it may
1124 signal a `file-supersession' error with data `(FILENAME)', in which
1125 case the proposed buffer modification is not allowed.
1127 This function is called automatically by XEmacs on the proper
1128 occasions. It exists so you can customize XEmacs by redefining it.
1129 See the file `userlock.el' for the standard definition.
1131 See also the file locking mechanism in *Note File Locks::.
1134 File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
1139 If a buffer is "read-only", then you cannot change its contents,
1140 although you may change your view of the contents by scrolling and
1143 Read-only buffers are used in two kinds of situations:
1145 * A buffer visiting a write-protected file is normally read-only.
1147 Here, the purpose is to show the user that editing the buffer with
1148 the aim of saving it in the file may be futile or undesirable.
1149 The user who wants to change the buffer text despite this can do
1150 so after clearing the read-only flag with `C-x C-q'.
1152 * Modes such as Dired and Rmail make buffers read-only when altering
1153 the contents with the usual editing commands is probably a mistake.
1155 The special commands of these modes bind `buffer-read-only' to
1156 `nil' (with `let') or bind `inhibit-read-only' to `t' around the
1157 places where they change the text.
1159 - Variable: buffer-read-only
1160 This buffer-local variable specifies whether the buffer is
1161 read-only. The buffer is read-only if this variable is non-`nil'.
1163 - Variable: inhibit-read-only
1164 If this variable is non-`nil', then read-only buffers and read-only
1165 characters may be modified. Read-only characters in a buffer are
1166 those that have non-`nil' `read-only' properties (either text
1167 properties or extent properties). *Note Extent Properties::, for
1168 more information about text properties and extent properties.
1170 If `inhibit-read-only' is `t', all `read-only' character
1171 properties have no effect. If `inhibit-read-only' is a list, then
1172 `read-only' character properties have no effect if they are members
1173 of the list (comparison is done with `eq').
1175 - Command: toggle-read-only
1176 This command changes whether the current buffer is read-only. It
1177 is intended for interactive use; don't use it in programs. At any
1178 given point in a program, you should know whether you want the
1179 read-only flag on or off; so you can set `buffer-read-only'
1180 explicitly to the proper value, `t' or `nil'.
1182 - Function: barf-if-buffer-read-only
1183 This function signals a `buffer-read-only' error if the current
1184 buffer is read-only. *Note Interactive Call::, for another way to
1185 signal an error if the current buffer is read-only.
projects / chise / xemacs-chise.git.1 / blob