# HG changeset patch # User Gerd Moellmann # Date 940849604 0 # Node ID cdd1c350aae952e962a9ac3f6e4ff9e7862be19d # Parent d39ec0a2708195d4a0d8cfe225be27ef1b66c77c Patches from rms. diff -r d39ec0a27081 -r cdd1c350aae9 lispref/internals.texi --- a/lispref/internals.texi Mon Oct 25 04:58:18 1999 +0000 +++ b/lispref/internals.texi Mon Oct 25 11:06:44 1999 +0000 @@ -64,13 +64,19 @@ extra time is not too severe a problem. @cindex @file{site-load.el} + You can specify additional files to preload by writing a library named -@file{site-load.el} that loads them. You may need to increase the value -of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the -additional data. (Try adding increments of 20000 until it is big -enough.) However, the advantage of preloading additional files -decreases as machines get faster. On modern machines, it is usually not -advisable. +@file{site-load.el} that loads them. You may need to add a definition + +@example +#define SITELOAD_PURESIZE_EXTRA @var{n} +@end example + +@noindent +to make @var{n} added bytes of pure space to hold the additional files. +(Try adding increments of 20000 until it is big enough.) However, the +advantage of preloading additional files decreases as machines get +faster. On modern machines, it is usually not advisable. After @file{loadup.el} reads @file{site-load.el}, it finds the documentation strings for primitive and preloaded functions (and @@ -209,6 +215,8 @@ might as well be reused, since no one will miss them. The second (``sweep'') phase of the garbage collector arranges to reuse them. +??? Maybe add something describing weak hash tables here? + @cindex free list The sweep phase puts unused cons cells onto a @dfn{free list} for future allocation; likewise for symbols and markers. It compacts @@ -433,7 +441,7 @@ @end group @group - if (NULL (args)) + if (NILP (args)) return Qnil; args_left = args; @@ -444,11 +452,11 @@ do @{ val = Feval (Fcar (args_left)); - if (!NULL (val)) + if (!NILP (val)) break; args_left = Fcdr (args_left); @} - while (!NULL (args_left)); + while (!NILP (args_left)); @end group @group @@ -726,14 +734,128 @@ 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 +@code{buffer_text} structure contains fields describing the text of a +buffer; the @code{buffer} structure holds other fields. In the case +of indirect buffers, two or more @code{buffer} structures reference +the same @code{buffer_text} structure. + +Here is a list of the @code{struct buffer_text} fields: + @table @code -@item name -The buffer name is a string that names the buffer. It is guaranteed to -be unique. @xref{Buffer Names}. +@item beg +This field contains the Actual address of the buffer contents. + +@item got +This holds the character position of the gap in the buffer. + +@item z +This field contains the character position of the end of the buffer +text. + +@item gpt_byte +Contains the byte position of the gap. + +@item z_byte +Holds the byte position of the end of the buffer text. + +@item gap_size +Contains the size of buffer's gap. + +@item modiff +This field counts buffer-modification events for this buffer. It is +incremented for each such event, and never otherwise changed. + +@item save_modiff +Contains the previous value of @code{modiff}, as of the last time a +buffer was visited or saved in a file. + +@item overlay_modiff +Counts modifications to overlays analogous to @code{modiff}. + +@item 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. + +@item 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. + +@item unchanged_modified +Contains the value of @code{modiff} at the time of the last redisplay +that finished. If this value matches @code{modiff}, +@code{beg_unchanged} and @code{end_unchanged} contain no useful +information. + +@item overlay_unchanged_modified +Contains the value of @code{overlay_modiff} at the time of the last +redisplay that finished. If this value matches @code{overlay_modiff}, +@code{beg_unchanged} and @code{end_unchanged} contain no useful +information. + +@item markers +The markers that refer to this buffer. This is actually a single +marker, and successive elements in its marker @code{chain} are the other +markers referring to this buffer text. -@item save_modified -This field contains the time when the buffer was last saved, as an integer. -@xref{Buffer Modification}. +@item intervals +Contains the interval tree which records the text properties of this +buffer. +@end table + +The fields of @code{struct buffer} are: + +@table @code +@item 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. + +@item own_text +This is a @code{struct buffer_text} structure. In an ordinary buffer, +it holds the buffer contents. In indirect buffers, this field is not +used. + +@item text +This points to the @code{buffer_text} structure that is used for this +buffer. In an ordinary buffer, this is the @code{own_text} field above. +In an indirect buffer, this is the @code{own_text} field of the base +buffer. + +@item pt +Contains the character position of point in a buffer. + +@item pt_byte +Contains the byte position of point in a buffer. + +@item begv +This field contains the character position of the beginning of the +accessible range of text in the buffer. + +@item begv_byte +This field contains the byte position of the beginning of the +accessible range of text in the buffer. + +@item zv +This field contains the character position of the end of the +accessible range of text in the buffer. + +@item zv_byte +This field contains the byte position of the end of the +accessible range of text in the buffer. + +@item base_buffer +In an indirect buffer, this points to the base buffer. In an ordinary +buffer, it is null. + +@item 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 +@code{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.) @item modtime This field contains the modification time of the visited file. It is @@ -744,16 +866,98 @@ @item auto_save_modified This field contains the time when the buffer was last auto-saved. +@item auto_save_failure_time +The time at which we detected a failure to auto-save, or -1 if we didn't +have a failure. + @item last_window_start This field contains the @code{window-start} position in the buffer as of the last time the buffer was displayed in a window. +@item clip_changed +This flag is set when narrowing changes in a buffer. + +@item prevent_redisplay_optimizations_p +A flag indicating the redisplay optiomizations should not be used +to display this buffer. + @item undo_list This field points to the buffer's undo list. @xref{Undo}. -@item syntax_table_v +@item name +The buffer name is a string that names the buffer. It is guaranteed to +be unique. @xref{Buffer Names}. + +@item filename +The name of the file visited in this buffer, or @code{nil}. + +@item directory +The directory for expanding relative file names. + +@item 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 +@code{buffer_text} structure because indirect buffers are never saved. + +@item auto_save_file_name +File name used for auto-saving this buffer. This is not in the +@code{buffer_text} because it's not used in indirect buffers at all. + +@item read_only +Non-@code{nil} means this buffer is read-only. + +@item mark +This field contains the mark for the buffer. The mark is a marker, +hence it is also included on the list @code{markers}. @xref{The Mark}. + +@item 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.) @xref{Buffer-Local +Variables}. + +@item major_mode +Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. + +@item mode_name +Pretty name of major mode, e.g., @code{"Lisp"}. + +@item mode_line_format +Mode line element that controls the format of the mode line. If this +is @code{nil}, no mode line will be displayed. + +@item header_line_format +This field is analoguous to @code{mode_line_format} for the mode +line displayed at the top of windows. + +@item keymap +This field holds the buffer's local keymap. @xref{Keymaps}. + +@item abbrev_table +This buffer's local abbrevs. + +@item syntax_table This field contains the syntax table for the buffer. @xref{Syntax Tables}. +@item category_table +This field contains the category table for the buffer. + +@item case_fold_search +The value of @code{case-fold-search} in this buffer. + +@item tab_width +The value of @code{tab-width} in this buffer. + +@item fill_column +The value of @code{fill-column} in this buffer. + +@item left_margin +The value of @code{left-margin} in this buffer. + +@item auto_fill_function +The value of @code{auto-fill-function} in this buffer. + @item downcase_table This field contains the conversion table for converting text to lower case. @xref{Case Tables}. @@ -770,44 +974,38 @@ This field contains the equivalence table for case-folding search. @xref{Case Tables}. +@item truncate_lines +The value of @code{truncate-lines} in this buffer. + +@item ctl_arrow +The value of @code{ctl-arrow} in this buffer. + +@item selective_display +The value of @code{selective-display} in this buffer. + +@item selective_display_ellipsis +The value of @code{selective-display-ellipsis} in this buffer. + +@item minor_modes +An alist of the minor modes of this buffer. + +@item overwrite_mode +The value of @code{overwrite_mode} in this buffer. + +@item abbrev_mode +The value of @code{abbrev-mode} in this buffer. + @item display_table This field contains the buffer's display table, or @code{nil} if it doesn't have one. @xref{Display Tables}. -@item markers -This field contains the chain of all markers that currently point into -the buffer. Deletion of text in the buffer, and motion of the buffer's -gap, must check each of these markers and perhaps update it. -@xref{Markers}. - -@item backed_up -This field is a flag that tells whether a backup file has been made -for the visited file of this buffer. - -@item mark -This field contains the mark for the buffer. The mark is a marker, -hence it is also included on the list @code{markers}. @xref{The Mark}. +@item save_modified +This field contains the time when the buffer was last saved, as an integer. +@xref{Buffer Modification}. @item mark_active This field is non-@code{nil} if the buffer's mark is active. -@item 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.) @xref{Buffer-Local -Variables}. - -@item base_buffer -This field holds the buffer's base buffer (if it is an indirect buffer), -or @code{nil}. - -@item keymap -This field holds the buffer's local keymap. @xref{Keymaps}. - -@item overlay_center -This field holds the current overlay center position. @xref{Overlays}. - @item 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 @@ -818,9 +1016,66 @@ the current overlay center position. They are sorted in order of increasing beginning position. +@item overlay_center +This field holds the current overlay center position. @xref{Overlays}. + @item enable_multibyte_characters This field holds the buffer's local value of @code{enable-multibyte-characters}---either @code{t} or @code{nil}. + +@item buffer_file_coding_system +The value of @code{buffer-file-coding-system} in this buffer. + +@item file_format +The value of @code{buffer-file-format} in this buffer. + +@item 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. + +@item begv_marker +In an indirect buffer, or a buffer that is the base of an indirect +buffer, this holds a marker that records @code{begv} for this buffer +when the buffer is not current. + +@item zv_marker +In an indirect buffer, or a buffer that is the base of an indirect +buffer, this holds a marker that records @code{zv} for this buffer when +the buffer is not current. + +@item file_truename +The truename of the visited file, or @code{nil}. + +@item invisibility_spec +The value of @code{buffer-invisibility-spec} in this buffer. + +@item last_selected_window +This is the last window that was selected with this buffer in it, or @code{nil} +if that window no longer displays this buffer. + +@item display_count +This field is incremented each time the buffer is displayed in a window. + +@item left_margin_width +The value of @code{left-margin-width} in this buffer. + +@item right_margin_width +The value of @code{right-margin-width} in this buffer. + +@item indicate_empty_lines +Non-@code{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. + +@item display_time +This holds a time stamp that is updated each time this buffer is +displayed in a window. + +@item scroll_up_aggressively +The value of @code{scroll-up-aggressively} in this buffer. + +@item scroll_down_aggressively +The value of @code{scroll-down-aggressively} in this buffer. @end table @node Window Internals @@ -837,36 +1092,33 @@ @item mini_p Non-@code{nil} if this window is a minibuffer window. -@item buffer -The buffer that the window is displaying. This may change often during -the life of the window. +@item parent +Internally, Emacs arranges windows in a tree; each group of siblings has +a parent window whose area includes all the siblings. This field points +to a window's parent. -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. +Parent windows do not display buffers, and play little role in display +except to shape their child windows. Emacs Lisp programs usually have +no access to the parent windows; they operate on the windows at the +leaves of the tree, which actually display buffers. -@item pointm -@cindex window point internals -This is the value of point in the current buffer when this window is -selected; when it is not selected, it retains its previous value. +The following four fields also describe the window tree structure. -@item start -The position in the buffer that is the first character to be displayed -in the window. +@item hchild +In a window subdivided horizontally by child windows, the leftmost child. +Otherwise, @code{nil}. + +@item vchild +In a window subdivided vertically by child windows, the topmost child. +Otherwise, @code{nil}. -@item force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. +@item next +The next sibling of this window. It is @code{nil} in a window that is +the rightmost or bottommost of a group of siblings. -@item last_modified -The @code{modified} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time -a redisplay completed in this window. +@item prev +The previous sibling of this window. It is @code{nil} in a window that +is the leftmost or topmost of a group of siblings. @item left This is the left-hand edge of the window, measured in columns. (The @@ -884,33 +1136,153 @@ scroll bar and fringes, and/or the separator line on the right of the window (if any). -@item next -This is the window that is the next in the chain of siblings. It is -@code{nil} in a window that is the rightmost or bottommost of a group of -siblings. +@item buffer +The buffer that the window is displaying. This may change often during +the life of the window. + +@item start +The position in the buffer that is the first character to be displayed +in the window. + +@item pointm +@cindex window point internals +This is the value of point in the current buffer when this window is +selected; when it is not selected, it retains its previous value. + +@item force_start +If this flag is non-@code{nil}, it says that the window has been +scrolled explicitly by the Lisp program. This affects what the next +redisplay does if point is off the screen: instead of scrolling the +window to show the text around point, it moves point to a location that +is on the screen. + +@item optional_new_start +Set to a non-@code{nil} value when we have explicitly changed the value of +@code{start}, but don't want the next redisplay to be obliged to use the +new value. + +@item frozen_window_start_p +This field is set temporarily to 1 to indicate to redisplay that +@code{start} of this window should not be changed, even if point +gets invisible. -@item prev -This is the window that is the previous in the chain of siblings. It is -@code{nil} in a window that is the leftmost or topmost of a group of -siblings. +@item start_at_line_beg +Non-@code{nil} means current value of @code{start} was the beginning of a line +when it was chosen. + +@item too_small_ok +Non-@code{nil} means don't delete this window for becoming ``too small''. + +@item height_fixed_p +This field is temporarily set to 1 to fix the height of the selected +window when the echo area is resized. + +@item use_time +This is the last time that the window was selected. The function +@code{get-lru-window} uses this field. + +@item sequence_number +A unique number assigned to this window when it was created. + +@item last_modified +The @code{modiff} field of the window's buffer, as of the last time +a redisplay completed in this window. + +@item last_overlay_modified +The @code{overlay_modiff} field of the window's buffer, as of the last +time a redisplay completed in this window. + +@item last_point +The buffer's value of point, as of the last time a redisplay completed +in this window. + +@item last_had_star +A non-@code{nil} value means the window's buffer was ``modified'' when the +window was last updated. + +@item vertical_scroll_bar +This window's vertical scroll bar. -@item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. +@item left_margin_width +The width of the left margin in this window, or @code{nil} not to +specify it (in which case the buffer's value of @code{left-margin-width} +is used. + +@item right_margin_width +Likewise for the right margin. + +@begin ignore +@item last_mark_x +@item last_mark_y +???Not used. +@end ignore + +@item window_end_pos +This is computed as @code{z} minus the buffer position of the last glyph +in the current matrix of the window. The value is only valid if +@code{window_end_valid} is not @code{nil}. + +@item window_end_bytepos +The byte position corresponding to @code{window_end_pos}. + +@item window_end_vpos +The window-relative vertical position of the line containing +@code{window_end_pos}. + +@item window_end_valid +This field is set to a non-@code{nil} value if @code{window_end_pos} is truly +valid. This is @code{nil} if nontrivial redisplay is preempted since in that +case the display that @code{window_end_pos} was computed for did not get +onto the screen. + +@item redisplay_end_trigger +If redisplay in this window goes beyond this buffer position, it runs +run the @code{redisplay-end-trigger-hook}. -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. +@begin ignore +@item orig_height +@item orig_top +??? Are temporary storage areas. +@end ignore + +@item cursor +A structure describing where the cursor is in this window. + +@item last_cursor +The value of @code{cursor} as of the last redisplay that finished. + +@item phys_cursor +A structure describing where the cursor of this window physically is. + +@item phys_cursor_type +The type of cursor that was last displayed on this window. +@item phys_cursor_on_p +This field is non-zero if the cursor is physically on. + +@item cursor_off_p +Non-zero means the cursor in this window is logically on. + +@item last_cursor_off_p +This field contains the value of @code{cursor_off_p} as of the time of +the last redisplay. + +@item must_be_updated_p +This is set to 1 during redisplay when this window must be updated. + +@item pseudo_window_p +A non-zero value of this field means this is a window that is not +part of the normal window tree. + @item hscroll This is the number of columns that the display in the window is scrolled horizontally to the left. Normally, this is 0. -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. +@item vscroll +Vertical scroll amount, in pixels. Normally, this is 0. + +@item dedicated +Non-@code{nil} if this window is dedicated to its buffer. @item display_table The window's display table, or @code{nil} if none is specified for it. @@ -930,6 +1302,16 @@ If the region (or part of it) is highlighted in this window, this field holds the mark position that made one end of that region. Otherwise, this field is @code{nil}. + +@item column_number_displayed +The column number currently displayed in this window's mode line, or @code{nil} +if column numbers are not being displayed. + +@item current_matrix +A glyph matrix describing the current display of this window. + +@item desired_matrix +A glyph matrix describing the desired display of this window. @end table @node Process Internals @@ -1005,4 +1387,26 @@ @item tty_name The name of the terminal that the subprocess is using, or @code{nil} if it is using pipes. + +@item decode_coding_system +Coding-system for decoding the input from this process. + +@item decoding_buf +A working buffer for decoding. + +@item decoding_carryover +Size of carryover in decoding. + +@item encode_coding_system +Coding-system for encoding the output to this process. + +@item encoding_buf +A working buffer for enecoding. + +@item encoding_carryover +Size of carryover in encoding. + +@item inherit_coding_system_flag +Flag to set @code{coding-system} of the process buffer from the +coding system used to decode process output. @end table