15 Using Multiple Buffers
*************************

  Text you are editing in Emacs resides in an object called a
buffer.  Each time you visit a file, Emacs creates a buffer to
hold the file's text.  Each time you invoke Dired, Emacs creates a buffer
to hold the directory listing.  If you send a message with C-x m,
a buffer named `*mail*' is used to hold the text of the message.
When you ask for a command's documentation, it appears in a buffer
called `*Help*'.

  At any time, one and only one buffer is selected.  It is also
called the current buffer.  Saying a command operates on "the
buffer" really means that the command operates on the selected
buffer, as most commands do.

  When Emacs creates multiple windows, each window has a chosen buffer which
is displayed there, but at any time only one of the windows is selected and
its chosen buffer is the selected buffer.  Each window's mode line displays
the name of the buffer the window is displaying (see Windows).

  Each buffer has a name which can be of any length but is
case-sensitive.  You can select a buffer using its name.  Most
buffers are created when you visit files; their names are derived from
the files' names.  You can also create an empty buffer with any name you
want.  A newly started Emacs has a buffer named `*scratch*' which
you can use for evaluating Lisp expressions in Emacs.

  Each buffer records what file it is visiting, whether it is
modified, and what major mode and minor modes are in effect in it
(see Major Modes).  Any Emacs variable can be made local to a
particular buffer, meaning its value in that buffer can be different from
the value in other buffers.  See Locals.

* Select Buffer::   Creating a new buffer or reselecting an old one.
* List Buffers::    Getting a list of buffers that exist.
* Misc Buffer::     Renaming; changing read-onliness; copying text.
* Kill Buffer::     Killing buffers you no longer need.
* Several Buffers:: How to go through the list of all buffers
                     and operate variously on several of them.

15.1 Creating and Selecting Buffers
===================================

C-x b buffer <RET>
Select or create a buffer named buffer (switch-to-buffer).
C-x 4 b buffer <RET>
Similar, but select a buffer named buffer in another window
(switch-to-buffer-other-window).
M-x switch-to-other-buffer n
Switch to the previous buffer.

  To select a buffer named bufname, type C-x b bufname
<RET>.  This is the command switch-to-buffer with argument
bufname.  You can use completion on an abbreviation for the buffer
name you want (see Completion).  An empty argument to C-x b
specifies the most recently selected buffer that is not displayed in any
window.

  Most buffers are created when you visit files, or use Emacs commands
that display text.  You can also create a buffer explicitly by typing
C-x b bufname <RET>, which creates a new, empty buffer
that is not visiting any file, and selects it for editing.  The new
buffer's major mode is determined by the value of
default-major-mode (see Major Modes).  Buffers not visiting
files are usually used for making notes to yourself.  If you try to save
one, you are asked for the file name to use.

 The function switch-to-buffer-other-frame is similar to
switch-to-buffer except that it creates a new frame in which to
display the selected buffer.

Use M-x switch-to-other-buffer to visit the previous buffer. If
you supply a positive integer n, the nth most recent buffer
is displayed. If you supply an argument of 0, the current buffer is
moved to the bottom of the buffer stack.

  Note that you can also use C-x C-f and any other command for
visiting a file to switch buffers.  See Visiting.

15.2 Listing Existing Buffers
=============================

C-x C-b
List the existing buffers (list-buffers).

  To print a list of all existing buffers, type C-x C-b.  Each
line in the list shows one buffer's name, major mode, and visited file.
A `*' at the beginning of a line indicates the buffer has been
"modified".  If several buffers are modified, it may be time to save
some with C-x s (see Saving).  A `%' indicates a read-only
buffer.  A `.' marks the selected buffer.  Here is an example of a
buffer list:

 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
    *Help*         1287  Fundamental    
    files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
  % RMAIL          64042 RMAIL          /u/rms/RMAIL
 *% man            747   Dired          /u2/emacs/man/
    net.emacs      343885 Fundamental   /u/rms/net.emacs
    fileio.c       27691 C              /u2/emacs/src/fileio.c
    NEWS           67340 Text           /u2/emacs/etc/NEWS
    *scratch*      0     Lisp Interaction

Note that the buffer `*Help*' was made by a help request; it is not
visiting any file.  The buffer man was made by Dired on the
directory `/u2/emacs/man/'.

As you move the mouse over the `*Buffer List*' buffer, the lines
are highlighted.  This visual cue indicates that clicking the right
mouse button (button3) will pop up a menu of commands on the
buffer represented by this line.  This menu duplicates most of those
commands which are bound to keys in the `*Buffer List*' buffer.

15.3 Miscellaneous Buffer Operations
====================================

C-x C-q
Toggle read-only status of buffer (toggle-read-only).
M-x rename-buffer
Change the name of the current buffer.
M-x view-buffer
Scroll through a buffer.

  A buffer can be read-only, which means that commands to change
its text are not allowed.  Normally, read-only buffers are created by
subsystems such as Dired and Rmail that have special commands to operate
on the text.  Emacs also creates a read-only buffer if you
visit a file that is protected.  To make changes in a read-only buffer,
use the command C-x C-q (toggle-read-only).  It makes a
read-only buffer writable, and makes a writable buffer read-only.  This
works by setting the variable buffer-read-only, which has a local
value in each buffer and makes a buffer read-only if its value is
non-nil.

  M-x rename-buffer changes the name of the current buffer,
prompting for the new name in the minibuffer.  There is no default.  If you
specify a name that is used by a different buffer, an error is signalled and
renaming is not done.

  M-x view-buffer is similar to M-x view-file (see Misc File Ops), but it examines an already existing Emacs buffer.  View mode
provides convenient commands for scrolling through the buffer but not
for changing it.  When you exit View mode, the resulting value of point
remains in effect.

To copy text from one buffer to another, use the commands M-x
append-to-buffer and M-x insert-buffer.  See Accumulating Text.

15.4 Killing Buffers
====================

  After using Emacs for a while, you may accumulate a large number of
buffers and may want to eliminate the ones you no
longer need.  There are several commands for doing this.

C-x k
Kill a buffer, specified by name (kill-buffer).
M-x kill-some-buffers
Offer to kill each buffer, one by one.

 
  C-x k (kill-buffer) kills one buffer, whose name you
specify in the minibuffer.  If you type just <RET> in the
minibuffer, the default, killing the current buffer, is used.  If the
current buffer is killed, the buffer that has been selected recently but
does not appear in any window now is selected.  If the buffer being
killed contains unsaved changes, you are asked to confirm with yes
before the buffer is killed.

  The command M-x kill-some-buffers asks about each buffer, one by
one.  An answer of y means to kill the buffer.  Killing the current
buffer or a buffer containing unsaved changes selects a new buffer or asks
for confirmation just like kill-buffer.

15.5 Operating on Several Buffers
=================================

  The buffer-menu facility is like a "Dired for buffers"; it allows
you to request operations on various Emacs buffers by editing a
buffer containing a list of them.  You can save buffers, kill them
(here called deleting them, for consistency with Dired), or display
them.

M-x buffer-menu
Begin editing a buffer listing all Emacs buffers.

  The command buffer-menu writes a list of all Emacs buffers into
the buffer `*Buffer List*', and selects that buffer in Buffer Menu
mode.  The buffer is read-only.  You can only change it using the special
commands described in this section.  Most of the commands are graphic
characters.  You can use  Emacs cursor motion commands in the
`*Buffer List*' buffer.  If the cursor is on a line describing a
buffer, the following  special commands apply to that buffer:

d
Request to delete (kill) the buffer, then move down.  A `D' before
the buffer name on a line indicates a deletion request.  Requested
deletions actually take place when you use the x command.
k
Synonym for d.
C-d
Like d but move up afterwards instead of down.
s
Request to save the buffer.  An `S' before the buffer name on a line
indicates the request.  Requested saves actually take place when you use
the x command.  You can request both saving and deletion for the
same buffer.
~
Mark buffer "unmodified".  The command ~ does this
immediately when typed.
x
Perform previously requested deletions and saves.
u
Remove any request made for the current line, and move down.
<DEL>
Move to previous line and remove any request made for that line.

  All commands that add or remove flags to request later operations
also move down a line.  They accept a numeric argument as a repeat count,
unless otherwise specified.

  There are also special commands to use the buffer list to select another
buffer, and to specify one or more other buffers for display in additional
windows.

1
Select the buffer in a full-frame window.  This command takes effect
immediately.
2
Immediately set up two windows, with this buffer in one and the
buffer selected before `*Buffer List*' in the other.
f
Immediately select the buffer in place of the `*Buffer List*' buffer.
o
Immediately select the buffer in another window as if by C-x 4 b,
leaving `*Buffer List*' visible.
q
Immediately select this buffer, and display any buffers previously
flagged with the m command in other windows.  If there are no 
buffers flagged with m, this command is equivalent to 1.
m
Flag this buffer to be displayed in another window if the q
command is used.  The request shows as a `>' at the beginning of
the line.  The same buffer may not have both a delete request and a
display request.

 Going back between a buffer-menu buffer and other Emacs buffers is
easy.  You can, for example, switch from the `*Buffer List*'
buffer to another Emacs buffer, and edit there.  You can then reselect the
buffer-menu buffer and perform operations already
requested, or you can kill that buffer or pay no further attention to it.
 All that buffer-menu does directly is create and select a
suitable buffer, and turn on Buffer Menu mode.  All the other
capabilities of the buffer menu are implemented by special commands
provided in Buffer Menu mode.  

  The only difference between buffer-menu and list-buffers is
that buffer-menu selects the `*Buffer List*' buffer and
list-buffers does not.  If you run list-buffers (that is,
type C-x C-b) and select the buffer list manually, you can use all
the commands described here.

