annotate lispref/internals.texi @ 34097:0225d8e15f2c

(coordinates_in_window): Handle computations for positions on the vertical bar and fringes differently for window-system frames. Consider some pixels near the vertical bar as on the bar if the frame doesn't have vertical scroll bars. Associate positions between mode or header lines with the right window, the left one.
author Gerd Moellmann <gerd@gnu.org>
date Fri, 01 Dec 2000 20:44:31 +0000
parents 5192df3c8dd6
children 534f7d0b195c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 26783
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 26783
diff changeset
4 @c Free Software Foundation, Inc.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node GNU Emacs Internals, Standard Errors, Tips, Top
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @comment node-name, next, previous, up
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @appendix GNU Emacs Internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 This chapter describes how the runnable Emacs executable is dumped with
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 the preloaded Lisp libraries in it, how storage is allocated, and some
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 internal aspects of GNU Emacs that may be of interest to C programmers.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 @menu
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
16 * Building Emacs:: How to the dumped Emacs is made.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
19 * Memory Usage:: Info about total size of Lisp objects made so far.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Writing Emacs Primitives:: Writing C code for Emacs.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * Object Internals:: Data formats of buffers, windows, processes.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
24 @node Building Emacs
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 @appendixsec Building Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 @cindex building Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 @pindex temacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 This section explains the steps involved in building the Emacs
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 executable. You don't have to know this material to build and install
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 Emacs, since the makefiles do all these things automatically. This
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 information is pertinent to Emacs maintenance.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 Compilation of the C source files in the @file{src} directory
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 produces an executable file called @file{temacs}, also called a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 routines, but not the editing commands.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @cindex @file{loadup.el}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 the real runnable Emacs executable. These arguments direct
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @file{temacs} to evaluate the Lisp files specified in the file
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @file{loadup.el}. These files set up the normal Emacs editing
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
44 environment, resulting in an Emacs that is still impure but no longer
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 bare.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 It takes a substantial time to load the standard Lisp files. Luckily,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 you don't have to do this each time you run Emacs; @file{temacs} can
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
49 dump out an executable program called @file{emacs} that has these files
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 preloaded. @file{emacs} starts more quickly because it does not need to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 load the files. This is the Emacs executable that is normally
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 installed.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 To create @file{emacs}, use the command @samp{temacs -batch -l loadup
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 from trying to initialize any of its data on the terminal; this ensures
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 that the tables of terminal information are empty in the dumped Emacs.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 The argument @samp{dump} tells @file{loadup.el} to dump a new executable
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 named @file{emacs}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 Some operating systems don't support dumping. On those systems, you
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 must start Emacs with the @samp{temacs -l loadup} command each time you
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
63 use it. This takes a substantial time, but since you need to start
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
64 Emacs once a day at most---or once a week if you never log out---the
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
65 extra time is not too severe a problem.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @cindex @file{site-load.el}
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
68
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 You can specify additional files to preload by writing a library named
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
70 @file{site-load.el} that loads them. You may need to add a definition
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
71
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
72 @example
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
73 #define SITELOAD_PURESIZE_EXTRA @var{n}
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
74 @end example
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
75
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
76 @noindent
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
77 to make @var{n} added bytes of pure space to hold the additional files.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
78 (Try adding increments of 20000 until it is big enough.) However, the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
79 advantage of preloading additional files decreases as machines get
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
80 faster. On modern machines, it is usually not advisable.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
14514
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
82 After @file{loadup.el} reads @file{site-load.el}, it finds the
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
83 documentation strings for primitive and preloaded functions (and
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
84 variables) in the file @file{etc/DOC} where they are stored, by calling
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
85 @code{Snarf-documentation} (@pxref{Accessing Documentation}).
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
86
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @cindex @file{site-init.el}
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
88 You can specify other Lisp expressions to execute just before dumping
14514
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
89 by putting them in a library named @file{site-init.el}. This file is
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
90 executed after the documentation strings are found.
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
91
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
92 If you want to preload function or variable definitions, there are
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
93 three ways you can do this and make their documentation strings
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
94 accessible when you subsequently run Emacs:
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
95
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
96 @itemize @bullet
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
97 @item
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
98 Arrange to scan these files when producing the @file{etc/DOC} file,
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
99 and load them with @file{site-load.el}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
14514
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
101 @item
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
102 Load the files with @file{site-init.el}, then copy the files into the
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
103 installation directory for Lisp files when you install Emacs.
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
104
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
105 @item
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
106 Specify a non-@code{nil} value for
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
107 @code{byte-compile-dynamic-docstrings} as a local variable in each of these
14514
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
108 files, and load them with either @file{site-load.el} or
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
109 @file{site-init.el}. (This method has the drawback that the
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
110 documentation strings take up space in Emacs all the time.)
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
111 @end itemize
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
112
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
113 It is not advisable to put anything in @file{site-load.el} or
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
114 @file{site-init.el} that would alter any of the features that users
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
115 expect in an ordinary unmodified Emacs. If you feel you must override
2f15f316326d Clarify site-load.el vs site-init.el and how to deal with doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
116 normal features for your site, do it with @file{default.el}, so that
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
117 users can override your changes if they wish. @xref{Startup Summary}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @defun dump-emacs to-file from-file
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @cindex unexec
18413
487c3d3c2283 dump-emacs works only with -batch.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
121 This function dumps the current state of Emacs into an executable file
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @var{to-file}. It takes symbols from @var{from-file} (this is normally
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 the executable file @file{temacs}).
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
18413
487c3d3c2283 dump-emacs works only with -batch.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
125 If you want to use this function in an Emacs that was already dumped,
487c3d3c2283 dump-emacs works only with -batch.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
126 you must run Emacs with @samp{-batch}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
129 @node Pure Storage
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @appendixsec Pure Storage
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @cindex pure storage
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
133 Emacs Lisp uses two kinds of storage for user-created Lisp objects:
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
134 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
135 all the new data created during an Emacs session are kept; see the
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
136 following section for information on normal storage. Pure storage is
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
137 used for certain data in the preloaded standard Lisp files---data that
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
138 should never change during actual use of Emacs.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 Pure storage is allocated only while @file{temacs} is loading the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 standard preloaded Lisp libraries. In the file @file{emacs}, it is
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
142 marked as read-only (on operating systems that permit this), so that
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 the memory space can be shared by all the Emacs jobs running on the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 machine at once. Pure storage is not expandable; a fixed amount is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 allocated when Emacs is compiled, and if that is not sufficient for the
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
146 preloaded libraries, @file{temacs} crashes. If that happens, you must
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
147 increase the compilation parameter @code{PURESIZE} in the file
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @file{src/puresize.h}. This normally won't happen unless you try to
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 preload additional libraries or add features to the standard ones.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @defun purecopy object
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
152 This function makes a copy in pure storage of @var{object}, and returns
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
153 it. It copies a string by simply making a new string with the same
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 characters in pure storage. It recursively copies the contents of
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
155 vectors and cons cells. It does not make copies of other objects such
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
156 as symbols, but just returns them unchanged. It signals an error if
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 asked to copy markers.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158
11139
311f3ea4a759 Minor purecopy correction.
Richard M. Stallman <rms@gnu.org>
parents: 10487
diff changeset
159 This function is a no-op except while Emacs is being built and dumped;
311f3ea4a759 Minor purecopy correction.
Richard M. Stallman <rms@gnu.org>
parents: 10487
diff changeset
160 it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
311f3ea4a759 Minor purecopy correction.
Richard M. Stallman <rms@gnu.org>
parents: 10487
diff changeset
161 a few packages call it just in case you decide to preload them.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @defvar pure-bytes-used
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
165 The value of this variable is the number of bytes of pure storage
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 allocated so far. Typically, in a dumped Emacs, this number is very
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 close to the total amount of pure storage available---if it were not,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 we would preallocate less.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @defvar purify-flag
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
172 This variable determines whether @code{defun} should make a copy of the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 function definition in pure storage. If it is non-@code{nil}, then the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 function definition is copied into pure storage.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
176 This flag is @code{t} while loading all of the basic functions for
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 building Emacs initially (allowing those functions to be sharable and
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
178 non-collectible). Dumping Emacs as an executable always writes
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
179 @code{nil} in this variable, regardless of the value it actually has
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
180 before and after dumping.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
182 You should not change this flag in a running Emacs.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @end defvar
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
185 @node Garbage Collection
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @appendixsec Garbage Collection
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @cindex garbage collector
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @cindex memory allocation
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 When a program creates a list or the user defines a new function (such
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
191 as by loading a library), that data is placed in normal storage. If
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
192 normal storage runs low, then Emacs asks the operating system to
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 allocate more memory in blocks of 1k bytes. Each block is used for one
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
194 type of Lisp object, so symbols, cons cells, markers, etc., are
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
195 segregated in distinct blocks in memory. (Vectors, long strings,
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
196 buffers and certain other editing types, which are fairly large, are
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
197 allocated in individual blocks, one per object, while small strings are
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
198 packed into blocks of 8k bytes.)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
200 It is quite common to use some storage for a while, then release it by
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
201 (for example) killing a buffer or deleting the last pointer to an
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 object. Emacs provides a @dfn{garbage collector} to reclaim this
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 abandoned storage. (This name is traditional, but ``garbage recycler''
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 might be a more intuitive metaphor for this facility.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
206 The garbage collector operates by finding and marking all Lisp objects
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
207 that are still accessible to Lisp programs. To begin with, it assumes
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
208 all the symbols, their values and associated function definitions, and
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
209 any data presently on the stack, are accessible. Any objects that can
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
210 be reached indirectly through other accessible objects are also
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
211 accessible.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
213 When marking is finished, all objects still unmarked are garbage. No
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 matter what the Lisp program or the user does, it is impossible to refer
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
215 to them, since there is no longer a way to reach them. Their space
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
216 might as well be reused, since no one will miss them. The second
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
217 (``sweep'') phase of the garbage collector arranges to reuse them.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
219 @c ??? Maybe add something describing weak hash tables here?
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
220
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @cindex free list
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
222 The sweep phase puts unused cons cells onto a @dfn{free list}
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
223 for future allocation; likewise for symbols and markers. It compacts
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
224 the accessible strings so they occupy fewer 8k blocks; then it frees the
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
225 other 8k blocks. Vectors, buffers, windows, and other large objects are
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
226 individually allocated and freed using @code{malloc} and @code{free}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @cindex CL note---allocate more storage
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @quotation
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
230 @b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 call the garbage collector when the free list is empty. Instead, it
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 simply requests the operating system to allocate more storage, and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 processing continues until @code{gc-cons-threshold} bytes have been
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 used.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 This means that you can make sure that the garbage collector will not
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 run during a certain portion of a Lisp program by calling the garbage
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 collector explicitly just before it (provided that portion of the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 program does not use so much space as to force a second garbage
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 collection).
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 @end quotation
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @deffn Command garbage-collect
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
244 This command runs a garbage collection, and returns information on
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 the amount of space in use. (Garbage collection can also occur
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 spontaneously if you use more than @code{gc-cons-threshold} bytes of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 Lisp data since the previous garbage collection.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
249 @code{garbage-collect} returns a list containing the following
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 information:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
252 @example
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 ((@var{used-conses} . @var{free-conses})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 (@var{used-syms} . @var{free-syms})
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
256 @end group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
257 (@var{used-miscs} . @var{free-miscs})
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @var{used-string-chars}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @var{used-vector-slots}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
260 (@var{used-floats} . @var{free-floats})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
261 (@var{used-intervals} . @var{free-intervals}))
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
262 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
263
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
264 Here is an example:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
265
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
266 @example
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
267 @group
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 (garbage-collect)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
269 @result{} ((106886 . 13184) (9769 . 0)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
270 (7731 . 4651) 347543 121628
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
271 (31 . 94) (1273 . 168))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @end group
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
273 @end example
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 Here is a table explaining each element:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @table @var
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @item used-conses
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 The number of cons cells in use.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @item free-conses
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 The number of cons cells for which space has been obtained from the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 operating system, but that are not currently being used.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @item used-syms
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 The number of symbols in use.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @item free-syms
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 The number of symbols for which space has been obtained from the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 operating system, but that are not currently being used.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
292 @item used-miscs
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
293 The number of miscellaneous objects in use. These include markers and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
294 overlays, plus certain objects not visible to users.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
296 @item free-miscs
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
297 The number of miscellaneous objects for which space has been obtained
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
298 from the operating system, but that are not currently being used.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @item used-string-chars
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 The total size of all strings, in characters.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @item used-vector-slots
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 The total number of elements of existing vectors.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @item used-floats
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @c Emacs 19 feature
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 The number of floats in use.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @item free-floats
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @c Emacs 19 feature
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 The number of floats for which space has been obtained from the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 operating system, but that are not currently being used.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
314
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
315 @item used-intervals
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
316 The number of intervals in use. Intervals are an internal
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
317 data structure used for representing text properties.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
318
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
319 @item free-intervals
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
320 The number of intervals for which space has been obtained
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
321 from the operating system, but that are not currently being used.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @end deffn
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
15769
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
325 @defopt garbage-collection-messages
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
326 If this variable is non-@code{nil}, Emacs displays a message at the
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
327 beginning and end of garbage collection. The default value is
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
328 @code{nil}, meaning there are no such messages.
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
329 @end defopt
43d4b9cf0b69 Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents: 14514
diff changeset
330
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @defopt gc-cons-threshold
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
332 The value of this variable is the number of bytes of storage that must
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 be allocated for Lisp objects after one garbage collection in order to
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
334 trigger another garbage collection. A cons cell counts as eight bytes,
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 a string as one byte per character plus a few bytes of overhead, and so
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
336 on; space allocated to the contents of buffers does not count. Note
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
337 that the subsequent garbage collection does not happen immediately when
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
338 the threshold is exhausted, but only the next time the Lisp evaluator is
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 called.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
341 The initial threshold value is 400,000. If you specify a larger
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 value, garbage collection will happen less often. This reduces the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 amount of time spent garbage collecting, but increases total memory use.
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
344 You may want to do this when running a program that creates lots of
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 Lisp data.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
347 You can make collections more frequent by specifying a smaller value,
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 down to 10,000. A value less than 10,000 will remain in effect only
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 until the subsequent garbage collection, at which time
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @code{garbage-collect} will set the threshold back to 10,000.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @end defopt
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
353 The value return by @code{garbage-collect} describes the amount of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
354 memory used by Lisp data, broken down by data type. By contrast, the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 function @code{memory-limit} provides information on the total amount of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
356 memory Emacs is currently using.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
357
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @c Emacs 19 feature
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @defun memory-limit
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 This function returns the address of the last byte Emacs has allocated,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 divided by 1024. We divide the value by 1024 to make sure it fits in a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 Lisp integer.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 You can use this to get a general idea of how your actions affect the
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 memory usage.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @end defun
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
368 @node Memory Usage
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
369 @section Memory Usage
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
370
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
371 These functions and variables give information about the total amount
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
372 of memory allocation that Emacs has done, broken down by data type.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
373 Note the difference between these and the values returned by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
374 @code{(garbage-collect)}; those count objects that currently exist, but
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
375 these count the number or size of all allocations, including those for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
376 objects that have since been freed.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
377
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
378 @defvar cons-cells-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
379 The total number of cons cells that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
380 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
381 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
382
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
383 @defvar floats-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
384 The total number of floats that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
385 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
386 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
387
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
388 @defvar vector-cells-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
389 The total number of vector cells that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
390 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
391 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
392
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
393 @defvar symbols-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
394 The total number of symbols that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
395 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
396 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
397
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
398 @defvar string-chars-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
399 The total number of string characters that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
400 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
401 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
402
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
403 @defvar misc-objects-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
404 The total number of miscellaneous objects that have been allocated so
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
405 far in this Emacs session. These include markers and overlays, plus
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
406 certain objects not visible to users.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
407 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
408
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
409 @defvar intervals-consed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
410 The total number of intervals that have been allocated so far
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
411 in this Emacs session.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
412 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
413
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
414 @node Writing Emacs Primitives
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @appendixsec Writing Emacs Primitives
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @cindex primitive function internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 Lisp primitives are Lisp functions implemented in C. The details of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 interfacing the C function so that Lisp can call it are handled by a few
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 C macros. The only way to really understand how to write new C code is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 to read the source, but we can explain some things here.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 An example of a special form is the definition of @code{or}, from
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @file{eval.c}. (An ordinary function would have the same general
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 appearance.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @cindex garbage collection protection
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15769
diff changeset
431 "Eval args until one of them yields non-nil; return that value.\n\
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 The remaining args are not evalled at all.\n\
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @group
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
435 If all args return nil, return nil.")
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 (args)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 Lisp_Object args;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @{
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 register Lisp_Object val;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 Lisp_Object args_left;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 struct gcpro gcpro1;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @group
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
445 if (NILP (args))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 return Qnil;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 args_left = args;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 GCPRO1 (args_left);
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 do
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @{
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 val = Feval (Fcar (args_left));
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
456 if (!NILP (val))
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 break;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 args_left = Fcdr (args_left);
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @}
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
460 while (!NILP (args_left));
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 UNGCPRO;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 return val;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 Let's start with a precise explanation of the arguments to the
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
471 @code{DEFUN} macro. Here is a template for them:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @table @var
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @item lname
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
479 This is the name of the Lisp symbol to define as the function name; in
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
480 the example above, it is @code{or}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @item fname
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 This is the C function name for this function. This is
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 the name that is used in C code for calling the function. The name is,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 by convention, @samp{F} prepended to the Lisp name, with all dashes
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 (@samp{-}) in the Lisp name changed to underscores. Thus, to call this
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 function from C code, call @code{For}. Remember that the arguments must
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 be of type @code{Lisp_Object}; various macros and functions for creating
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 values of type @code{Lisp_Object} are declared in the file
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @file{lisp.h}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @item sname
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 This is a C variable name to use for a structure that holds the data for
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 the subr object that represents the function in Lisp. This structure
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 conveys the Lisp symbol name to the initialization routine that will
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 create the symbol and store the subr object as its definition. By
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 convention, this name is always @var{fname} with @samp{F} replaced with
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 @samp{S}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @item min
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
501 This is the minimum number of arguments that the function requires. The
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
502 function @code{or} allows a minimum of zero arguments.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @item max
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
505 This is the maximum number of arguments that the function accepts, if
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
506 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
507 indicating a special form that receives unevaluated arguments, or
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
508 @code{MANY}, indicating an unlimited number of evaluated arguments (the
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
509 equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
510 macros. If @var{max} is a number, it may not be less than @var{min} and
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
511 it may not be greater than seven.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 @item interactive
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 This is an interactive specification, a string such as might be used as
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 the argument of @code{interactive} in a Lisp function. In the case of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
517 called interactively. A value of @code{""} indicates a function that
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
518 should receive no arguments when called interactively.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 @item doc
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 This is the documentation string. It is written just like a
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 documentation string for a function defined in Lisp, except you must
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 write @samp{\n\} at the end of each line. In particular, the first line
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 should be a single sentence.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
527 After the call to the @code{DEFUN} macro, you must write the argument
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
528 name list that every C function must have, followed by ordinary C
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
529 declarations for the arguments. For a function with a fixed maximum
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
530 number of arguments, declare a C argument for each Lisp argument, and
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
531 give them all type @code{Lisp_Object}. When a Lisp function has no
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
532 upper limit on the number of arguments, its implementation in C actually
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
533 receives exactly two arguments: the first is the number of Lisp
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
534 arguments, and the second is the address of a block containing their
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
535 values. They have types @code{int} and @w{@code{Lisp_Object *}}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 Within the function @code{For} itself, note the use of the macros
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 a variable from garbage collection---to inform the garbage collector that
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 it must look in that variable and regard its contents as an accessible
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 object. This is necessary whenever you call @code{Feval} or anything
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 that can directly or indirectly call @code{Feval}. At such a time, any
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 Lisp object that you intend to refer to again must be protected somehow.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @code{UNGCPRO} cancels the protection of the variables that are
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 protected in the current function. It is necessary to do this explicitly.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
547 For most data types, it suffices to protect at least one pointer to
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
548 the object; as long as the object is not recycled, all pointers to it
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
549 remain valid. This is not so for strings, because the garbage collector
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
550 can move them. When the garbage collector moves a string, it relocates
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
551 all the pointers it knows about; any other pointers become invalid.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
552 Therefore, you must protect all pointers to strings across any point
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
553 where garbage collection may be possible.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
555 The macro @code{GCPRO1} protects just one local variable. If you want
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
556 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
557 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
559 These macros implicitly use local variables such as @code{gcpro1}; you
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
560 must declare these explicitly, with type @code{struct gcpro}. Thus, if
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
561 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
562 Alas, we can't explain all the tricky details here.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563
10487
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
564 You must not use C initializers for static or global variables unless
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
565 the variables are never written once Emacs is dumped. These variables
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
566 with initializers are allocated in an area of memory that becomes
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
567 read-only (on certain operating systems) as a result of dumping Emacs.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
568 @xref{Pure Storage}.
10476
4d87344e6dfb *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
569
10487
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
570 Do not use static variables within functions---place all static
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
571 variables at top level in the file. This is necessary because Emacs on
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
572 some operating systems defines the keyword @code{static} as a null
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
573 macro. (This definition is used because those systems put all variables
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
574 declared static in a place that becomes read-only after dumping, whether
9a4ff0104cdc entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 10476
diff changeset
575 they have initializers or not.)
10476
4d87344e6dfb *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
576
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
577 Defining the C function is not enough to make a Lisp primitive
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
578 available; you must also create the Lisp symbol for the primitive and
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
579 store a suitable subr object in its function cell. The code looks like
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
580 this:
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 defsubr (&@var{subr-structure-name});
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @end example
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @noindent
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
587 Here @var{subr-structure-name} is the name you used as the third
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
588 argument to @code{DEFUN}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
590 If you add a new primitive to a file that already has Lisp primitives
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
591 defined in it, find the function (near the end of the file) named
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
592 @code{syms_of_@var{something}}, and add the call to @code{defsubr}
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
593 there. If the file doesn't have this function, or if you create a new
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
594 file, add to it a @code{syms_of_@var{filename}} (e.g.,
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
595 @code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
596 of these functions are called, and add a call to
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
597 @code{syms_of_@var{filename}} there.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
599 @vindex byte-boolean-vars
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
600 The function @code{syms_of_@var{filename}} is also the place to define
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
601 any C variables that are to be visible as Lisp variables.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
602 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
603 in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
604 visible in Lisp with a value that is always an integer.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
605 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
606 with a value that is either @code{t} or @code{nil}. Note that variables
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
607 defined with @code{DEFVAR_BOOL} are automatically added to the list
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
608 @code{byte-boolean-vars} used by the byte compiler.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
610 If you define a file-scope C variable of type @code{Lisp_Object},
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
611 you must protect it from garbage-collection by calling @code{staticpro}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
612 in @code{syms_of_@var{filename}}, like this:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
613
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
614 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
615 staticpro (&@var{variable});
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
616 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
617
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
618 Here is another example function, with more complicated arguments.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
619 This comes from the code in @file{window.c}, and it demonstrates the use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
620 of macros and functions to manipulate Lisp objects.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 Scoordinates_in_window_p, 2, 2,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 "xSpecify coordinate pair: \nXExpression which evals to window: ",
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
627 "Return non-nil if COORDINATES is in WINDOW.\n\
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
628 COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
629 ...
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
632 If they are on the border between WINDOW and its right sibling,\n\
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
633 `vertical-line' is returned.")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
634 (coordinates, window)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
635 register Lisp_Object coordinates, window;
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 @{
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
637 int x, y;
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
638 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
639
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
640 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
641 CHECK_LIVE_WINDOW (window, 0);
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
642 CHECK_CONS (coordinates, 1);
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
643 x = XINT (Fcar (coordinates));
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
644 y = XINT (Fcdr (coordinates));
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
648 switch (coordinates_in_window (XWINDOW (window), &x, &y))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
649 @{
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
650 case 0: /* NOT in window at all. */
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
651 return Qnil;
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @end group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
653
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
654 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
655 case 1: /* In text part of window. */
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
656 return Fcons (make_number (x), make_number (y));
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
657 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
658
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
660 case 2: /* In mode line of window. */
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
661 return Qmode_line;
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @end group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
663
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
665 case 3: /* On right border of window. */
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
666 return Qvertical_line;
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @end group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
668
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
670 default:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
671 abort ();
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
672 @}
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @}
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @end group
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @end smallexample
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
677 Note that C code cannot call functions by name unless they are defined
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
678 in C. The way to call a function written in Lisp is to use
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
679 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
680 the Lisp function @code{funcall} accepts an unlimited number of
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
681 arguments, in C it takes two: the number of Lisp-level arguments, and a
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
682 one-dimensional array containing their values. The first Lisp-level
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
683 argument is the Lisp function to call, and the rest are the arguments to
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
684 pass to it. Since @code{Ffuncall} can call the evaluator, you must
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
685 protect pointers from garbage collection around the call to
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
686 @code{Ffuncall}.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
687
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
688 The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
689 provide handy ways to call a Lisp function conveniently with a fixed
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
690 number of arguments. They work by calling @code{Ffuncall}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @file{eval.c} is a very good file to look through for examples;
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @file{lisp.h} contains the definitions for some important macros and
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 functions.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
696 If you define a function which is side-effect free, update the code in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
697 @file{byte-opt.el} which binds @code{side-effect-free-fns} and
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
698 @code{side-effect-and-error-free-fns} to include it. This will help the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
699 optimizer.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
700
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
701 @node Object Internals
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 @appendixsec Object Internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 @cindex object internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 GNU Emacs Lisp manipulates many different types of data. The actual
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
706 data are stored in a heap and the only access that programs have to it
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
707 is through pointers. Pointers are thirty-two bits wide in most
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 implementations. Depending on the operating system and type of machine
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
709 for which you compile Emacs, twenty-eight bits are used to address the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18413
diff changeset
710 object, and the remaining four bits are used for a GC mark bit and the
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 tag that identifies the object's type.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
713 Because Lisp objects are represented as tagged pointers, it is always
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
714 possible to determine the Lisp data type of any object. The C data type
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
715 @code{Lisp_Object} can hold any Lisp object of any data type. Ordinary
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
716 variables have type @code{Lisp_Object}, which means they can hold any
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
717 type of Lisp value; you can determine the actual data type only at run
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
718 time. The same is true for function arguments; if you want a function
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
719 to accept only a certain type of argument, you must check the type
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
720 explicitly using a suitable predicate (@pxref{Type Predicates}).
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @cindex type checking internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 * Buffer Internals:: Components of a buffer structure.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 * Window Internals:: Components of a window structure.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 * Process Internals:: Components of a process structure.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @end menu
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
729 @node Buffer Internals
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @appendixsubsec Buffer Internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @cindex internals, of buffer
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @cindex buffer internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 Buffers contain fields not directly accessible by the Lisp programmer.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 We describe them here, naming them by the names used in the C code.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 Many are accessible indirectly in Lisp programs via Lisp primitives.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
738 Two structures are used to represent buffers in C. The
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
739 @code{buffer_text} structure contains fields describing the text of a
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
740 buffer; the @code{buffer} structure holds other fields. In the case
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
741 of indirect buffers, two or more @code{buffer} structures reference
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
742 the same @code{buffer_text} structure.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
743
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
744 Here is a list of the @code{struct buffer_text} fields:
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
745
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @table @code
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
747 @item beg
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
748 This field contains the actual address of the buffer contents.
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
749
33340
5192df3c8dd6 Typo fixed.
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
750 @item gpt
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
751 This holds the character position of the gap in the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
752
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
753 @item z
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
754 This field contains the character position of the end of the buffer
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
755 text.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
756
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
757 @item gpt_byte
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
758 Contains the byte position of the gap.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
759
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
760 @item z_byte
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
761 Holds the byte position of the end of the buffer text.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
762
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
763 @item gap_size
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
764 Contains the size of buffer's gap.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
765
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
766 @item modiff
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
767 This field counts buffer-modification events for this buffer. It is
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
768 incremented for each such event, and never otherwise changed.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
769
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
770 @item save_modiff
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
771 Contains the previous value of @code{modiff}, as of the last time a
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
772 buffer was visited or saved in a file.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
773
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
774 @item overlay_modiff
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
775 Counts modifications to overlays analogous to @code{modiff}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
776
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
777 @item beg_unchanged
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
778 Holds the number of characters at the start of the text that are known
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
779 to be unchanged since the last redisplay that finished.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
780
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
781 @item end_unchanged
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
782 Holds the number of characters at the end of the text that are known to
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
783 be unchanged since the last redisplay that finished.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
784
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
785 @item unchanged_modified
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
786 Contains the value of @code{modiff} at the time of the last redisplay
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
787 that finished. If this value matches @code{modiff},
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
788 @code{beg_unchanged} and @code{end_unchanged} contain no useful
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
789 information.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
790
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
791 @item overlay_unchanged_modified
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
792 Contains the value of @code{overlay_modiff} at the time of the last
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
793 redisplay that finished. If this value matches @code{overlay_modiff},
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
794 @code{beg_unchanged} and @code{end_unchanged} contain no useful
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
795 information.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
796
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
797 @item markers
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
798 The markers that refer to this buffer. This is actually a single
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
799 marker, and successive elements in its marker @code{chain} are the other
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
800 markers referring to this buffer text.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
802 @item intervals
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
803 Contains the interval tree which records the text properties of this
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
804 buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
805 @end table
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
806
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
807 The fields of @code{struct buffer} are:
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
808
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
809 @table @code
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
810 @item next
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
811 Points to the next buffer, in the chain of all buffers including killed
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
812 buffers. This chain is used only for garbage collection, in order to
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
813 collect killed buffers properly. Note that vectors, and most kinds of
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
814 objects allocated as vectors, are all on one chain, but buffers are on a
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
815 separate chain of their own.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
816
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
817 @item own_text
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
818 This is a @code{struct buffer_text} structure. In an ordinary buffer,
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
819 it holds the buffer contents. In indirect buffers, this field is not
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
820 used.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
821
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
822 @item text
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
823 This points to the @code{buffer_text} structure that is used for this
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
824 buffer. In an ordinary buffer, this is the @code{own_text} field above.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
825 In an indirect buffer, this is the @code{own_text} field of the base
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
826 buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
827
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
828 @item pt
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
829 Contains the character position of point in a buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
830
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
831 @item pt_byte
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
832 Contains the byte position of point in a buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
833
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
834 @item begv
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
835 This field contains the character position of the beginning of the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
836 accessible range of text in the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
837
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
838 @item begv_byte
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
839 This field contains the byte position of the beginning of the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
840 accessible range of text in the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
841
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
842 @item zv
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
843 This field contains the character position of the end of the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
844 accessible range of text in the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
845
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
846 @item zv_byte
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
847 This field contains the byte position of the end of the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
848 accessible range of text in the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
849
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
850 @item base_buffer
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
851 In an indirect buffer, this points to the base buffer. In an ordinary
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
852 buffer, it is null.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
853
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
854 @item local_var_flags
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
855 This field contains flags indicating that certain variables are local in
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
856 this buffer. Such variables are declared in the C code using
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
857 @code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
858 fields in the buffer structure itself. (Some of these fields are
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
859 described in this table.)
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @item modtime
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 This field contains the modification time of the visited file. It is
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
863 set when the file is written or read. Before writing the buffer into a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
864 file, this field is compared to the modification time of the file to see
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
865 if the file has changed on disk. @xref{Buffer Modification}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @item auto_save_modified
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 This field contains the time when the buffer was last auto-saved.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
870 @item auto_save_failure_time
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
871 The time at which we detected a failure to auto-save, or -1 if we didn't
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
872 have a failure.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
873
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @item last_window_start
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 This field contains the @code{window-start} position in the buffer as of
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 the last time the buffer was displayed in a window.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
878 @item clip_changed
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
879 This flag is set when narrowing changes in a buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
880
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
881 @item prevent_redisplay_optimizations_p
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
882 this flag indicates that redisplay optimizations should not be used
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
883 to display this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
884
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
885 @item undo_list
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
886 This field points to the buffer's undo list. @xref{Undo}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
888 @item name
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
889 The buffer name is a string that names the buffer. It is guaranteed to
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
890 be unique. @xref{Buffer Names}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
891
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
892 @item filename
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
893 The name of the file visited in this buffer, or @code{nil}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
894
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
895 @item directory
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
896 The directory for expanding relative file names.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
897
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
898 @item save_length
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
899 Length of the file this buffer is visiting, when last read or saved.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
900 This and other fields concerned with saving are not kept in the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
901 @code{buffer_text} structure because indirect buffers are never saved.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
902
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
903 @item auto_save_file_name
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
904 File name used for auto-saving this buffer. This is not in the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
905 @code{buffer_text} because it's not used in indirect buffers at all.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
906
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
907 @item read_only
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
908 Non-@code{nil} means this buffer is read-only.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
909
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
910 @item mark
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
911 This field contains the mark for the buffer. The mark is a marker,
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
912 hence it is also included on the list @code{markers}. @xref{The Mark}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
913
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
914 @item local_var_alist
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
915 This field contains the association list describing the buffer-local
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
916 variable bindings of this buffer, not including the built-in
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
917 buffer-local bindings that have special slots in the buffer object.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
918 (Those slots are omitted from this table.) @xref{Buffer-Local
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
919 Variables}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
920
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
921 @item major_mode
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
922 Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
923
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
924 @item mode_name
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
925 Pretty name of major mode, e.g., @code{"Lisp"}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
926
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
927 @item mode_line_format
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
928 Mode line element that controls the format of the mode line. If this
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
929 is @code{nil}, no mode line will be displayed.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
930
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
931 @item header_line_format
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
932 This field is analoguous to @code{mode_line_format} for the mode
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
933 line displayed at the top of windows.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
934
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
935 @item keymap
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
936 This field holds the buffer's local keymap. @xref{Keymaps}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
937
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
938 @item abbrev_table
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
939 This buffer's local abbrevs.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
940
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
941 @item syntax_table
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 This field contains the syntax table for the buffer. @xref{Syntax Tables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
944 @item category_table
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
945 This field contains the category table for the buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
946
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
947 @item case_fold_search
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
948 The value of @code{case-fold-search} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
949
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
950 @item tab_width
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
951 The value of @code{tab-width} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
952
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
953 @item fill_column
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
954 The value of @code{fill-column} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
955
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
956 @item left_margin
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
957 The value of @code{left-margin} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
958
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
959 @item auto_fill_function
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
960 The value of @code{auto-fill-function} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
961
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 @item downcase_table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 This field contains the conversion table for converting text to lower case.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
964 @xref{Case Tables}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 @item upcase_table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 This field contains the conversion table for converting text to upper case.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
968 @xref{Case Tables}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @item case_canon_table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 This field contains the conversion table for canonicalizing text for
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
972 case-folding search. @xref{Case Tables}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @item case_eqv_table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 This field contains the equivalence table for case-folding search.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
976 @xref{Case Tables}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
978 @item truncate_lines
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
979 The value of @code{truncate-lines} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
980
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
981 @item ctl_arrow
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
982 The value of @code{ctl-arrow} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
983
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
984 @item selective_display
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
985 The value of @code{selective-display} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
986
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
987 @item selective_display_ellipsis
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
988 The value of @code{selective-display-ellipsis} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
989
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
990 @item minor_modes
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
991 An alist of the minor modes of this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
992
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
993 @item overwrite_mode
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
994 The value of @code{overwrite_mode} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
995
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
996 @item abbrev_mode
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
997 The value of @code{abbrev-mode} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
998
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 @item display_table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 This field contains the buffer's display table, or @code{nil} if it doesn't
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 have one. @xref{Display Tables}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1003 @item save_modified
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1004 This field contains the time when the buffer was last saved, as an integer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1005 @xref{Buffer Modification}.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1007 @item mark_active
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1008 This field is non-@code{nil} if the buffer's mark is active.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1009
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1010 @item overlays_before
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1011 This field holds a list of the overlays in this buffer that end at or
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1012 before the current overlay center position. They are sorted in order of
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1013 decreasing end position.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1014
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1015 @item overlays_after
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1016 This field holds a list of the overlays in this buffer that end after
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1017 the current overlay center position. They are sorted in order of
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1018 increasing beginning position.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1019
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1020 @item overlay_center
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1021 This field holds the current overlay center position. @xref{Overlays}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1022
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1023 @item enable_multibyte_characters
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1024 This field holds the buffer's local value of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1025 @code{enable-multibyte-characters}---either @code{t} or @code{nil}.
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1026
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1027 @item buffer_file_coding_system
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1028 The value of @code{buffer-file-coding-system} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1029
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1030 @item file_format
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1031 The value of @code{buffer-file-format} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1032
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1033 @item pt_marker
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1034 In an indirect buffer, or a buffer that is the base of an indirect
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1035 buffer, this holds a marker that records point for this buffer when the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1036 buffer is not current.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1037
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1038 @item begv_marker
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1039 In an indirect buffer, or a buffer that is the base of an indirect
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1040 buffer, this holds a marker that records @code{begv} for this buffer
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1041 when the buffer is not current.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1042
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1043 @item zv_marker
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1044 In an indirect buffer, or a buffer that is the base of an indirect
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1045 buffer, this holds a marker that records @code{zv} for this buffer when
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1046 the buffer is not current.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1047
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1048 @item file_truename
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1049 The truename of the visited file, or @code{nil}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1050
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1051 @item invisibility_spec
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1052 The value of @code{buffer-invisibility-spec} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1053
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1054 @item last_selected_window
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1055 This is the last window that was selected with this buffer in it, or @code{nil}
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1056 if that window no longer displays this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1057
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1058 @item display_count
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1059 This field is incremented each time the buffer is displayed in a window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1060
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1061 @item left_margin_width
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1062 The value of @code{left-margin-width} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1063
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1064 @item right_margin_width
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1065 The value of @code{right-margin-width} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1066
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1067 @item indicate_empty_lines
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1068 Non-@code{nil} means indicate empty lines (lines with no text) with a
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1069 small bitmap in the fringe, when using a window system that can do it.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1070
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1071 @item display_time
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1072 This holds a time stamp that is updated each time this buffer is
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1073 displayed in a window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1074
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1075 @item scroll_up_aggressively
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1076 The value of @code{scroll-up-aggressively} in this buffer.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1077
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1078 @item scroll_down_aggressively
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1079 The value of @code{scroll-down-aggressively} in this buffer.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1082 @node Window Internals
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @appendixsubsec Window Internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @cindex internals, of window
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 @cindex window internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 Windows have the following accessible fields:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 @table @code
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 @item frame
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1091 The frame that this window is on.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @item mini_p
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1094 Non-@code{nil} if this window is a minibuffer window.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1096 @item parent
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1097 Internally, Emacs arranges windows in a tree; each group of siblings has
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1098 a parent window whose area includes all the siblings. This field points
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1099 to a window's parent.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1101 Parent windows do not display buffers, and play little role in display
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1102 except to shape their child windows. Emacs Lisp programs usually have
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1103 no access to the parent windows; they operate on the windows at the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1104 leaves of the tree, which actually display buffers.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1106 The following four fields also describe the window tree structure.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1108 @item hchild
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1109 In a window subdivided horizontally by child windows, the leftmost child.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1110 Otherwise, @code{nil}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1111
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1112 @item vchild
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1113 In a window subdivided vertically by child windows, the topmost child.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1114 Otherwise, @code{nil}.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1115
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1116 @item next
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1117 The next sibling of this window. It is @code{nil} in a window that is
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1118 the rightmost or bottommost of a group of siblings.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1119
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1120 @item prev
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1121 The previous sibling of this window. It is @code{nil} in a window that
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1122 is the leftmost or topmost of a group of siblings.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1123
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 @item left
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1125 This is the left-hand edge of the window, measured in columns. (The
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 leftmost column on the screen is @w{column 0}.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @item top
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1129 This is the top edge of the window, measured in lines. (The top line on
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 the screen is @w{line 0}.)
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1132 @item height
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1133 The height of the window, measured in lines.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1134
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1135 @item width
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1136 The width of the window, measured in columns. This width includes the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1137 scroll bar and fringes, and/or the separator line on the right of the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1138 window (if any).
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1139
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1140 @item buffer
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1141 The buffer that the window is displaying. This may change often during
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1142 the life of the window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1143
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1144 @item start
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1145 The position in the buffer that is the first character to be displayed
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1146 in the window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1147
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1148 @item pointm
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1149 @cindex window point internals
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1150 This is the value of point in the current buffer when this window is
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1151 selected; when it is not selected, it retains its previous value.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1152
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1153 @item force_start
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1154 If this flag is non-@code{nil}, it says that the window has been
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1155 scrolled explicitly by the Lisp program. This affects what the next
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1156 redisplay does if point is off the screen: instead of scrolling the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1157 window to show the text around point, it moves point to a location that
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1158 is on the screen.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1159
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1160 @item frozen_window_start_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1161 This field is set temporarily to 1 to indicate to redisplay that
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1162 @code{start} of this window should not be changed, even if point
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1163 gets invisible.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1165 @item start_at_line_beg
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1166 Non-@code{nil} means current value of @code{start} was the beginning of a line
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1167 when it was chosen.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1168
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1169 @item too_small_ok
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1170 Non-@code{nil} means don't delete this window for becoming ``too small''.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1171
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1172 @item height_fixed_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1173 This field is temporarily set to 1 to fix the height of the selected
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1174 window when the echo area is resized.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1175
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1176 @item use_time
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1177 This is the last time that the window was selected. The function
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1178 @code{get-lru-window} uses this field.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1179
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1180 @item sequence_number
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1181 A unique number assigned to this window when it was created.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1182
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1183 @item last_modified
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1184 The @code{modiff} field of the window's buffer, as of the last time
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1185 a redisplay completed in this window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1186
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1187 @item last_overlay_modified
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1188 The @code{overlay_modiff} field of the window's buffer, as of the last
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1189 time a redisplay completed in this window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1190
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1191 @item last_point
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1192 The buffer's value of point, as of the last time a redisplay completed
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1193 in this window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1194
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1195 @item last_had_star
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1196 A non-@code{nil} value means the window's buffer was ``modified'' when the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1197 window was last updated.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1198
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1199 @item vertical_scroll_bar
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1200 This window's vertical scroll bar.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1202 @item left_margin_width
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1203 The width of the left margin in this window, or @code{nil} not to
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1204 specify it (in which case the buffer's value of @code{left-margin-width}
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1205 is used.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1206
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1207 @item right_margin_width
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1208 Likewise for the right margin.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1209
26783
626ae4bb4994 Fix makeinfo complaints.
Dave Love <fx@gnu.org>
parents: 26199
diff changeset
1210 @ignore
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1211 @item last_mark_x
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1212 @item last_mark_y
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1213 ???Not used.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1214 @end ignore
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1215
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1216 @item window_end_pos
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1217 This is computed as @code{z} minus the buffer position of the last glyph
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1218 in the current matrix of the window. The value is only valid if
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1219 @code{window_end_valid} is not @code{nil}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1220
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1221 @item window_end_bytepos
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1222 The byte position corresponding to @code{window_end_pos}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1223
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1224 @item window_end_vpos
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1225 The window-relative vertical position of the line containing
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1226 @code{window_end_pos}.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1227
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1228 @item window_end_valid
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1229 This field is set to a non-@code{nil} value if @code{window_end_pos} is truly
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1230 valid. This is @code{nil} if nontrivial redisplay is preempted since in that
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1231 case the display that @code{window_end_pos} was computed for did not get
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1232 onto the screen.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1233
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1234 @item redisplay_end_trigger
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1235 If redisplay in this window goes beyond this buffer position, it runs
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1236 run the @code{redisplay-end-trigger-hook}.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1237
26783
626ae4bb4994 Fix makeinfo complaints.
Dave Love <fx@gnu.org>
parents: 26199
diff changeset
1238 @ignore
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1239 @item orig_height
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1240 @item orig_top
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1241 ??? Are temporary storage areas.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1242 @end ignore
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1243
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1244 @item cursor
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1245 A structure describing where the cursor is in this window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1246
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1247 @item last_cursor
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1248 The value of @code{cursor} as of the last redisplay that finished.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1249
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1250 @item phys_cursor
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1251 A structure describing where the cursor of this window physically is.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1252
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1253 @item phys_cursor_type
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1254 The type of cursor that was last displayed on this window.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1256 @item phys_cursor_on_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1257 This field is non-zero if the cursor is physically on.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1258
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1259 @item cursor_off_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1260 Non-zero means the cursor in this window is logically on.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1261
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1262 @item last_cursor_off_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1263 This field contains the value of @code{cursor_off_p} as of the time of
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1264 the last redisplay.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1265
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1266 @item must_be_updated_p
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1267 This is set to 1 during redisplay when this window must be updated.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1268
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @item hscroll
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1270 This is the number of columns that the display in the window is scrolled
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 horizontally to the left. Normally, this is 0.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1273 @item vscroll
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1274 Vertical scroll amount, in pixels. Normally, this is 0.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1275
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1276 @item dedicated
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1277 Non-@code{nil} if this window is dedicated to its buffer.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 @item display_table
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1280 The window's display table, or @code{nil} if none is specified for it.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1281
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1282 @item update_mode_line
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1283 Non-@code{nil} means this window's mode line needs to be updated.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1284
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1285 @item base_line_number
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1286 The line number of a certain position in the buffer, or @code{nil}.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1287 This is used for displaying the line number of point in the mode line.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1288
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1289 @item base_line_pos
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1290 The position in the buffer for which the line number is known, or
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1291 @code{nil} meaning none is known.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1292
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1293 @item region_showing
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1294 If the region (or part of it) is highlighted in this window, this field
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1295 holds the mark position that made one end of that region. Otherwise,
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1296 this field is @code{nil}.
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1297
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1298 @item column_number_displayed
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1299 The column number currently displayed in this window's mode line, or @code{nil}
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1300 if column numbers are not being displayed.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1301
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1302 @item current_matrix
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1303 A glyph matrix describing the current display of this window.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1304
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1305 @item desired_matrix
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1306 A glyph matrix describing the desired display of this window.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 @end table
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1309 @node Process Internals
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 @appendixsubsec Process Internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @cindex internals, of process
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 @cindex process internals
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 The fields of a process are:
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1316 @table @code
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 @item name
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 A string, the name of the process.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @item command
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 A list containing the command arguments that were used to start this
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 process.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 @item filter
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 A function used to accept output from the process instead of a buffer,
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 or @code{nil}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328 @item sentinel
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 A function called whenever the process receives a signal, or @code{nil}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 @item buffer
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 The associated buffer of the process.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @item pid
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 An integer, the Unix process @sc{id}.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 @item childp
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 A flag, non-@code{nil} if this is really a child process.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 It is @code{nil} for a network connection.
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @item mark
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
1342 A marker indicating the position of the end of the last output from this
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
1343 process inserted into the buffer. This is often but not always the end
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
1344 of the buffer.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 @item kill_without_query
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1347 If this is non-@code{nil}, killing Emacs while this process is still
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1348 running does not ask for confirmation about killing the process.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1349
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1350 @item raw_status_low
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1351 @itemx raw_status_high
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1352 These two fields record 16 bits each of the process status returned by
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1353 the @code{wait} system call.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1354
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1355 @item status
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1356 The process status, as @code{process-status} should return it.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1357
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1358 @item tick
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1359 @itemx update_tick
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1360 If these two fields are not equal, a change in the status of the process
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1361 needs to be reported, either by running the sentinel or by inserting a
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1362 message in the process buffer.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1363
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1364 @item pty_flag
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1365 Non-@code{nil} if communication with the subprocess uses a @sc{pty};
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1366 @code{nil} if it uses a pipe.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1367
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1368 @item infd
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1369 The file descriptor for input from the process.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1370
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1371 @item outfd
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1372 The file descriptor for output to the process.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1373
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1374 @item subtty
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1375 The file descriptor for the terminal that the subprocess is using. (On
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1376 some systems, there is no need to record this, so the value is
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6451
diff changeset
1377 @code{nil}.)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11139
diff changeset
1378
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11139
diff changeset
1379 @item tty_name
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11139
diff changeset
1380 The name of the terminal that the subprocess is using,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11139
diff changeset
1381 or @code{nil} if it is using pipes.
26165
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1382
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1383 @item decode_coding_system
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1384 Coding-system for decoding the input from this process.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1385
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1386 @item decoding_buf
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1387 A working buffer for decoding.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1388
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1389 @item decoding_carryover
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1390 Size of carryover in decoding.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1391
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1392 @item encode_coding_system
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1393 Coding-system for encoding the output to this process.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1394
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1395 @item encoding_buf
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1396 A working buffer for enecoding.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1397
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1398 @item encoding_carryover
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1399 Size of carryover in encoding.
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1400
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1401 @item inherit_coding_system_flag
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1402 Flag to set @code{coding-system} of the process buffer from the
cdd1c350aae9 Patches from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1403 coding system used to decode process output.
6451
8240c0b1d695 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 @end table