37.8 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 deletes 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. Several functions, notably other-buffer, use this ordering. A buffer list displayed for the user also follows this order.

Every frame has its own order for the buffer list. Switching to a new buffer inside of a particular frame changes the buffer list order for that frame, but does not affect the buffer list order of any other frames. In addition, there is a global, non-frame buffer list order that is independent of the buffer list orders for any particular frame.

Note that the different buffer lists all contain the same elements. It is only the order of those elements that is different.

Function: buffer-list &optional frame

This function returns a list of all buffers, including those whose names begin with a space. The elements are actual buffers, not their names. The order of the list is specific to frame, which defaults to the current frame. If frame is t, the global, non-frame ordering is returned instead.

(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")

Buffers appear earlier in the list if they were current more recently.

This list is a copy of a list used inside SXEmacs; modifying it has no effect on the buffers.

Function: other-buffer &optional buffer-or-name frame visible-ok

This function returns the first buffer in the buffer list other than buffer-or-name, in frame’s ordering for the buffer list. (frame defaults to the current frame. If frame is t, then the global, non-frame ordering is used.) Usually this is the buffer most recently shown in the selected window, aside from buffer-or-name. Buffers are moved to the front of the list when they are selected and to the end when they are buried. Buffers whose names start with a space are not considered.

If buffer-or-name is not supplied (or if it is not a buffer), then other-buffer returns the first buffer on the buffer list that is not visible in any window in a visible frame.

If the selected frame has a non-nil buffer-predicate property, 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. See X Frame Properties.

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).

Note that in FSF Emacs 19, there is no frame argument, and visible-ok is the second argument instead of the third.

Command: list-buffers &optional files-only

This function displays a listing of the names of existing buffers. It clears the buffer ‘*Buffer List*’, then inserts the listing into that buffer and displays it in a window. list-buffers is intended for interactive use, and is described fully in The SXEmacs Reference Manual. It returns nil.

Command: bury-buffer &optional buffer-or-name before

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.

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.

If you wish to replace a buffer in all the windows that display it, use replace-buffer-in-windows. See Buffers and Windows.