28.9 Creating Buffers

This section describes the two primitives for creating buffers. get-buffer-create creates a buffer if it finds no existing buffer with the specified name; generate-new-buffer always creates a new buffer and gives it a unique name.

Both functions accept an optional argument inhibit-buffer-hooks. If it is non-nil, the buffer they create does not run the hooks kill-buffer-hook, kill-buffer-query-functions (see Killing Buffers), and buffer-list-update-hook (see The Buffer List). This avoids slowing down internal or temporary buffers that are never presented to users or passed on to other applications.

Other functions you can use to create buffers include with-output-to-temp-buffer (see Temporary Displays) and create-file-buffer (see Visiting Files). Starting a subprocess can also create a buffer (see Processes).

Function: get-buffer-create buffer-or-name &optional inhibit-buffer-hooks

This function returns a buffer named buffer-or-name. The buffer returned does not become the current buffer—this function does not change which buffer is current.

buffer-or-name must be either a string or an existing buffer. If it is a string and a live buffer with that name already exists, get-buffer-create returns that buffer. If no such buffer exists, it creates a new buffer. If buffer-or-name is a buffer instead of a string, it is returned as given, even if it is dead.

(get-buffer-create "foo")
     ⇒ #<buffer foo>

The major mode for a newly created buffer is set to Fundamental mode. (The default value of the variable major-mode is handled at a higher level; see How Emacs Chooses a Major Mode.) If the name begins with a space, the buffer initially disables undo information recording (see Undo).

Function: generate-new-buffer name &optional inhibit-buffer-hooks

This function returns a newly created, empty buffer, but does not make it current. The name of the buffer is generated by passing name to the function generate-new-buffer-name (see Buffer Names). Thus, if there is no buffer named name, then that is the name of the new buffer; if that name is in use, a suffix of the form ‘<n>’, where n is an integer, is appended to name.

An error is signaled if name is not a string.

(generate-new-buffer "bar")
     ⇒ #<buffer bar>
(generate-new-buffer "bar")
     ⇒ #<buffer bar<2>>
(generate-new-buffer "bar")
     ⇒ #<buffer bar<3>>

The major mode for the new buffer is set to Fundamental mode. The default value of the variable major-mode is handled at a higher level. See How Emacs Chooses a Major Mode.