@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Buffers, Windows, Files, Top
+@node Buffers
@chapter Using Multiple Buffers
@cindex buffers
the file's text. Each time you invoke Dired, a buffer is used to hold
the directory listing. If you send a message with @kbd{C-x m}, a
buffer is used to hold the text of the message. When you ask for a
-command's documentation, that appears in a buffer named @samp{*Help*}.
+command's documentation, that appears in a buffer named @file{*Help*}.
Each buffer has a unique name, which can be of any length. When a
buffer is displayed in a window, its name is shown in the mode line
matters in buffer names. Most buffers are made by visiting files, and
their names are derived from the files' names; however, you can also
create an empty buffer with any name you want. A newly started Emacs
-has several buffers, including one named @samp{*scratch*}, which can
+has several buffers, including one named @file{*scratch*}, which can
be used for evaluating Lisp expressions and is not associated with any
file (@pxref{Lisp Interaction}).
by the largest buffer position representable by @dfn{Emacs integers}.
This is because Emacs tracks buffer positions using that data type.
For typical 64-bit machines, this maximum buffer size is @math{2^61 -
-2} bytes, or about 2 EiB. For typical 32-bit machines, the maximum is
-usually @math{2^29 - 2} bytes, or about 512 MiB. Buffer sizes are
-also limited by the amount of memory present in the system.
+2} bytes, or about 2 EiB@. For typical 32-bit machines, the maximum is
+usually @math{2^29 - 2} bytes, or about 512 MiB@. Buffer sizes are
+also limited by the amount of memory in the system.
@menu
* Select Buffer:: Creating a new buffer or reselecting an old one.
determines the new buffer's major mode; the default value is
Fundamental mode. @xref{Major Modes}. One reason to create a new
buffer is to use it for making temporary notes. If you try to save
-it, Emacs asks for the file name to use.
+it, Emacs asks for the file name to use, and the buffer's major mode
+is re-established taking that file name into account (@pxref{Choosing
+Modes}).
@kindex C-x @key{LEFT}
@kindex C-x @key{RIGHT}
@samp{.} in the first field of a line indicates that the buffer is
current. @samp{%} indicates a read-only buffer. @samp{*} indicates
-that the buffer is ``modified.'' If several buffers are modified, it
+that the buffer is ``modified''. If several buffers are modified, it
may be time to save some with @kbd{C-x s} (@pxref{Save Commands}).
Here is an example of a buffer list:
% HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO
% NEWS 481184 Outline ~/cvs/emacs/etc/NEWS
*scratch* 191 Lisp Interaction
- * *Messages* 1554 Fundamental
+ * *Messages* 1554 Messages
@end smallexample
@noindent
-The buffer @samp{*Help*} was made by a help request (@pxref{Help}); it
+The buffer @file{*Help*} was made by a help request (@pxref{Help}); it
is not visiting any file. The buffer @code{src} was made by Dired on
the directory @file{~/cvs/emacs/src/}. You can list only buffers that
are visiting files by giving the command a prefix argument, as in
@table @kbd
@item C-x C-q
-Toggle read-only status of buffer (@code{toggle-read-only}).
+Toggle read-only status of buffer (@code{read-only-mode}).
@item M-x rename-buffer @key{RET} @var{name} @key{RET}
Change the name of the current buffer.
@item M-x rename-uniquely
have special commands to operate on the text; also by visiting a file
whose access control says you cannot write it.
-@findex toggle-read-only
- The command @kbd{C-x C-q} (@code{toggle-read-only}) makes a read-only
+@findex read-only-mode
+@vindex view-read-only
+ The command @kbd{C-x C-q} (@code{read-only-mode}) makes a read-only
buffer writable, and makes a writable buffer read-only. This works by
setting the variable @code{buffer-read-only}, which has a local value
in each buffer and makes the buffer read-only if its value is
-non-@code{nil}.
+non-@code{nil}. If you change the option @code{view-read-only} to a
+non-@code{nil} value, making the buffer read-only with @kbd{C-x C-q}
+also enables View mode in the buffer (@pxref{View Mode}).
@findex rename-buffer
@kbd{M-x rename-buffer} changes the name of the current buffer. You
@kbd{M-x rename-uniquely} renames the current buffer to a similar
name with a numeric suffix added to make it both different and unique.
This command does not need an argument. It is useful for creating
-multiple shell buffers: if you rename the @samp{*shell*} buffer, then
+multiple shell buffers: if you rename the @file{*shell*} buffer, then
do @kbd{M-x shell} again, it makes a new shell buffer named
-@samp{*shell*}; meanwhile, the old shell buffer continues to exist
+@file{*shell*}; meanwhile, the old shell buffer continues to exist
under its new name. This method is also good for mail buffers,
compilation buffers, and most Emacs features that create special
buffers with particular names. (With some of these features, such as
To kill internal buffers as well, call @code{kill-matching-buffers}
with a prefix argument.
- The buffer menu feature is also convenient for killing various
+ The Buffer Menu feature is also convenient for killing various
buffers. @xref{Several Buffers}.
@vindex kill-buffer-hook
@cindex Midnight mode
@vindex midnight-mode
@vindex midnight-hook
- You can also have this buffer purging done for you, every day at
-midnight, by enabling Midnight mode. Midnight mode operates each day
+ You can also have this buffer purging done for you, once a day,
+by enabling Midnight mode. Midnight mode operates each day
at midnight; at that time, it runs @code{clean-buffer-list}, or
whichever functions you have placed in the normal hook
@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use
@node Several Buffers
@section Operating on Several Buffers
-@cindex buffer menu
+@cindex Buffer Menu
@table @kbd
@item M-x buffer-menu
Similar, but do it in another window.
@end table
- The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
+ The @dfn{Buffer Menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
does not merely list buffers. It also allows you to perform various
operations on buffers, through an interface similar to Dired
(@pxref{Dired}). You can save buffers, kill them (here called
@findex buffer-menu
@findex buffer-menu-other-window
- To use the buffer menu, type @kbd{C-x C-b} and switch to the window
-displaying the @samp{*Buffer List*} buffer. You can also type
-@kbd{M-x buffer-menu} to open the buffer menu in the selected window.
+ To use the Buffer Menu, type @kbd{C-x C-b} and switch to the window
+displaying the @file{*Buffer List*} buffer. You can also type
+@kbd{M-x buffer-menu} to open the Buffer Menu in the selected window.
Alternatively, the command @kbd{M-x buffer-menu-other-window} opens
-the buffer menu in another window, and selects that window.
+the Buffer Menu in another window, and selects that window.
- The buffer menu is a read-only buffer, and can be changed only
+ The Buffer Menu is a read-only buffer, and can be changed only
through the special commands described in this section. The usual
-Emacs cursor motion commands can be used in this buffer. The
-following commands apply to the buffer described on the current line:
+cursor motion commands can be used in this buffer. The following
+commands apply to the buffer described on the current line:
@table @kbd
@item d
-Request to delete (kill) the buffer, then move down. The request
-shows as a @samp{D} on the line, before the buffer name. Requested
-deletions take place when you type the @kbd{x} command.
+@findex Buffer-menu-delete
+@kindex d @r{(Buffer Menu)}
+Flag the buffer for deletion (killing), then move point to the next
+line (@code{Buffer-menu-delete}). The deletion flag is indicated by
+the character @samp{D} on the line, before the buffer name. The
+deletion occurs only when you type the @kbd{x} command (see below).
+
@item C-d
-Like @kbd{d} but move up afterwards instead of down.
+@findex Buffer-menu-delete-backwards
+@kindex C-d @r{(Buffer Menu)}
+Like @kbd{d}, but move point up instead of down
+(@code{Buffer-menu-delete-backwards}).
+
@item s
-Request to save the buffer. The request shows as an @samp{S} on the
-line. Requested saves take place when you type the @kbd{x} command.
-You may request both saving and deletion for the same buffer.
+@findex Buffer-menu-save
+@kindex s @r{(Buffer Menu)}
+Flag the buffer for saving (@code{Buffer-menu-save}). The save flag
+is indicated by the character @samp{S} on the line, before the buffer
+name. The saving occurs only when you type @kbd{x}. You may request
+both saving and deletion for the same buffer.
+
@item x
-Perform previously requested deletions and saves.
+@findex Buffer-menu-execute
+@kindex x @r{(Buffer Menu)}
+Perform all flagged deletions and saves (@code{Buffer-menu-execute}).
+
@item u
-Remove any request made for the current line, and move down.
+@findex Buffer-menu-unmark
+@kindex u @r{(Buffer Menu)}
+Remove all flags from the current line, and move down
+(@code{Buffer-menu-unmark}).
+
@item @key{DEL}
-Move to previous line and remove any request made for that line.
+@findex Buffer-menu-backup-unmark
+@kindex DEL @r{(Buffer Menu)}
+Move to the previous line and remove all flags on that line
+(@code{Buffer-menu-backup-unmark}).
@end table
- The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
-flags also move down (or up) one line. They accept a numeric argument
-as a repeat count.
+@noindent
+The commands for adding or removing flags, @kbd{d}, @kbd{C-d}, @kbd{s}
+and @kbd{u}, all accept a numeric argument as a repeat count.
- These commands operate immediately on the buffer listed on the current
-line:
+ The following commands operate immediately on the buffer listed on
+the current line. They also accept a numeric argument as a repeat
+count.
@table @kbd
@item ~
-Mark the buffer ``unmodified.'' The command @kbd{~} does this
-immediately when you type it.
+@findex Buffer-menu-not-modified
+@kindex ~ @r{(Buffer Menu)}
+Mark the buffer as unmodified (@code{Buffer-menu-not-modified}).
+@xref{Save Commands}.
+
@item %
-Toggle the buffer's read-only flag. The command @kbd{%} does
-this immediately when you type it.
+@findex Buffer-menu-toggle-read-only
+@kindex % @r{(Buffer Menu)}
+Toggle the buffer's read-only status
+(@code{Buffer-menu-toggle-read-only}). @xref{Misc Buffer}.
+
@item t
-Visit the buffer as a tags table. @xref{Select Tags Table}.
+@findex Buffer-menu-visit-tags-table
+@kindex % @r{(Buffer Menu)}
+Visit the buffer as a tags table
+(@code{Buffer-menu-visit-tags-table}). @xref{Select Tags Table}.
@end table
- There are also commands to select another buffer or buffers:
+ The following commands are used to select another buffer or buffers:
@table @kbd
@item q
-Quit the buffer menu---immediately display the most recent formerly
-visible buffer in its place.
+@findex quit-window
+@kindex q @r{(Buffer Menu)}
+Quit the Buffer Menu (@code{quit-window}). The most recent formerly
+visible buffer is displayed in its place.
+
@item @key{RET}
@itemx f
-Immediately select this line's buffer in place of the @samp{*Buffer
-List*} buffer.
+@findex Buffer-menu-this-window
+@kindex f @r{(Buffer Menu)}
+@kindex RET @r{(Buffer Menu)}
+Select this line's buffer, replacing the @file{*Buffer List*} buffer
+in its window (@code{Buffer-menu-this-window}).
+
@item o
-Immediately select this line's buffer in another window as if by
-@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
+@findex Buffer-menu-other-window
+@kindex o @r{(Buffer Menu)}
+Select this line's buffer in another window, as if by @kbd{C-x 4 b},
+leaving @file{*Buffer List*} visible
+(@code{Buffer-menu-other-window}).
+
@item C-o
-Immediately display this line's buffer in another window, but don't
-select the window.
+@findex Buffer-menu-switch-other-window
+@kindex C-o @r{(Buffer Menu)}
+Display this line's buffer in another window, without selecting it
+(@code{Buffer-menu-switch-other-window}).
+
@item 1
-Immediately select this line's buffer in a full-screen window.
+@findex Buffer-menu-1-window
+@kindex 1 @r{(Buffer Menu)}
+Select this line's buffer in a full-frame window
+(@code{Buffer-menu-1-window}).
+
@item 2
-Immediately set up two windows, with this line's buffer selected in
-one, and the previously current buffer (aside from the buffer
-@samp{*Buffer List*}) displayed in the other.
+@findex Buffer-menu-2-window
+@kindex 2 @r{(Buffer Menu)}
+Set up two windows on the current frame, with this line's buffer
+selected in one, and a previously current buffer (aside from
+@file{*Buffer List*}) in the other (@code{Buffer-menu-2-window}).
+
@item b
-Bury the buffer listed on this line.
+@findex Buffer-menu-bury
+@kindex b @r{(Buffer Menu)}
+Bury this line's buffer (@code{Buffer-menu-bury}).
+
@item m
+@findex Buffer-menu-mark
+@kindex m @r{(Buffer Menu)}
Mark this line's buffer to be displayed in another window if you exit
-with the @kbd{v} command. The request shows as a @samp{>} at the
-beginning of the line. (A single buffer may not have both a delete
-request and a display request.)
+with the @kbd{v} command (@code{Buffer-menu-mark}). The display flag
+is indicated by the character @samp{>} at the beginning of the line.
+(A single buffer may not have both deletion and display flags.)
+
@item v
-Immediately select this line's buffer, and also display in other windows
-any buffers previously marked with the @kbd{m} command. If you have not
-marked any buffers, this command is equivalent to @kbd{1}.
+@findex Buffer-menu-select
+@kindex v @r{(Buffer Menu)}
+Select this line's buffer, and also display in other windows any
+buffers flagged with the @kbd{m} command (@code{Buffer-menu-select}).
+If you have not flagged any buffers, this command is equivalent to
+@kbd{1}.
@end table
- There is also a command that affects the entire buffer list:
+ The following commands affect the entire buffer list:
@table @kbd
+@item S
+@findex tabulated-list-sort
+@kindex S @r{(Buffer Menu)}
+Sort the Buffer Menu entries according to their values in the column
+at point. With a numeric prefix argument @var{n}, sort according to
+the @var{n}-th column (@code{tabulated-list-sort}).
+
@item T
-Delete, or reinsert, lines for non-file buffers. This command toggles
-the inclusion of such buffers in the buffer list.
+@findex Buffer-menu-toggle-files-only
+@kindex T @r{(Buffer Menu)}
+Delete, or reinsert, lines for non-file buffers
+@code{Buffer-menu-toggle-files-only}). This command toggles the
+inclusion of such buffers in the buffer list.
@end table
- What @code{buffer-menu} actually does is create and switch to a
-suitable buffer, and turn on Buffer Menu mode in it. Everything else
-described above is implemented by the special commands provided in
-Buffer Menu mode. One consequence of this is that you can switch from
-the @samp{*Buffer List*} buffer to another Emacs buffer, and edit
-there. You can reselect the @samp{*Buffer List*} buffer later, to
-perform the operations already requested, or you can kill it, or pay
-no further attention to it.
-
- Normally, the buffer @samp{*Buffer List*} is not updated
+ Normally, the buffer @file{*Buffer List*} is not updated
automatically when buffers are created and killed; its contents are
just text. If you have created, deleted or renamed buffers, the way
-to update @samp{*Buffer List*} to show what you have done is to type
+to update @file{*Buffer List*} to show what you have done is to type
@kbd{g} (@code{revert-buffer}). You can make this happen regularly
every @code{auto-revert-interval} seconds if you enable Auto Revert
mode in this buffer, as long as it is not marked modified. Global
-Auto Revert mode applies to the @samp{*Buffer List*} buffer only if
+Auto Revert mode applies to the @file{*Buffer List*} buffer only if
@code{global-auto-revert-non-file-buffers} is non-@code{nil}.
@iftex
@inforef{Autorevert,, emacs-xtra}, for details.
An @dfn{indirect buffer} shares the text of some other buffer, which
is called the @dfn{base buffer} of the indirect buffer. In some ways it
-is the analogue, for buffers, of a symbolic link between files.
+is a buffer analogue of a symbolic link between files.
@table @kbd
@findex make-indirect-buffer
@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
-Create an indirect buffer named @var{indirect-name} whose base buffer
-is @var{base-buffer}.
+Create an indirect buffer named @var{indirect-name} with base buffer
+@var{base-buffer}.
@findex clone-indirect-buffer
@item M-x clone-indirect-buffer @key{RET}
Create an indirect buffer that is a twin copy of the current buffer.
@code{clone-indirect-buffer-hook} after creating the indirect buffer.
The more general way to make an indirect buffer is with the command
-@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from
-buffer @var{base-buffer}, under the name @var{indirect-name}. It
-prompts for both @var{base-buffer} and @var{indirect-name} using the
-minibuffer.
+@kbd{M-x make-indirect-buffer}. It creates an indirect buffer
+named @var{indirect-name} from a buffer @var{base-buffer}, prompting for
+both using the minibuffer.
@node Buffer Convenience
@section Convenience Features and Customization of Buffer Handling
@menu
* Uniquify:: Making buffer names unique with directory parts.
-* Iswitchb:: Switching between buffers with substrings.
+* Icomplete:: Fast minibuffer selection.
* Buffer Menus:: Configurable buffer menu.
@end menu
@cindex unique buffer names
@cindex directories in buffer names
When several buffers visit identically-named files, Emacs must give
-the buffers distinct names. The usual method for making buffer names
-unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer
-names (all but one of them).
+the buffers distinct names. The default method
+(@code{uniquify-buffer-name-style} set to
+@code{post-forward-angle-brackets}) for making buffer names unique
+adds @samp{<dir1>}, @samp{<dir2>}, etc. to the end of the buffer
+names.
@vindex uniquify-buffer-name-style
- Other methods work by adding parts of each file's directory to the
-buffer name. To select one, load the library @file{uniquify} (e.g.
-using @code{(require 'uniquify)}), and customize the variable
-@code{uniquify-buffer-name-style} (@pxref{Easy Customization}).
-
- To begin with, the @code{forward} naming method includes part of the
-file's directory name at the beginning of the buffer name; using this
-method, buffers visiting the files @file{/u/rms/tmp/Makefile} and
+ There are several styles to make buffer names unique. To select
+one, customize the variable @code{uniquify-buffer-name-style}
+(@pxref{Easy Customization}).
+
+ The @code{forward} naming method includes part of the file's
+directory name at the beginning of the buffer name; using this method,
+buffers visiting the files @file{/u/rms/tmp/Makefile} and
@file{/usr/projects/zaphod/Makefile} would be named
-@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead
-of @samp{Makefile} and @samp{Makefile<2>}).
+@samp{tmp/Makefile} and @samp{zaphod/Makefile}.
In contrast, the @code{post-forward} naming method would call the
-buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the
+buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}. The default
+method @code{post-forward-angle-brackets} is like @code{post-forward}
+except that it prepends the unique path in angle brackets. The
@code{reverse} naming method would call them @samp{Makefile\tmp} and
@samp{Makefile\zaphod}. The nontrivial difference between
@code{post-forward} and @code{reverse} occurs when just one directory
name is not enough to distinguish two files; then @code{reverse} puts
the directory names in reverse order, so that @file{/top/middle/file}
becomes @samp{file\middle\top}, while @code{post-forward} puts them in
-forward order after the file name, as in @samp{file|top/middle}.
+forward order after the file name, as in @samp{file|top/middle}. If
+@code{uniquify-buffer-name-style} is set to @code{nil}, the buffer
+names simply get a @samp{<2>} etc. prepended. This used to be the
+default behavior in Emacs versions up to 24.4.
Which rule to follow for putting the directory names in the buffer
name is not very important if you are going to @emph{look} at the
know the rule, you won't have to look. And then you may find that one
rule or another is easier for you to remember and apply quickly.
-@node Iswitchb
-@subsection Switching Between Buffers using Substrings
-
-@findex iswitchb-mode
-@cindex Iswitchb mode
-@cindex mode, Iswitchb
-@kindex C-x b @r{(Iswitchb mode)}
-@kindex C-x 4 b @r{(Iswitchb mode)}
-@kindex C-x 5 b @r{(Iswitchb mode)}
-@kindex C-x 4 C-o @r{(Iswitchb mode)}
-
- Iswitchb global minor mode provides convenient switching between
-buffers using substrings of their names. It replaces the normal
-definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
-4 C-o} with alternative commands that are somewhat ``smarter.''
-
- When one of these commands prompts you for a buffer name, you can
-type in just a substring of the name you want to choose. As you enter
-the substring, Iswitchb mode continuously displays a list of buffers
-that match the substring you have typed.
-
- At any time, you can type @key{RET} to select the first buffer in
-the list. So the way to select a particular buffer is to make it the
+@node Icomplete
+@subsection Fast minibuffer selection
+
+@findex icomplete-mode
+@cindex Icomplete mode
+
+ Icomplete global minor mode provides a convenient way to quickly select an
+element among the possible completions in a minibuffer. When enabled, typing
+in the minibuffer continuously displays a list of possible completions that
+match the string you have typed.
+
+ At any time, you can type @key{C-j} to select the first completion in
+the list. So the way to select a particular completion is to make it the
first in the list. There are two ways to do this. You can type more
-of the buffer name and thus narrow down the list, excluding unwanted
-buffers above the desired one. Alternatively, you can use @kbd{C-s}
-and @kbd{C-r} to rotate the list until the desired buffer is first.
+of the completion name and thus narrow down the list, excluding unwanted
+completions above the desired one. Alternatively, you can use @kbd{C-.}
+and @kbd{C-,} to rotate the list until the desired buffer is first.
- @key{TAB} while entering the buffer name performs completion on the
-string you have entered, based on the displayed list of buffers.
+ @key{M-TAB} will select the first completion in the list, like @key{C-j} but
+without exiting the minibuffer, so you can edit it further. This is typically
+used when entering a file name, where @key{M-TAB} can be used a few times to
+descend in the hierarchy of directories.
- To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize
-the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy
+ To enable Icomplete mode, type @kbd{M-x icomplete-mode}, or customize
+the variable @code{icomplete-mode} to @code{t} (@pxref{Easy
Customization}).
@node Buffer Menus
@findex msb-mode
@cindex mode, MSB
@cindex MSB mode
-@cindex buffer menu
@findex mouse-buffer-menu
@kindex C-Down-Mouse-1
MSB global minor mode (``MSB'' stands for ``mouse select buffer'')