@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/buffers
-@node Buffers, Windows, Backups and Auto-Saving, Top
+@node Buffers
@chapter Buffers
@cindex buffer
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
* Modification Time:: Determining whether the visited file was changed
- ``behind Emacs's back''.
+ "behind Emacs's back".
* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
* The Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
@end menu
@node Buffer Basics
-@comment node-name, next, previous, up
@section Buffer Basics
@ifnottex
@cindex changing to another buffer
@cindex current buffer
- There are, in general, many buffers in an Emacs session. At any time,
-one of them is designated as the @dfn{current buffer}. This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (@pxref{Text}). Normally the buffer that is displayed on
-the screen in the selected window is the current buffer, but this is not
-always so: a Lisp program can temporarily designate any buffer as
-current in order to operate on its contents, without changing what is
-displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-@code{set-buffer}. The specified buffer remains current until a new one
-is designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-that, you must use the functions described in @ref{Displaying Buffers}.
-
- @strong{Warning:} Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in Emacs Lisp can be called from other programs
-as well as from the command loop; it is convenient for the caller if
-the subroutine does not change which buffer is current (unless, of
-course, that is the subroutine's purpose). Therefore, you should
-normally use @code{set-buffer} within a @code{save-current-buffer} or
-@code{save-excursion} (@pxref{Excursions}) form that will restore the
-current buffer when your function is done. Here, as an example, is a
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated the @dfn{current buffer}---the buffer
+in which most editing takes place. Most of the primitives for
+examining or changing text operate implicitly on the current buffer
+(@pxref{Text}).
+
+ Normally, the buffer displayed in the selected window is the current
+buffer, but this is not always so: a Lisp program can temporarily
+designate any buffer as current in order to operate on its contents,
+without changing what is displayed on the screen. The most basic
+function for designating a current buffer is @code{set-buffer}.
+
+@defun current-buffer
+This function returns the current buffer.
+
+@example
+@group
+(current-buffer)
+ @result{} #<buffer buffers.texi>
+@end group
+@end example
+@end defun
+
+@defun set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.
+@var{buffer-or-name} must be an existing buffer or the name of an
+existing buffer. The return value is the buffer made current.
+
+This function does not display the buffer in any window, so the user
+cannot necessarily see the buffer. But Lisp programs will now operate
+on it.
+@end defun
+
+ When an editing command returns to the editor command loop, Emacs
+automatically calls @code{set-buffer} on the buffer shown in the
+selected window. This is to prevent confusion: it ensures that the
+buffer that the cursor is in, when Emacs reads a command, is the
+buffer to which that command applies (@pxref{Command Loop}). Thus,
+you should not use @code{set-buffer} to switch visibly to a different
+buffer; for that, use the functions described in @ref{Switching
+Buffers}.
+
+ When writing a Lisp function, do @emph{not} rely on this behavior of
+the command loop to restore the current buffer after an operation.
+Editing commands can also be called as Lisp functions by other
+programs, not just from the command loop; it is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose).
+
+ To operate temporarily on another buffer, put the @code{set-buffer}
+within a @code{save-current-buffer} form. Here, as an example, is a
simplified version of the command @code{append-to-buffer}:
@example
@group
(defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region."
+ "Append the text of the region to BUFFER."
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-current-buffer
@end example
@noindent
-This function binds a local variable to record the current buffer, and
-then @code{save-current-buffer} arranges to make it current again.
-Next, @code{set-buffer} makes the specified buffer current. Finally,
+Here, we bind a local variable to record the current buffer, and then
+@code{save-current-buffer} arranges to make it current again later.
+Next, @code{set-buffer} makes the specified buffer current, and
@code{insert-buffer-substring} copies the string from the original
-current buffer to the specified (and now current) buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with @code{let} or function arguments) for
-a variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use @code{save-current-buffer} or
-@code{save-excursion} to make sure that the buffer current at the
-beginning is current again whenever the variable is unbound.
+buffer to the specified (and now current) buffer.
+
+ Alternatively, we can use the @code{with-current-buffer} macro:
+
+@example
+@group
+(defun append-to-buffer (buffer start end)
+ "Append the text of the region to BUFFER."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (with-current-buffer (get-buffer-create buffer)
+ (insert-buffer-substring oldbuf start end))))
+@end group
+@end example
+
+ In either case, if the buffer appended to happens to be displayed in
+some window, the next redisplay will show how its text has changed.
+If it is not displayed in any window, you will not see the change
+immediately on the screen. The command causes the buffer to become
+current temporarily, but does not cause it to be displayed.
+
+ If you make local bindings (with @code{let} or function arguments)
+for a variable that may also have buffer-local bindings, make sure
+that the same buffer is current at the beginning and at the end of the
+local binding's scope. Otherwise you might bind it in one buffer and
+unbind it in another!
Do not rely on using @code{set-buffer} to change the current buffer
back, because that won't do the job if a quit happens while the wrong
@end example
@noindent
-Using @code{save-current-buffer}, as we did, handles quitting, errors,
-and @code{throw}, as well as ordinary evaluation.
-
-@defun current-buffer
-This function returns the current buffer.
-
-@example
-@group
-(current-buffer)
- @result{} #<buffer buffers.texi>
-@end group
-@end example
-@end defun
-
-@defun set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer.
-@var{buffer-or-name} must be an existing buffer or the name of an
-existing buffer. The return value is the buffer made current.
-
-This function does not display the buffer in any window, so the user
-cannot necessarily see the buffer. But Lisp programs will now operate
-on it.
-@end defun
+Using @code{save-current-buffer} or @code{with-current-buffer}, as we
+did, correctly handles quitting, errors, and @code{throw}, as well as
+ordinary evaluation.
@defspec save-current-buffer body@dots{}
The @code{save-current-buffer} special form saves the identity of the
visited in the current buffer, or @code{nil} if no file is visited.
It is a permanent local, unaffected by
@code{kill-all-local-variables}. @xref{Truenames}, and
-@ref{Definition of abbreviate-file-name}.
+@ref{abbreviate-file-name}.
@end defvar
@defvar buffer-file-number
use.
If @var{filename} is @code{nil} or the empty string, that stands for
-``no visited file.'' In this case, @code{set-visited-file-name} marks
+``no visited file''. In this case, @code{set-visited-file-name} marks
the buffer as having no visited file, without changing the buffer's
modified flag.
last file modification time, after which @code{visited-file-modtime}
returns zero.
-@c Wordy to avoid overfull hbox. --rjc 16mar92
-When the function @code{set-visited-file-name} is called interactively, it
-prompts for @var{filename} in the minibuffer.
+When the function @code{set-visited-file-name} is called
+interactively, it prompts for @var{filename} in the minibuffer.
@end deffn
@defvar list-buffers-directory
@end defun
@node Modification Time
-@comment node-name, next, previous, up
@section Buffer Modification Time
@cindex comparing file modification time
@cindex modification time of buffer
@defvar inhibit-read-only
If this variable is non-@code{nil}, then read-only buffers and,
depending on the actual value, some or all read-only characters may be
-modified. Read-only characters in a buffer are those that have
-non-@code{nil} @code{read-only} properties (either text properties or
-overlay properties). @xref{Special Properties}, for more information
-about text properties. @xref{Overlays}, for more information about
-overlays and their properties.
+modified. Read-only characters in a buffer are those that have a
+non-@code{nil} @code{read-only} text property. @xref{Special
+Properties}, for more information about text properties.
If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
properties have no effect. If @code{inhibit-read-only} is a list, then
of the list (comparison is done with @code{eq}).
@end defvar
-@deffn Command toggle-read-only &optional arg
-This command toggles whether the current buffer is read-only. It is
-intended for interactive use; do not use it in programs. At any given
-point in a program, you should know whether you want the read-only flag
-on or off; so you can set @code{buffer-read-only} explicitly to the
-proper value, @code{t} or @code{nil}.
-
-If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
-@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
-@code{nil} otherwise. @xref{Prefix Command Arguments}.
+@deffn Command read-only-mode &optional arg
+This is the mode command for Read Only minor mode, a buffer-local
+minor mode. When the mode is enabled, @code{buffer-read-only} is
+non-@code{nil} in the buffer; when disabled, @code{buffer-read-only}
+is @code{nil} in the buffer. The calling convention is the same as
+for other minor mode commands (@pxref{Minor Mode Conventions}).
+
+This minor mode mainly serves as a wrapper for
+@code{buffer-read-only}; unlike most minor modes, there is no separate
+@code{read-only-mode} variable. Even when Read Only mode is disabled,
+characters with non-@code{nil} @code{read-only} text properties remain
+read-only. To temporarily ignore all read-only states, bind
+@code{inhibit-read-only}, as described above.
+
+When enabling Read Only mode, this mode command also enables View mode
+if the option @code{view-read-only} is non-@code{nil}. @xref{Misc
+Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}.
+When disabling Read Only mode, it disables View mode if View mode was
+enabled.
@end deffn
@defun barf-if-buffer-read-only
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
- Creating a buffer adds it to the end of the buffer list, and killing a
-buffer removes it from that list. A buffer moves to the front of this
-list whenever it is chosen for display in a window (@pxref{Displaying
-Buffers}) or a window displaying it is selected (@pxref{Selecting
-Windows}). A buffer moves to the end of the list when it is buried (see
-@code{bury-buffer}, below). There are no functions available to the
-Lisp programmer which directly manipulate the buffer list.
+ Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it from that list. A buffer moves to the front of
+this list whenever it is chosen for display in a window
+(@pxref{Switching Buffers}) or a window displaying it is selected
+(@pxref{Selecting Windows}). A buffer moves to the end of the list
+when it is buried (see @code{bury-buffer}, below). There are no
+functions available to the Lisp programmer which directly manipulate
+the buffer list.
In addition to the fundamental buffer list just described, Emacs
maintains a local buffer list for each frame, in which the buffers that
resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
whether a buffer is displayed somewhere or not.
-If no suitable buffer exists, the buffer @samp{*scratch*} is returned
+If no suitable buffer exists, the buffer @file{*scratch*} is returned
(and created, if necessary).
@end defun
The argument @var{visible-ok} is handled as with @code{other-buffer},
see above. If no suitable buffer can be found, the buffer
-@samp{*scratch*} is returned.
+@file{*scratch*} is returned.
@end defun
@deffn Command bury-buffer &optional buffer-or-name
@code{other-buffer} to return. The argument can be either a buffer
itself or the name of one.
-@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
-as well as the fundamental buffer list; therefore, the buffer that you
-bury will come last in the value of @code{(buffer-list @var{frame})} and
-in the value of @code{(buffer-list)}.
+This functions operates on each frame's @code{buffer-list} parameter as
+well as the fundamental buffer list; therefore, the buffer that you bury
+will come last in the value of @code{(buffer-list @var{frame})} and in
+the value of @code{(buffer-list)}. In addition, it also puts the buffer
+at the end of the list of buffer of the selected window (@pxref{Window
+History}) provided it is shown in that window.
If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer. In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window. @xref{Displaying Buffers}.
-But if the selected window is dedicated to its buffer, it deletes that
-window if there are other windows left on its frame. Otherwise, if the
-selected window is the only window on its frame, it iconifies that
-frame. If @var{buffer-or-name} is displayed in some other window, it
-remains displayed there.
+current buffer. In addition, if the current buffer is displayed in the
+selected window, this makes sure that the window is either deleted or
+another buffer is shown in it. More precisely, if the window is
+dedicated (@pxref{Dedicated Windows}) and there are other windows on its
+frame, the window is deleted. If the window is both dedicated and the
+only window on its frame's terminal, the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
+with the window. If the window is not dedicated to its buffer, it calls
+@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
+buffer in that window. If @var{buffer-or-name} is displayed in some
+other window, it remains displayed there.
To replace a buffer in all the windows that display it, use
-@code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
+@code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
@end deffn
@deffn Command unbury-buffer
-This command switches to the last buffer in the local buffer list of the
-selected frame. More precisely, it calls the function
-@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the
-buffer returned by @code{last-buffer}, see above, in the selected
+This command switches to the last buffer in the local buffer list of
+the selected frame. More precisely, it calls the function
+@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
+buffer returned by @code{last-buffer} (see above), in the selected
window.
@end deffn
@defun generate-new-buffer name
This function returns a newly created, empty buffer, but does not make
-it current. If there is no buffer named @var{name}, then that is the
-name of the new buffer. If that name is in use, this function adds
-suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
-integer. It tries successive integers starting with 2 until it finds an
-available name.
+it current. The name of the buffer is generated by passing @var{name}
+to the function @code{generate-new-buffer-name} (@pxref{Buffer
+Names}). Thus, if there is no buffer named @var{name}, then that is
+the name of the new buffer; if that name is in use, a suffix of the
+form @samp{<@var{n}>}, where @var{n} is an integer, is appended to
+@var{name}.
An error is signaled if @var{name} is not a string.
The major mode for the new buffer is set to Fundamental mode. The default
value of the variable @code{major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
-
-See the related function @code{generate-new-buffer-name} in @ref{Buffer
-Names}.
@end defun
@node Killing Buffers
distinct according to @code{eq} although both are dead.
If you kill a buffer that is current or displayed in a window, Emacs
-automatically selects or displays some other buffer instead. This means
-that killing a buffer can in general change the current buffer.
-Therefore, when you kill a buffer, you should also take the precautions
+automatically selects or displays some other buffer instead. This
+means that killing a buffer can change the current buffer. Therefore,
+when you kill a buffer, you should also take the precautions
associated with changing the current buffer (unless you happen to know
that the buffer being killed isn't current). @xref{Current Buffer}.
If you kill a buffer that is the base buffer of one or more indirect
-buffers, the indirect buffers are automatically killed as well.
-
- The @code{buffer-name} of a killed buffer is @code{nil}. You can use
-this feature to test whether a buffer has been killed:
+@iftex
+buffers,
+@end iftex
+@ifnottex
+buffers (@pxref{Indirect Buffers}),
+@end ifnottex
+the indirect buffers are automatically killed as well.
-@example
-@group
-(defun buffer-killed-p (buffer)
- "Return t if BUFFER is killed."
- (not (buffer-name buffer)))
-@end group
-@end example
+@cindex live buffer
+ The @code{buffer-name} of a buffer is @code{nil} if, and only if,
+the buffer is killed. A buffer that has not been killed is called a
+@dfn{live} buffer. To test whether a buffer is live or killed, use
+the function @code{buffer-live-p} (see below).
@deffn Command kill-buffer &optional buffer-or-name
This function kills the buffer @var{buffer-or-name}, freeing all its
buffer.
Any processes that have this buffer as the @code{process-buffer} are
-sent the @code{SIGHUP} signal, which normally causes them to terminate.
-(The basic meaning of @code{SIGHUP} is that a dialup line has been
-disconnected.) @xref{Signals to Processes}.
+sent the @code{SIGHUP} (``hangup'') signal, which normally causes them
+to terminate. @xref{Signals to Processes}.
If the buffer is visiting a file and contains unsaved changes,
@code{kill-buffer} asks the user to confirm before the buffer is killed.
@end defvar
@defun buffer-live-p object
-This function returns @code{t} if @var{object} is a buffer which has
-not been killed, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a live buffer (a
+buffer which has not been killed), @code{nil} otherwise.
@end defun
@node Indirect Buffers