Mercurial > emacs
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 |
rev | line source |
---|---|
6451 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
27189 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999 |
4 @c Free Software Foundation, Inc. | |
6451 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/internals | |
7 @node GNU Emacs Internals, Standard Errors, Tips, Top | |
8 @comment node-name, next, previous, up | |
9 @appendix GNU Emacs Internals | |
10 | |
11 This chapter describes how the runnable Emacs executable is dumped with | |
12 the preloaded Lisp libraries in it, how storage is allocated, and some | |
13 internal aspects of GNU Emacs that may be of interest to C programmers. | |
14 | |
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 | 17 * Pure Storage:: A kludge to make preloaded Lisp functions sharable. |
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 | 20 * Writing Emacs Primitives:: Writing C code for Emacs. |
21 * Object Internals:: Data formats of buffers, windows, processes. | |
22 @end menu | |
23 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
24 @node Building Emacs |
6451 | 25 @appendixsec Building Emacs |
26 @cindex building Emacs | |
27 @pindex temacs | |
28 | |
29 This section explains the steps involved in building the Emacs | |
30 executable. You don't have to know this material to build and install | |
31 Emacs, since the makefiles do all these things automatically. This | |
32 information is pertinent to Emacs maintenance. | |
33 | |
34 Compilation of the C source files in the @file{src} directory | |
35 produces an executable file called @file{temacs}, also called a | |
36 @dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O | |
37 routines, but not the editing commands. | |
38 | |
39 @cindex @file{loadup.el} | |
40 The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create | |
41 the real runnable Emacs executable. These arguments direct | |
42 @file{temacs} to evaluate the Lisp files specified in the file | |
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 | 45 bare. |
46 | |
47 It takes a substantial time to load the standard Lisp files. Luckily, | |
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 | 50 preloaded. @file{emacs} starts more quickly because it does not need to |
51 load the files. This is the Emacs executable that is normally | |
52 installed. | |
53 | |
54 To create @file{emacs}, use the command @samp{temacs -batch -l loadup | |
55 dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} | |
56 from trying to initialize any of its data on the terminal; this ensures | |
57 that the tables of terminal information are empty in the dumped Emacs. | |
58 The argument @samp{dump} tells @file{loadup.el} to dump a new executable | |
59 named @file{emacs}. | |
60 | |
61 Some operating systems don't support dumping. On those systems, you | |
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 | 66 |
67 @cindex @file{site-load.el} | |
26165 | 68 |
6451 | 69 You can specify additional files to preload by writing a library named |
26165 | 70 @file{site-load.el} that loads them. You may need to add a definition |
71 | |
72 @example | |
73 #define SITELOAD_PURESIZE_EXTRA @var{n} | |
74 @end example | |
75 | |
76 @noindent | |
77 to make @var{n} added bytes of pure space to hold the additional files. | |
78 (Try adding increments of 20000 until it is big enough.) However, the | |
79 advantage of preloading additional files decreases as machines get | |
80 faster. On modern machines, it is usually not advisable. | |
6451 | 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 | 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 | 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 | 118 |
119 @defun dump-emacs to-file from-file | |
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 | 122 @var{to-file}. It takes symbols from @var{from-file} (this is normally |
123 the executable file @file{temacs}). | |
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 | 127 @end defun |
128 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
129 @node Pure Storage |
6451 | 130 @appendixsec Pure Storage |
131 @cindex pure storage | |
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 | 139 |
140 Pure storage is allocated only while @file{temacs} is loading the | |
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 | 143 the memory space can be shared by all the Emacs jobs running on the |
144 machine at once. Pure storage is not expandable; a fixed amount is | |
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 | 148 @file{src/puresize.h}. This normally won't happen unless you try to |
149 preload additional libraries or add features to the standard ones. | |
150 | |
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 | 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 | 157 asked to copy markers. |
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 | 162 @end defun |
163 | |
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 | 166 allocated so far. Typically, in a dumped Emacs, this number is very |
167 close to the total amount of pure storage available---if it were not, | |
168 we would preallocate less. | |
169 @end defvar | |
170 | |
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 | 173 function definition in pure storage. If it is non-@code{nil}, then the |
174 function definition is copied into pure storage. | |
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 | 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 | 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 | 183 @end defvar |
184 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
185 @node Garbage Collection |
6451 | 186 @appendixsec Garbage Collection |
187 @cindex garbage collector | |
188 | |
189 @cindex memory allocation | |
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 | 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 | 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 | 202 object. Emacs provides a @dfn{garbage collector} to reclaim this |
203 abandoned storage. (This name is traditional, but ``garbage recycler'' | |
204 might be a more intuitive metaphor for this facility.) | |
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 | 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 | 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 | 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 | 220 |
6451 | 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 | 227 |
228 @cindex CL note---allocate more storage | |
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 | 231 call the garbage collector when the free list is empty. Instead, it |
232 simply requests the operating system to allocate more storage, and | |
233 processing continues until @code{gc-cons-threshold} bytes have been | |
234 used. | |
235 | |
236 This means that you can make sure that the garbage collector will not | |
237 run during a certain portion of a Lisp program by calling the garbage | |
238 collector explicitly just before it (provided that portion of the | |
239 program does not use so much space as to force a second garbage | |
240 collection). | |
241 @end quotation | |
242 | |
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 | 245 the amount of space in use. (Garbage collection can also occur |
246 spontaneously if you use more than @code{gc-cons-threshold} bytes of | |
247 Lisp data since the previous garbage collection.) | |
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 | 250 information: |
251 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
252 @example |
6451 | 253 @group |
254 ((@var{used-conses} . @var{free-conses}) | |
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 | 258 @var{used-string-chars} |
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 | 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 | 272 @end group |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
273 @end example |
6451 | 274 |
275 Here is a table explaining each element: | |
276 | |
277 @table @var | |
278 @item used-conses | |
279 The number of cons cells in use. | |
280 | |
281 @item free-conses | |
282 The number of cons cells for which space has been obtained from the | |
283 operating system, but that are not currently being used. | |
284 | |
285 @item used-syms | |
286 The number of symbols in use. | |
287 | |
288 @item free-syms | |
289 The number of symbols for which space has been obtained from the | |
290 operating system, but that are not currently being used. | |
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 | 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 | 299 |
300 @item used-string-chars | |
301 The total size of all strings, in characters. | |
302 | |
303 @item used-vector-slots | |
304 The total number of elements of existing vectors. | |
305 | |
306 @item used-floats | |
307 @c Emacs 19 feature | |
308 The number of floats in use. | |
309 | |
310 @item free-floats | |
311 @c Emacs 19 feature | |
312 The number of floats for which space has been obtained from the | |
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 | 322 @end table |
323 @end deffn | |
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 | 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 | 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 | 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 | 339 called. |
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 | 342 value, garbage collection will happen less often. This reduces the |
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 | 345 Lisp data. |
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 | 348 down to 10,000. A value less than 10,000 will remain in effect only |
349 until the subsequent garbage collection, at which time | |
350 @code{garbage-collect} will set the threshold back to 10,000. | |
351 @end defopt | |
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 | 358 @c Emacs 19 feature |
359 @defun memory-limit | |
360 This function returns the address of the last byte Emacs has allocated, | |
361 divided by 1024. We divide the value by 1024 to make sure it fits in a | |
362 Lisp integer. | |
363 | |
364 You can use this to get a general idea of how your actions affect the | |
365 memory usage. | |
366 @end defun | |
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 | 415 @appendixsec Writing Emacs Primitives |
416 @cindex primitive function internals | |
417 | |
418 Lisp primitives are Lisp functions implemented in C. The details of | |
419 interfacing the C function so that Lisp can call it are handled by a few | |
420 C macros. The only way to really understand how to write new C code is | |
421 to read the source, but we can explain some things here. | |
422 | |
423 An example of a special form is the definition of @code{or}, from | |
424 @file{eval.c}. (An ordinary function would have the same general | |
425 appearance.) | |
426 | |
427 @cindex garbage collection protection | |
428 @smallexample | |
429 @group | |
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 | 432 The remaining args are not evalled at all.\n\ |
433 @end group | |
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 | 436 (args) |
437 Lisp_Object args; | |
438 @{ | |
439 register Lisp_Object val; | |
440 Lisp_Object args_left; | |
441 struct gcpro gcpro1; | |
442 @end group | |
443 | |
444 @group | |
26165 | 445 if (NILP (args)) |
6451 | 446 return Qnil; |
447 | |
448 args_left = args; | |
449 GCPRO1 (args_left); | |
450 @end group | |
451 | |
452 @group | |
453 do | |
454 @{ | |
455 val = Feval (Fcar (args_left)); | |
26165 | 456 if (!NILP (val)) |
6451 | 457 break; |
458 args_left = Fcdr (args_left); | |
459 @} | |
26165 | 460 while (!NILP (args_left)); |
6451 | 461 @end group |
462 | |
463 @group | |
464 UNGCPRO; | |
465 return val; | |
466 @} | |
467 @end group | |
468 @end smallexample | |
469 | |
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 | 472 |
473 @example | |
474 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) | |
475 @end example | |
476 | |
477 @table @var | |
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 | 481 |
482 @item fname | |
483 This is the C function name for this function. This is | |
484 the name that is used in C code for calling the function. The name is, | |
485 by convention, @samp{F} prepended to the Lisp name, with all dashes | |
486 (@samp{-}) in the Lisp name changed to underscores. Thus, to call this | |
487 function from C code, call @code{For}. Remember that the arguments must | |
488 be of type @code{Lisp_Object}; various macros and functions for creating | |
489 values of type @code{Lisp_Object} are declared in the file | |
490 @file{lisp.h}. | |
491 | |
492 @item sname | |
493 This is a C variable name to use for a structure that holds the data for | |
494 the subr object that represents the function in Lisp. This structure | |
495 conveys the Lisp symbol name to the initialization routine that will | |
496 create the symbol and store the subr object as its definition. By | |
497 convention, this name is always @var{fname} with @samp{F} replaced with | |
498 @samp{S}. | |
499 | |
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 | 503 |
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 | 512 |
513 @item interactive | |
514 This is an interactive specification, a string such as might be used as | |
515 the argument of @code{interactive} in a Lisp function. In the case of | |
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 | 519 |
520 @item doc | |
521 This is the documentation string. It is written just like a | |
522 documentation string for a function defined in Lisp, except you must | |
523 write @samp{\n\} at the end of each line. In particular, the first line | |
524 should be a single sentence. | |
525 @end table | |
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 | 536 |
537 Within the function @code{For} itself, note the use of the macros | |
538 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect'' | |
539 a variable from garbage collection---to inform the garbage collector that | |
540 it must look in that variable and regard its contents as an accessible | |
541 object. This is necessary whenever you call @code{Feval} or anything | |
542 that can directly or indirectly call @code{Feval}. At such a time, any | |
543 Lisp object that you intend to refer to again must be protected somehow. | |
544 @code{UNGCPRO} cancels the protection of the variables that are | |
545 protected in the current function. It is necessary to do this explicitly. | |
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 | 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 | 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 | 563 |
10487 | 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 | 570 Do not use static variables within functions---place all static |
571 variables at top level in the file. This is necessary because Emacs on | |
572 some operating systems defines the keyword @code{static} as a null | |
573 macro. (This definition is used because those systems put all variables | |
574 declared static in a place that becomes read-only after dumping, whether | |
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 | 581 |
582 @example | |
583 defsubr (&@var{subr-structure-name}); | |
584 @end example | |
585 | |
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 | 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 | 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 | 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 | 621 |
622 @smallexample | |
623 @group | |
624 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, | |
625 Scoordinates_in_window_p, 2, 2, | |
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 | 630 @end group |
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 | 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 | 645 @end group |
646 | |
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 | 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 | 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 | 662 @end group |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
663 |
6451 | 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 | 667 @end group |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
668 |
6451 | 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 | 673 @} |
674 @end group | |
675 @end smallexample | |
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 | 691 |
692 @file{eval.c} is a very good file to look through for examples; | |
693 @file{lisp.h} contains the definitions for some important macros and | |
694 functions. | |
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 | 702 @appendixsec Object Internals |
703 @cindex object internals | |
704 | |
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 | 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 | 711 tag that identifies the object's type. |
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 | 721 @cindex type checking internals |
722 | |
723 @menu | |
724 * Buffer Internals:: Components of a buffer structure. | |
725 * Window Internals:: Components of a window structure. | |
726 * Process Internals:: Components of a process structure. | |
727 @end menu | |
728 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
729 @node Buffer Internals |
6451 | 730 @appendixsubsec Buffer Internals |
731 @cindex internals, of buffer | |
732 @cindex buffer internals | |
733 | |
734 Buffers contain fields not directly accessible by the Lisp programmer. | |
735 We describe them here, naming them by the names used in the C code. | |
736 Many are accessible indirectly in Lisp programs via Lisp primitives. | |
737 | |
26165 | 738 Two structures are used to represent buffers in C. The |
739 @code{buffer_text} structure contains fields describing the text of a | |
740 buffer; the @code{buffer} structure holds other fields. In the case | |
741 of indirect buffers, two or more @code{buffer} structures reference | |
742 the same @code{buffer_text} structure. | |
743 | |
744 Here is a list of the @code{struct buffer_text} fields: | |
745 | |
6451 | 746 @table @code |
26165 | 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 | 749 |
33340 | 750 @item gpt |
26165 | 751 This holds the character position of the gap in the buffer. |
752 | |
753 @item z | |
754 This field contains the character position of the end of the buffer | |
755 text. | |
756 | |
757 @item gpt_byte | |
758 Contains the byte position of the gap. | |
759 | |
760 @item z_byte | |
761 Holds the byte position of the end of the buffer text. | |
762 | |
763 @item gap_size | |
764 Contains the size of buffer's gap. | |
765 | |
766 @item modiff | |
767 This field counts buffer-modification events for this buffer. It is | |
768 incremented for each such event, and never otherwise changed. | |
769 | |
770 @item save_modiff | |
771 Contains the previous value of @code{modiff}, as of the last time a | |
772 buffer was visited or saved in a file. | |
773 | |
774 @item overlay_modiff | |
775 Counts modifications to overlays analogous to @code{modiff}. | |
776 | |
777 @item beg_unchanged | |
778 Holds the number of characters at the start of the text that are known | |
779 to be unchanged since the last redisplay that finished. | |
780 | |
781 @item end_unchanged | |
782 Holds the number of characters at the end of the text that are known to | |
783 be unchanged since the last redisplay that finished. | |
784 | |
785 @item unchanged_modified | |
786 Contains the value of @code{modiff} at the time of the last redisplay | |
787 that finished. If this value matches @code{modiff}, | |
788 @code{beg_unchanged} and @code{end_unchanged} contain no useful | |
789 information. | |
790 | |
791 @item overlay_unchanged_modified | |
792 Contains the value of @code{overlay_modiff} at the time of the last | |
793 redisplay that finished. If this value matches @code{overlay_modiff}, | |
794 @code{beg_unchanged} and @code{end_unchanged} contain no useful | |
795 information. | |
796 | |
797 @item markers | |
798 The markers that refer to this buffer. This is actually a single | |
799 marker, and successive elements in its marker @code{chain} are the other | |
800 markers referring to this buffer text. | |
6451 | 801 |
26165 | 802 @item intervals |
803 Contains the interval tree which records the text properties of this | |
804 buffer. | |
805 @end table | |
806 | |
807 The fields of @code{struct buffer} are: | |
808 | |
809 @table @code | |
810 @item next | |
811 Points to the next buffer, in the chain of all buffers including killed | |
812 buffers. This chain is used only for garbage collection, in order to | |
813 collect killed buffers properly. Note that vectors, and most kinds of | |
814 objects allocated as vectors, are all on one chain, but buffers are on a | |
815 separate chain of their own. | |
816 | |
817 @item own_text | |
818 This is a @code{struct buffer_text} structure. In an ordinary buffer, | |
819 it holds the buffer contents. In indirect buffers, this field is not | |
820 used. | |
821 | |
822 @item text | |
823 This points to the @code{buffer_text} structure that is used for this | |
824 buffer. In an ordinary buffer, this is the @code{own_text} field above. | |
825 In an indirect buffer, this is the @code{own_text} field of the base | |
826 buffer. | |
827 | |
828 @item pt | |
829 Contains the character position of point in a buffer. | |
830 | |
831 @item pt_byte | |
832 Contains the byte position of point in a buffer. | |
833 | |
834 @item begv | |
835 This field contains the character position of the beginning of the | |
836 accessible range of text in the buffer. | |
837 | |
838 @item begv_byte | |
839 This field contains the byte position of the beginning of the | |
840 accessible range of text in the buffer. | |
841 | |
842 @item zv | |
843 This field contains the character position of the end of the | |
844 accessible range of text in the buffer. | |
845 | |
846 @item zv_byte | |
847 This field contains the byte position of the end of the | |
848 accessible range of text in the buffer. | |
849 | |
850 @item base_buffer | |
851 In an indirect buffer, this points to the base buffer. In an ordinary | |
852 buffer, it is null. | |
853 | |
854 @item local_var_flags | |
855 This field contains flags indicating that certain variables are local in | |
856 this buffer. Such variables are declared in the C code using | |
857 @code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in | |
858 fields in the buffer structure itself. (Some of these fields are | |
859 described in this table.) | |
6451 | 860 |
861 @item modtime | |
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 | 866 |
867 @item auto_save_modified | |
868 This field contains the time when the buffer was last auto-saved. | |
869 | |
26165 | 870 @item auto_save_failure_time |
871 The time at which we detected a failure to auto-save, or -1 if we didn't | |
872 have a failure. | |
873 | |
6451 | 874 @item last_window_start |
875 This field contains the @code{window-start} position in the buffer as of | |
876 the last time the buffer was displayed in a window. | |
877 | |
26165 | 878 @item clip_changed |
879 This flag is set when narrowing changes in a buffer. | |
880 | |
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 | 883 to display this buffer. |
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 | 887 |
26165 | 888 @item name |
889 The buffer name is a string that names the buffer. It is guaranteed to | |
890 be unique. @xref{Buffer Names}. | |
891 | |
892 @item filename | |
893 The name of the file visited in this buffer, or @code{nil}. | |
894 | |
895 @item directory | |
896 The directory for expanding relative file names. | |
897 | |
898 @item save_length | |
899 Length of the file this buffer is visiting, when last read or saved. | |
900 This and other fields concerned with saving are not kept in the | |
901 @code{buffer_text} structure because indirect buffers are never saved. | |
902 | |
903 @item auto_save_file_name | |
904 File name used for auto-saving this buffer. This is not in the | |
905 @code{buffer_text} because it's not used in indirect buffers at all. | |
906 | |
907 @item read_only | |
908 Non-@code{nil} means this buffer is read-only. | |
909 | |
910 @item mark | |
911 This field contains the mark for the buffer. The mark is a marker, | |
912 hence it is also included on the list @code{markers}. @xref{The Mark}. | |
913 | |
914 @item local_var_alist | |
915 This field contains the association list describing the buffer-local | |
916 variable bindings of this buffer, not including the built-in | |
917 buffer-local bindings that have special slots in the buffer object. | |
918 (Those slots are omitted from this table.) @xref{Buffer-Local | |
919 Variables}. | |
920 | |
921 @item major_mode | |
922 Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. | |
923 | |
924 @item mode_name | |
925 Pretty name of major mode, e.g., @code{"Lisp"}. | |
926 | |
927 @item mode_line_format | |
928 Mode line element that controls the format of the mode line. If this | |
929 is @code{nil}, no mode line will be displayed. | |
930 | |
931 @item header_line_format | |
932 This field is analoguous to @code{mode_line_format} for the mode | |
933 line displayed at the top of windows. | |
934 | |
935 @item keymap | |
936 This field holds the buffer's local keymap. @xref{Keymaps}. | |
937 | |
938 @item abbrev_table | |
939 This buffer's local abbrevs. | |
940 | |
941 @item syntax_table | |
6451 | 942 This field contains the syntax table for the buffer. @xref{Syntax Tables}. |
943 | |
26165 | 944 @item category_table |
945 This field contains the category table for the buffer. | |
946 | |
947 @item case_fold_search | |
948 The value of @code{case-fold-search} in this buffer. | |
949 | |
950 @item tab_width | |
951 The value of @code{tab-width} in this buffer. | |
952 | |
953 @item fill_column | |
954 The value of @code{fill-column} in this buffer. | |
955 | |
956 @item left_margin | |
957 The value of @code{left-margin} in this buffer. | |
958 | |
959 @item auto_fill_function | |
960 The value of @code{auto-fill-function} in this buffer. | |
961 | |
6451 | 962 @item downcase_table |
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 | 965 |
966 @item upcase_table | |
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 | 969 |
970 @item case_canon_table | |
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 | 973 |
974 @item case_eqv_table | |
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 | 977 |
26165 | 978 @item truncate_lines |
979 The value of @code{truncate-lines} in this buffer. | |
980 | |
981 @item ctl_arrow | |
982 The value of @code{ctl-arrow} in this buffer. | |
983 | |
984 @item selective_display | |
985 The value of @code{selective-display} in this buffer. | |
986 | |
987 @item selective_display_ellipsis | |
988 The value of @code{selective-display-ellipsis} in this buffer. | |
989 | |
990 @item minor_modes | |
991 An alist of the minor modes of this buffer. | |
992 | |
993 @item overwrite_mode | |
994 The value of @code{overwrite_mode} in this buffer. | |
995 | |
996 @item abbrev_mode | |
997 The value of @code{abbrev-mode} in this buffer. | |
998 | |
6451 | 999 @item display_table |
1000 This field contains the buffer's display table, or @code{nil} if it doesn't | |
1001 have one. @xref{Display Tables}. | |
1002 | |
26165 | 1003 @item save_modified |
1004 This field contains the time when the buffer was last saved, as an integer. | |
1005 @xref{Buffer Modification}. | |
6451 | 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 | 1020 @item overlay_center |
1021 This field holds the current overlay center position. @xref{Overlays}. | |
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 | 1026 |
1027 @item buffer_file_coding_system | |
1028 The value of @code{buffer-file-coding-system} in this buffer. | |
1029 | |
1030 @item file_format | |
1031 The value of @code{buffer-file-format} in this buffer. | |
1032 | |
1033 @item pt_marker | |
1034 In an indirect buffer, or a buffer that is the base of an indirect | |
1035 buffer, this holds a marker that records point for this buffer when the | |
1036 buffer is not current. | |
1037 | |
1038 @item begv_marker | |
1039 In an indirect buffer, or a buffer that is the base of an indirect | |
1040 buffer, this holds a marker that records @code{begv} for this buffer | |
1041 when the buffer is not current. | |
1042 | |
1043 @item zv_marker | |
1044 In an indirect buffer, or a buffer that is the base of an indirect | |
1045 buffer, this holds a marker that records @code{zv} for this buffer when | |
1046 the buffer is not current. | |
1047 | |
1048 @item file_truename | |
1049 The truename of the visited file, or @code{nil}. | |
1050 | |
1051 @item invisibility_spec | |
1052 The value of @code{buffer-invisibility-spec} in this buffer. | |
1053 | |
1054 @item last_selected_window | |
1055 This is the last window that was selected with this buffer in it, or @code{nil} | |
1056 if that window no longer displays this buffer. | |
1057 | |
1058 @item display_count | |
1059 This field is incremented each time the buffer is displayed in a window. | |
1060 | |
1061 @item left_margin_width | |
1062 The value of @code{left-margin-width} in this buffer. | |
1063 | |
1064 @item right_margin_width | |
1065 The value of @code{right-margin-width} in this buffer. | |
1066 | |
1067 @item indicate_empty_lines | |
1068 Non-@code{nil} means indicate empty lines (lines with no text) with a | |
1069 small bitmap in the fringe, when using a window system that can do it. | |
1070 | |
1071 @item display_time | |
1072 This holds a time stamp that is updated each time this buffer is | |
1073 displayed in a window. | |
1074 | |
1075 @item scroll_up_aggressively | |
1076 The value of @code{scroll-up-aggressively} in this buffer. | |
1077 | |
1078 @item scroll_down_aggressively | |
1079 The value of @code{scroll-down-aggressively} in this buffer. | |
6451 | 1080 @end table |
1081 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1082 @node Window Internals |
6451 | 1083 @appendixsubsec Window Internals |
1084 @cindex internals, of window | |
1085 @cindex window internals | |
1086 | |
1087 Windows have the following accessible fields: | |
1088 | |
1089 @table @code | |
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 | 1092 |
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 | 1095 |
26165 | 1096 @item parent |
1097 Internally, Emacs arranges windows in a tree; each group of siblings has | |
1098 a parent window whose area includes all the siblings. This field points | |
1099 to a window's parent. | |
6451 | 1100 |
26165 | 1101 Parent windows do not display buffers, and play little role in display |
1102 except to shape their child windows. Emacs Lisp programs usually have | |
1103 no access to the parent windows; they operate on the windows at the | |
1104 leaves of the tree, which actually display buffers. | |
6451 | 1105 |
26165 | 1106 The following four fields also describe the window tree structure. |
6451 | 1107 |
26165 | 1108 @item hchild |
1109 In a window subdivided horizontally by child windows, the leftmost child. | |
1110 Otherwise, @code{nil}. | |
1111 | |
1112 @item vchild | |
1113 In a window subdivided vertically by child windows, the topmost child. | |
1114 Otherwise, @code{nil}. | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
1115 |
26165 | 1116 @item next |
1117 The next sibling of this window. It is @code{nil} in a window that is | |
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 | 1120 @item prev |
1121 The previous sibling of this window. It is @code{nil} in a window that | |
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 | 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 | 1126 leftmost column on the screen is @w{column 0}.) |
1127 | |
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 | 1130 the screen is @w{line 0}.) |
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 | 1140 @item buffer |
1141 The buffer that the window is displaying. This may change often during | |
1142 the life of the window. | |
1143 | |
1144 @item start | |
1145 The position in the buffer that is the first character to be displayed | |
1146 in the window. | |
1147 | |
1148 @item pointm | |
1149 @cindex window point internals | |
1150 This is the value of point in the current buffer when this window is | |
1151 selected; when it is not selected, it retains its previous value. | |
1152 | |
1153 @item force_start | |
1154 If this flag is non-@code{nil}, it says that the window has been | |
1155 scrolled explicitly by the Lisp program. This affects what the next | |
1156 redisplay does if point is off the screen: instead of scrolling the | |
1157 window to show the text around point, it moves point to a location that | |
1158 is on the screen. | |
1159 | |
1160 @item frozen_window_start_p | |
1161 This field is set temporarily to 1 to indicate to redisplay that | |
1162 @code{start} of this window should not be changed, even if point | |
1163 gets invisible. | |
6451 | 1164 |
26165 | 1165 @item start_at_line_beg |
1166 Non-@code{nil} means current value of @code{start} was the beginning of a line | |
1167 when it was chosen. | |
1168 | |
1169 @item too_small_ok | |
1170 Non-@code{nil} means don't delete this window for becoming ``too small''. | |
1171 | |
1172 @item height_fixed_p | |
1173 This field is temporarily set to 1 to fix the height of the selected | |
1174 window when the echo area is resized. | |
1175 | |
1176 @item use_time | |
1177 This is the last time that the window was selected. The function | |
1178 @code{get-lru-window} uses this field. | |
1179 | |
1180 @item sequence_number | |
1181 A unique number assigned to this window when it was created. | |
1182 | |
1183 @item last_modified | |
1184 The @code{modiff} field of the window's buffer, as of the last time | |
1185 a redisplay completed in this window. | |
1186 | |
1187 @item last_overlay_modified | |
1188 The @code{overlay_modiff} field of the window's buffer, as of the last | |
1189 time a redisplay completed in this window. | |
1190 | |
1191 @item last_point | |
1192 The buffer's value of point, as of the last time a redisplay completed | |
1193 in this window. | |
1194 | |
1195 @item last_had_star | |
1196 A non-@code{nil} value means the window's buffer was ``modified'' when the | |
1197 window was last updated. | |
1198 | |
1199 @item vertical_scroll_bar | |
1200 This window's vertical scroll bar. | |
6451 | 1201 |
26165 | 1202 @item left_margin_width |
1203 The width of the left margin in this window, or @code{nil} not to | |
1204 specify it (in which case the buffer's value of @code{left-margin-width} | |
1205 is used. | |
1206 | |
1207 @item right_margin_width | |
1208 Likewise for the right margin. | |
1209 | |
26783 | 1210 @ignore |
26165 | 1211 @item last_mark_x |
1212 @item last_mark_y | |
1213 ???Not used. | |
1214 @end ignore | |
1215 | |
1216 @item window_end_pos | |
1217 This is computed as @code{z} minus the buffer position of the last glyph | |
1218 in the current matrix of the window. The value is only valid if | |
1219 @code{window_end_valid} is not @code{nil}. | |
1220 | |
1221 @item window_end_bytepos | |
1222 The byte position corresponding to @code{window_end_pos}. | |
1223 | |
1224 @item window_end_vpos | |
1225 The window-relative vertical position of the line containing | |
1226 @code{window_end_pos}. | |
1227 | |
1228 @item window_end_valid | |
1229 This field is set to a non-@code{nil} value if @code{window_end_pos} is truly | |
1230 valid. This is @code{nil} if nontrivial redisplay is preempted since in that | |
1231 case the display that @code{window_end_pos} was computed for did not get | |
1232 onto the screen. | |
1233 | |
1234 @item redisplay_end_trigger | |
1235 If redisplay in this window goes beyond this buffer position, it runs | |
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 | 1238 @ignore |
26165 | 1239 @item orig_height |
1240 @item orig_top | |
1241 ??? Are temporary storage areas. | |
1242 @end ignore | |
1243 | |
1244 @item cursor | |
1245 A structure describing where the cursor is in this window. | |
1246 | |
1247 @item last_cursor | |
1248 The value of @code{cursor} as of the last redisplay that finished. | |
1249 | |
1250 @item phys_cursor | |
1251 A structure describing where the cursor of this window physically is. | |
1252 | |
1253 @item phys_cursor_type | |
1254 The type of cursor that was last displayed on this window. | |
6451 | 1255 |
26165 | 1256 @item phys_cursor_on_p |
1257 This field is non-zero if the cursor is physically on. | |
1258 | |
1259 @item cursor_off_p | |
1260 Non-zero means the cursor in this window is logically on. | |
1261 | |
1262 @item last_cursor_off_p | |
1263 This field contains the value of @code{cursor_off_p} as of the time of | |
1264 the last redisplay. | |
1265 | |
1266 @item must_be_updated_p | |
1267 This is set to 1 during redisplay when this window must be updated. | |
1268 | |
6451 | 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 | 1271 horizontally to the left. Normally, this is 0. |
1272 | |
26165 | 1273 @item vscroll |
1274 Vertical scroll amount, in pixels. Normally, this is 0. | |
1275 | |
1276 @item dedicated | |
1277 Non-@code{nil} if this window is dedicated to its buffer. | |
6451 | 1278 |
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 | 1297 |
1298 @item column_number_displayed | |
1299 The column number currently displayed in this window's mode line, or @code{nil} | |
1300 if column numbers are not being displayed. | |
1301 | |
1302 @item current_matrix | |
1303 A glyph matrix describing the current display of this window. | |
1304 | |
1305 @item desired_matrix | |
1306 A glyph matrix describing the desired display of this window. | |
6451 | 1307 @end table |
1308 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1309 @node Process Internals |
6451 | 1310 @appendixsubsec Process Internals |
1311 @cindex internals, of process | |
1312 @cindex process internals | |
1313 | |
1314 The fields of a process are: | |
1315 | |
1316 @table @code | |
1317 @item name | |
1318 A string, the name of the process. | |
1319 | |
1320 @item command | |
1321 A list containing the command arguments that were used to start this | |
1322 process. | |
1323 | |
1324 @item filter | |
1325 A function used to accept output from the process instead of a buffer, | |
1326 or @code{nil}. | |
1327 | |
1328 @item sentinel | |
1329 A function called whenever the process receives a signal, or @code{nil}. | |
1330 | |
1331 @item buffer | |
1332 The associated buffer of the process. | |
1333 | |
1334 @item pid | |
1335 An integer, the Unix process @sc{id}. | |
1336 | |
1337 @item childp | |
1338 A flag, non-@code{nil} if this is really a child process. | |
1339 It is @code{nil} for a network connection. | |
1340 | |
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 | 1345 |
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 | 1378 |
1379 @item tty_name | |
1380 The name of the terminal that the subprocess is using, | |
1381 or @code{nil} if it is using pipes. | |
26165 | 1382 |
1383 @item decode_coding_system | |
1384 Coding-system for decoding the input from this process. | |
1385 | |
1386 @item decoding_buf | |
1387 A working buffer for decoding. | |
1388 | |
1389 @item decoding_carryover | |
1390 Size of carryover in decoding. | |
1391 | |
1392 @item encode_coding_system | |
1393 Coding-system for encoding the output to this process. | |
1394 | |
1395 @item encoding_buf | |
1396 A working buffer for enecoding. | |
1397 | |
1398 @item encoding_carryover | |
1399 Size of carryover in encoding. | |
1400 | |
1401 @item inherit_coding_system_flag | |
1402 Flag to set @code{coding-system} of the process buffer from the | |
1403 coding system used to decode process output. | |
6451 | 1404 @end table |