E.6.1 Buffer Internals

Buffers contain fields not directly accessible by the Lisp programmer. We describe them here, naming them by the names used in the C code. Many are accessible indirectly in Lisp programs via Lisp primitives.

Two structures 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 is a list of the struct buffer_text fields:

beg

This field contains the actual address of the buffer contents.

gpt

This holds the character position of the gap in the buffer.

z

This field contains the character position of the end of the buffer text.

gpt_byte

Contains the byte position of the gap.

z_byte

Holds the byte position of the end of the buffer text.

gap_size

Contains the size of buffer's gap.

modiff

This field counts buffer-modification events for this buffer. It is incremented for each such event, and never otherwise changed.

save_modiff

Contains the previous value of modiff, as of the last time a buffer was visited or saved in a file.

overlay_modiff

Counts modifications to overlays analogous to modiff.

beg_unchanged

Holds the number of characters at the start of the text that are known to be unchanged since the last redisplay that finished.

end_unchanged

Holds the number of characters at the end of the text that are known to be unchanged since the last redisplay that finished.

unchanged_modified

Contains the value of modiff at the time of the last redisplay that finished. If this value matches modiff, beg_unchanged and end_unchanged contain no useful information.

overlay_unchanged_modified

Contains the value of overlay_modiff at the time of the last redisplay that finished. If this value matches overlay_modiff, 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 are the other markers referring to this buffer text.

intervals

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

The fields of struct buffer are:

next

Points to the next buffer, in the chain of all buffers including killed buffers. This chain is used only for garbage collection, in order to collect killed buffers properly. Note that vectors, and most kinds of objects allocated as vectors, are all on one chain, but buffers are on a separate chain of their own.

own_text

This is a struct buffer_text structure. In an ordinary buffer, it holds the buffer contents. In indirect buffers, this field is not used.

text

This points to the buffer_text structure that is used 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.

pt

Contains the character position of point in a buffer.

pt_byte

Contains the byte position of point in a buffer.

begv

This field contains the character position of the beginning of the accessible range of text in the buffer.

begv_byte

This field contains the byte position of the beginning of the accessible range of text in the buffer.

zv

This field contains the character position of the end of the accessible range of text in the buffer.

zv_byte

This field contains the byte position 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_var_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

This field contains 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

This field contains the time when the buffer was last auto-saved.

auto_save_failure_time

The time at which we detected a failure to auto-save, or -1 if we didn't have a failure.

last_window_start

This field contains the window-start position in the buffer as of the last time the buffer was displayed in a window.

clip_changed

This flag is set when narrowing changes in a buffer.

prevent_redisplay_optimizations_p

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

undo_list

This field points to the buffer's undo list. See Undo.

name

The buffer name is a string that names the buffer. It is guaranteed to be unique. See Buffer Names.

filename

The name of the file visited in this buffer, or nil.

directory

The directory for expanding relative file names.

save_length

Length of the file this buffer is visiting, when last read or saved. This and other fields concerned with saving are not kept in the buffer_text structure because indirect buffers are never saved.

auto_save_file_name

File name used for auto-saving this buffer. This is not in the buffer_text because it's not used in indirect buffers at all.

read_only

Non-nil means this buffer is read-only.

mark

This field contains 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

This field contains 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 major mode, e.g., "Lisp".

mode_line_format

Mode line element that controls the format of the mode line. If this is nil, no mode line will be displayed.

header_line_format

This field is analoguous to mode_line_format for the mode line displayed at the top of windows.

keymap

This field holds the buffer's local keymap. See Keymaps.

abbrev_table

This buffer's local abbrevs.

syntax_table

This field contains the syntax table for the buffer. See Syntax Tables.

category_table

This field contains the category table for the buffer.

case_fold_search

The value of case-fold-search in this buffer.

tab_width

The value of tab-width in this buffer.

fill_column

The value of fill-column in this buffer.

left_margin

The value of left-margin in this buffer.

auto_fill_function

The value of auto-fill-function in this buffer.

downcase_table

This field contains the conversion table for converting text to lower case. See Case Tables.

upcase_table

This field contains the conversion table for converting text to upper case. See Case Tables.

case_canon_table

This field contains the conversion table for canonicalizing text for case-folding search. See Case Tables.

case_eqv_table

This field contains the equivalence table for case-folding search. See Case Tables.

truncate_lines

The value of truncate-lines in this buffer.

ctl_arrow

The value of ctl-arrow in this buffer.

selective_display

The value of selective-display in this buffer.

selective_display_ellipsis

The value of selective-display-ellipsis in this buffer.

minor_modes

An alist of the minor modes of this buffer.

overwrite_mode

The value of overwrite_mode in this buffer.

abbrev_mode

The value of abbrev-mode in this buffer.

display_table

This field contains the buffer's display table, or nil if it doesn't have one. See Display Tables.

save_modified

This field contains the time when the buffer was last saved, as an integer. See Buffer Modification.

mark_active

This field is non-nil if the buffer's mark is active.

overlays_before

This field holds a list of the overlays in this buffer that end at or before the current overlay center position. They are sorted in order of decreasing end position.

overlays_after

This field holds a list of the overlays in this buffer that end after the current overlay center position. They are sorted in order of increasing beginning position.

overlay_center

This field holds the current overlay center position. See Overlays.

enable_multibyte_characters

This field holds the buffer's local value of enable-multibyte-characters—either t or nil.

buffer_file_coding_system

The value of buffer-file-coding-system in this buffer.

file_format

The value of buffer-file-format in this buffer.

pt_marker

In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records point for this buffer when the buffer is not current.

begv_marker

In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records begv for this buffer when the buffer is not current.

zv_marker

In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records zv for this buffer when the buffer is not current.

file_truename

The truename of the visited file, or nil.

invisibility_spec

The value of buffer-invisibility-spec in this buffer.

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.

display_count

This field is incremented each time the buffer is displayed in a window.

left_margin_width

The value of left-margin-width in this buffer.

right_margin_width

The value of right-margin-width in this buffer.

indicate_empty_lines

Non-nil means indicate empty lines (lines with no text) with a small bitmap in the fringe, when using a window system that can do it.

display_time

This holds a time stamp that is updated each time this buffer is displayed in a window.

scroll_up_aggressively

The value of scroll-up-aggressively in this buffer.

scroll_down_aggressively

The value of scroll-down-aggressively in this buffer.