+@node Current Buffer
+@section The Current Buffer
+@cindex selecting a buffer
+@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 designate any buffer as current
+temporarily 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
+this, you must use the functions described in @ref{Displaying Buffers}.
+
+ However, 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-excursion} that will
+restore the current buffer when your function is done
+(@pxref{Excursions}). Here is an example, the code for the command
+@code{append-to-buffer} (with the documentation string abridged):
+
+@example
+@group
+(defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+@dots{}"
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+@end group
+@end example
+
+@noindent
+This function binds a local variable to the current buffer, and then
+@code{save-excursion} records the values of point, the mark, and the
+original buffer. Next, @code{set-buffer} makes another buffer current.
+Finally, @code{insert-buffer-substring} copies the string from the
+original current buffer to the new 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-excursion} to make sure that the
+buffer current at the beginning is current again whenever the variable
+is unbound.
+
+ It is not reliable to change the current buffer back with
+@code{set-buffer}, because that won't do the job if a quit happens while
+the wrong buffer is current. Here is what @emph{not} to do:
+
+@example
+@group
+(let (buffer-read-only
+ (obuf (current-buffer)))
+ (set-buffer @dots{})
+ @dots{}
+ (set-buffer obuf))
+@end group
+@end example
+
+@noindent
+Using @code{save-excursion}, as shown below, handles quitting, errors,
+and @code{throw}, as well as ordinary evaluation.
+
+@example
+@group
+(let (buffer-read-only)
+ (save-excursion
+ (set-buffer @dots{})
+ @dots{}))
+@end group
+@end example
+
+@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. It does
+not display the buffer in the currently selected window or in any other
+window, so the user cannot necessarily see the buffer. But Lisp
+programs can in any case work on it.
+
+This function returns the buffer identified by @var{buffer-or-name}.
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
+@end defun
+