27.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 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 29.3.3 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 (see section 29.3.1 Access to Frame Parameters).

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, see section 29.9 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. See section 29.3.3 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. See section 28.6 Buffers and Windows.