2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/buffers.info
8 @node Buffers, Windows, Backups and Auto-Saving, Top
12 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
13 are used to hold the contents of files that are being visited; there may
14 also be buffers that are not visiting files. While several buffers may
15 exist at one time, exactly one buffer is designated the @dfn{current
16 buffer} at any time. Most editing commands act on the contents of the
17 current buffer. Each buffer, including the current buffer, may or may
18 not be displayed in any window.
21 * Buffer Basics:: What is a buffer?
22 * Current Buffer:: Designating a buffer as current
23 so primitives will access its contents.
24 * Buffer Names:: Accessing and changing buffer names.
25 * Buffer File Name:: The buffer file name indicates which file is visited.
26 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
27 * Modification Time:: Determining whether the visited file was changed
28 ``behind SXEmacs's back''.
29 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
30 * The Buffer List:: How to look at all the existing buffers.
31 * Creating Buffers:: Functions that create buffers.
32 * Killing Buffers:: Buffers exist until explicitly killed.
33 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
38 @section Buffer Basics
41 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
42 are used to hold the contents of files that are being visited; there may
43 also be buffers that are not visiting files. While several buffers may
44 exist at one time, exactly one buffer is designated the @dfn{current
45 buffer} at any time. Most editing commands act on the contents of the
46 current buffer. Each buffer, including the current buffer, may or may
47 not be displayed in any windows.
50 Buffers in SXEmacs editing are objects that have distinct names and
51 hold text that can be edited. Buffers appear to Lisp programs as a
52 special data type. You can think of the contents of a buffer as an
53 extendible string; insertions and deletions may occur in any part of the
57 A Lisp buffer object contains numerous pieces of information. Some of
58 this information is directly accessible to the programmer through
59 variables, while other information is accessible only through
60 special-purpose functions. For example, the visited file name is
61 directly accessible through a variable, while the value of point is
62 accessible only through a primitive function.
64 Buffer-specific information that is directly accessible is stored in
65 @dfn{buffer-local} variable bindings, which are variable values that are
66 effective only in a particular buffer. This feature allows each buffer
67 to override the values of certain variables. Most major modes override
68 variables such as @code{fill-column} or @code{comment-column} in this
69 way. For more information about buffer-local variables and functions
70 related to them, see @ref{Buffer-Local Variables}.
72 For functions and variables related to visiting files in buffers, see
73 @ref{Visiting Files} and @ref{Saving Buffers}. For functions and
74 variables related to the display of buffers in windows, see
75 @ref{Buffers and Windows}.
78 This function returns @code{t} if @var{object} is a buffer,
83 @section The Current Buffer
84 @cindex selecting a buffer
85 @cindex changing to another buffer
86 @cindex current buffer
88 There are, in general, many buffers in a SXEmacs session. At any time,
89 one of them is designated as the @dfn{current buffer}. This is the
90 buffer in which most editing takes place, because most of the primitives
91 for examining or changing text in a buffer operate implicitly on the
92 current buffer (@pxref{Text}).
94 If you span your SXEmacs session on multiple displays it may happen
95 that you appear to have more than one current buffer, but it remains one
96 current buffer per display. Spanning SXEmacs in this sense also spans
97 a scope where some (probably many) buffers are non-current and one among
98 them is current in this scope.
100 Normally the buffer that is displayed on the screen in the selected
101 window is the current buffer, but this is not always so: a Lisp program
102 can designate any buffer as current temporarily in order to operate on
103 its contents, without changing what is displayed on the screen.
105 The way to designate a current buffer in a Lisp program is by calling
106 @code{set-buffer}. The specified buffer remains current until a new one
109 When an editing command returns to the editor command loop, the
110 command loop designates the buffer displayed in the selected window as
111 current, to prevent confusion: the buffer that the cursor is in when
112 Emacs reads a command is the buffer that the command will apply to.
113 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
114 switch visibly to a different buffer so that the user can edit it. For
115 this, you must use the functions described in @ref{Displaying Buffers}.
117 However, Lisp functions that change to a different current buffer
118 should not depend on the command loop to set it back afterwards.
119 Editing commands written in SXEmacs Lisp can be called from other
120 programs as well as from the command loop. It is convenient for the
121 caller if the subroutine does not change which buffer is current
122 (unless, of course, that is the subroutine's purpose). Therefore, you
123 should normally use @code{set-buffer} within a @code{save-excursion}
124 that will restore the current buffer when your function is done
125 (@pxref{Excursions}). Here is an example, the code for the command
126 @code{append-to-buffer} (with the documentation string abridged):
130 (defun append-to-buffer (buffer start end)
131 "Append to specified buffer the text of the region.
133 (interactive "BAppend to buffer: \nr")
134 (let ((oldbuf (current-buffer)))
136 (set-buffer (get-buffer-create buffer))
137 (insert-buffer-substring oldbuf start end))))
142 This function binds a local variable to the current buffer, and then
143 @code{save-excursion} records the values of point, the mark, and the
144 original buffer. Next, @code{set-buffer} makes another buffer current.
145 Finally, @code{insert-buffer-substring} copies the string from the
146 original current buffer to the new current buffer.
148 If the buffer appended to happens to be displayed in some window,
149 the next redisplay will show how its text has changed. Otherwise, you
150 will not see the change immediately on the screen. The buffer becomes
151 current temporarily during the execution of the command, but this does
152 not cause it to be displayed.
154 If you make local bindings (with @code{let} or function arguments) for
155 a variable that may also have buffer-local bindings, make sure that the
156 same buffer is current at the beginning and at the end of the local
157 binding's scope. Otherwise you might bind it in one buffer and unbind
158 it in another! There are two ways to do this. In simple cases, you may
159 see that nothing ever changes the current buffer within the scope of the
160 binding. Otherwise, use @code{save-excursion} to make sure that the
161 buffer current at the beginning is current again whenever the variable
164 It is not reliable to change the current buffer back with
165 @code{set-buffer}, because that won't do the job if a quit happens while
166 the wrong buffer is current. Here is what @emph{not} to do:
170 (let (buffer-read-only
171 (obuf (current-buffer)))
179 Using @code{save-excursion}, as shown below, handles quitting, errors,
180 and @code{throw}, as well as ordinary evaluation.
184 (let (buffer-read-only)
191 @defun current-buffer
192 This function returns the current buffer.
197 @result{} #<buffer buffers.texi>
202 @defun set-buffer buffer-or-name
203 This function makes @var{buffer-or-name} the current buffer. It does
204 not display the buffer in the currently selected window or in any other
205 window, so the user cannot necessarily see the buffer. But Lisp
206 programs can in any case work on it.
208 @var{buffer-or-name} must be a buffer or the name of an existing
209 buffer--else an error is signaled. This function returns the buffer
210 identified by @var{buffer-or-name}.
215 @section Buffer Names
218 Each buffer has a unique name, which is a string. Many of the
219 functions that work on buffers accept either a buffer or a buffer name
220 as an argument. Any argument called @var{buffer-or-name} is of this
221 sort, and an error is signaled if it is neither a string nor a buffer.
222 Any argument called @var{buffer} must be an actual buffer
225 Buffers that are ephemeral and generally uninteresting to the user
226 have names starting with a space, so that the @code{list-buffers} and
227 @code{buffer-menu} commands don't mention them. A name starting with
228 space also initially disables recording undo information; see
231 @defun buffer-name &optional buffer
232 This function returns the name of @var{buffer} as a string. If
233 @var{buffer} is not supplied, it defaults to the current buffer.
235 If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
236 has been killed. @xref{Killing Buffers}.
241 @result{} "buffers.texi"
245 (setq foo (get-buffer "temp"))
246 @result{} #<buffer temp>
258 @result{} #<killed buffer>
263 @deffn Command rename-buffer newname &optional unique
264 This function renames the current buffer to @var{newname}. An error
265 is signaled if @var{newname} is not a string, or if there is already a
266 buffer with that name. The function returns @code{nil}.
269 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
270 already in use. However, if @var{unique} is non-@code{nil}, it modifies
271 @var{newname} to make a name that is not in use. Interactively, you can
272 make @var{unique} non-@code{nil} with a numeric prefix argument.
274 One application of this command is to rename the @samp{*shell*} buffer
275 to some other name, thus making it possible to create a second shell
276 buffer under the name @samp{*shell*}.
279 @defun get-buffer buffer-or-name
280 This function returns the buffer named @var{buffer-or-name}. If
281 @var{buffer-or-name} is a string and there is no buffer with that name,
282 the value is @code{nil}. If @var{buffer-or-name} is actually a buffer,
283 it is returned as given. (That is not very useful, so the argument is
284 usually a name.) For example:
288 (setq b (get-buffer "lewis"))
289 @result{} #<buffer lewis>
293 @result{} #<buffer lewis>
296 (get-buffer "Frazzle-nots")
301 See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
304 @defun generate-new-buffer-name starting-name &optional ignore
305 This function returns a name that would be unique for a new buffer---but
306 does not create the buffer. It starts with @var{starting-name}, and
307 produces a name not currently in use for any buffer by appending a
308 number inside of @samp{<@dots{}>}.
310 If @var{ignore} is given, it specifies a name that is okay to use (if it
311 is in the sequence to be tried), even if a buffer with that name exists.
313 See the related function @code{generate-new-buffer} in @ref{Creating
318 @node Buffer File Name
319 @section Buffer File Name
321 @cindex buffer file name
322 @cindex file name of buffer
324 The @dfn{buffer file name} is the name of the file that is visited in
325 that buffer. When a buffer is not visiting a file, its buffer file name
326 is @code{nil}. Most of the time, the buffer name is the same as the
327 nondirectory part of the buffer file name, but the buffer file name and
328 the buffer name are distinct and can be set independently.
329 @xref{Visiting Files}.
331 @defun buffer-file-name &optional buffer
332 This function returns the absolute file name of the file that
333 @var{buffer} is visiting. If @var{buffer} is not visiting any file,
334 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not
335 supplied, it defaults to the current buffer.
339 (buffer-file-name (other-buffer))
340 @result{} "/usr/user/lewis/manual/files.texi"
345 @defvar buffer-file-name
346 This buffer-local variable contains the name of the file being visited
347 in the current buffer, or @code{nil} if it is not visiting a file. It
348 is a permanent local, unaffected by @code{kill-local-variables}.
353 @result{} "/usr/user/lewis/manual/buffers.texi"
357 It is risky to change this variable's value without doing various other
358 things. See the definition of @code{set-visited-file-name} in
359 @file{files.el}; some of the things done there, such as changing the
360 buffer name, are not strictly necessary, but others are essential to
361 avoid confusing SXEmacs.
364 @defvar buffer-file-truename
365 This buffer-local variable holds the truename of the file visited in the
366 current buffer, or @code{nil} if no file is visited. It is a permanent
367 local, unaffected by @code{kill-local-variables}. @xref{Truenames}.
370 @defvar buffer-file-number
371 This buffer-local variable holds the file number and directory device
372 number of the file visited in the current buffer, or @code{nil} if no
373 file or a nonexistent file is visited. It is a permanent local,
374 unaffected by @code{kill-local-variables}. @xref{Truenames}.
376 The value is normally a list of the form @code{(@var{filenum}
377 @var{devnum})}. This pair of numbers uniquely identifies the file among
378 all files accessible on the system. See the function
379 @code{file-attributes}, in @ref{File Attributes}, for more information
383 @defun get-file-buffer filename
384 This function returns the buffer visiting file @var{filename}. If
385 there is no such buffer, it returns @code{nil}. The argument
386 @var{filename}, which must be a string, is expanded (@pxref{File Name
387 Expansion}), then compared against the visited file names of all live
392 (get-file-buffer "buffers.texi")
393 @result{} #<buffer buffers.texi>
397 In unusual circumstances, there can be more than one buffer visiting
398 the same file name. In such cases, this function returns the first
399 such buffer in the buffer list.
402 @deffn Command set-visited-file-name filename
403 If @var{filename} is a non-empty string, this function changes the
404 name of the file visited in current buffer to @var{filename}. (If the
405 buffer had no visited file, this gives it one.) The @emph{next time}
406 the buffer is saved it will go in the newly-specified file. This
407 command marks the buffer as modified, since it does not (as far as
408 SXEmacs knows) match the contents of @var{filename}, even if it matched
409 the former visited file.
411 If @var{filename} is @code{nil} or the empty string, that stands for
412 ``no visited file''. In this case, @code{set-visited-file-name} marks
413 the buffer as having no visited file.
415 @c Wordy to avoid overfull hbox. --rjc 16mar92
416 When the function @code{set-visited-file-name} is called interactively,
417 it prompts for @var{filename} in the minibuffer.
419 See also @code{clear-visited-file-modtime} and
420 @code{verify-visited-file-modtime} in @ref{Buffer Modification}.
423 @defvar list-buffers-directory
424 This buffer-local variable records a string to display in a buffer
425 listing in place of the visited file name, for buffers that don't have a
426 visited file name. Dired buffers use this variable.
430 @node Buffer Modification
431 @section Buffer Modification
432 @cindex buffer modification
433 @cindex modification flag (of buffer)
435 SXEmacs keeps a flag called the @dfn{modified flag} for each buffer, to
436 record whether you have changed the text of the buffer. This flag is
437 set to @code{t} whenever you alter the contents of the buffer, and
438 cleared to @code{nil} when you save it. Thus, the flag shows whether
439 there are unsaved changes. The flag value is normally shown in the
440 modeline (@pxref{Modeline Variables}), and controls saving
441 (@pxref{Saving Buffers}) and auto-saving (@pxref{Auto-Saving}).
443 Some Lisp programs set the flag explicitly. For example, the function
444 @code{set-visited-file-name} sets the flag to @code{t}, because the text
445 does not match the newly-visited file, even if it is unchanged from the
446 file formerly visited.
448 The functions that modify the contents of buffers are described in
451 @defun buffer-modified-p &optional buffer
452 This function returns @code{t} if the buffer @var{buffer} has been modified
453 since it was last read in from a file or saved, or @code{nil}
454 otherwise. If @var{buffer} is not supplied, the current buffer
458 @defun set-buffer-modified-p flag &optional buffer
459 This function marks @var{buffer} as modified if @var{flag} is
460 non-@code{nil}, or as unmodified if the flag is @code{nil}.
461 @var{buffer} defaults to the current buffer.
463 Another effect of calling this function is to cause unconditional
464 redisplay of the modeline for the current buffer. In fact, the
465 function @code{redraw-modeline} works by doing this:
469 (set-buffer-modified-p (buffer-modified-p))
474 @c ARG is only in XEmacs/SXEmacs
475 @deffn Command not-modified &optional arg
476 This command marks the current buffer as unmodified, and not needing
477 to be saved. (If @var{arg} is non-@code{nil}, the buffer is instead
478 marked as modified.) Don't use this function in programs, since it
479 prints a message in the echo area; use @code{set-buffer-modified-p}
484 @defun buffer-modified-tick &optional buffer
485 This function returns @var{buffer}`s modification-count. This is a
486 counter that increments every time the buffer is modified. If
487 @var{buffer} is @code{nil} (or omitted), the current buffer is used.
491 @node Modification Time
492 @section Comparison of Modification Time
493 @cindex comparison of modification time
494 @cindex modification time, comparison of
496 Suppose that you visit a file and make changes in its buffer, and
497 meanwhile the file itself is changed on disk. At this point, saving the
498 buffer would overwrite the changes in the file. Occasionally this may
499 be what you want, but usually it would lose valuable information.
501 SXEmacs therefore checks the file's modification time using the
502 functions described below before saving the file.
504 @defun verify-visited-file-modtime buffer
505 This function compares what @var{buffer} has recorded for the
506 modification time of its visited file against the actual modification
507 time of the file as recorded by the operating system. The two should be
508 the same unless some other process has written the file since SXEmacs
511 The function returns @code{t} if the last actual modification time and
512 SXEmacs's recorded modification time are the same, @code{nil} otherwise.
515 @defun clear-visited-file-modtime
516 This function clears out the record of the last modification time of
517 the file being visited by the current buffer. As a result, the next
518 attempt to save this buffer will not complain of a discrepancy in
519 file modification times.
521 This function is called in @code{set-visited-file-name} and other
522 exceptional places where the usual test to avoid overwriting a changed
523 file should not be done.
527 @defun visited-file-modtime
528 This function returns the buffer's recorded last file modification time,
529 as a list of the form @code{(@var{high} . @var{low})}. (This is the
530 same format that @code{file-attributes} uses to return time values; see
531 @ref{File Attributes}.)
535 @defun set-visited-file-modtime &optional time
536 This function updates the buffer's record of the last modification time
537 of the visited file, to the value specified by @var{time} if @var{time}
538 is not @code{nil}, and otherwise to the last modification time of the
541 If @var{time} is not @code{nil}, it should have the form
542 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
543 either case containing two integers, each of which holds 16 bits of the
546 This function is useful if the buffer was not read from the file
547 normally, or if the file itself has been changed for some known benign
551 @defun ask-user-about-supersession-threat filename
552 @cindex obsolete buffer
553 This function is used to ask a user how to proceed after an attempt to
554 modify an obsolete buffer visiting file @var{filename}. An
555 @dfn{obsolete buffer} is an unmodified buffer for which the associated
556 file on disk is newer than the last save-time of the buffer. This means
557 some other program has probably altered the file.
559 @kindex file-supersession
560 Depending on the user's answer, the function may return normally, in
561 which case the modification of the buffer proceeds, or it may signal a
562 @code{file-supersession} error with data @code{(@var{filename})}, in
563 which case the proposed buffer modification is not allowed.
565 This function is called automatically by SXEmacs on the proper
566 occasions. It exists so you can customize SXEmacs by redefining it.
567 See the file @file{userlock.el} for the standard definition.
569 See also the file locking mechanism in @ref{File Locks}.
573 @node Read Only Buffers
574 @section Read-Only Buffers
575 @cindex read-only buffer
576 @cindex buffer, read-only
578 If a buffer is @dfn{read-only}, then you cannot change its contents,
579 although you may change your view of the contents by scrolling and
582 Read-only buffers are used in two kinds of situations:
586 A buffer visiting a write-protected file is normally read-only.
588 Here, the purpose is to show the user that editing the buffer with the
589 aim of saving it in the file may be futile or undesirable. The user who
590 wants to change the buffer text despite this can do so after clearing
591 the read-only flag with @kbd{C-x C-q}.
594 Modes such as Dired and Rmail make buffers read-only when altering the
595 contents with the usual editing commands is probably a mistake.
597 The special commands of these modes bind @code{buffer-read-only} to
598 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
599 @code{t} around the places where they change the text.
602 @defvar buffer-read-only
603 This buffer-local variable specifies whether the buffer is read-only.
604 The buffer is read-only if this variable is non-@code{nil}.
607 @defvar inhibit-read-only
608 If this variable is non-@code{nil}, then read-only buffers and read-only
609 characters may be modified. Read-only characters in a buffer are those
610 that have non-@code{nil} @code{read-only} properties (either text
611 properties or extent properties). @xref{Extent Properties}, for more
612 information about text properties and extent properties.
614 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
615 properties have no effect. If @code{inhibit-read-only} is a list, then
616 @code{read-only} character properties have no effect if they are members
617 of the list (comparison is done with @code{eq}).
620 @deffn Command toggle-read-only &optional arg
621 This command changes whether the current buffer is read-only.
622 Interactively, if a prefix arg @var{arg} is supplied, set the current
623 buffer read only if and only if @var{arg} is positive.
625 This command is intended for interactive use only; don't use it in
626 programs. At any given point in a program, you should know whether you
627 want the read-only flag on or off; so you can set
628 @code{buffer-read-only} explicitly to the proper value, @code{t} or
632 @defun barf-if-buffer-read-only &optional buffer start end
633 This function signals a @code{buffer-read-only} error if @var{buffer} is
634 read-only. @var{buffer} defaults to the current buffer.
635 @xref{Interactive Call}, for another way to signal an error if the
636 current buffer is read-only.
638 If optional argument @var{start} is non-@code{nil}, all extents in the
639 buffer which overlap that part of the buffer are checked to ensure none
640 has a @code{read-only} property. (Extents that lie completely within the
641 range, however, are not checked.) @var{end} defaults to the value of
644 If @var{start} and @var{end} are equal, the range checked is
645 [@var{start}, @var{end}] (i.e. closed on both ends); otherwise, the
646 range checked is (@var{start}, @var{end}) \(open on both ends), except
647 that extents that lie completely within [@var{start}, @var{end}] are not
648 checked. See @code{extent-in-region-p} for a fuller discussion.
652 @node The Buffer List
653 @section The Buffer List
656 The @dfn{buffer list} is a list of all live buffers. Creating a
657 buffer adds it to this list, and killing a buffer deletes it. The order
658 of the buffers in the list is based primarily on how recently each
659 buffer has been displayed in the selected window. Buffers move to the
660 front of the list when they are selected and to the end when they are
661 buried. Several functions, notably @code{other-buffer}, use this
662 ordering. A buffer list displayed for the user also follows this order.
664 @c SXEmacs/XEmacs feature
665 Every frame has its own order for the buffer list. Switching to a
666 new buffer inside of a particular frame changes the buffer list order
667 for that frame, but does not affect the buffer list order of any other
668 frames. In addition, there is a global, non-frame buffer list order
669 that is independent of the buffer list orders for any particular frame.
671 Note that the different buffer lists all contain the same elements. It
672 is only the order of those elements that is different.
674 @defun buffer-list &optional frame
675 This function returns a list of all buffers, including those whose
676 names begin with a space. The elements are actual buffers, not their
677 names. The order of the list is specific to @var{frame}, which
678 defaults to the current frame. If @var{frame} is @code{t}, the
679 global, non-frame ordering is returned instead.
684 @result{} (#<buffer buffers.texi>
685 #<buffer *Minibuf-1*> #<buffer buffer.c>
686 #<buffer *Help*> #<buffer TAGS>)
690 ;; @r{Note that the name of the minibuffer}
691 ;; @r{begins with a space!}
692 (mapcar (function buffer-name) (buffer-list))
693 @result{} ("buffers.texi" " *Minibuf-1*"
694 "buffer.c" "*Help*" "TAGS")
698 Buffers appear earlier in the list if they were current more recently.
700 This list is a copy of a list used inside SXEmacs; modifying it has no
701 effect on the buffers.
704 @defun other-buffer &optional buffer-or-name frame visible-ok
705 This function returns the first buffer in the buffer list other than
706 @var{buffer-or-name}, in @var{frame}'s ordering for the buffer list.
707 (@var{frame} defaults to the current frame. If @var{frame} is
708 @code{t}, then the global, non-frame ordering is used.) Usually this is
709 the buffer most recently shown in the selected window, aside from
710 @var{buffer-or-name}. Buffers are moved to the front of the list when
711 they are selected and to the end when they are buried. Buffers whose
712 names start with a space are not considered.
714 If @var{buffer-or-name} is not supplied (or if it is not a buffer),
715 then @code{other-buffer} returns the first buffer on the buffer list
716 that is not visible in any window in a visible frame.
718 If the selected frame has a non-@code{nil} @code{buffer-predicate}
719 property, then @code{other-buffer} uses that predicate to decide which
720 buffers to consider. It calls the predicate once for each buffer, and
721 if the value is @code{nil}, that buffer is ignored. @xref{X Frame
725 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
726 a buffer visible in any window on any visible frame, except as a last
727 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
728 whether a buffer is displayed somewhere or not.
730 If no suitable buffer exists, the buffer @samp{*scratch*} is returned
731 (and created, if necessary).
733 Note that in FSF Emacs 19, there is no @var{frame} argument, and
734 @var{visible-ok} is the second argument instead of the third.
737 @deffn Command list-buffers &optional files-only
738 This function displays a listing of the names of existing buffers. It
739 clears the buffer @samp{*Buffer List*}, then inserts the listing into
740 that buffer and displays it in a window. @code{list-buffers} is
741 intended for interactive use, and is described fully in @cite{The
742 SXEmacs Reference Manual}. It returns @code{nil}.
745 @deffn Command bury-buffer &optional buffer-or-name before
746 This function puts @var{buffer-or-name} at the end of the buffer list
747 without changing the order of any of the other buffers on the list.
748 This buffer therefore becomes the least desirable candidate for
749 @code{other-buffer} to return.
751 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
752 current buffer. In addition, if the buffer is displayed in the selected
753 window, this switches to some other buffer (obtained using
754 @code{other-buffer}) in the selected window. But if the buffer is
755 displayed in some other window, it remains displayed there.
757 If you wish to replace a buffer in all the windows that display it, use
758 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
762 @node Creating Buffers
763 @section Creating Buffers
764 @cindex creating buffers
765 @cindex buffers, creating
767 This section describes the two primitives for creating buffers.
768 @code{get-buffer-create} creates a buffer if it finds no existing buffer
769 with the specified name; @code{generate-new-buffer} always creates a new
770 buffer and gives it a unique name.
772 Other functions you can use to create buffers include
773 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
774 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a
775 subprocess can also create a buffer (@pxref{Processes}).
777 @defun get-buffer-create name
778 This function returns a buffer named @var{name}. It returns an existing
779 buffer with that name, if one exists; otherwise, it creates a new
780 buffer. The buffer does not become the current buffer---this function
781 does not change which buffer is current.
783 An error is signaled if @var{name} is not a string.
787 (get-buffer-create "foo")
788 @result{} #<buffer foo>
792 The major mode for the new buffer is set to Fundamental mode. The
793 variable @code{default-major-mode} is handled at a higher level.
794 @xref{Auto Major Mode}.
797 @defun generate-new-buffer name
798 This function returns a newly created, empty buffer, but does not make
799 it current. If there is no buffer named @var{name}, then that is the
800 name of the new buffer. If that name is in use, this function adds
801 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
802 integer. It tries successive integers starting with 2 until it finds an
805 An error is signaled if @var{name} is not a string.
809 (generate-new-buffer "bar")
810 @result{} #<buffer bar>
813 (generate-new-buffer "bar")
814 @result{} #<buffer bar<2>>
817 (generate-new-buffer "bar")
818 @result{} #<buffer bar<3>>
822 The major mode for the new buffer is set to Fundamental mode. The
823 variable @code{default-major-mode} is handled at a higher level.
824 @xref{Auto Major Mode}.
826 See the related function @code{generate-new-buffer-name} in @ref{Buffer
830 @node Killing Buffers
831 @section Killing Buffers
832 @cindex killing buffers
833 @cindex buffers, killing
835 @dfn{Killing a buffer} makes its name unknown to SXEmacs and makes its
836 text space available for other use.
838 The buffer object for the buffer that has been killed remains in
839 existence as long as anything refers to it, but it is specially marked
840 so that you cannot make it current or display it. Killed buffers retain
841 their identity, however; two distinct buffers, when killed, remain
842 distinct according to @code{eq}.
844 If you kill a buffer that is current or displayed in a window, SXEmacs
845 automatically selects or displays some other buffer instead. This means
846 that killing a buffer can in general change the current buffer.
847 Therefore, when you kill a buffer, you should also take the precautions
848 associated with changing the current buffer (unless you happen to know
849 that the buffer being killed isn't current). @xref{Current Buffer}.
851 If you kill a buffer that is the base buffer of one or more indirect
852 buffers, the indirect buffers are automatically killed as well.
854 The @code{buffer-name} of a killed buffer is @code{nil}. To test
855 whether a buffer has been killed, you can either use this feature
856 or the function @code{buffer-live-p}.
858 @defun buffer-live-p object
859 This function returns @code{t} if @var{object} is an editor buffer that
860 has not been deleted, @code{nil} otherwise.
863 @deffn Command kill-buffer buffer-or-name
864 This function kills the buffer @var{buffer-or-name}, freeing all its
865 memory for use as space for other buffers.
867 It returns @code{nil}. The argument @var{buffer-or-name} may be a
868 buffer or the name of one.
870 Note: Emacs version 18 and older was unable to return the memory to the
873 Any processes that have this buffer as the @code{process-buffer} are
874 sent the @code{SIGHUP} signal, which normally causes them to terminate.
875 (The basic meaning of @code{SIGHUP} is that a dialup line has been
876 disconnected.) @xref{Deleting Processes}.
878 If the buffer is visiting a file and contains unsaved changes,
879 @code{kill-buffer} asks the user to confirm before the buffer is killed.
880 It does this even if not called interactively. To prevent the request
881 for confirmation, clear the modified flag before calling
882 @code{kill-buffer}. @xref{Buffer Modification}.
884 Killing a buffer that is already dead has no effect.
887 (kill-buffer "foo.unchanged")
889 (kill-buffer "foo.changed")
891 ---------- Buffer: Minibuffer ----------
892 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
893 ---------- Buffer: Minibuffer ----------
899 @defvar kill-buffer-query-functions
900 After confirming unsaved changes, @code{kill-buffer} calls the functions
901 in the list @code{kill-buffer-query-functions}, in order of appearance,
902 with no arguments. The buffer being killed is the current buffer when
903 they are called. The idea is that these functions ask for confirmation
904 from the user for various nonstandard reasons. If any of them returns
905 @code{nil}, @code{kill-buffer} spares the buffer's life.
908 @defvar kill-buffer-hook
909 This is a normal hook run by @code{kill-buffer} after asking all the
910 questions it is going to ask, just before actually killing the buffer.
911 The buffer to be killed is current when the hook functions run.
915 @defvar buffer-offer-save
916 This variable, if non-@code{nil} in a particular buffer, tells
917 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to
918 save that buffer, just as they offer to save file-visiting buffers. The
919 variable @code{buffer-offer-save} automatically becomes buffer-local
920 when set for any reason. @xref{Buffer-Local Variables}.
924 @node Indirect Buffers
925 @section Indirect Buffers
926 @cindex indirect buffers
929 An @dfn{indirect buffer} shares the text of some other buffer, which
930 is called the @dfn{base buffer} of the indirect buffer. In some ways it
931 is the analogue, for buffers, of a symbolic link among files. The base
932 buffer may not itself be an indirect buffer. One base buffer may have
933 several @dfn{indirect children}.
935 The text of the indirect buffer is always identical to the text of its
936 base buffer; changes made by editing either one are visible immediately
939 But in all other respects, the indirect buffer and its base buffer are
940 completely separate. They have different names, different values of
941 point and mark, different narrowing, different markers and extents
942 (though inserting or deleting text in either buffer relocates the
943 markers and extents for both), different font-locking, different major
944 modes, and different local variables.
946 Note: Unlike in FSF Emacs, SXEmacs indirect buffers do not automatically
947 share text properties among themselves and their base buffer.
949 An indirect buffer cannot visit a file, but its base buffer can. If
950 you try to save the indirect buffer, that actually works by saving the
953 Killing an indirect buffer has no effect on its base buffer. Killing
954 the base buffer kills all its indirect children.
956 @deffn Command make-indirect-buffer base-buffer name
957 This creates an indirect buffer named @var{name} whose base buffer
958 is @var{base-buffer}. The argument @var{base-buffer} may be a buffer
961 If @var{base-buffer} is an indirect buffer, its base buffer is used as
962 the base for the new buffer.
966 (make-indirect-buffer "*scratch*" "indirect")
967 @result{} #<buffer "indirect">
972 @defun buffer-base-buffer &optional buffer
973 This function returns the base buffer of @var{buffer}. If @var{buffer}
974 is not indirect, the value is @code{nil}. Otherwise, the value is
975 another buffer, which is never an indirect buffer. If @var{buffer} is
976 not supplied, it defaults to the current buffer.
980 (buffer-base-buffer (get-buffer "indirect"))
981 @result{} #<buffer "*scratch*">
986 @defun buffer-indirect-children &optional buffer
987 This function returns a list of all indirect buffers whose base buffer
988 is @var{buffer}. If @var{buffer} is indirect, the return value will
989 always be @code{nil}; see @code{make-indirect-buffer}. If @var{buffer} is not
990 supplied, it defaults to the current buffer.
994 (buffer-indirect-children (get-buffer "*scratch*"))
995 @result{} (#<buffer "indirect">)