— Command: switch-to-buffer buffer-or-name &optional norecord

This function makes buffer-or-name the current buffer, and also displays the buffer in the selected window. This means that a human can see the buffer and subsequent keyboard commands will apply to it. Contrast this with set-buffer, which makes buffer-or-name the current buffer but does not display it in the selected window; see Current Buffer.

If buffer-or-name is nil, switch-to-buffer chooses a buffer using other-buffer. If buffer-or-name is a string that does not identify an existing buffer, then a new buffer by that name is created. The major mode for the new buffer is set according to the variable major-mode; see Auto Major Mode.

When the selected window is the minibuffer window or is strongly dedicated to its buffer (see Dedicated Windows), this function calls pop-to-buffer (see below) to display the buffer in some other window.

Normally the specified buffer is put at the front of the buffer list (both the selected frame's buffer list and the frame-independent buffer list). This affects the operation of other-buffer. However, if norecord is non-nil, this is not done. See The Buffer List.

The switch-to-buffer function is often used interactively, as the binding of C-x b. It is also used frequently in programs. It returns the buffer that it switched to.

— Command: switch-to-buffer-other-window buffer-or-name &optional norecord

This function makes the buffer specified by buffer-or-name current and displays it in a window not currently selected, using the function pop-to-buffer (see below).

The currently selected window is absolutely never used to do the job. If the selected window already displays buffer-or-name, then it continues to do so, but another window is nonetheless found to display it in as well.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

— Command: pop-to-buffer buffer-or-name &optional other-window norecord

This command makes buffer-or-name the current buffer and switches to it in some window, preferably not the window previously selected. The “popped-to” window becomes the selected window. Its frame is given the X server's focus, if possible; see Input Focus. The return value is the buffer that was switched to.

If buffer-or-name is nil, that means to choose some other buffer, but you don't specify which. If buffer-or-name is a string that does not name an existing buffer, a buffer by that name is created. The major mode for the new buffer is set according to the variable major-mode. See Auto Major Mode.

If either of the variables display-buffer-reuse-frames or pop-up-frames is non-nil, pop-to-buffer looks for a window in any visible frame already displaying the buffer; if there is one, it selects and returns that window. If no such window exists and pop-up-frames is non-nil, it creates a new frame and displays the buffer in it. Otherwise, pop-to-buffer operates entirely within the selected frame. (If the selected frame has just a minibuffer, pop-to-buffer operates within the most recently selected frame that was not just a minibuffer.)

If the variable pop-up-windows is non-nil, windows may be split to create a new window that is different from the original window. For details, see Choosing Window.

If other-window is non-nil, pop-to-buffer finds or creates another window even if buffer-or-name is already visible in the selected window. Thus buffer-or-name could end up displayed in two windows. On the other hand, if buffer-or-name is already displayed in the selected window and other-window is nil, then the selected window is considered sufficient for displaying buffer-or-name, so that nothing needs to be done.

All the variables that affect display-buffer affect pop-to-buffer as well. See Choosing Window.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

— Command: replace-buffer-in-windows &optional buffer-or-name

This function replaces buffer-or-name in all windows displaying it with some other buffer. It uses other-buffer to choose the other buffer. In the usual applications of this function, you don't care which other buffer is used; you just want to make sure that buffer-or-name is no longer displayed.

The argument buffer-or-name may be a buffer or the name of an existing buffer and defaults to the current buffer.

If a window displaying buffer-or-name is dedicated (see Dedicated Windows), and is not the only window on its frame, that window is deleted. If that window is the only window on its frame and there are other frames left, the window's frame is deleted too. If there are no other frames left, some other buffer is displayed in that window.

This function returns nil.