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: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
55 Backup by Renaming or by Copying?
56 ---------------------------------
58 There are two ways that XEmacs can make a backup file:
60 * XEmacs can rename the original file so that it becomes a backup
61 file, and then write the buffer being saved into a new file.
62 After this procedure, any other names (i.e., hard links) of the
63 original file now refer to the backup file. The new file is owned
64 by the user doing the editing, and its group is the default for
65 new files written by the user in that directory.
67 * XEmacs can copy the original file into a backup file, and then
68 overwrite the original file with new contents. After this
69 procedure, any other names (i.e., hard links) of the original file
70 still refer to the current version of the file. The file's owner
71 and group will be unchanged.
73 The first method, renaming, is the default.
75 The variable `backup-by-copying', if non-`nil', says to use the
76 second method, which is to copy the original file and overwrite it with
77 the new buffer contents. The variable `file-precious-flag', if
78 non-`nil', also has this effect (as a sideline of its main
79 significance). *Note Saving Buffers::.
81 - Variable: backup-by-copying
82 If this variable is non-`nil', XEmacs always makes backup files by
85 The following two variables, when non-`nil', cause the second method
86 to be used in certain special cases. They have no effect on the
87 treatment of files that don't fall into the special cases.
89 - Variable: backup-by-copying-when-linked
90 If this variable is non-`nil', XEmacs makes backups by copying for
91 files with multiple names (hard links).
93 This variable is significant only if `backup-by-copying' is `nil',
94 since copying is always used when that variable is non-`nil'.
96 - Variable: backup-by-copying-when-mismatch
97 If this variable is non-`nil', XEmacs makes backups by copying in
98 cases where renaming would change either the owner or the group of
101 The value has no effect when renaming would not alter the owner or
102 group of the file; that is, for files which are owned by the user
103 and whose group matches the default for a new file created there
106 This variable is significant only if `backup-by-copying' is `nil',
107 since copying is always used when that variable is non-`nil'.
110 File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
112 Making and Deleting Numbered Backup Files
113 -----------------------------------------
115 If a file's name is `foo', the names of its numbered backup versions
116 are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
117 `foo.~3~', ..., `foo.~259~', and so on.
119 - User Option: version-control
120 This variable controls whether to make a single non-numbered backup
121 file or multiple numbered backups.
124 Make numbered backups if the visited file already has
125 numbered backups; otherwise, do not.
128 Do not make numbered backups.
131 Make numbered backups.
133 The use of numbered backups ultimately leads to a large number of
134 backup versions, which must then be deleted. XEmacs can do this
135 automatically or it can ask the user whether to delete them.
137 - User Option: kept-new-versions
138 The value of this variable is the number of newest versions to keep
139 when a new numbered backup is made. The newly made backup is
140 included in the count. The default value is 2.
142 - User Option: kept-old-versions
143 The value of this variable is the number of oldest versions to keep
144 when a new numbered backup is made. The default value is 2.
146 If there are backups numbered 1, 2, 3, 5, and 7, and both of these
147 variables have the value 2, then the backups numbered 1 and 2 are kept
148 as old versions and those numbered 5 and 7 are kept as new versions;
149 backup version 3 is excess. The function `find-backup-file-name'
150 (*note Backup Names::) is responsible for determining which backup
151 versions to delete, but does not delete them itself.
153 - User Option: delete-old-versions
154 If this variable is non-`nil', then saving a file deletes excess
155 backup versions silently. Otherwise, it asks the user whether to
158 - User Option: dired-kept-versions
159 This variable specifies how many of the newest backup versions to
160 keep in the Dired command `.' (`dired-clean-directory'). That's
161 the same thing `kept-new-versions' specifies when you make a new
162 backup file. The default value is 2.
165 File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
170 The functions in this section are documented mainly because you can
171 customize the naming conventions for backup files by redefining them.
172 If you change one, you probably need to change the rest.
174 - Function: backup-file-name-p filename
175 This function returns a non-`nil' value if FILENAME is a possible
176 name for a backup file. A file with the name FILENAME need not
177 exist; the function just checks the name.
179 (backup-file-name-p "foo")
181 (backup-file-name-p "foo~")
184 The standard definition of this function is as follows:
186 (defun backup-file-name-p (file)
187 "Return non-nil if FILE is a backup file \
188 name (numeric or not)..."
189 (string-match "~$" file))
191 Thus, the function returns a non-`nil' value if the file name ends
192 with a `~'. (We use a backslash to split the documentation
193 string's first line into two lines in the text, but produce just
194 one line in the string itself.)
196 This simple expression is placed in a separate function to make it
197 easy to redefine for customization.
199 - Function: make-backup-file-name filename
200 This function returns a string that is the name to use for a
201 non-numbered backup file for file FILENAME. On Unix, this is just
202 FILENAME with a tilde appended.
204 The standard definition of this function is as follows:
206 (defun make-backup-file-name (file)
207 "Create the non-numeric backup file name for FILE.
211 You can change the backup-file naming convention by redefining this
212 function. The following example redefines `make-backup-file-name'
213 to prepend a `.' in addition to appending a tilde:
215 (defun make-backup-file-name (filename)
216 (concat "." filename "~"))
218 (make-backup-file-name "backups.texi")
221 - Function: find-backup-file-name filename
222 This function computes the file name for a new backup file for
223 FILENAME. It may also propose certain existing backup files for
224 deletion. `find-backup-file-name' returns a list whose CAR is the
225 name for the new backup file and whose CDR is a list of backup
226 files whose deletion is proposed.
228 Two variables, `kept-old-versions' and `kept-new-versions',
229 determine which backup versions should be kept. This function
230 keeps those versions by excluding them from the CDR of the value.
231 *Note Numbered Backups::.
233 In this example, the value says that `~rms/foo.~5~' is the name to
234 use for the new backup file, and `~rms/foo.~3~' is an "excess"
235 version that the caller should consider deleting now.
237 (find-backup-file-name "~rms/foo")
238 => ("~rms/foo.~5~" "~rms/foo.~3~")
240 - Function: file-newest-backup filename
241 This function returns the name of the most recent backup file for
242 FILENAME, or `nil' if that file has no backup files.
244 Some file comparison commands use this function so that they can
245 automatically compare a file with its most recent backup.
248 File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
253 XEmacs periodically saves all files that you are visiting; this is
254 called "auto-saving". Auto-saving prevents you from losing more than a
255 limited amount of work if the system crashes. By default, auto-saves
256 happen every 300 keystrokes, or after around 30 seconds of idle time.
257 *Note Auto-Save: (emacs)Auto-Save, for information on auto-save for
258 users. Here we describe the functions used to implement auto-saving
259 and the variables that control them.
261 - Variable: buffer-auto-save-file-name
262 This buffer-local variable is the name of the file used for
263 auto-saving the current buffer. It is `nil' if the buffer should
266 buffer-auto-save-file-name
267 => "/xcssun/users/rms/lewis/#files.texi#"
269 - Command: auto-save-mode arg
270 When used interactively without an argument, this command is a
271 toggle switch: it turns on auto-saving of the current buffer if it
272 is off, and vice-versa. With an argument ARG, the command turns
273 auto-saving on if the value of ARG is `t', a nonempty list, or a
274 positive integer. Otherwise, it turns auto-saving off.
276 - Function: auto-save-file-name-p filename
277 This function returns a non-`nil' value if FILENAME is a string
278 that could be the name of an auto-save file. It works based on
279 knowledge of the naming convention for auto-save files: a name that
280 begins and ends with hash marks (`#') is a possible auto-save file
281 name. The argument FILENAME should not contain a directory part.
283 (make-auto-save-file-name)
284 => "/xcssun/users/rms/lewis/#files.texi#"
285 (auto-save-file-name-p "#files.texi#")
287 (auto-save-file-name-p "files.texi")
290 The standard definition of this function is as follows:
292 (defun auto-save-file-name-p (filename)
293 "Return non-nil if FILENAME can be yielded by..."
294 (string-match "^#.*#$" filename))
296 This function exists so that you can customize it if you wish to
297 change the naming convention for auto-save files. If you redefine
298 it, be sure to redefine the function `make-auto-save-file-name'
301 - Function: make-auto-save-file-name &optional filename
302 This function returns the file name to use for auto-saving the
303 current buffer. This is just the file name with hash marks (`#')
304 appended and prepended to it. This function does not look at the
305 variable `auto-save-visited-file-name' (described below); you
306 should check that before calling this function.
308 (make-auto-save-file-name)
309 => "/xcssun/users/rms/lewis/#backup.texi#"
311 The standard definition of this function is as follows:
313 (defun make-auto-save-file-name ()
314 "Return file name to use for auto-saves \
319 (file-name-directory buffer-file-name)
321 (file-name-nondirectory buffer-file-name)
324 (concat "#%" (buffer-name) "#"))))
326 This exists as a separate function so that you can redefine it to
327 customize the naming convention for auto-save files. Be sure to
328 change `auto-save-file-name-p' in a corresponding way.
330 - Variable: auto-save-visited-file-name
331 If this variable is non-`nil', XEmacs auto-saves buffers in the
332 files they are visiting. That is, the auto-save is done in the
333 same file that you are editing. Normally, this variable is `nil',
334 so auto-save files have distinct names that are created by
335 `make-auto-save-file-name'.
337 When you change the value of this variable, the value does not take
338 effect until the next time auto-save mode is reenabled in any given
339 buffer. If auto-save mode is already enabled, auto-saves continue
340 to go in the same file name until `auto-save-mode' is called again.
342 - Function: recent-auto-save-p
343 This function returns `t' if the current buffer has been
344 auto-saved since the last time it was read in or saved.
346 - Function: set-buffer-auto-saved
347 This function marks the current buffer as auto-saved. The buffer
348 will not be auto-saved again until the buffer text is changed
349 again. The function returns `nil'.
351 - User Option: auto-save-interval
352 The value of this variable is the number of characters that XEmacs
353 reads from the keyboard between auto-saves. Each time this many
354 more characters are read, auto-saving is done for all buffers in
357 - User Option: auto-save-timeout
358 The value of this variable is the number of seconds of idle time
359 that should cause auto-saving. Each time the user pauses for this
360 long, XEmacs auto-saves any buffers that need it. (Actually, the
361 specified timeout is multiplied by a factor depending on the size
362 of the current buffer.)
364 - Variable: auto-save-hook
365 This normal hook is run whenever an auto-save is about to happen.
367 - User Option: auto-save-default
368 If this variable is non-`nil', buffers that are visiting files
369 have auto-saving enabled by default. Otherwise, they do not.
371 - Command: do-auto-save &optional no-message current-only
372 This function auto-saves all buffers that need to be auto-saved.
373 It saves all buffers for which auto-saving is enabled and that
374 have been changed since the previous auto-save.
376 Normally, if any buffers are auto-saved, a message that says
377 `Auto-saving...' is displayed in the echo area while auto-saving is
378 going on. However, if NO-MESSAGE is non-`nil', the message is
381 If CURRENT-ONLY is non-`nil', only the current buffer is
384 - Function: delete-auto-save-file-if-necessary
385 This function deletes the current buffer's auto-save file if
386 `delete-auto-save-files' is non-`nil'. It is called every time a
389 - Variable: delete-auto-save-files
390 This variable is used by the function
391 `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
392 deletes auto-save files when a true save is done (in the visited
393 file). This saves disk space and unclutters your directory.
395 - Function: rename-auto-save-file
396 This function adjusts the current buffer's auto-save file name if
397 the visited file name has changed. It also renames an existing
398 auto-save file. If the visited file name has not changed, this
399 function does nothing.
401 - Variable: buffer-saved-size
402 The value of this buffer-local variable is the length of the
403 current buffer as of the last time it was read in, saved, or
404 auto-saved. This is used to detect a substantial decrease in
405 size, and turn off auto-saving in response.
407 If it is -1, that means auto-saving is temporarily shut off in this
408 buffer due to a substantial deletion. Explicitly saving the buffer
409 stores a positive value in this variable, thus reenabling
410 auto-saving. Turning auto-save mode off or on also alters this
413 - Variable: auto-save-list-file-name
414 This variable (if non-`nil') specifies a file for recording the
415 names of all the auto-save files. Each time XEmacs does
416 auto-saving, it writes two lines into this file for each buffer
417 that has auto-saving enabled. The first line gives the name of
418 the visited file (it's empty if the buffer has none), and the
419 second gives the name of the auto-save file.
421 If XEmacs exits normally, it deletes this file. If XEmacs
422 crashes, you can look in the file to find all the auto-save files
423 that might contain work that was otherwise lost. The
424 `recover-session' command uses these files.
426 The default name for this file is in your home directory and
427 starts with `.saves-'. It also contains the XEmacs process ID and
431 File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
436 If you have made extensive changes to a file and then change your
437 mind about them, you can get rid of them by reading in the previous
438 version of the file with the `revert-buffer' command. *Note Reverting
439 a Buffer: (emacs)Reverting.
441 - Command: revert-buffer &optional check-auto-save noconfirm
443 This command replaces the buffer text with the text of the visited
444 file on disk. This action undoes all changes since the file was
447 If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
448 auto-save file is more recent than the visited file,
449 `revert-buffer' asks the user whether to use that instead.
450 Otherwise, it always uses the text of the visited file itself.
451 Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
454 Normally, `revert-buffer' asks for confirmation before it changes
455 the buffer; but if the argument NOCONFIRM is non-`nil',
456 `revert-buffer' does not ask for confirmation.
458 Optional third argument PRESERVE-MODES non-`nil' means don't alter
459 the files modes. Normally we reinitialize them using
462 Reverting tries to preserve marker positions in the buffer by
463 using the replacement feature of `insert-file-contents'. If the
464 buffer contents and the file contents are identical before the
465 revert operation, reverting preserves all the markers. If they
466 are not identical, reverting does change the buffer; then it
467 preserves the markers in the unchanged text (if any) at the
468 beginning and end of the buffer. Preserving any additional
469 markers would be problematical.
471 You can customize how `revert-buffer' does its work by setting these
472 variables--typically, as buffer-local variables.
474 - Variable: revert-buffer-function
475 The value of this variable is the function to use to revert this
476 buffer. If non-`nil', it is called as a function with no
477 arguments to do the work of reverting. If the value is `nil',
478 reverting works the usual way.
480 Modes such as Dired mode, in which the text being edited does not
481 consist of a file's contents but can be regenerated in some other
482 fashion, give this variable a buffer-local value that is a
483 function to regenerate the contents.
485 - Variable: revert-buffer-insert-file-contents-function
486 The value of this variable, if non-`nil', is the function to use to
487 insert the updated contents when reverting this buffer. The
488 function receives two arguments: first the file name to use;
489 second, `t' if the user has asked to read the auto-save file.
491 - Variable: before-revert-hook
492 This normal hook is run by `revert-buffer' before actually
493 inserting the modified contents--but only if
494 `revert-buffer-function' is `nil'.
496 Font Lock mode uses this hook to record that the buffer contents
497 are no longer fontified.
499 - Variable: after-revert-hook
500 This normal hook is run by `revert-buffer' after actually inserting
501 the modified contents--but only if `revert-buffer-function' is
504 Font Lock mode uses this hook to recompute the fonts for the
505 updated buffer contents.
508 File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
513 A "buffer" is a Lisp object containing text to be edited. Buffers
514 are used to hold the contents of files that are being visited; there may
515 also be buffers that are not visiting files. While several buffers may
516 exist at one time, exactly one buffer is designated the "current
517 buffer" at any time. Most editing commands act on the contents of the
518 current buffer. Each buffer, including the current buffer, may or may
519 not be displayed in any window.
523 * Buffer Basics:: What is a buffer?
524 * Current Buffer:: Designating a buffer as current
525 so primitives will access its contents.
526 * Buffer Names:: Accessing and changing buffer names.
527 * Buffer File Name:: The buffer file name indicates which file is visited.
528 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
529 * Modification Time:: Determining whether the visited file was changed
530 ``behind XEmacs's back''.
531 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
532 * The Buffer List:: How to look at all the existing buffers.
533 * Creating Buffers:: Functions that create buffers.
534 * Killing Buffers:: Buffers exist until explicitly killed.
535 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
538 File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
543 A "buffer" is a Lisp object containing text to be edited. Buffers
544 are used to hold the contents of files that are being visited; there may
545 also be buffers that are not visiting files. While several buffers may
546 exist at one time, exactly one buffer is designated the "current
547 buffer" at any time. Most editing commands act on the contents of the
548 current buffer. Each buffer, including the current buffer, may or may
549 not be displayed in any windows.
551 Buffers in Emacs editing are objects that have distinct names and
552 hold text that can be edited. Buffers appear to Lisp programs as a
553 special data type. You can think of the contents of a buffer as an
554 extendible string; insertions and deletions may occur in any part of
555 the buffer. *Note Text::.
557 A Lisp buffer object contains numerous pieces of information. Some
558 of this information is directly accessible to the programmer through
559 variables, while other information is accessible only through
560 special-purpose functions. For example, the visited file name is
561 directly accessible through a variable, while the value of point is
562 accessible only through a primitive function.
564 Buffer-specific information that is directly accessible is stored in
565 "buffer-local" variable bindings, which are variable values that are
566 effective only in a particular buffer. This feature allows each buffer
567 to override the values of certain variables. Most major modes override
568 variables such as `fill-column' or `comment-column' in this way. For
569 more information about buffer-local variables and functions related to
570 them, see *Note Buffer-Local Variables::.
572 For functions and variables related to visiting files in buffers, see
573 *Note Visiting Files:: and *Note Saving Buffers::. For functions and
574 variables related to the display of buffers in windows, see *Note
575 Buffers and Windows::.
577 - Function: bufferp object
578 This function returns `t' if OBJECT is a buffer, `nil' otherwise.
581 File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
586 There are, in general, many buffers in an Emacs session. At any
587 time, one of them is designated as the "current buffer". This is the
588 buffer in which most editing takes place, because most of the primitives
589 for examining or changing text in a buffer operate implicitly on the
590 current buffer (*note Text::). Normally the buffer that is displayed on
591 the screen in the selected window is the current buffer, but this is not
592 always so: a Lisp program can designate any buffer as current
593 temporarily in order to operate on its contents, without changing what
594 is displayed on the screen.
596 The way to designate a current buffer in a Lisp program is by calling
597 `set-buffer'. The specified buffer remains current until a new one is
600 When an editing command returns to the editor command loop, the
601 command loop designates the buffer displayed in the selected window as
602 current, to prevent confusion: the buffer that the cursor is in when
603 Emacs reads a command is the buffer that the command will apply to.
604 (*Note Command Loop::.) Therefore, `set-buffer' is not the way to
605 switch visibly to a different buffer so that the user can edit it. For
606 this, you must use the functions described in *Note Displaying
609 However, Lisp functions that change to a different current buffer
610 should not depend on the command loop to set it back afterwards.
611 Editing commands written in XEmacs Lisp can be called from other
612 programs as well as from the command loop. It is convenient for the
613 caller if the subroutine does not change which buffer is current
614 (unless, of course, that is the subroutine's purpose). Therefore, you
615 should normally use `set-buffer' within a `save-excursion' that will
616 restore the current buffer when your function is done (*note
617 Excursions::). Here is an example, the code for the command
618 `append-to-buffer' (with the documentation string abridged):
620 (defun append-to-buffer (buffer start end)
621 "Append to specified buffer the text of the region.
623 (interactive "BAppend to buffer: \nr")
624 (let ((oldbuf (current-buffer)))
626 (set-buffer (get-buffer-create buffer))
627 (insert-buffer-substring oldbuf start end))))
629 This function binds a local variable to the current buffer, and then
630 `save-excursion' records the values of point, the mark, and the
631 original buffer. Next, `set-buffer' makes another buffer current.
632 Finally, `insert-buffer-substring' copies the string from the original
633 current buffer to the new current buffer.
635 If the buffer appended to happens to be displayed in some window,
636 the next redisplay will show how its text has changed. Otherwise, you
637 will not see the change immediately on the screen. The buffer becomes
638 current temporarily during the execution of the command, but this does
639 not cause it to be displayed.
641 If you make local bindings (with `let' or function arguments) for a
642 variable that may also have buffer-local bindings, make sure that the
643 same buffer is current at the beginning and at the end of the local
644 binding's scope. Otherwise you might bind it in one buffer and unbind
645 it in another! There are two ways to do this. In simple cases, you may
646 see that nothing ever changes the current buffer within the scope of the
647 binding. Otherwise, use `save-excursion' to make sure that the buffer
648 current at the beginning is current again whenever the variable is
651 It is not reliable to change the current buffer back with
652 `set-buffer', because that won't do the job if a quit happens while the
653 wrong buffer is current. Here is what _not_ to do:
655 (let (buffer-read-only
656 (obuf (current-buffer)))
661 Using `save-excursion', as shown below, handles quitting, errors, and
662 `throw', as well as ordinary evaluation.
664 (let (buffer-read-only)
669 - Function: current-buffer
670 This function returns the current buffer.
673 => #<buffer buffers.texi>
675 - Function: set-buffer buffer-or-name
676 This function makes BUFFER-OR-NAME the current buffer. It does
677 not display the buffer in the currently selected window or in any
678 other window, so the user cannot necessarily see the buffer. But
679 Lisp programs can in any case work on it.
681 BUFFER-OR-NAME must be a buffer or the name of an existing
682 buffer-else an error is signaled. This function returns the buffer
683 identified by BUFFER-OR-NAME.
686 File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
691 Each buffer has a unique name, which is a string. Many of the
692 functions that work on buffers accept either a buffer or a buffer name
693 as an argument. Any argument called BUFFER-OR-NAME is of this sort,
694 and an error is signaled if it is neither a string nor a buffer. Any
695 argument called BUFFER must be an actual buffer object, not a name.
697 Buffers that are ephemeral and generally uninteresting to the user
698 have names starting with a space, so that the `list-buffers' and
699 `buffer-menu' commands don't mention them. A name starting with space
700 also initially disables recording undo information; see *Note Undo::.
702 - Function: buffer-name &optional buffer
703 This function returns the name of BUFFER as a string. If BUFFER
704 is not supplied, it defaults to the current buffer.
706 If `buffer-name' returns `nil', it means that BUFFER has been
707 killed. *Note Killing Buffers::.
712 (setq foo (get-buffer "temp"))
721 - Command: rename-buffer newname &optional unique
722 This function renames the current buffer to NEWNAME. An error is
723 signaled if NEWNAME is not a string, or if there is already a
724 buffer with that name. The function returns `nil'.
726 Ordinarily, `rename-buffer' signals an error if NEWNAME is already
727 in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
728 make a name that is not in use. Interactively, you can make
729 UNIQUE non-`nil' with a numeric prefix argument.
731 One application of this command is to rename the `*shell*' buffer
732 to some other name, thus making it possible to create a second
733 shell buffer under the name `*shell*'.
735 - Function: get-buffer buffer-or-name
736 This function returns the buffer named BUFFER-OR-NAME. If
737 BUFFER-OR-NAME is a string and there is no buffer with that name,
738 the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is
739 returned as given. (That is not very useful, so the argument is
740 usually a name.) For example:
742 (setq b (get-buffer "lewis"))
746 (get-buffer "Frazzle-nots")
749 See also the function `get-buffer-create' in *Note Creating
752 - Function: generate-new-buffer-name starting-name &optional ignore
753 This function returns a name that would be unique for a new
754 buffer--but does not create the buffer. It starts with
755 STARTING-NAME, and produces a name not currently in use for any
756 buffer by appending a number inside of `<...>'.
758 If IGNORE is given, it specifies a name that is okay to use (if it
759 is in the sequence to be tried), even if a buffer with that name
762 See the related function `generate-new-buffer' in *Note Creating
766 File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
771 The "buffer file name" is the name of the file that is visited in
772 that buffer. When a buffer is not visiting a file, its buffer file name
773 is `nil'. Most of the time, the buffer name is the same as the
774 nondirectory part of the buffer file name, but the buffer file name and
775 the buffer name are distinct and can be set independently. *Note
778 - Function: buffer-file-name &optional buffer
779 This function returns the absolute file name of the file that
780 BUFFER is visiting. If BUFFER is not visiting any file,
781 `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
782 defaults to the current buffer.
784 (buffer-file-name (other-buffer))
785 => "/usr/user/lewis/manual/files.texi"
787 - Variable: buffer-file-name
788 This buffer-local variable contains the name of the file being
789 visited in the current buffer, or `nil' if it is not visiting a
790 file. It is a permanent local, unaffected by
791 `kill-local-variables'.
794 => "/usr/user/lewis/manual/buffers.texi"
796 It is risky to change this variable's value without doing various
797 other things. See the definition of `set-visited-file-name' in
798 `files.el'; some of the things done there, such as changing the
799 buffer name, are not strictly necessary, but others are essential
800 to avoid confusing XEmacs.
802 - Variable: buffer-file-truename
803 This buffer-local variable holds the truename of the file visited
804 in the current buffer, or `nil' if no file is visited. It is a
805 permanent local, unaffected by `kill-local-variables'. *Note
808 - Variable: buffer-file-number
809 This buffer-local variable holds the file number and directory
810 device number of the file visited in the current buffer, or `nil'
811 if no file or a nonexistent file is visited. It is a permanent
812 local, unaffected by `kill-local-variables'. *Note Truenames::.
814 The value is normally a list of the form `(FILENUM DEVNUM)'. This
815 pair of numbers uniquely identifies the file among all files
816 accessible on the system. See the function `file-attributes', in
817 *Note File Attributes::, for more information about them.
819 - Function: get-file-buffer filename
820 This function returns the buffer visiting file FILENAME. If there
821 is no such buffer, it returns `nil'. The argument FILENAME, which
822 must be a string, is expanded (*note File Name Expansion::), then
823 compared against the visited file names of all live buffers.
825 (get-file-buffer "buffers.texi")
826 => #<buffer buffers.texi>
828 In unusual circumstances, there can be more than one buffer
829 visiting the same file name. In such cases, this function returns
830 the first such buffer in the buffer list.
832 - Command: set-visited-file-name filename
833 If FILENAME is a non-empty string, this function changes the name
834 of the file visited in current buffer to FILENAME. (If the buffer
835 had no visited file, this gives it one.) The _next time_ the
836 buffer is saved it will go in the newly-specified file. This
837 command marks the buffer as modified, since it does not (as far as
838 XEmacs knows) match the contents of FILENAME, even if it matched
839 the former visited file.
841 If FILENAME is `nil' or the empty string, that stands for "no
842 visited file". In this case, `set-visited-file-name' marks the
843 buffer as having no visited file.
845 When the function `set-visited-file-name' is called interactively,
846 it prompts for FILENAME in the minibuffer.
848 See also `clear-visited-file-modtime' and
849 `verify-visited-file-modtime' in *Note Buffer Modification::.
851 - Variable: list-buffers-directory
852 This buffer-local variable records a string to display in a buffer
853 listing in place of the visited file name, for buffers that don't
854 have a visited file name. Dired buffers use this variable.
857 File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
862 XEmacs keeps a flag called the "modified flag" for each buffer, to
863 record whether you have changed the text of the buffer. This flag is
864 set to `t' whenever you alter the contents of the buffer, and cleared
865 to `nil' when you save it. Thus, the flag shows whether there are
866 unsaved changes. The flag value is normally shown in the modeline
867 (*note Modeline Variables::), and controls saving (*note Saving
868 Buffers::) and auto-saving (*note Auto-Saving::).
870 Some Lisp programs set the flag explicitly. For example, the
871 function `set-visited-file-name' sets the flag to `t', because the text
872 does not match the newly-visited file, even if it is unchanged from the
873 file formerly visited.
875 The functions that modify the contents of buffers are described in
878 - Function: buffer-modified-p &optional buffer
879 This function returns `t' if the buffer BUFFER has been modified
880 since it was last read in from a file or saved, or `nil'
881 otherwise. If BUFFER is not supplied, the current buffer is
884 - Function: set-buffer-modified-p flag &optional buffer
885 This function marks BUFFER as modified if FLAG is non-`nil', or as
886 unmodified if the flag is `nil'. BUFFER defaults to the current
889 Another effect of calling this function is to cause unconditional
890 redisplay of the modeline for the current buffer. In fact, the
891 function `redraw-modeline' works by doing this:
893 (set-buffer-modified-p (buffer-modified-p))
895 - Command: not-modified &optional arg
896 This command marks the current buffer as unmodified, and not
897 needing to be saved. (If ARG is non-`nil', the buffer is instead
898 marked as modified.) Don't use this function in programs, since it
899 prints a message in the echo area; use `set-buffer-modified-p'
902 - Function: buffer-modified-tick &optional buffer
903 This function returns BUFFER`s modification-count. This is a
904 counter that increments every time the buffer is modified. If
905 BUFFER is `nil' (or omitted), the current buffer is used.
908 File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
910 Comparison of Modification Time
911 ===============================
913 Suppose that you visit a file and make changes in its buffer, and
914 meanwhile the file itself is changed on disk. At this point, saving the
915 buffer would overwrite the changes in the file. Occasionally this may
916 be what you want, but usually it would lose valuable information.
917 XEmacs therefore checks the file's modification time using the functions
918 described below before saving the file.
920 - Function: verify-visited-file-modtime buffer
921 This function compares what BUFFER has recorded for the
922 modification time of its visited file against the actual
923 modification time of the file as recorded by the operating system.
924 The two should be the same unless some other process has written
925 the file since XEmacs visited or saved it.
927 The function returns `t' if the last actual modification time and
928 XEmacs's recorded modification time are the same, `nil' otherwise.
930 - Function: clear-visited-file-modtime
931 This function clears out the record of the last modification time
932 of the file being visited by the current buffer. As a result, the
933 next attempt to save this buffer will not complain of a
934 discrepancy in file modification times.
936 This function is called in `set-visited-file-name' and other
937 exceptional places where the usual test to avoid overwriting a
938 changed file should not be done.
940 - Function: visited-file-modtime
941 This function returns the buffer's recorded last file modification
942 time, as a list of the form `(HIGH . LOW)'. (This is the same
943 format that `file-attributes' uses to return time values; see
944 *Note File Attributes::.)
946 - Function: set-visited-file-modtime &optional time
947 This function updates the buffer's record of the last modification
948 time of the visited file, to the value specified by TIME if TIME
949 is not `nil', and otherwise to the last modification time of the
952 If TIME is not `nil', it should have the form `(HIGH . LOW)' or
953 `(HIGH LOW)', in either case containing two integers, each of
954 which holds 16 bits of the time.
956 This function is useful if the buffer was not read from the file
957 normally, or if the file itself has been changed for some known
960 - Function: ask-user-about-supersession-threat filename
961 This function is used to ask a user how to proceed after an
962 attempt to modify an obsolete buffer visiting file FILENAME. An
963 "obsolete buffer" is an unmodified buffer for which the associated
964 file on disk is newer than the last save-time of the buffer. This
965 means some other program has probably altered the file.
967 Depending on the user's answer, the function may return normally,
968 in which case the modification of the buffer proceeds, or it may
969 signal a `file-supersession' error with data `(FILENAME)', in which
970 case the proposed buffer modification is not allowed.
972 This function is called automatically by XEmacs on the proper
973 occasions. It exists so you can customize XEmacs by redefining it.
974 See the file `userlock.el' for the standard definition.
976 See also the file locking mechanism in *Note File Locks::.
979 File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
984 If a buffer is "read-only", then you cannot change its contents,
985 although you may change your view of the contents by scrolling and
988 Read-only buffers are used in two kinds of situations:
990 * A buffer visiting a write-protected file is normally read-only.
992 Here, the purpose is to show the user that editing the buffer with
993 the aim of saving it in the file may be futile or undesirable.
994 The user who wants to change the buffer text despite this can do
995 so after clearing the read-only flag with `C-x C-q'.
997 * Modes such as Dired and Rmail make buffers read-only when altering
998 the contents with the usual editing commands is probably a mistake.
1000 The special commands of these modes bind `buffer-read-only' to
1001 `nil' (with `let') or bind `inhibit-read-only' to `t' around the
1002 places where they change the text.
1004 - Variable: buffer-read-only
1005 This buffer-local variable specifies whether the buffer is
1006 read-only. The buffer is read-only if this variable is non-`nil'.
1008 - Variable: inhibit-read-only
1009 If this variable is non-`nil', then read-only buffers and read-only
1010 characters may be modified. Read-only characters in a buffer are
1011 those that have non-`nil' `read-only' properties (either text
1012 properties or extent properties). *Note Extent Properties::, for
1013 more information about text properties and extent properties.
1015 If `inhibit-read-only' is `t', all `read-only' character
1016 properties have no effect. If `inhibit-read-only' is a list, then
1017 `read-only' character properties have no effect if they are members
1018 of the list (comparison is done with `eq').
1020 - Command: toggle-read-only &optional arg
1021 This command changes whether the current buffer is read-only.
1022 Interactively, if a prefix arg ARG is supplied, set the current
1023 buffer read only if and only if ARG is positive.
1025 This command is intended for interactive use only; don't use it in
1026 programs. At any given point in a program, you should know
1027 whether you want the read-only flag on or off; so you can set
1028 `buffer-read-only' explicitly to the proper value, `t' or `nil'.
1030 - Function: barf-if-buffer-read-only &optional buffer start end
1031 This function signals a `buffer-read-only' error if BUFFER is
1032 read-only. BUFFER defaults to the current buffer. *Note
1033 Interactive Call::, for another way to signal an error if the
1034 current buffer is read-only.
1036 If optional argument START is non-`nil', all extents in the buffer
1037 which overlap that part of the buffer are checked to ensure none
1038 has a `read-only' property. (Extents that lie completely within the
1039 range, however, are not checked.) END defaults to the value of
1042 If START and END are equal, the range checked is [START, END]
1043 (i.e. closed on both ends); otherwise, the range checked is
1044 (START, END) \(open on both ends), except that extents that lie
1045 completely within [START, END] are not checked. See
1046 `extent-in-region-p' for a fuller discussion.
1049 File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
1054 The "buffer list" is a list of all live buffers. Creating a buffer
1055 adds it to this list, and killing a buffer deletes it. The order of
1056 the buffers in the list is based primarily on how recently each buffer
1057 has been displayed in the selected window. Buffers move to the front
1058 of the list when they are selected and to the end when they are buried.
1059 Several functions, notably `other-buffer', use this ordering. A
1060 buffer list displayed for the user also follows this order.
1062 Every frame has its own order for the buffer list. Switching to a
1063 new buffer inside of a particular frame changes the buffer list order
1064 for that frame, but does not affect the buffer list order of any other
1065 frames. In addition, there is a global, non-frame buffer list order
1066 that is independent of the buffer list orders for any particular frame.
1068 Note that the different buffer lists all contain the same elements.
1069 It is only the order of those elements that is different.
1071 - Function: buffer-list &optional frame
1072 This function returns a list of all buffers, including those whose
1073 names begin with a space. The elements are actual buffers, not
1074 their names. The order of the list is specific to FRAME, which
1075 defaults to the current frame. If FRAME is `t', the global,
1076 non-frame ordering is returned instead.
1079 => (#<buffer buffers.texi>
1080 #<buffer *Minibuf-1*> #<buffer buffer.c>
1081 #<buffer *Help*> #<buffer TAGS>)
1083 ;; Note that the name of the minibuffer
1084 ;; begins with a space!
1085 (mapcar (function buffer-name) (buffer-list))
1086 => ("buffers.texi" " *Minibuf-1*"
1087 "buffer.c" "*Help*" "TAGS")
1089 Buffers appear earlier in the list if they were current more
1092 This list is a copy of a list used inside XEmacs; modifying it has
1093 no effect on the buffers.
1095 - Function: other-buffer &optional buffer-or-name frame visible-ok
1096 This function returns the first buffer in the buffer list other
1097 than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
1098 (FRAME defaults to the current frame. If FRAME is `t', then the
1099 global, non-frame ordering is used.) Usually this is the buffer
1100 most recently shown in the selected window, aside from
1101 BUFFER-OR-NAME. Buffers are moved to the front of the list when
1102 they are selected and to the end when they are buried. Buffers
1103 whose names start with a space are not considered.
1105 If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
1106 `other-buffer' returns the first buffer on the buffer list that is
1107 not visible in any window in a visible frame.
1109 If the selected frame has a non-`nil' `buffer-predicate' property,
1110 then `other-buffer' uses that predicate to decide which buffers to
1111 consider. It calls the predicate once for each buffer, and if the
1112 value is `nil', that buffer is ignored. *Note X Frame
1115 If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
1116 visible in any window on any visible frame, except as a last
1117 resort. If VISIBLE-OK is non-`nil', then it does not matter
1118 whether a buffer is displayed somewhere or not.
1120 If no suitable buffer exists, the buffer `*scratch*' is returned
1121 (and created, if necessary).
1123 Note that in FSF Emacs 19, there is no FRAME argument, and
1124 VISIBLE-OK is the second argument instead of the third.
1126 - Command: list-buffers &optional files-only
1127 This function displays a listing of the names of existing buffers.
1128 It clears the buffer `*Buffer List*', then inserts the listing
1129 into that buffer and displays it in a window. `list-buffers' is
1130 intended for interactive use, and is described fully in `The XEmacs
1131 Reference Manual'. It returns `nil'.
1133 - Command: bury-buffer &optional buffer-or-name before
1134 This function puts BUFFER-OR-NAME at the end of the buffer list
1135 without changing the order of any of the other buffers on the list.
1136 This buffer therefore becomes the least desirable candidate for
1137 `other-buffer' to return.
1139 If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
1140 current buffer. In addition, if the buffer is displayed in the
1141 selected window, this switches to some other buffer (obtained using
1142 `other-buffer') in the selected window. But if the buffer is
1143 displayed in some other window, it remains displayed there.
1145 If you wish to replace a buffer in all the windows that display
1146 it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.