@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001, 2004
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Buffers, Windows, Files, Top
@cindex selected buffer
@cindex current buffer
- At any time, one and only one buffer is @dfn{selected}. It is also
-called the @dfn{current buffer}. Often we say that a command operates on
+ At any time, one and only one buffer is @dfn{current}. It is also
+called the @dfn{selected buffer}. Often we say that a command operates on
``the buffer'' as if there were only one; but really this means that the
-command operates on the selected buffer (most commands do).
+command operates on the current buffer (most commands do).
When Emacs has multiple windows, each window has its own chosen
buffer and displays it; at any time, only one of the windows is
-selected, and its chosen buffer is the selected buffer. Each window's
+selected, and its chosen buffer is the current buffer. Each window's
mode line normally displays the name of the window's chosen buffer
(@pxref{Windows}).
particular buffer, meaning its value in that buffer can be different from
the value in other buffers. @xref{Locals}.
+@cindex buffer size, maximum
+ A buffer's size cannot be larger than some maximum, which is defined
+by the largest buffer position representable by the @dfn{Emacs integer}
+data type. This is because Emacs tracks buffer positions using that
+data type. For 32-bit machines, the largest buffer size is 256
+megabytes.
+
@menu
* Select Buffer:: Creating a new buffer or reselecting an old one.
* List Buffers:: Getting a list of buffers that exist.
* 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.
-* Indirect Buffers:: An indirect buffer shares the text of another buffer.
+* Indirect Buffers:: An indirect buffer shares the text of another buffer.
* Buffer Convenience:: Convenience and customization features for
buffer handling.
@end menu
@key{RET}}. This runs the command @code{switch-to-buffer} with argument
@var{bufname}. You can use completion on an abbreviation for the buffer
name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
-specifies the most recently selected buffer that is not displayed in any
-window.@refill
+specifies the buffer that was current most recently among those not
+now displayed in any window.
@kindex C-x 4 b
@findex switch-to-buffer-other-window
file. The buffers are listed in the order that they were current; the
buffers that were current most recently come first.
- @samp{*} at the beginning of a line indicates the buffer is ``modified.''
+ @samp{*} in the first field of a line indicates the buffer is ``modified.''
If several buffers are modified, it may be time to save some with @kbd{C-x s}
(@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the
-selected buffer. Here is an example of a buffer list:@refill
+current buffer. Here is an example of a buffer list:@refill
@smallexample
- 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
+CRM Buffer Size Mode File
+. * .emacs 3294 Emacs-Lisp ~/.emacs
+ % *Help* 101 Help
+ search.c 86055 C ~/cvs/emacs/src/search.c
+ % src 20959 Dired by name ~/cvs/emacs/src/
+ * *mail* 42 Mail
+ % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO
+ % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS
+ *scratch* 191 Lisp Interaction
+ * *Messages* 1554 Fundamental
@end smallexample
@noindent
Note that the buffer @samp{*Help*} was made by a help request; it is
-not visiting any file. The buffer @code{man} was made by Dired on the
-directory @file{/u2/emacs/man/}. You can list only buffers that are
+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; for instance, by typing
@kbd{C-u C-x C-b}.
+@code{list-buffers} omits buffers whose name begins with a blank,
+unless they visit files: such buffers are used internally by Emacs.
+
@need 2000
@node Misc Buffer
@section Miscellaneous Buffer Operations
@table @kbd
@item C-x C-q
-Toggle read-only status of buffer (@code{vc-toggle-read-only}).
+Toggle read-only status of buffer (@code{toggle-read-only}).
@item M-x rename-buffer @key{RET} @var{name} @key{RET}
Change the name of the current buffer.
@item M-x rename-uniquely
@end table
@kindex C-x C-q
-@c Don't index vc-toggle-read-only here, it is indexed in files.texi,
-@c in the node "Basic VC Editing".
-@c @findex vc-toggle-read-only
@vindex buffer-read-only
@cindex read-only buffer
A buffer can be @dfn{read-only}, which means that commands to change
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
If you wish to make changes in a read-only buffer, use the command
-@kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer
-writable, and makes a writable buffer read-only. In most cases, this
+@kbd{C-x C-q} (@code{toggle-read-only}). It 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}. If the file is maintained with version control,
-@kbd{C-x C-q} works through the version control system to change the
-read-only status of the file as well as the buffer. @xref{Version
+non-@code{nil}. If you have files under version control, you may find
+it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only}
+instead. Then, typing @kbd{C-x C-q} not only changes the read-only
+flag, but it also checks the file in or out. @xref{Version
Control}.
@findex rename-buffer
specify a name that is in use for some other buffer, an error happens and
no renaming is done.
- @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 do @kbd{M-x
-shell} again, it makes a new shell buffer named @samp{*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.
+@findex rename-uniquely
+ @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
+do @kbd{M-x shell} again, it makes a new shell buffer named
+@samp{*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
+@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to
+switch to some other buffer before using the command, in order for it
+to make a different buffer.)
@findex view-buffer
@kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
buffer releases its space back to the operating system so that other
programs can use it. Here are some commands for killing buffers:
-@c WideCommands
@table @kbd
@item C-x k @var{bufname} @key{RET}
Kill buffer @var{bufname} (@code{kill-buffer}).
@kindex C-x k
@kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
-specify in the minibuffer. The default, used if you type just @key{RET}
-in the minibuffer, is to kill the current buffer. If you kill the
-current buffer, another buffer is selected; one that has been selected
-recently but does not appear in any window now. If you ask to kill a
-file-visiting buffer that is modified (has unsaved editing), then you
-must confirm with @kbd{yes} before the buffer is killed.
+specify in the minibuffer. The default, used if you type just
+@key{RET} in the minibuffer, is to kill the current buffer. If you
+kill the current buffer, another buffer becomes current: one that was
+current in the recent past but is not displayed in any window now. If
+you ask to kill a file-visiting buffer that is modified (has unsaved
+editing), then you must confirm with @kbd{yes} before the buffer is
+killed.
The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
one. An answer of @kbd{y} means to kill the buffer. Killing the current
@table @kbd
@item M-x buffer-menu
Begin editing a buffer listing all Emacs buffers.
+@item M-x buffer-menu-other-window.
+Similar, but do it in another window.
@end table
@findex buffer-menu
- The command @code{buffer-menu} writes a list of all Emacs buffers into
-the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
-mode. The buffer is read-only, and can be changed only through the
-special commands described in this section. The usual Emacs cursor
-motion commands can be used in the @samp{*Buffer List*} buffer. The
-following commands apply to the buffer described on the current line.
+@findex buffer-menu-other-window
+ The command @code{buffer-menu} writes a list of all Emacs
+buffers@footnote{Buffers which don't visit files and whose names begin
+with a space are omitted: these are used internally by Emacs.} into the
+buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
+mode. The list in the @samp{*Buffer List*} buffer looks exactly as
+described in @ref{List Buffers}. The buffer is read-only, and can be
+changed only through the special commands described in this section.
+The usual Emacs cursor motion commands can be used in the @samp{*Buffer
+List*} buffer. The following commands apply to the buffer described on
+the current line.
@table @kbd
@item d
@item 1
Immediately select this line's buffer in a full-screen window.
@item 2
-Immediately set up two windows, with this line's buffer in one, and the
-previously selected buffer (aside from the buffer @samp{*Buffer List*})
-in the other.
+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.
@item b
Bury the buffer listed on this line.
@item m
and select the buffer list manually, you can use all of the commands
described here.
- The buffer @samp{*Buffer List*} is not updated automatically when
+ Normally, the buffer @samp{*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 @kbd{g}
(@code{revert-buffer}) or repeat the @code{buffer-menu} command.
+ The @samp{*Buffer List*} buffer does automatically update every
+@code{auto-revert-interval} seconds if you enable Auto Revert mode in
+it. (As long as it is not marked modified.) Global Auto Revert mode
+does not update the @samp{*Buffer List*} buffer by default, but it
+does if @code{global-auto-revert-non-file-buffers} is non-@code{nil}.
+@inforef{Autorevert,, emacs-xtra}, for details.
+
+ The command @code{buffer-menu-other-window} works the same as
+@code{buffer-menu}, except that it displays the buffers list in
+another window.
+
@node Indirect Buffers
@section Indirect Buffers
@cindex indirect buffer
One way to use indirect buffers is to display multiple views of an
outline. @xref{Outline Views}.
-@cindex multiple @samp{*info*} and @samp{*Help*} buffers
A quick and handy way to make an indirect buffer is with the command
@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect
buffer whose base buffer is the current buffer. With a numeric
argument, it prompts for the name of the indirect buffer; otherwise it
defaults to the name of the current buffer, modifying it by adding a
-@samp{<@var{n}>} prefix if required. @kbd{C-x 4 c}
+@samp{<@var{n}>} suffix if required. @kbd{C-x 4 c}
(@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
-clone-indirect-buffer}, but it selects the cloned buffer in another
-window. These commands come in handy if you want to create new
-@samp{*info*} or @samp{*Help*} buffers, for example.
+clone-indirect-buffer}, but it selects the new buffer in another
+window.
- The more general way 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.
+ 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.
@node Buffer Convenience
@section Convenience Features and Customization of Buffer Handling
@menu
* Uniquify:: Buffer names can contain directory parts.
* Iswitchb:: Switching between buffers with substrings.
-* Buffer Menus:: Configurable buffer menu.
+* Buffer Menus:: Configurable buffer menu.
@end menu
@node Uniquify
prefer. It replaces the bindings of @code{mouse-buffer-menu},
normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You
can customize the menu in the @code{msb} Custom group.
+
+@ignore
+ arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695
+@end ignore