+@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 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{Note:} 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 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-current-buffer
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+@end group
+@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,
+@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.
+
+ 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
+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-current-buffer}, as shown here, handles quitting,
+errors, and @code{throw}, as well as ordinary evaluation.
+
+@example
+@group
+(let (buffer-read-only)
+ (save-current-buffer
+ (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. This does
+not display the buffer in any window, so the user cannot necessarily see
+the buffer. But Lisp programs will now operate 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
+
+@defspec save-current-buffer body...
+The @code{save-current-buffer} macro saves the identity of the current
+buffer, evaluates the @var{body} forms, and finally restores that buffer
+as current. The return value is the value of the last form in
+@var{body}. The current buffer is restored even in case of an abnormal
+exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+
+If the buffer that used to be current has been killed by the time of
+exit from @code{save-current-buffer}, then it is not made current again,
+of course. Instead, whichever buffer was current just before exit
+remains current.
+@end defspec
+
+@defmac with-current-buffer buffer body...
+The @code{with-current-buffer} macro saves the identity of the current
+buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
+finally restores the buffer. The return value is the value of the last
+form in @var{body}. The current buffer is restored even in case of an
+abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+@end defmac
+
+@defmac with-temp-buffer body...
+The @code{with-temp-buffer} macro evaluates the @var{body} forms
+with a temporary buffer as the current buffer. It saves the identity of
+the current buffer, creates a temporary buffer and makes it current,
+evaluates the @var{body} forms, and finally restores the previous
+current buffer while killing the temporary buffer.
+
+The return value is the value of the last form in @var{body}. You can
+return the contents of the temporary buffer by using
+@code{(buffer-string)} as the last form.
+
+The current buffer is restored even in case of an abnormal exit via
+@code{throw} or error (@pxref{Nonlocal Exits}).
+@end defmac
+
+See also @code{with-temp-file} in @ref{Writing to Files}.
+