Function: get-buffer-create

get-buffer-create is a function defined in buffer.c.

Signature

(get-buffer-create BUFFER-OR-NAME &optional INHIBIT-BUFFER-HOOKS)

Documentation

Return the buffer specified by BUFFER-OR-NAME, creating a new one if needed.

If BUFFER-OR-NAME is a string and a live buffer with that name exists, return that buffer. If no such buffer exists, create a new buffer with that name and return it.

If BUFFER-OR-NAME starts with a space, the new buffer does not keep undo information. If optional argument INHIBIT-BUFFER-HOOKS is non-nil, the new buffer does not run the hooks kill-buffer-hook, kill-buffer-query-functions, and buffer-list-update-hook. This avoids slowing down internal or temporary buffers that are never presented to users or passed on to other applications.

If BUFFER-OR-NAME is a buffer instead of a string, return it as given, even if it is dead. The return value is never nil.

Other relevant functions are documented in the buffer group.

View in manual

Probably introduced at or before Emacs version 19.29.

Shortdoc

;; buffer
(get-buffer-create "*foo*")
    e.g. => #<buffer *foo*>

Aliases

org-get-buffer-create

Source Code

// Defined in /usr/src/emacs/src/buffer.c
{
  register Lisp_Object buffer, name;
  register struct buffer *b;

  buffer = Fget_buffer (buffer_or_name);
  if (!NILP (buffer))
    return buffer;

  if (SCHARS (buffer_or_name) == 0)
    error ("Empty string for buffer name is not allowed");

  b = allocate_buffer ();

  /* An ordinary buffer uses its own struct buffer_text.  */
  b->text = &b->own_text;
  b->base_buffer = NULL;
  /* No one shares the text with us now.  */
  b->indirections = 0;
  /* No one shows us now.  */
  b->window_count = 0;

  memset (&b->local_flags, 0, sizeof (b->local_flags));

  BUF_GAP_SIZE (b) = 20;
  block_input ();
  /* We allocate extra 1-byte at the tail and keep it always '\0' for
     anchoring a search.  */
  alloc_buffer_text (b, BUF_GAP_SIZE (b) + 1);
  unblock_input ();
  if (! BUF_BEG_ADDR (b))
    buffer_memory_full (BUF_GAP_SIZE (b) + 1);

  b->pt = BEG;
  b->begv = BEG;
  b->zv = BEG;
  b->pt_byte = BEG_BYTE;
  b->begv_byte = BEG_BYTE;
  b->zv_byte = BEG_BYTE;

  BUF_GPT (b) = BEG;
  BUF_GPT_BYTE (b) = BEG_BYTE;

  BUF_Z (b) = BEG;
  BUF_Z_BYTE (b) = BEG_BYTE;
  BUF_MODIFF (b) = 1;
  BUF_CHARS_MODIFF (b) = 1;
  BUF_OVERLAY_MODIFF (b) = 1;
  BUF_SAVE_MODIFF (b) = 1;
  BUF_COMPACT (b) = 1;
  set_buffer_intervals (b, NULL);
  BUF_UNCHANGED_MODIFIED (b) = 1;
  BUF_OVERLAY_UNCHANGED_MODIFIED (b) = 1;
  BUF_END_UNCHANGED (b) = 0;
  BUF_BEG_UNCHANGED (b) = 0;
  *(BUF_GPT_ADDR (b)) = *(BUF_Z_ADDR (b)) = 0; /* Put an anchor '\0'.  */
  b->text->inhibit_shrinking = false;
  b->text->redisplay = false;

  b->newline_cache = 0;
  b->width_run_cache = 0;
  b->bidi_paragraph_cache = 0;
  bset_width_table (b, Qnil);
  b->prevent_redisplay_optimizations_p = 1;

#ifdef HAVE_TREE_SITTER
  /* By default, use empty linecol, which means disable tracking.  */
  SET_BUF_TS_LINECOL_BEGV (b, TREESIT_EMPTY_LINECOL);
  SET_BUF_TS_LINECOL_POINT (b, TREESIT_EMPTY_LINECOL);
  SET_BUF_TS_LINECOL_ZV (b, TREESIT_EMPTY_LINECOL);
#endif

  /* An ordinary buffer normally doesn't need markers
     to handle BEGV and ZV.  */
  bset_pt_marker (b, Qnil);
  bset_begv_marker (b, Qnil);
  bset_zv_marker (b, Qnil);

  name = Fcopy_sequence (buffer_or_name);
  set_string_intervals (name, NULL);
  bset_name (b, name);
  bset_last_name (b, name);

  b->inhibit_buffer_hooks = !NILP (inhibit_buffer_hooks);
  bset_undo_list (b, SREF (name, 0) != ' ' ? Qnil : Qt);

  reset_buffer (b);
  reset_buffer_local_variables (b, 1);

  bset_mark (b, Fmake_marker ());
  BUF_MARKERS (b) = NULL;

  /* Put this in the alist of all live buffers.  */
  XSETBUFFER (buffer, b);
  Vbuffer_alist = nconc2 (Vbuffer_alist, list1 (Fcons (name, buffer)));

  run_buffer_list_update_hook (b);

  return buffer;
}