E.9.1 Buffer Internals

Two structures (see buffer.h) are used to represent buffers in C. The buffer_text structure contains fields describing the text of a buffer; the buffer structure holds other fields. In the case of indirect buffers, two or more buffer structures reference the same buffer_text structure.

Here are some of the fields in struct buffer_text:

beg

The address of the buffer contents. The buffer contents is a linear C array of char, with the gap somewhere in its midst.

gpt
gpt_byte

The character and byte positions of the buffer gap. See The Buffer Gap.

z
z_byte

The character and byte positions of the end of the buffer text.

gap_size

The size of buffer’s gap. See The Buffer Gap.

modiff
save_modiff
chars_modiff
overlay_modiff

These fields count the number of buffer-modification events performed in this buffer. modiff is incremented after each buffer-modification event, and is never otherwise changed; save_modiff contains the value of modiff the last time the buffer was visited or saved; chars_modiff counts only modifications to the characters in the buffer, ignoring all other kinds of changes (such as text properties); and overlay_modiff counts only modifications to the buffer’s overlays.

beg_unchanged
end_unchanged

The number of characters at the start and end of the text that are known to be unchanged since the last complete redisplay.

unchanged_modified
overlay_unchanged_modified

The values of modiff and overlay_modiff, respectively, after the last complete redisplay. If their current values match modiff or overlay_modiff, that means beg_unchanged and end_unchanged contain no useful information.

markers

The markers that refer to this buffer. This is actually a single marker, and successive elements in its marker chain (a linked list) are the other markers referring to this buffer text.

intervals

The interval tree which records the text properties of this buffer.

Some of the fields of struct buffer are:

header

A header of type union vectorlike_header is common to all vectorlike objects.

own_text

A struct buffer_text structure that ordinarily holds the buffer contents. In indirect buffers, this field is not used.

text

A pointer to the buffer_text structure for this buffer. In an ordinary buffer, this is the own_text field above. In an indirect buffer, this is the own_text field of the base buffer.

next

A pointer to the next buffer, in the chain of all buffers, including killed buffers. This chain is used only for allocation and garbage collection, in order to collect killed buffers properly.

pt
pt_byte

The character and byte positions of point in a buffer.

begv
begv_byte

The character and byte positions of the beginning of the accessible range of text in the buffer.

zv
zv_byte

The character and byte positions of the end of the accessible range of text in the buffer.

base_buffer

In an indirect buffer, this points to the base buffer. In an ordinary buffer, it is null.

local_flags

This field contains flags indicating that certain variables are local in this buffer. Such variables are declared in the C code using DEFVAR_PER_BUFFER, and their buffer-local bindings are stored in fields in the buffer structure itself. (Some of these fields are described in this table.)

modtime

The modification time of the visited file. It is set when the file is written or read. Before writing the buffer into a file, this field is compared to the modification time of the file to see if the file has changed on disk. See Buffer Modification.

auto_save_modified

The time when the buffer was last auto-saved.

last_window_start

The window-start position in the buffer as of the last time the buffer was displayed in a window.

clip_changed

This flag indicates that narrowing has changed in the buffer. See Narrowing.

prevent_redisplay_optimizations_p

This flag indicates that redisplay optimizations should not be used to display this buffer.

inhibit_buffer_hooks

This flag indicates that the buffer should not run the hooks kill-buffer-hook, kill-buffer-query-functions (see Killing Buffers), and buffer-list-update-hook (see The Buffer List). It is set at buffer creation (see Creating Buffers), and avoids slowing down internal or temporary buffers, such as those created by with-temp-buffer (see Current Buffer).

name

A Lisp string that names the buffer. It is guaranteed to be unique. See Buffer Names. This and the following fields have their names in the C struct definition end in a _ to indicate that they should not be accessed directly, but via the BVAR macro, like this:

  Lisp_Object buf_name = BVAR (buffer, name);
save_length

The length of the file this buffer is visiting, when last read or saved. It can have 2 special values: −1 means auto-saving was turned off in this buffer, and −2 means don’t turn off auto-saving if buffer text shrinks a lot. This and other fields concerned with saving are not kept in the buffer_text structure because indirect buffers are never saved.

directory

The directory for expanding relative file names. This is the value of the buffer-local variable default-directory (see Functions that Expand Filenames).

filename

The name of the file visited in this buffer, or nil. This is the value of the buffer-local variable buffer-file-name (see Buffer File Name).

undo_list
backed_up
auto_save_file_name
auto_save_file_format
read_only
file_format
file_truename
invisibility_spec
display_count
display_time

These fields store the values of Lisp variables that are automatically buffer-local (see Buffer-Local Variables), whose corresponding variable names have the additional prefix buffer- and have underscores replaced with dashes. For instance, undo_list stores the value of buffer-undo-list.

mark

The mark for the buffer. The mark is a marker, hence it is also included on the list markers. See The Mark.

local_var_alist

The association list describing the buffer-local variable bindings of this buffer, not including the built-in buffer-local bindings that have special slots in the buffer object. (Those slots are omitted from this table.) See Buffer-Local Variables.

major_mode

Symbol naming the major mode of this buffer, e.g., lisp-mode.

mode_name

Pretty name of the major mode, e.g., "Lisp".

keymap
abbrev_table
syntax_table
category_table
display_table

These fields store the buffer’s local keymap (see Keymaps), abbrev table (see Abbrev Tables), syntax table (see Syntax Tables), category table (see Categories), and display table (see Display Tables).

downcase_table
upcase_table
case_canon_table

These fields store the conversion tables for converting text to lower case, upper case, and for canonicalizing text for case-fold search. See The Case Table.

minor_modes

An alist of the minor modes of this buffer.

pt_marker
begv_marker
zv_marker

These fields are only used in an indirect buffer, or in a buffer that is the base of an indirect buffer. Each holds a marker that records pt, begv, and zv respectively, for this buffer when the buffer is not current.

mode_line_format
header_line_format
case_fold_search
tab_width
fill_column
left_margin
auto_fill_function
truncate_lines
word_wrap
ctl_arrow
bidi_display_reordering
bidi_paragraph_direction
selective_display
selective_display_ellipses
overwrite_mode
abbrev_mode
mark_active
enable_multibyte_characters
buffer_file_coding_system
cache_long_line_scans
point_before_scroll
left_fringe_width
right_fringe_width
fringes_outside_margins
scroll_bar_width
indicate_empty_lines
indicate_buffer_boundaries
fringe_indicator_alist
fringe_cursor_alist
scroll_up_aggressively
scroll_down_aggressively
cursor_type
cursor_in_non_selected_windows

These fields store the values of Lisp variables that are automatically buffer-local (see Buffer-Local Variables), whose corresponding variable names have underscores replaced with dashes. For instance, mode_line_format stores the value of mode-line-format.

overlays

The interval tree containing this buffer’s overlays.

last_selected_window

This is the last window that was selected with this buffer in it, or nil if that window no longer displays this buffer.