Mercurial > emacs
annotate lispref/internals.texi @ 20279:69a6030e443a
(kill-region): Detect read-only text
by getting an error trying to delete it.
Handle the cases where we can, and can't, get the killed text
from the undo list with much the same code.
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Wed, 19 Nov 1997 21:36:56 +0000 |
parents | 487c3d3c2283 |
children | 66d807bdc5b4 |
rev | line source |
---|---|
6451 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/internals | |
6 @node GNU Emacs Internals, Standard Errors, Tips, Top | |
7 @comment node-name, next, previous, up | |
8 @appendix GNU Emacs Internals | |
9 | |
10 This chapter describes how the runnable Emacs executable is dumped with | |
11 the preloaded Lisp libraries in it, how storage is allocated, and some | |
12 internal aspects of GNU Emacs that may be of interest to C programmers. | |
13 | |
14 @menu | |
15 * Building Emacs:: How to preload Lisp libraries into Emacs. | |
16 * Pure Storage:: A kludge to make preloaded Lisp functions sharable. | |
17 * Garbage Collection:: Reclaiming space for Lisp objects no longer used. | |
18 * Writing Emacs Primitives:: Writing C code for Emacs. | |
19 * Object Internals:: Data formats of buffers, windows, processes. | |
20 @end menu | |
21 | |
22 @node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals | |
23 @appendixsec Building Emacs | |
24 @cindex building Emacs | |
25 @pindex temacs | |
26 | |
27 This section explains the steps involved in building the Emacs | |
28 executable. You don't have to know this material to build and install | |
29 Emacs, since the makefiles do all these things automatically. This | |
30 information is pertinent to Emacs maintenance. | |
31 | |
32 Compilation of the C source files in the @file{src} directory | |
33 produces an executable file called @file{temacs}, also called a | |
34 @dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O | |
35 routines, but not the editing commands. | |
36 | |
37 @cindex @file{loadup.el} | |
38 The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create | |
39 the real runnable Emacs executable. These arguments direct | |
40 @file{temacs} to evaluate the Lisp files specified in the file | |
41 @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
|
42 environment, resulting in an Emacs that is still impure but no longer |
6451 | 43 bare. |
44 | |
45 It takes a substantial time to load the standard Lisp files. Luckily, | |
46 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
|
47 dump out an executable program called @file{emacs} that has these files |
6451 | 48 preloaded. @file{emacs} starts more quickly because it does not need to |
49 load the files. This is the Emacs executable that is normally | |
50 installed. | |
51 | |
52 To create @file{emacs}, use the command @samp{temacs -batch -l loadup | |
53 dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} | |
54 from trying to initialize any of its data on the terminal; this ensures | |
55 that the tables of terminal information are empty in the dumped Emacs. | |
56 The argument @samp{dump} tells @file{loadup.el} to dump a new executable | |
57 named @file{emacs}. | |
58 | |
59 Some operating systems don't support dumping. On those systems, you | |
60 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
|
61 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
|
62 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
|
63 extra time is not too severe a problem. |
6451 | 64 |
65 @cindex @file{site-load.el} | |
66 You can specify additional files to preload by writing a library named | |
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
|
67 @file{site-load.el} that loads them. You may need to increase the value |
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
|
68 of @code{PURESIZE}, in @file{src/puresize.h}, to make room for 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
|
69 additional data. (Try adding increments of 20000 until it is big |
6451 | 70 enough.) However, the advantage of preloading additional files |
71 decreases as machines get faster. On modern machines, it is usually not | |
72 advisable. | |
73 | |
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
|
74 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
|
75 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
|
76 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
|
77 @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
|
78 |
6451 | 79 @cindex @file{site-init.el} |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
80 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
|
81 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
|
82 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
|
83 |
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 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
|
85 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
|
86 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
|
87 |
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
|
88 @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
|
89 @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
|
90 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
|
91 and load them with @file{site-load.el}. |
6451 | 92 |
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
|
93 @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
|
94 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
|
95 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
|
96 |
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 Specify a non-@code{nil} value for |
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 @code{byte-compile-dynamic-docstrings} as a local variable in each these |
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
|
100 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
|
101 @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
|
102 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
|
103 @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
|
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 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
|
106 @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
|
107 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
|
108 normal features for your site, do it with @file{default.el}, so that |
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 users can override your changes if they wish. @xref{Start-up Summary}. |
6451 | 110 |
111 @defun dump-emacs to-file from-file | |
112 @cindex unexec | |
18413
487c3d3c2283
dump-emacs works only with -batch.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
113 This function dumps the current state of Emacs into an executable file |
6451 | 114 @var{to-file}. It takes symbols from @var{from-file} (this is normally |
115 the executable file @file{temacs}). | |
116 | |
18413
487c3d3c2283
dump-emacs works only with -batch.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
117 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
|
118 you must run Emacs with @samp{-batch}. |
6451 | 119 @end defun |
120 | |
121 @deffn Command emacs-version | |
122 This function returns a string describing the version of Emacs that is | |
123 running. It is useful to include this string in bug reports. | |
124 | |
125 @example | |
126 @group | |
127 (emacs-version) | |
12098 | 128 @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \ |
129 of Tue Jun 6 1995 on balloon" | |
6451 | 130 @end group |
131 @end example | |
132 | |
133 Called interactively, the function prints the same information in the | |
134 echo area. | |
135 @end deffn | |
136 | |
137 @defvar emacs-build-time | |
12098 | 138 The value of this variable is the time at which Emacs was built at the |
6451 | 139 local site. |
140 | |
141 @example | |
142 @group | |
143 emacs-build-time | |
12098 | 144 @result{} "Tue Jun 6 14:55:57 1995" |
6451 | 145 @end group |
146 @end example | |
147 @end defvar | |
148 | |
149 @defvar emacs-version | |
150 The value of this variable is the version of Emacs being run. It is a | |
12098 | 151 string such as @code{"19.29.1"}. |
6451 | 152 @end defvar |
153 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
154 The following two variables did not exist before Emacs version 19.23, |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
155 which reduces their usefulness at present, but we hope they will be |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
156 convenient in the future. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
157 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
158 @defvar emacs-major-version |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
159 The major version number of Emacs, as an integer. For Emacs version |
12098 | 160 19.29, the value is 19. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
161 @end defvar |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
162 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
163 @defvar emacs-minor-version |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
164 The minor version number of Emacs, as an integer. For Emacs version |
12098 | 165 19.29, the value is 29. |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
166 @end defvar |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
167 |
6451 | 168 @node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals |
169 @appendixsec Pure Storage | |
170 @cindex pure storage | |
171 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
172 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
|
173 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
174 all the new data created during an Emacs session is kept; see the |
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
175 following section for information on normal storage. Pure storage is |
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
176 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
|
177 should never change during actual use of Emacs. |
6451 | 178 |
179 Pure storage is allocated only while @file{temacs} is loading the | |
180 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
|
181 marked as read-only (on operating systems that permit this), so that |
6451 | 182 the memory space can be shared by all the Emacs jobs running on the |
183 machine at once. Pure storage is not expandable; a fixed amount is | |
184 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
|
185 preloaded libraries, @file{temacs} crashes. If that happens, you must |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
186 increase the compilation parameter @code{PURESIZE} in the file |
6451 | 187 @file{src/puresize.h}. This normally won't happen unless you try to |
188 preload additional libraries or add features to the standard ones. | |
189 | |
190 @defun purecopy object | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
191 This function makes a copy of @var{object} in pure storage and returns |
6451 | 192 it. It copies strings by simply making a new string with the same |
193 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
|
194 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
|
195 as symbols, but just returns them unchanged. It signals an error if |
6451 | 196 asked to copy markers. |
197 | |
11139
311f3ea4a759
Minor purecopy correction.
Richard M. Stallman <rms@gnu.org>
parents:
10487
diff
changeset
|
198 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
|
199 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
|
200 a few packages call it just in case you decide to preload them. |
6451 | 201 @end defun |
202 | |
203 @defvar pure-bytes-used | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
204 The value of this variable is the number of bytes of pure storage |
6451 | 205 allocated so far. Typically, in a dumped Emacs, this number is very |
206 close to the total amount of pure storage available---if it were not, | |
207 we would preallocate less. | |
208 @end defvar | |
209 | |
210 @defvar purify-flag | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
211 This variable determines whether @code{defun} should make a copy of the |
6451 | 212 function definition in pure storage. If it is non-@code{nil}, then the |
213 function definition is copied into pure storage. | |
214 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
215 This flag is @code{t} while loading all of the basic functions for |
6451 | 216 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
|
217 non-collectible). Dumping Emacs as an executable always writes |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
218 @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
|
219 before and after dumping. |
6451 | 220 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
221 You should not change this flag in a running Emacs. |
6451 | 222 @end defvar |
223 | |
224 @node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals | |
225 @appendixsec Garbage Collection | |
226 @cindex garbage collector | |
227 | |
228 @cindex memory allocation | |
229 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
|
230 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
|
231 normal storage runs low, then Emacs asks the operating system to |
6451 | 232 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
|
233 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
|
234 segregated in distinct blocks in memory. (Vectors, long strings, |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
235 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
|
236 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
|
237 packed into blocks of 8k bytes.) |
6451 | 238 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
239 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
|
240 (for example) killing a buffer or deleting the last pointer to an |
6451 | 241 object. Emacs provides a @dfn{garbage collector} to reclaim this |
242 abandoned storage. (This name is traditional, but ``garbage recycler'' | |
243 might be a more intuitive metaphor for this facility.) | |
244 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
245 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
|
246 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
|
247 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
|
248 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
|
249 be reached indirectly through other accessible objects are also |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
250 accessible. |
6451 | 251 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
252 When marking is finished, all objects still unmarked are garbage. No |
6451 | 253 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
|
254 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
|
255 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
|
256 (``sweep'') phase of the garbage collector arranges to reuse them. |
6451 | 257 |
258 @cindex free list | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
259 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
|
260 for future allocation; likewise for symbols and markers. It compacts |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
261 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
|
262 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
|
263 individually allocated and freed using @code{malloc} and @code{free}. |
6451 | 264 |
265 @cindex CL note---allocate more storage | |
266 @quotation | |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
267 @b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not |
6451 | 268 call the garbage collector when the free list is empty. Instead, it |
269 simply requests the operating system to allocate more storage, and | |
270 processing continues until @code{gc-cons-threshold} bytes have been | |
271 used. | |
272 | |
273 This means that you can make sure that the garbage collector will not | |
274 run during a certain portion of a Lisp program by calling the garbage | |
275 collector explicitly just before it (provided that portion of the | |
276 program does not use so much space as to force a second garbage | |
277 collection). | |
278 @end quotation | |
279 | |
280 @deffn Command garbage-collect | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
281 This command runs a garbage collection, and returns information on |
6451 | 282 the amount of space in use. (Garbage collection can also occur |
283 spontaneously if you use more than @code{gc-cons-threshold} bytes of | |
284 Lisp data since the previous garbage collection.) | |
285 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
286 @code{garbage-collect} returns a list containing the following |
6451 | 287 information: |
288 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
289 @example |
6451 | 290 @group |
291 ((@var{used-conses} . @var{free-conses}) | |
292 (@var{used-syms} . @var{free-syms}) | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
293 @end group |
6451 | 294 (@var{used-markers} . @var{free-markers}) |
295 @var{used-string-chars} | |
296 @var{used-vector-slots} | |
297 (@var{used-floats} . @var{free-floats})) | |
298 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
299 @group |
6451 | 300 (garbage-collect) |
301 @result{} ((3435 . 2332) (1688 . 0) | |
302 (57 . 417) 24510 3839 (4 . 1)) | |
303 @end group | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
304 @end example |
6451 | 305 |
306 Here is a table explaining each element: | |
307 | |
308 @table @var | |
309 @item used-conses | |
310 The number of cons cells in use. | |
311 | |
312 @item free-conses | |
313 The number of cons cells for which space has been obtained from the | |
314 operating system, but that are not currently being used. | |
315 | |
316 @item used-syms | |
317 The number of symbols in use. | |
318 | |
319 @item free-syms | |
320 The number of symbols for which space has been obtained from the | |
321 operating system, but that are not currently being used. | |
322 | |
323 @item used-markers | |
324 The number of markers in use. | |
325 | |
326 @item free-markers | |
327 The number of markers for which space has been obtained from the | |
328 operating system, but that are not currently being used. | |
329 | |
330 @item used-string-chars | |
331 The total size of all strings, in characters. | |
332 | |
333 @item used-vector-slots | |
334 The total number of elements of existing vectors. | |
335 | |
336 @item used-floats | |
337 @c Emacs 19 feature | |
338 The number of floats in use. | |
339 | |
340 @item free-floats | |
341 @c Emacs 19 feature | |
342 The number of floats for which space has been obtained from the | |
343 operating system, but that are not currently being used. | |
344 @end table | |
345 @end deffn | |
346 | |
15769
43d4b9cf0b69
Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents:
14514
diff
changeset
|
347 @defopt garbage-collection-messages |
43d4b9cf0b69
Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents:
14514
diff
changeset
|
348 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
|
349 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
|
350 @code{nil}, meaning there are no such messages. |
43d4b9cf0b69
Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents:
14514
diff
changeset
|
351 @end defopt |
43d4b9cf0b69
Describe garbage-collection-messages.
Richard M. Stallman <rms@gnu.org>
parents:
14514
diff
changeset
|
352 |
6451 | 353 @defopt gc-cons-threshold |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
354 The value of this variable is the number of bytes of storage that must |
6451 | 355 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
|
356 trigger another garbage collection. A cons cell counts as eight bytes, |
6451 | 357 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
|
358 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
|
359 that the subsequent garbage collection does not happen immediately when |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
360 the threshold is exhausted, but only the next time the Lisp evaluator is |
6451 | 361 called. |
362 | |
12098 | 363 The initial threshold value is 300,000. If you specify a larger |
6451 | 364 value, garbage collection will happen less often. This reduces the |
365 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
|
366 You may want to do this when running a program that creates lots of |
6451 | 367 Lisp data. |
368 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
369 You can make collections more frequent by specifying a smaller value, |
6451 | 370 down to 10,000. A value less than 10,000 will remain in effect only |
371 until the subsequent garbage collection, at which time | |
372 @code{garbage-collect} will set the threshold back to 10,000. | |
373 @end defopt | |
374 | |
375 @c Emacs 19 feature | |
376 @defun memory-limit | |
377 This function returns the address of the last byte Emacs has allocated, | |
378 divided by 1024. We divide the value by 1024 to make sure it fits in a | |
379 Lisp integer. | |
380 | |
381 You can use this to get a general idea of how your actions affect the | |
382 memory usage. | |
383 @end defun | |
384 | |
385 @node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals | |
386 @appendixsec Writing Emacs Primitives | |
387 @cindex primitive function internals | |
388 | |
389 Lisp primitives are Lisp functions implemented in C. The details of | |
390 interfacing the C function so that Lisp can call it are handled by a few | |
391 C macros. The only way to really understand how to write new C code is | |
392 to read the source, but we can explain some things here. | |
393 | |
394 An example of a special form is the definition of @code{or}, from | |
395 @file{eval.c}. (An ordinary function would have the same general | |
396 appearance.) | |
397 | |
398 @cindex garbage collection protection | |
399 @smallexample | |
400 @group | |
401 DEFUN ("or", For, Sor, 0, UNEVALLED, 0, | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15769
diff
changeset
|
402 "Eval args until one of them yields non-nil; return that value.\n\ |
6451 | 403 The remaining args are not evalled at all.\n\ |
404 @end group | |
405 @group | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
406 If all args return nil, return nil.") |
6451 | 407 (args) |
408 Lisp_Object args; | |
409 @{ | |
410 register Lisp_Object val; | |
411 Lisp_Object args_left; | |
412 struct gcpro gcpro1; | |
413 @end group | |
414 | |
415 @group | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
416 if (NULL (args)) |
6451 | 417 return Qnil; |
418 | |
419 args_left = args; | |
420 GCPRO1 (args_left); | |
421 @end group | |
422 | |
423 @group | |
424 do | |
425 @{ | |
426 val = Feval (Fcar (args_left)); | |
427 if (!NULL (val)) | |
428 break; | |
429 args_left = Fcdr (args_left); | |
430 @} | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
431 while (!NULL (args_left)); |
6451 | 432 @end group |
433 | |
434 @group | |
435 UNGCPRO; | |
436 return val; | |
437 @} | |
438 @end group | |
439 @end smallexample | |
440 | |
441 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
|
442 @code{DEFUN} macro. Here is a template for them: |
6451 | 443 |
444 @example | |
445 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) | |
446 @end example | |
447 | |
448 @table @var | |
449 @item lname | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
450 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
|
451 the example above, it is @code{or}. |
6451 | 452 |
453 @item fname | |
454 This is the C function name for this function. This is | |
455 the name that is used in C code for calling the function. The name is, | |
456 by convention, @samp{F} prepended to the Lisp name, with all dashes | |
457 (@samp{-}) in the Lisp name changed to underscores. Thus, to call this | |
458 function from C code, call @code{For}. Remember that the arguments must | |
459 be of type @code{Lisp_Object}; various macros and functions for creating | |
460 values of type @code{Lisp_Object} are declared in the file | |
461 @file{lisp.h}. | |
462 | |
463 @item sname | |
464 This is a C variable name to use for a structure that holds the data for | |
465 the subr object that represents the function in Lisp. This structure | |
466 conveys the Lisp symbol name to the initialization routine that will | |
467 create the symbol and store the subr object as its definition. By | |
468 convention, this name is always @var{fname} with @samp{F} replaced with | |
469 @samp{S}. | |
470 | |
471 @item min | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
472 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
|
473 function @code{or} allows a minimum of zero arguments. |
6451 | 474 |
475 @item max | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
476 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
|
477 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
|
478 indicating a special form that receives unevaluated arguments, or |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
479 @code{MANY}, indicating an unlimited number of evaluated arguments (the |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
480 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
|
481 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
|
482 it may not be greater than seven. |
6451 | 483 |
484 @item interactive | |
485 This is an interactive specification, a string such as might be used as | |
486 the argument of @code{interactive} in a Lisp function. In the case of | |
487 @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
|
488 called interactively. A value of @code{""} indicates a function that |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
489 should receive no arguments when called interactively. |
6451 | 490 |
491 @item doc | |
492 This is the documentation string. It is written just like a | |
493 documentation string for a function defined in Lisp, except you must | |
494 write @samp{\n\} at the end of each line. In particular, the first line | |
495 should be a single sentence. | |
496 @end table | |
497 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
498 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
|
499 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
|
500 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
|
501 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
|
502 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
|
503 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
|
504 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
|
505 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
|
506 values. They have types @code{int} and @w{@code{Lisp_Object *}}. |
6451 | 507 |
508 Within the function @code{For} itself, note the use of the macros | |
509 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect'' | |
510 a variable from garbage collection---to inform the garbage collector that | |
511 it must look in that variable and regard its contents as an accessible | |
512 object. This is necessary whenever you call @code{Feval} or anything | |
513 that can directly or indirectly call @code{Feval}. At such a time, any | |
514 Lisp object that you intend to refer to again must be protected somehow. | |
515 @code{UNGCPRO} cancels the protection of the variables that are | |
516 protected in the current function. It is necessary to do this explicitly. | |
517 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
518 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
|
519 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
|
520 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
|
521 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
|
522 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
|
523 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
|
524 where garbage collection may be possible. |
6451 | 525 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
526 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
|
527 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
|
528 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist. |
6451 | 529 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
530 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
|
531 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
|
532 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
|
533 Alas, we can't explain all the tricky details here. |
6451 | 534 |
10487 | 535 You must not use C initializers for static or global variables unless |
536 they are never written once Emacs is dumped. These variables with | |
537 initializers are allocated in an area of memory that becomes read-only | |
538 (on certain operating systems) as a result of dumping Emacs. @xref{Pure | |
539 Storage}. | |
10476
4d87344e6dfb
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7601
diff
changeset
|
540 |
10487 | 541 Do not use static variables within functions---place all static |
542 variables at top level in the file. This is necessary because Emacs on | |
543 some operating systems defines the keyword @code{static} as a null | |
544 macro. (This definition is used because those systems put all variables | |
545 declared static in a place that becomes read-only after dumping, whether | |
546 they have initializers or not.) | |
10476
4d87344e6dfb
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7601
diff
changeset
|
547 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
548 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
|
549 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
|
550 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
|
551 this: |
6451 | 552 |
553 @example | |
554 defsubr (&@var{subr-structure-name}); | |
555 @end example | |
556 | |
557 @noindent | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
558 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
|
559 argument to @code{DEFUN}. |
6451 | 560 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
561 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
|
562 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
|
563 @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
|
564 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
|
565 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
|
566 @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
|
567 of these functions are called, and add a call to |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
568 @code{syms_of_@var{filename}} there. |
6451 | 569 |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
570 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
|
571 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
|
572 @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
|
573 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
|
574 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
|
575 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
576 with a value that is either @code{t} or @code{nil}. |
6451 | 577 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
578 Here is another example function, with more complicated arguments. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
579 This comes from the code for the X Window System, and it demonstrates |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
580 the use of macros and functions to manipulate Lisp objects. |
6451 | 581 |
582 @smallexample | |
583 @group | |
584 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, | |
585 Scoordinates_in_window_p, 2, 2, | |
586 "xSpecify coordinate pair: \nXExpression which evals to window: ", | |
587 "Return non-nil if POSITIONS is in WINDOW.\n\ | |
588 \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\ | |
589 @end group | |
590 @group | |
591 Returned value is list of positions expressed\n\ | |
592 relative to window upper left corner.") | |
593 (coordinate, window) | |
594 register Lisp_Object coordinate, window; | |
595 @{ | |
596 register Lisp_Object xcoord, ycoord; | |
597 @end group | |
598 | |
599 @group | |
600 if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate); | |
601 CHECK_WINDOW (window, 2); | |
602 xcoord = Fcar (coordinate); | |
603 ycoord = Fcar (Fcdr (coordinate)); | |
604 CHECK_NUMBER (xcoord, 0); | |
605 CHECK_NUMBER (ycoord, 1); | |
606 @end group | |
607 @group | |
608 if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) | |
609 || (XINT (xcoord) >= (XINT (XWINDOW (window)->left) | |
610 + XINT (XWINDOW (window)->width)))) | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
611 return Qnil; |
6451 | 612 XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left); |
613 @end group | |
614 @group | |
615 if (XINT (ycoord) == (screen_height - 1)) | |
616 return Qnil; | |
617 @end group | |
618 @group | |
619 if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) | |
620 || (XINT (ycoord) >= (XINT (XWINDOW (window)->top) | |
621 + XINT (XWINDOW (window)->height)) - 1)) | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
622 return Qnil; |
6451 | 623 @end group |
624 @group | |
625 XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top); | |
626 return (Fcons (xcoord, Fcons (ycoord, Qnil))); | |
627 @} | |
628 @end group | |
629 @end smallexample | |
630 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
631 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
|
632 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
|
633 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
634 the Lisp function @code{funcall} accepts an unlimited number of |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
635 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
|
636 one-dimensional array containing their values. The first Lisp-level |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
637 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
|
638 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
|
639 protect pointers from garbage collection around the call to |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
640 @code{Ffuncall}. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
641 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
642 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
|
643 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
|
644 number of arguments. They work by calling @code{Ffuncall}. |
6451 | 645 |
646 @file{eval.c} is a very good file to look through for examples; | |
647 @file{lisp.h} contains the definitions for some important macros and | |
648 functions. | |
649 | |
650 @node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals | |
651 @appendixsec Object Internals | |
652 @cindex object internals | |
653 | |
654 GNU Emacs Lisp manipulates many different types of data. The actual | |
655 data are stored in a heap and the only access that programs have to it is | |
656 through pointers. Pointers are thirty-two bits wide in most | |
657 implementations. Depending on the operating system and type of machine | |
658 for which you compile Emacs, twenty-four to twenty-six bits are used to | |
659 address the object, and the remaining six to eight bits are used for a | |
660 tag that identifies the object's type. | |
661 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
662 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
|
663 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
|
664 @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
|
665 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
|
666 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
|
667 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
|
668 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
|
669 explicitly using a suitable predicate (@pxref{Type Predicates}). |
6451 | 670 @cindex type checking internals |
671 | |
672 @menu | |
673 * Buffer Internals:: Components of a buffer structure. | |
674 * Window Internals:: Components of a window structure. | |
675 * Process Internals:: Components of a process structure. | |
676 @end menu | |
677 | |
678 @node Buffer Internals, Window Internals, Object Internals, Object Internals | |
679 @appendixsubsec Buffer Internals | |
680 @cindex internals, of buffer | |
681 @cindex buffer internals | |
682 | |
683 Buffers contain fields not directly accessible by the Lisp programmer. | |
684 We describe them here, naming them by the names used in the C code. | |
685 Many are accessible indirectly in Lisp programs via Lisp primitives. | |
686 | |
687 @table @code | |
688 @item name | |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
689 The buffer name is a string that names the buffer. It is guaranteed to |
6451 | 690 be unique. @xref{Buffer Names}. |
691 | |
692 @item save_modified | |
693 This field contains the time when the buffer was last saved, as an integer. | |
694 @xref{Buffer Modification}. | |
695 | |
696 @item modtime | |
697 This field contains the modification time of the visited file. It is | |
698 set when the file is written or read. Every time the buffer is written | |
699 to the file, this field is compared to the modification time of the | |
700 file. @xref{Buffer Modification}. | |
701 | |
702 @item auto_save_modified | |
703 This field contains the time when the buffer was last auto-saved. | |
704 | |
705 @item last_window_start | |
706 This field contains the @code{window-start} position in the buffer as of | |
707 the last time the buffer was displayed in a window. | |
708 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
709 @item undo_list |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
710 This field points to the buffer's undo list. @xref{Undo}. |
6451 | 711 |
712 @item syntax_table_v | |
713 This field contains the syntax table for the buffer. @xref{Syntax Tables}. | |
714 | |
715 @item downcase_table | |
716 This field contains the conversion table for converting text to lower case. | |
717 @xref{Case Table}. | |
718 | |
719 @item upcase_table | |
720 This field contains the conversion table for converting text to upper case. | |
721 @xref{Case Table}. | |
722 | |
723 @item case_canon_table | |
724 This field contains the conversion table for canonicalizing text for | |
725 case-folding search. @xref{Case Table}. | |
726 | |
727 @item case_eqv_table | |
728 This field contains the equivalence table for case-folding search. | |
729 @xref{Case Table}. | |
730 | |
731 @item display_table | |
732 This field contains the buffer's display table, or @code{nil} if it doesn't | |
733 have one. @xref{Display Tables}. | |
734 | |
735 @item markers | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
736 This field contains the chain of all markers that currently point into |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
737 the buffer. Deletion of text in the buffer, and motion of the buffer's |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
738 gap, must check each of these markers and perhaps update it. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
739 @xref{Markers}. |
6451 | 740 |
741 @item backed_up | |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
742 This field is a flag that tells whether a backup file has been made |
6451 | 743 for the visited file of this buffer. |
744 | |
745 @item mark | |
746 This field contains the mark for the buffer. The mark is a marker, | |
747 hence it is also included on the list @code{markers}. @xref{The Mark}. | |
748 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
749 @item mark_active |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
750 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
|
751 |
6451 | 752 @item local_var_alist |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
753 This field contains the association list describing the variables local |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
754 in this buffer, and their values, with the exception of local variables |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
755 that have special slots in the buffer object. (Those slots are omitted |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
756 from this table.) @xref{Buffer-Local Variables}. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
757 |
12098 | 758 @item base_buffer |
759 This field holds the buffer's base buffer (if it is an indirect buffer), | |
760 or @code{nil}. | |
761 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
762 @item keymap |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
763 This field holds the buffer's local keymap. @xref{Keymaps}. |
6451 | 764 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
765 @item overlay_center |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
766 This field holds the current overlay center position. @xref{Overlays}. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
767 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
768 @item overlays_before |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
769 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
|
770 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
|
771 decreasing end position. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
772 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
773 @item overlays_after |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
774 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
|
775 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
|
776 increasing beginning position. |
6451 | 777 @end table |
778 | |
779 @node Window Internals, Process Internals, Buffer Internals, Object Internals | |
780 @appendixsubsec Window Internals | |
781 @cindex internals, of window | |
782 @cindex window internals | |
783 | |
784 Windows have the following accessible fields: | |
785 | |
786 @table @code | |
787 @item frame | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
788 The frame that this window is on. |
6451 | 789 |
790 @item mini_p | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
791 Non-@code{nil} if this window is a minibuffer window. |
6451 | 792 |
793 @item buffer | |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
794 The buffer that the window is displaying. This may change often during |
6451 | 795 the life of the window. |
796 | |
797 @item dedicated | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
798 Non-@code{nil} if this window is dedicated to its buffer. |
6451 | 799 |
800 @item pointm | |
801 @cindex window point internals | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
802 This is the value of point in the current buffer when this window is |
6451 | 803 selected; when it is not selected, it retains its previous value. |
804 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
805 @item start |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
806 The position in the buffer that is the first character to be displayed |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
807 in the window. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
808 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
809 @item force_start |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
810 If this flag is non-@code{nil}, it says that the window has been |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
811 scrolled explicitly by the Lisp program. This affects what the next |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
812 redisplay does if point is off the screen: instead of scrolling the |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
813 window to show the text around point, it moves point to a location that |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
814 is on the screen. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
815 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
816 @item last_modified |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
817 The @code{modified} field of the window's buffer, as of the last time |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
818 a redisplay completed in this window. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
819 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
820 @item last_point |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
821 The buffer's value of point, as of the last time |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
822 a redisplay completed in this window. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
823 |
6451 | 824 @item left |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
825 This is the left-hand edge of the window, measured in columns. (The |
6451 | 826 leftmost column on the screen is @w{column 0}.) |
827 | |
828 @item top | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
829 This is the top edge of the window, measured in lines. (The top line on |
6451 | 830 the screen is @w{line 0}.) |
831 | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
832 @item height |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
833 The height of the window, measured in lines. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
834 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
835 @item width |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
836 The width of the window, measured in columns. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
837 |
6451 | 838 @item next |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
839 This is the window that is the next in the chain of siblings. It is |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
840 @code{nil} in a window that is the rightmost or bottommost of a group of |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
841 siblings. |
6451 | 842 |
843 @item prev | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
844 This is the window that is the previous in the chain of siblings. It is |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
845 @code{nil} in a window that is the leftmost or topmost of a group of |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
846 siblings. |
6451 | 847 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
848 @item parent |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
849 Internally, Emacs arranges windows in a tree; each group of siblings has |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
850 a parent window whose area includes all the siblings. This field points |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
851 to a window's parent. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
852 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
853 Parent windows do not display buffers, and play little role in display |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
854 except to shape their child windows. Emacs Lisp programs usually have |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
855 no access to the parent windows; they operate on the windows at the |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
856 leaves of the tree, which actually display buffers. |
6451 | 857 |
858 @item hscroll | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
859 This is the number of columns that the display in the window is scrolled |
6451 | 860 horizontally to the left. Normally, this is 0. |
861 | |
862 @item use_time | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
863 This is the last time that the window was selected. The function |
6451 | 864 @code{get-lru-window} uses this field. |
865 | |
866 @item display_table | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
867 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
|
868 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
869 @item update_mode_line |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
870 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
|
871 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
872 @item base_line_number |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
873 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
|
874 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
|
875 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
876 @item base_line_pos |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
877 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
|
878 @code{nil} meaning none is known. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
879 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
880 @item region_showing |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
881 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
|
882 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
|
883 this field is @code{nil}. |
6451 | 884 @end table |
885 | |
886 @node Process Internals, , Window Internals, Object Internals | |
887 @appendixsubsec Process Internals | |
888 @cindex internals, of process | |
889 @cindex process internals | |
890 | |
891 The fields of a process are: | |
892 | |
893 @table @code | |
894 @item name | |
895 A string, the name of the process. | |
896 | |
897 @item command | |
898 A list containing the command arguments that were used to start this | |
899 process. | |
900 | |
901 @item filter | |
902 A function used to accept output from the process instead of a buffer, | |
903 or @code{nil}. | |
904 | |
905 @item sentinel | |
906 A function called whenever the process receives a signal, or @code{nil}. | |
907 | |
908 @item buffer | |
909 The associated buffer of the process. | |
910 | |
911 @item pid | |
912 An integer, the Unix process @sc{id}. | |
913 | |
914 @item childp | |
915 A flag, non-@code{nil} if this is really a child process. | |
916 It is @code{nil} for a network connection. | |
917 | |
918 @item mark | |
7601
c5927c75b2b5
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
919 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
|
920 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
|
921 of the buffer. |
6451 | 922 |
923 @item kill_without_query | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
924 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
|
925 running does not ask for confirmation about killing the process. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
926 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
927 @item raw_status_low |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
928 @itemx raw_status_high |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
929 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
|
930 the @code{wait} system call. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
931 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
932 @item status |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
933 The process status, as @code{process-status} should return it. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
934 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
935 @item tick |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
936 @itemx update_tick |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
937 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
|
938 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
|
939 message in the process buffer. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
940 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
941 @item pty_flag |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
942 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
|
943 @code{nil} if it uses a pipe. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
944 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
945 @item infd |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
946 The file descriptor for input from the process. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
947 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
948 @item outfd |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
949 The file descriptor for output to the process. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
950 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
951 @item subtty |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6451
diff
changeset
|
952 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
|
953 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
|
954 @code{nil}.) |
12098 | 955 |
956 @item tty_name | |
957 The name of the terminal that the subprocess is using, | |
958 or @code{nil} if it is using pipes. | |
6451 | 959 @end table |