GNU Info

(elisp)The Buffer List

---

Next: Creating Buffers Prev: Read Only Buffers Up: Buffers

---

Enter node , (file) or (file)node

The Buffer List
===============

   The "buffer list" is a list of all live buffers.  Creating a buffer
adds it to this list, and killing a buffer excises it.  The order of
the buffers in the list is based primarily on how recently each buffer
has been displayed in the selected window.  Buffers move to the front
of the list when they are selected and to the end when they are buried
(see `bury-buffer', below).  Several functions, notably `other-buffer',
use this ordering.  A buffer list displayed for the user also follows
this order.

   In addition to the fundamental Emacs buffer list, each frame has its
own version of the buffer list, in which the buffers that have been
selected in that frame come first, starting with the buffers most
recently selected _in that frame_.  (This order is recorded in FRAME's
`buffer-list' frame parameter; see Note: Window Frame Parameters.)
The buffers that were never selected in FRAME come afterward, ordered
according to the fundamental Emacs buffer list.

 - Function: buffer-list &optional frame
     This function returns the buffer list, including all buffers, even
     those whose names begin with a space.  The elements are actual
     buffers, not their names.

     If FRAME is a frame, this returns FRAME's buffer list.  If FRAME
     is `nil', the fundamental Emacs buffer list is used: all the
     buffers appear in order of most recent selection, regardless of
     which frames they were selected in.

          (buffer-list)
               => (#<buffer buffers.texi>
                   #<buffer  *Minibuf-1*> #<buffer buffer.c>
                   #<buffer *Help*> #<buffer TAGS>)
          
          ;; Note that the name of the minibuffer
          ;;   begins with a space!
          (mapcar (function buffer-name) (buffer-list))
              => ("buffers.texi" " *Minibuf-1*"
                  "buffer.c" "*Help*" "TAGS")

   The list that `buffer-list' returns is constructed specifically by
`buffer-list'; it is not an internal Emacs data structure, and
modifying it has no effect on the order of buffers.  If you want to
change the order of buffers in the frame-independent buffer list, here
is an easy way:

     (defun reorder-buffer-list (new-list)
       (while new-list
         (bury-buffer (car new-list))
         (setq new-list (cdr new-list))))

   With this method, you can specify any order for the list, but there
is no danger of losing a buffer or adding something that is not a valid
live buffer.

   To change the order or value of a frame's buffer list, set the
frame's `buffer-list' frame parameter with `modify-frame-parameters'
(Note: Parameter Access).

 - Function: other-buffer &optional buffer visible-ok frame
     This function returns the first buffer in the buffer list other
     than BUFFER.  Usually this is the buffer selected most recently (in
     frame FRAME or else the currently selected frame, Note: Input
     Focus), aside from BUFFER.  Buffers whose names start with a
     space are not considered at all.

     If BUFFER is not supplied (or if it is not a buffer), then
     `other-buffer' returns the first buffer in the selected frame's
     buffer list that is not now visible in any window in a visible
     frame.

     If FRAME has a non-`nil' `buffer-predicate' parameter, then
     `other-buffer' uses that predicate to decide which buffers to
     consider.  It calls the predicate once for each buffer, and if the
     value is `nil', that buffer is ignored.  Note: Window Frame
     Parameters.

     If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
     visible in any window on any visible frame, except as a last
     resort.   If VISIBLE-OK is non-`nil', then it does not matter
     whether a buffer is displayed somewhere or not.

     If no suitable buffer exists, the buffer `*scratch*' is returned
     (and created, if necessary).

 - Command: bury-buffer &optional buffer-or-name
     This function puts BUFFER-OR-NAME at the end of the buffer list,
     without changing the order of any of the other buffers on the list.
     This buffer therefore becomes the least desirable candidate for
     `other-buffer' to return.

     `bury-buffer' operates on each frame's `buffer-list' parameter as
     well as the frame-independent Emacs buffer list; therefore, the
     buffer that you bury will come last in the value of `(buffer-list
     FRAME)' and in the value of `(buffer-list nil)'.

     If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
     current buffer.  In addition, if the buffer is displayed in the
     selected window, this switches to some other buffer (obtained using
     `other-buffer') in the selected window.  But if the buffer is
     displayed in some other window, it remains displayed there.

     To replace a buffer in all the windows that display it, use
     `replace-buffer-in-windows'.  Note: Buffers and Windows.