Mercurial > hg > xemacs-beta
annotate man/lispref/os.texi @ 4885:6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
lisp/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Correct the semantics of #'member*, #'eql, #'assoc* in the
presence of bignums; change the integerp byte code to fixnump
semantics.
* bytecomp.el (fixnump, integerp, byte-compile-integerp):
Change the integerp byte code to fixnump; add a byte-compile
method to integerp using fixnump and numberp and avoiding a
funcall most of the time, since in the non-core contexts where
integerp is used, it's mostly distinguishing between fixnums and
things that are not numbers at all.
* byte-optimize.el (side-effect-free-fns, byte-after-unbind-ops)
(byte-compile-side-effect-and-error-free-ops):
Replace the integerp bytecode with fixnump; add fixnump to the
side-effect-free-fns. Add the other extended number type
predicates to the list in passing.
* obsolete.el (floatp-safe): Mark this as obsolete.
* cl.el (eql): Go into more detail in the docstring here. Don't
bother checking whether both arguments are numbers; one is enough,
#'equal will fail correctly if they have distinct types.
(subst): Replace a call to #'integerp (deciding whether to use
#'memq or not) with one to #'fixnump.
Delete most-positive-fixnum, most-negative-fixnum from this file;
they're now always in C, so they can't be modified from Lisp.
* cl-seq.el (member*, assoc*, rassoc*):
Correct these functions in the presence of bignums.
* cl-macs.el (cl-make-type-test): The type test for a fixnum is
now fixnump. Ditch floatp-safe, use floatp instead.
(eql): Correct this compiler macro in the presence of bignums.
(assoc*): Correct this compiler macro in the presence of bignums.
* simple.el (undo):
Change #'integerp to #'fixnump here, since we use #'delq with the
same value as ELT a few lines down.
src/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Fix problems with #'eql, extended number types, and the hash table
implementation; change the Bintegerp bytecode to fixnump semantics
even on bignum builds, since #'integerp can have a fast
implementation in terms of #'fixnump for most of its extant uses,
but not vice-versa.
* lisp.h: Always #include number.h; we want the macros provided in
it, even if the various number types are not available.
* number.h (NON_FIXNUM_NUMBER_P): New macro, giving 1 when its
argument is of non-immediate number type. Equivalent to FLOATP if
WITH_NUMBER_TYPES is not defined.
* elhash.c (lisp_object_eql_equal, lisp_object_eql_hash):
Use NON_FIXNUM_NUMBER_P in these functions, instead of FLOATP,
giving more correct behaviour in the presence of the extended
number types.
* bytecode.c (Bfixnump, execute_optimized_program):
Rename Bintegerp to Bfixnump; change its semantics to reflect the
new name on builds with bignum support.
* data.c (Ffixnump, Fintegerp, syms_of_data, vars_of_data):
Always make #'fixnump available, even on non-BIGNUM builds;
always implement #'integerp in this file, even on BIGNUM builds.
Move most-positive-fixnum, most-negative-fixnum here from
number.c, so they are Lisp constants even on builds without number
types, and attempts to change or bind them error.
Use the NUMBERP and INTEGERP macros even on builds without
extended number types.
* data.c (fixnum_char_or_marker_to_int):
Rename this function from integer_char_or_marker_to_int, to better
reflect the arguments it accepts.
* number.c (Fevenp, Foddp, syms_of_number):
Never provide #'integerp in this file. Remove #'oddp,
#'evenp; their implementations are overridden by those in cl.el.
* number.c (vars_of_number):
most-positive-fixnum, most-negative-fixnum are no longer here.
man/ChangeLog addition:
2010-01-23 Aidan Kehoe <kehoea@parhasard.net>
Generally: be careful to say fixnum, not integer, when talking
about fixed-precision integral types. I'm sure I've missed
instances, both here and in the docstrings, but this is a decent
start.
* lispref/text.texi (Columns):
Document where only fixnums, not integers generally, are accepted.
(Registers):
Remove some ancient char-int confoundance here.
* lispref/strings.texi (Creating Strings, Creating Strings):
Be more exact in describing where fixnums but not integers in
general are accepted.
(Creating Strings): Use a more contemporary example to illustrate
how concat deals with lists including integers about #xFF. Delete
some obsolete documentation on same.
(Char Table Types): Document that only fixnums are accepted as
values in syntax tables.
* lispref/searching.texi (String Search, Search and Replace):
Be exact in describing where fixnums but not integers in general
are accepted.
* lispref/range-tables.texi (Range Tables): Be exact in describing
them; only fixnums are accepted to describe ranges.
* lispref/os.texi (Killing XEmacs, User Identification)
(Time of Day, Time Conversion):
Be more exact about using fixnum where only fixed-precision
integers are accepted.
* lispref/objects.texi (Integer Type): Be more exact (and
up-to-date) about the possible values for
integers. Cross-reference to documentation of the bignum extension.
(Equality Predicates):
(Range Table Type):
(Array Type): Use fixnum, not integer, to describe a
fixed-precision integer.
(Syntax Table Type): Correct some English syntax here.
* lispref/numbers.texi (Numbers): Change the phrasing here to use
fixnum to mean the fixed-precision integers normal in emacs.
Document that our terminology deviates from that of Common Lisp,
and that we're working on it.
(Compatibility Issues): Reiterate the Common Lisp versus Emacs
Lisp compatibility issues.
(Comparison of Numbers, Arithmetic Operations):
* lispref/commands.texi (Command Loop Info, Working With Events):
* lispref/buffers.texi (Modification Time):
Be more exact in describing where fixnums but not integers in
general are accepted.
author | Aidan Kehoe <kehoea@parhasard.net> |
---|---|
date | Sun, 24 Jan 2010 15:21:27 +0000 |
parents | aa5ed11f473b |
children | 1537701f08a1 |
rev | line source |
---|---|
428 | 1 @c -*-texinfo-*- |
2 @c This is part of the XEmacs Lisp Reference Manual. | |
444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
428 | 4 @c See the file lispref.texi for copying conditions. |
5 @setfilename ../../info/os.info | |
6 @node System Interface, X-Windows, Processes, Top | |
7 @chapter Operating System Interface | |
8 | |
9 This chapter is about starting and getting out of Emacs, access to | |
10 values in the operating system environment, and terminal input, output, | |
11 and flow control. | |
12 | |
13 @xref{Building XEmacs}, for related information. See also | |
14 @ref{Display}, for additional operating system status information | |
15 pertaining to the terminal and the screen. | |
16 | |
17 @menu | |
18 * Starting Up:: Customizing XEmacs start-up processing. | |
19 * Getting Out:: How exiting works (permanent or temporary). | |
20 * System Environment:: Distinguish the name and kind of system. | |
21 * User Identification:: Finding the name and user id of the user. | |
22 * Time of Day:: Getting the current time. | |
23 * Time Conversion:: Converting a time from numeric form to a string, or | |
24 to calendrical data (or vice versa). | |
25 * Timers:: Setting a timer to call a function at a certain time. | |
26 * Terminal Input:: Recording terminal input for debugging. | |
27 * Terminal Output:: Recording terminal output for debugging. | |
28 * Flow Control:: How to turn output flow control on or off. | |
29 * Batch Mode:: Running XEmacs without terminal interaction. | |
30 @end menu | |
31 @ignore | |
32 * Special Keysyms:: Defining system-specific key symbols for X windows. | |
33 @end ignore | |
34 | |
35 @node Starting Up | |
36 @section Starting Up XEmacs | |
37 | |
38 This section describes what XEmacs does when it is started, and how you | |
39 can customize these actions. | |
40 | |
41 @menu | |
42 * Start-up Summary:: Sequence of actions XEmacs performs at start-up. | |
43 * Init File:: Details on reading the init file (@file{.emacs}). | |
44 * Terminal-Specific:: How the terminal-specific Lisp file is read. | |
45 * Command Line Arguments:: How command line arguments are processed, | |
46 and how you can customize them. | |
47 @end menu | |
48 | |
49 @node Start-up Summary | |
50 @subsection Summary: Sequence of Actions at Start Up | |
51 @cindex initialization | |
52 @cindex start up of XEmacs | |
53 @cindex @file{startup.el} | |
54 | |
55 The order of operations performed (in @file{startup.el}) by XEmacs when | |
56 it is started up is as follows: | |
57 | |
58 @enumerate | |
59 @item | |
60 It loads the initialization library for the window system, if you are | |
61 using a window system. This library's name is | |
62 @file{term/@var{windowsystem}-win.el}. | |
63 | |
64 @item | |
65 It processes the initial options. (Some of them are handled | |
66 even earlier than this.) | |
67 | |
68 @item | |
69 It initializes the X window frame and faces, if appropriate. | |
70 | |
71 @item | |
72 It runs the normal hook @code{before-init-hook}. | |
73 | |
74 @item | |
75 It loads the library @file{site-start}, unless the option | |
76 @samp{-no-site-file} was specified. The library's file name is usually | |
77 @file{site-start.el}. | |
78 @cindex @file{site-start.el} | |
79 | |
444 | 80 @item |
428 | 81 It loads the file @file{~/.emacs} unless @samp{-q} was specified on |
82 the command line. (This is not done in @samp{-batch} mode.) The @samp{-u} | |
83 option can specify the user name whose home directory should be used | |
84 instead of @file{~}. | |
85 | |
444 | 86 @item |
428 | 87 It loads the library @file{default} unless @code{inhibit-default-init} |
88 is non-@code{nil}. (This is not done in @samp{-batch} mode or if | |
89 @samp{-q} was specified on the command line.) The library's file name | |
90 is usually @file{default.el}. | |
91 @cindex @file{default.el} | |
92 | |
93 @item | |
94 It runs the normal hook @code{after-init-hook}. | |
95 | |
96 @item | |
97 It sets the major mode according to @code{initial-major-mode}, provided | |
98 the buffer @samp{*scratch*} is still current and still in Fundamental | |
99 mode. | |
100 | |
444 | 101 @item |
428 | 102 It loads the terminal-specific Lisp file, if any, except when in batch |
103 mode or using a window system. | |
104 | |
105 @item | |
106 It displays the initial echo area message, unless you have suppressed | |
107 that with @code{inhibit-startup-echo-area-message}. | |
108 | |
444 | 109 @item |
428 | 110 It processes the action arguments from the command line. |
111 | |
444 | 112 @item |
428 | 113 It runs @code{term-setup-hook}. |
114 | |
115 @item | |
116 It calls @code{frame-notice-user-settings}, which modifies the | |
117 parameters of the selected frame according to whatever the init files | |
118 specify. | |
119 | |
444 | 120 @item |
428 | 121 It runs @code{window-setup-hook}. @xref{Terminal-Specific}. |
122 | |
444 | 123 @item |
428 | 124 It displays copyleft, nonwarranty, and basic use information, provided |
125 there were no remaining command line arguments (a few steps above) and | |
126 the value of @code{inhibit-startup-message} is @code{nil}. | |
127 @end enumerate | |
128 | |
129 @defopt inhibit-startup-message | |
130 This variable inhibits the initial startup messages (the nonwarranty, | |
131 etc.). If it is non-@code{nil}, then the messages are not printed. | |
132 | |
133 This variable exists so you can set it in your personal init file, once | |
134 you are familiar with the contents of the startup message. Do not set | |
135 this variable in the init file of a new user, or in a way that affects | |
136 more than one user, because that would prevent new users from receiving | |
137 the information they are supposed to see. | |
138 @end defopt | |
139 | |
140 @defopt inhibit-startup-echo-area-message | |
141 This variable controls the display of the startup echo area message. | |
142 You can suppress the startup echo area message by adding text with this | |
143 form to your @file{.emacs} file: | |
144 | |
145 @example | |
146 (setq inhibit-startup-echo-area-message | |
147 "@var{your-login-name}") | |
148 @end example | |
149 | |
150 Simply setting @code{inhibit-startup-echo-area-message} to your login | |
151 name is not sufficient to inhibit the message; Emacs explicitly checks | |
152 whether @file{.emacs} contains an expression as shown above. Your login | |
153 name must appear in the expression as a Lisp string constant. | |
154 | |
155 This way, you can easily inhibit the message for yourself if you wish, | |
156 but thoughtless copying of your @file{.emacs} file will not inhibit the | |
157 message for someone else. | |
158 @end defopt | |
159 | |
160 @node Init File | |
161 @subsection The Init File: @file{.emacs} | |
162 @cindex init file | |
163 @cindex @file{.emacs} | |
164 | |
165 When you start XEmacs, it normally attempts to load the file | |
166 @file{.emacs} from your home directory. This file, if it exists, must | |
167 contain Lisp code. It is called your @dfn{init file}. The command line | |
168 switches @samp{-q} and @samp{-u} affect the use of the init file; | |
169 @samp{-q} says not to load an init file, and @samp{-u} says to load a | |
170 specified user's init file instead of yours. @xref{Entering XEmacs,,, | |
171 xemacs, The XEmacs User's Manual}. | |
172 | |
173 @cindex default init file | |
174 A site may have a @dfn{default init file}, which is the library named | |
175 @file{default.el}. XEmacs finds the @file{default.el} file through the | |
176 standard search path for libraries (@pxref{How Programs Do Loading}). | |
177 The XEmacs distribution does not come with this file; sites may provide | |
178 one for local customizations. If the default init file exists, it is | |
179 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is | |
180 specified. But your own personal init file, if any, is loaded first; if | |
181 it sets @code{inhibit-default-init} to a non-@code{nil} value, then | |
182 XEmacs does not subsequently load the @file{default.el} file. | |
183 | |
184 Another file for site-customization is @file{site-start.el}. Emacs | |
185 loads this @emph{before} the user's init file. You can inhibit the | |
186 loading of this file with the option @samp{-no-site-file}. | |
187 | |
188 @defvar site-run-file | |
189 This variable specifies the site-customization file to load | |
190 before the user's init file. Its normal value is @code{"site-start"}. | |
191 @end defvar | |
192 | |
193 If there is a great deal of code in your @file{.emacs} file, you | |
194 should move it into another file named @file{@var{something}.el}, | |
195 byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs} | |
196 file load the other file using @code{load} (@pxref{Loading}). | |
197 | |
198 @xref{Init File Examples,,, xemacs, The XEmacs User's Manual}, for | |
199 examples of how to make various commonly desired customizations in your | |
200 @file{.emacs} file. | |
201 | |
202 @defopt inhibit-default-init | |
203 This variable prevents XEmacs from loading the default initialization | |
204 library file for your session of XEmacs. If its value is non-@code{nil}, | |
205 then the default library is not loaded. The default value is | |
206 @code{nil}. | |
207 @end defopt | |
208 | |
209 @defvar before-init-hook | |
210 @defvarx after-init-hook | |
211 These two normal hooks are run just before, and just after, loading of | |
212 the user's init file, @file{default.el}, and/or @file{site-start.el}. | |
213 @end defvar | |
214 | |
215 @node Terminal-Specific | |
216 @subsection Terminal-Specific Initialization | |
217 @cindex terminal-specific initialization | |
218 | |
219 Each terminal type can have its own Lisp library that XEmacs loads when | |
220 run on that type of terminal. For a terminal type named @var{termtype}, | |
221 the library is called @file{term/@var{termtype}}. XEmacs finds the file | |
222 by searching the @code{load-path} directories as it does for other | |
223 files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally, | |
224 terminal-specific Lisp library is located in @file{emacs/lisp/term}, a | |
225 subdirectory of the @file{emacs/lisp} directory in which most XEmacs Lisp | |
226 libraries are kept.@refill | |
227 | |
228 The library's name is constructed by concatenating the value of the | |
229 variable @code{term-file-prefix} and the terminal type. Normally, | |
230 @code{term-file-prefix} has the value @code{"term/"}; changing this | |
231 is not recommended. | |
232 | |
233 The usual function of a terminal-specific library is to enable special | |
234 keys to send sequences that XEmacs can recognize. It may also need to | |
235 set or add to @code{function-key-map} if the Termcap entry does not | |
236 specify all the terminal's function keys. @xref{Terminal Input}. | |
237 | |
238 @cindex Termcap | |
239 When the name of the terminal type contains a hyphen, only the part of | |
240 the name before the first hyphen is significant in choosing the library | |
241 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use | |
242 the @file{term/aaa} library. If necessary, the library can evaluate | |
243 @code{(getenv "TERM")} to find the full name of the terminal | |
244 type.@refill | |
245 | |
246 Your @file{.emacs} file can prevent the loading of the | |
247 terminal-specific library by setting the variable | |
248 @code{term-file-prefix} to @code{nil}. This feature is useful when | |
249 experimenting with your own peculiar customizations. | |
250 | |
251 You can also arrange to override some of the actions of the | |
252 terminal-specific library by setting the variable | |
253 @code{term-setup-hook}. This is a normal hook which XEmacs runs using | |
254 @code{run-hooks} at the end of XEmacs initialization, after loading both | |
255 your @file{.emacs} file and any terminal-specific libraries. You can | |
256 use this variable to define initializations for terminals that do not | |
257 have their own libraries. @xref{Hooks}. | |
258 | |
259 @defvar term-file-prefix | |
260 @cindex @code{TERM} environment variable | |
261 If the @code{term-file-prefix} variable is non-@code{nil}, XEmacs loads | |
262 a terminal-specific initialization file as follows: | |
263 | |
264 @example | |
265 (load (concat term-file-prefix (getenv "TERM"))) | |
266 @end example | |
267 | |
268 @noindent | |
269 You may set the @code{term-file-prefix} variable to @code{nil} in your | |
270 @file{.emacs} file if you do not wish to load the | |
271 terminal-initialization file. To do this, put the following in | |
272 your @file{.emacs} file: @code{(setq term-file-prefix nil)}. | |
273 @end defvar | |
274 | |
444 | 275 @defvar term-setup-hook |
428 | 276 This variable is a normal hook that XEmacs runs after loading your |
277 @file{.emacs} file, the default initialization file (if any) and the | |
278 terminal-specific Lisp file. | |
279 | |
280 You can use @code{term-setup-hook} to override the definitions made by a | |
281 terminal-specific file. | |
282 @end defvar | |
283 | |
284 @defvar window-setup-hook | |
285 This variable is a normal hook which XEmacs runs after loading your | |
286 @file{.emacs} file and the default initialization file (if any), after | |
287 loading terminal-specific Lisp code, and after running the hook | |
288 @code{term-setup-hook}. | |
289 @end defvar | |
290 | |
291 @node Command Line Arguments | |
292 @subsection Command Line Arguments | |
293 @cindex command line arguments | |
294 | |
295 You can use command line arguments to request various actions when you | |
296 start XEmacs. Since you do not need to start XEmacs more than once per | |
297 day, and will often leave your XEmacs session running longer than that, | |
298 command line arguments are hardly ever used. As a practical matter, it | |
299 is best to avoid making the habit of using them, since this habit would | |
300 encourage you to kill and restart XEmacs unnecessarily often. These | |
301 options exist for two reasons: to be compatible with other editors (for | |
302 invocation by other programs) and to enable shell scripts to run | |
303 specific Lisp programs. | |
304 | |
305 This section describes how Emacs processes command line arguments, | |
306 and how you can customize them. | |
307 | |
308 @ignore | |
309 (Note that some other editors require you to start afresh each time | |
310 you want to edit a file. With this kind of editor, you will probably | |
311 specify the file as a command line argument. The recommended way to | |
312 use XEmacs is to start it only once, just after you log in, and do | |
313 all your editing in the same XEmacs process. Each time you want to edit | |
314 a different file, you visit it with the existing XEmacs, which eventually | |
315 comes to have many files in it ready for editing. Usually you do not | |
316 kill the XEmacs until you are about to log out.) | |
317 @end ignore | |
318 | |
319 @defun command-line | |
320 This function parses the command line that XEmacs was called with, | |
321 processes it, loads the user's @file{.emacs} file and displays the | |
322 startup messages. | |
323 @end defun | |
324 | |
325 @defvar command-line-processed | |
326 The value of this variable is @code{t} once the command line has been | |
327 processed. | |
328 | |
329 If you redump XEmacs by calling @code{dump-emacs}, you may wish to set | |
330 this variable to @code{nil} first in order to cause the new dumped XEmacs | |
331 to process its new command line arguments. | |
332 @end defvar | |
333 | |
334 @defvar command-switch-alist | |
335 @cindex switches on command line | |
336 @cindex options on command line | |
337 @cindex command line options | |
338 The value of this variable is an alist of user-defined command-line | |
339 options and associated handler functions. This variable exists so you | |
340 can add elements to it. | |
341 | |
342 A @dfn{command line option} is an argument on the command line of the | |
343 form: | |
344 | |
345 @example | |
346 -@var{option} | |
347 @end example | |
348 | |
444 | 349 The elements of the @code{command-switch-alist} look like this: |
428 | 350 |
351 @example | |
352 (@var{option} . @var{handler-function}) | |
353 @end example | |
354 | |
355 The @var{handler-function} is called to handle @var{option} and receives | |
356 the option name as its sole argument. | |
357 | |
358 In some cases, the option is followed in the command line by an | |
359 argument. In these cases, the @var{handler-function} can find all the | |
360 remaining command-line arguments in the variable | |
361 @code{command-line-args-left}. (The entire list of command-line | |
362 arguments is in @code{command-line-args}.) | |
363 | |
364 The command line arguments are parsed by the @code{command-line-1} | |
365 function in the @file{startup.el} file. See also @ref{Command | |
366 Switches, , Command Line Switches and Arguments, xemacs, The XEmacs | |
367 User's Manual}. | |
368 @end defvar | |
369 | |
370 @defvar command-line-args | |
371 The value of this variable is the list of command line arguments passed | |
372 to XEmacs. | |
373 @end defvar | |
374 | |
375 @defvar command-line-functions | |
376 This variable's value is a list of functions for handling an | |
377 unrecognized command-line argument. Each time the next argument to be | |
378 processed has no special meaning, the functions in this list are called, | |
379 in order of appearance, until one of them returns a non-@code{nil} | |
380 value. | |
381 | |
382 These functions are called with no arguments. They can access the | |
383 command-line argument under consideration through the variable | |
384 @code{argi}. The remaining arguments (not including the current one) | |
385 are in the variable @code{command-line-args-left}. | |
386 | |
387 When a function recognizes and processes the argument in @code{argi}, it | |
388 should return a non-@code{nil} value to say it has dealt with that | |
389 argument. If it has also dealt with some of the following arguments, it | |
390 can indicate that by deleting them from @code{command-line-args-left}. | |
391 | |
392 If all of these functions return @code{nil}, then the argument is used | |
393 as a file name to visit. | |
394 @end defvar | |
395 | |
396 @node Getting Out | |
397 @section Getting out of XEmacs | |
398 @cindex exiting XEmacs | |
399 | |
400 There are two ways to get out of XEmacs: you can kill the XEmacs job, | |
401 which exits permanently, or you can suspend it, which permits you to | |
402 reenter the XEmacs process later. As a practical matter, you seldom kill | |
403 XEmacs---only when you are about to log out. Suspending is much more | |
404 common. | |
405 | |
406 @menu | |
407 * Killing XEmacs:: Exiting XEmacs irreversibly. | |
408 * Suspending XEmacs:: Exiting XEmacs reversibly. | |
409 @end menu | |
410 | |
411 @node Killing XEmacs | |
412 @subsection Killing XEmacs | |
413 @cindex killing XEmacs | |
414 | |
415 Killing XEmacs means ending the execution of the XEmacs process. The | |
416 parent process normally resumes control. The low-level primitive for | |
417 killing XEmacs is @code{kill-emacs}. | |
418 | |
444 | 419 @deffn Command kill-emacs &optional exit-data |
428 | 420 This function exits the XEmacs process and kills it. |
421 | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
422 If @var{exit-data} is a fixnum, then it is used as the exit status |
428 | 423 of the XEmacs process. (This is useful primarily in batch operation; see |
424 @ref{Batch Mode}.) | |
425 | |
426 If @var{exit-data} is a string, its contents are stuffed into the | |
427 terminal input buffer so that the shell (or whatever program next reads | |
428 input) can read them. | |
444 | 429 @end deffn |
428 | 430 |
431 All the information in the XEmacs process, aside from files that have | |
432 been saved, is lost when the XEmacs is killed. Because killing XEmacs | |
433 inadvertently can lose a lot of work, XEmacs queries for confirmation | |
434 before actually terminating if you have buffers that need saving or | |
435 subprocesses that are running. This is done in the function | |
436 @code{save-buffers-kill-emacs}. | |
437 | |
438 @defvar kill-emacs-query-functions | |
439 After asking the standard questions, @code{save-buffers-kill-emacs} | |
440 calls the functions in the list @code{kill-buffer-query-functions}, in | |
441 order of appearance, with no arguments. These functions can ask for | |
442 additional confirmation from the user. If any of them returns | |
443 non-@code{nil}, XEmacs is not killed. | |
444 @end defvar | |
445 | |
446 @defvar kill-emacs-hook | |
447 This variable is a normal hook; once @code{save-buffers-kill-emacs} is | |
448 finished with all file saving and confirmation, it runs the functions in | |
449 this hook. | |
450 @end defvar | |
451 | |
452 @node Suspending XEmacs | |
453 @subsection Suspending XEmacs | |
454 @cindex suspending XEmacs | |
455 | |
456 @dfn{Suspending XEmacs} means stopping XEmacs temporarily and returning | |
457 control to its superior process, which is usually the shell. This | |
458 allows you to resume editing later in the same XEmacs process, with the | |
459 same buffers, the same kill ring, the same undo history, and so on. To | |
460 resume XEmacs, use the appropriate command in the parent shell---most | |
461 likely @code{fg}. | |
462 | |
463 Some operating systems do not support suspension of jobs; on these | |
464 systems, ``suspension'' actually creates a new shell temporarily as a | |
465 subprocess of XEmacs. Then you would exit the shell to return to XEmacs. | |
466 | |
467 Suspension is not useful with window systems such as X, because the | |
468 XEmacs job may not have a parent that can resume it again, and in any | |
469 case you can give input to some other job such as a shell merely by | |
470 moving to a different window. Therefore, suspending is not allowed | |
471 when XEmacs is an X client. | |
472 | |
444 | 473 @deffn Command suspend-emacs &optional stuffstring |
428 | 474 This function stops XEmacs and returns control to the superior process. |
475 If and when the superior process resumes XEmacs, @code{suspend-emacs} | |
476 returns @code{nil} to its caller in Lisp. | |
477 | |
444 | 478 If optional arg @var{stuffstring} is non-@code{nil}, its characters are |
479 sent to be read as terminal input by XEmacs's superior shell. The | |
480 characters in @var{stuffstring} are not echoed by the superior shell; | |
481 only the results appear. | |
428 | 482 |
483 Before suspending, @code{suspend-emacs} runs the normal hook | |
484 @code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a | |
485 normal hook; its value was a single function, and if its value was | |
486 non-@code{nil}, then @code{suspend-emacs} returned immediately without | |
487 actually suspending anything. | |
488 | |
489 After the user resumes XEmacs, @code{suspend-emacs} runs the normal hook | |
490 @code{suspend-resume-hook}. @xref{Hooks}. | |
491 | |
492 The next redisplay after resumption will redraw the entire screen, | |
493 unless the variable @code{no-redraw-on-reenter} is non-@code{nil} | |
494 (@pxref{Refresh Screen}). | |
495 | |
496 In the following example, note that @samp{pwd} is not echoed after | |
497 XEmacs is suspended. But it is read and executed by the shell. | |
498 | |
499 @smallexample | |
500 @group | |
501 (suspend-emacs) | |
502 @result{} nil | |
503 @end group | |
504 | |
505 @group | |
506 (add-hook 'suspend-hook | |
507 (function (lambda () | |
508 (or (y-or-n-p | |
509 "Really suspend? ") | |
510 (error "Suspend cancelled"))))) | |
511 @result{} (lambda nil | |
512 (or (y-or-n-p "Really suspend? ") | |
513 (error "Suspend cancelled"))) | |
514 @end group | |
515 @group | |
516 (add-hook 'suspend-resume-hook | |
517 (function (lambda () (message "Resumed!")))) | |
518 @result{} (lambda nil (message "Resumed!")) | |
519 @end group | |
520 @group | |
521 (suspend-emacs "pwd") | |
522 @result{} nil | |
523 @end group | |
524 @group | |
525 ---------- Buffer: Minibuffer ---------- | |
526 Really suspend? @kbd{y} | |
527 ---------- Buffer: Minibuffer ---------- | |
528 @end group | |
529 | |
530 @group | |
531 ---------- Parent Shell ---------- | |
532 lewis@@slug[23] % /user/lewis/manual | |
533 lewis@@slug[24] % fg | |
534 @end group | |
535 | |
536 @group | |
537 ---------- Echo Area ---------- | |
538 Resumed! | |
539 @end group | |
540 @end smallexample | |
444 | 541 @end deffn |
428 | 542 |
543 @defvar suspend-hook | |
544 This variable is a normal hook run before suspending. | |
545 @end defvar | |
546 | |
547 @defvar suspend-resume-hook | |
548 This variable is a normal hook run after suspending. | |
549 @end defvar | |
550 | |
551 @node System Environment | |
552 @section Operating System Environment | |
553 @cindex operating system environment | |
554 | |
555 XEmacs provides access to variables in the operating system environment | |
556 through various functions. These variables include the name of the | |
557 system, the user's @sc{uid}, and so on. | |
558 | |
559 @defvar system-type | |
560 The value of this variable is a symbol indicating the type of operating | |
561 system XEmacs is operating on. Here is a table of the possible values: | |
562 | |
563 @table @code | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
564 @item aix |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
565 AIX 4.2 or later. |
428 | 566 |
567 @item berkeley-unix | |
568 Berkeley BSD. | |
569 | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
570 @item cygwin32 |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
571 Cygwin. |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
572 |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
573 @item darwin |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
574 Mac OS X. |
428 | 575 |
576 @item gnu | |
577 A GNU system using the GNU HURD and Mach. | |
578 | |
579 @item hpux | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
580 Hewlett-Packard HPUX operating system, version 11.0 or later. |
428 | 581 |
582 @item irix | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
583 Silicon Graphics Irix system, version 6.0 or later. |
428 | 584 |
585 @item linux | |
586 A GNU system using the Linux kernel. | |
587 | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
588 @item mach |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
589 The Mach kernel with a BSD 4.3 layer. |
428 | 590 |
591 @item usg-unix-v | |
592 AT&T System V. | |
593 | |
594 @item windows-nt | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
595 Microsoft windows NT or one of its descendants. |
428 | 596 @end table |
597 | |
598 We do not wish to add new symbols to make finer distinctions unless it | |
599 is absolutely necessary! In fact, we hope to eliminate some of these | |
600 alternatives in the future. We recommend using | |
601 @code{system-configuration} to distinguish between different operating | |
602 systems. | |
603 @end defvar | |
604 | |
605 @defvar system-configuration | |
606 This variable holds the three-part configuration name for the | |
607 hardware/software configuration of your system, as a string. The | |
608 convenient way to test parts of this string is with @code{string-match}. | |
609 @end defvar | |
610 | |
611 @defun system-name | |
612 This function returns the name of the machine you are running on. | |
613 @example | |
614 (system-name) | |
615 @result{} "prep.ai.mit.edu" | |
616 @end example | |
617 @end defun | |
618 | |
619 @vindex system-name | |
620 The symbol @code{system-name} is a variable as well as a function. In | |
621 fact, the function returns whatever value the variable | |
622 @code{system-name} currently holds. Thus, you can set the variable | |
623 @code{system-name} in case Emacs is confused about the name of your | |
624 system. The variable is also useful for constructing frame titles | |
625 (@pxref{Frame Titles}). | |
626 | |
627 @defvar mail-host-address | |
628 If this variable is non-@code{nil}, it is used instead of | |
629 @code{system-name} for purposes of generating email addresses. For | |
630 example, it is used when constructing the default value of | |
631 @code{user-mail-address}. @xref{User Identification}. (Since this is | |
632 done when XEmacs starts up, the value actually used is the one saved when | |
633 XEmacs was dumped. @xref{Building XEmacs}.) | |
634 @end defvar | |
635 | |
444 | 636 @deffn Command getenv var &optional interactivep |
428 | 637 @cindex environment variable access |
638 This function returns the value of the environment variable @var{var}, | |
639 as a string. Within XEmacs, the environment variable values are kept in | |
640 the Lisp variable @code{process-environment}. | |
641 | |
444 | 642 When invoked interactively, @code{getenv} prints the value in the echo area. |
643 | |
428 | 644 @example |
645 @group | |
646 (getenv "USER") | |
647 @result{} "lewis" | |
648 @end group | |
649 | |
650 @group | |
651 lewis@@slug[10] % printenv | |
652 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin | |
653 USER=lewis | |
654 @end group | |
655 @group | |
656 TERM=ibmapa16 | |
657 SHELL=/bin/csh | |
658 HOME=/user/lewis | |
659 @end group | |
660 @end example | |
444 | 661 @end deffn |
428 | 662 |
444 | 663 @deffn Command setenv variable &optional value unset |
428 | 664 This command sets the value of the environment variable named |
665 @var{variable} to @var{value}. Both arguments should be strings. This | |
666 function works by modifying @code{process-environment}; binding that | |
667 variable with @code{let} is also reasonable practice. | |
668 @end deffn | |
669 | |
670 @defvar process-environment | |
671 This variable is a list of strings, each describing one environment | |
444 | 672 variable. The functions @code{getenv} and @code{setenv} work by |
673 manipulating this variable. | |
428 | 674 |
675 @smallexample | |
676 @group | |
677 process-environment | |
678 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp" | |
679 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" | |
444 | 680 "USER=lewis" |
428 | 681 @end group |
682 @group | |
444 | 683 "TERM=ibmapa16" |
428 | 684 "SHELL=/bin/csh" |
685 "HOME=/user/lewis") | |
686 @end group | |
687 @end smallexample | |
688 @end defvar | |
689 | |
690 @defvar path-separator | |
691 This variable holds a string which says which character separates | |
692 directories in a search path (as found in an environment variable). Its | |
693 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS | |
694 and Windows NT. | |
695 @end defvar | |
696 | |
697 @defvar invocation-name | |
698 This variable holds the program name under which Emacs was invoked. The | |
699 value is a string, and does not include a directory name. | |
700 @end defvar | |
701 | |
702 @defvar invocation-directory | |
703 This variable holds the directory from which the Emacs executable was | |
704 invoked, or perhaps @code{nil} if that directory cannot be determined. | |
705 @end defvar | |
706 | |
707 @defvar installation-directory | |
708 If non-@code{nil}, this is a directory within which to look for the | |
709 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} | |
710 when Emacs can't find those directories in their standard installed | |
711 locations, but can find them in a directory related somehow to the one | |
712 containing the Emacs executable. | |
713 @end defvar | |
714 | |
715 @defun load-average &optional use-floats | |
716 This function returns a list of the current 1-minute, 5-minute and | |
717 15-minute load averages. The values are integers that are 100 times the | |
718 system load averages. (The load averages indicate the number of | |
719 processes trying to run.) | |
720 | |
444 | 721 When @var{use-floats} is non-@code{nil}, floats will be returned instead |
428 | 722 of integers. These floats are not multiplied by 100. |
723 | |
724 @example | |
725 @group | |
726 (load-average) | |
727 @result{} (169 158 164) | |
728 (load-average t) | |
729 @result{} (1.69921875 1.58984375 1.640625) | |
730 @end group | |
731 | |
732 @group | |
733 lewis@@rocky[5] % uptime | |
734 8:06pm up 16 day(s), 21:57, 40 users, | |
735 load average: 1.68, 1.59, 1.64 | |
736 @end group | |
737 @end example | |
738 | |
739 If the 5-minute or 15-minute load averages are not available, return a | |
740 shortened list, containing only those averages which are available. | |
741 | |
444 | 742 On some systems, this function may require special privileges to run, or |
428 | 743 it may be unimplemented for the particular system type. In that case, |
744 the function will signal an error. | |
745 @end defun | |
746 | |
747 @defun emacs-pid | |
748 This function returns the process @sc{id} of the Emacs process. | |
749 @end defun | |
750 | |
751 @node User Identification | |
752 @section User Identification | |
753 | |
754 @defvar user-mail-address | |
755 This holds the nominal email address of the user who is using Emacs. | |
756 When Emacs starts up, it computes a default value that is usually right, | |
757 but users often set this themselves when the default value is not right. | |
758 @end defvar | |
759 | |
760 @defun user-login-name &optional uid | |
761 If you don't specify @var{uid}, this function returns the name under | |
762 which the user is logged in. If the environment variable @code{LOGNAME} | |
763 is set, that value is used. Otherwise, if the environment variable | |
764 @code{USER} is set, that value is used. Otherwise, the value is based | |
765 on the effective @sc{uid}, not the real @sc{uid}. | |
766 | |
767 If you specify @var{uid}, the value is the user name that corresponds | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
768 to @var{uid} (which should be a fixnum). |
428 | 769 |
770 @example | |
771 @group | |
772 (user-login-name) | |
773 @result{} "lewis" | |
774 @end group | |
775 @end example | |
776 @end defun | |
777 | |
778 @defun user-real-login-name | |
779 This function returns the user name corresponding to Emacs's real | |
780 @sc{uid}. This ignores the effective @sc{uid} and ignores the | |
781 environment variables @code{LOGNAME} and @code{USER}. | |
782 @end defun | |
783 | |
784 @defvar user-full-name | |
785 This variable holds the name of the user running this Emacs. It is | |
786 initialized at startup time from the value of @code{NAME} environment | |
444 | 787 variable. You can change the value of this variable to alter the result |
428 | 788 of the @code{user-full-name} function. |
789 @end defvar | |
790 | |
791 @defun user-full-name &optional user | |
792 This function returns the full name of @var{user}. If @var{user} is | |
793 @code{nil}, it defaults to the user running this Emacs. In that case, | |
794 the value of @code{user-full-name} variable, if non-@code{nil}, will be | |
795 used. | |
796 | |
444 | 797 If @var{user} is specified explicitly, @code{user-full-name} variable is |
428 | 798 ignored. |
799 | |
800 @example | |
801 @group | |
802 (user-full-name) | |
803 @result{} "Hrvoje Niksic" | |
804 (setq user-full-name "Hrvoje \"Niksa\" Niksic") | |
805 (user-full-name) | |
806 @result{} "Hrvoje \"Niksa\" Niksic" | |
807 (user-full-name "hniksic") | |
808 @result{} "Hrvoje Niksic" | |
809 @end group | |
810 @end example | |
811 @end defun | |
812 | |
813 @vindex user-full-name | |
814 @vindex user-real-login-name | |
815 @vindex user-login-name | |
816 The symbols @code{user-login-name}, @code{user-real-login-name} and | |
817 @code{user-full-name} are variables as well as functions. The functions | |
818 return the same values that the variables hold. These variables allow | |
819 you to ``fake out'' Emacs by telling the functions what to return. The | |
820 variables are also useful for constructing frame titles (@pxref{Frame | |
821 Titles}). | |
822 | |
823 @defun user-real-uid | |
824 This function returns the real @sc{uid} of the user. | |
825 | |
826 @example | |
827 @group | |
828 (user-real-uid) | |
829 @result{} 19 | |
830 @end group | |
831 @end example | |
832 @end defun | |
833 | |
834 @defun user-uid | |
444 | 835 This function returns the effective @sc{uid} of the user. |
428 | 836 @end defun |
837 | |
838 @defun user-home-directory | |
839 This function returns the ``@code{HOME}'' directory of the user, and is | |
840 intended to replace occurrences of ``@code{(getenv "HOME")}''. Under | |
841 Unix systems, the following is done: | |
842 | |
843 @enumerate | |
844 @item | |
845 Return the value of ``@code{(getenv "HOME")}'', if set. | |
846 | |
847 @item | |
848 Return ``/'', as a fallback, but issue a warning. (Future versions of | |
849 XEmacs will also attempt to lookup the @code{HOME} directory via | |
850 @code{getpwent()}, but this has not yet been implemented.) | |
851 @end enumerate | |
852 | |
853 Under MS Windows, this is done: | |
854 | |
855 @enumerate | |
856 @item | |
857 Return the value of ``@code{(getenv "HOME")}'', if set. | |
858 | |
859 @item | |
3772 | 860 If the environment variables @code{HOMEDRIVE} and @code{HOMEPATH} are |
428 | 861 both set, return the concatenation (the following description uses MS |
862 Windows environment variable substitution syntax): | |
3772 | 863 @code{%HOMEDRIVE%%HOMEPATH%}. |
428 | 864 |
865 @item | |
866 Return ``C:\'', as a fallback, but issue a warning. | |
867 @end enumerate | |
868 @end defun | |
869 | |
870 @node Time of Day | |
871 @section Time of Day | |
872 | |
873 This section explains how to determine the current time and the time | |
874 zone. | |
875 | |
876 @defun current-time-string &optional time-value | |
877 This function returns the current time and date as a humanly-readable | |
878 string. The format of the string is unvarying; the number of characters | |
879 used for each part is always the same, so you can reliably use | |
880 @code{substring} to extract pieces of it. It is wise to count the | |
881 characters from the beginning of the string rather than from the end, as | |
882 additional information may be added at the end. | |
883 | |
884 @c Emacs 19 feature | |
885 The argument @var{time-value}, if given, specifies a time to format | |
886 instead of the current time. The argument should be a list whose first | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
887 two elements are fixnums. Thus, you can use times obtained from |
428 | 888 @code{current-time} (see below) and from @code{file-attributes} |
889 (@pxref{File Attributes}). | |
890 | |
891 @example | |
892 @group | |
893 (current-time-string) | |
894 @result{} "Wed Oct 14 22:21:05 1987" | |
895 @end group | |
896 @end example | |
897 @end defun | |
898 | |
899 @c Emacs 19 feature | |
900 @defun current-time | |
901 This function returns the system's time value as a list of three | |
902 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers | |
903 @var{high} and @var{low} combine to give the number of seconds since | |
904 0:00 January 1, 1970, which is | |
905 @ifinfo | |
906 @var{high} * 2**16 + @var{low}. | |
907 @end ifinfo | |
908 @tex | |
909 $high*2^{16}+low$. | |
910 @end tex | |
911 | |
912 The third element, @var{microsec}, gives the microseconds since the | |
913 start of the current second (or 0 for systems that return time only on | |
914 the resolution of a second). | |
915 | |
916 The first two elements can be compared with file time values such as you | |
917 get with the function @code{file-attributes}. @xref{File Attributes}. | |
918 @end defun | |
919 | |
920 @c Emacs 19 feature | |
921 @defun current-time-zone &optional time-value | |
922 This function returns a list describing the time zone that the user is | |
923 in. | |
924 | |
925 The value has the form @code{(@var{offset} @var{name})}. Here | |
926 @var{offset} is an integer giving the number of seconds ahead of UTC | |
927 (east of Greenwich). A negative value means west of Greenwich. The | |
928 second element, @var{name} is a string giving the name of the time | |
929 zone. Both elements change when daylight savings time begins or ends; | |
930 if the user has specified a time zone that does not use a seasonal time | |
931 adjustment, then the value is constant through time. | |
932 | |
933 If the operating system doesn't supply all the information necessary to | |
934 compute the value, both elements of the list are @code{nil}. | |
935 | |
936 The argument @var{time-value}, if given, specifies a time to analyze | |
937 instead of the current time. The argument should be a cons cell | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
938 containing two fixnums, or a list whose first two elements are |
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
939 fixnums. Thus, you can use times obtained from @code{current-time} |
428 | 940 (see above) and from @code{file-attributes} (@pxref{File Attributes}). |
941 @end defun | |
942 | |
943 @node Time Conversion | |
944 @section Time Conversion | |
945 | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
946 These functions convert time values (lists of two or three fixnums) |
428 | 947 to strings or to calendrical information. There is also a function to |
948 convert calendrical information to a time value. You can get time | |
949 values from the functions @code{current-time} (@pxref{Time of Day}) and | |
950 @code{file-attributes} (@pxref{File Attributes}). | |
951 | |
952 @defun format-time-string format-string &optional time | |
953 This function converts @var{time} to a string according to | |
954 @var{format-string}. If @var{time} is omitted, it defaults to the | |
955 current time. The argument @var{format-string} may contain | |
956 @samp{%}-sequences which say to substitute parts of the time. Here is a | |
957 table of what the @samp{%}-sequences mean: | |
958 | |
959 @table @samp | |
960 @item %a | |
961 This stands for the abbreviated name of the day of week. | |
962 @item %A | |
963 This stands for the full name of the day of week. | |
964 @item %b | |
965 This stands for the abbreviated name of the month. | |
966 @item %B | |
967 This stands for the full name of the month. | |
968 @item %c | |
969 This is a synonym for @samp{%x %X}. | |
970 @item %C | |
971 This has a locale-specific meaning. In the default locale (named C), it | |
972 is equivalent to @samp{%A, %B %e, %Y}. | |
973 @item %d | |
974 This stands for the day of month, zero-padded. | |
975 @item %D | |
976 This is a synonym for @samp{%m/%d/%y}. | |
977 @item %e | |
978 This stands for the day of month, blank-padded. | |
979 @item %h | |
980 This is a synonym for @samp{%b}. | |
981 @item %H | |
982 This stands for the hour (00-23). | |
983 @item %I | |
984 This stands for the hour (00-12). | |
985 @item %j | |
986 This stands for the day of the year (001-366). | |
987 @item %k | |
988 This stands for the hour (0-23), blank padded. | |
989 @item %l | |
990 This stands for the hour (1-12), blank padded. | |
991 @item %m | |
992 This stands for the month (01-12). | |
993 @item %M | |
994 This stands for the minute (00-59). | |
995 @item %n | |
996 This stands for a newline. | |
997 @item %p | |
998 This stands for @samp{AM} or @samp{PM}, as appropriate. | |
999 @item %r | |
1000 This is a synonym for @samp{%I:%M:%S %p}. | |
1001 @item %R | |
1002 This is a synonym for @samp{%H:%M}. | |
1003 @item %S | |
1004 This stands for the seconds (00-60). | |
1005 @item %t | |
1006 This stands for a tab character. | |
1007 @item %T | |
1008 This is a synonym for @samp{%H:%M:%S}. | |
1009 @item %U | |
1010 This stands for the week of the year (01-52), assuming that weeks | |
1011 start on Sunday. | |
1012 @item %w | |
1013 This stands for the numeric day of week (0-6). Sunday is day 0. | |
1014 @item %W | |
1015 This stands for the week of the year (01-52), assuming that weeks | |
1016 start on Monday. | |
1017 @item %x | |
1018 This has a locale-specific meaning. In the default locale (named C), it | |
1019 is equivalent to @samp{%D}. | |
1020 @item %X | |
1021 This has a locale-specific meaning. In the default locale (named C), it | |
1022 is equivalent to @samp{%T}. | |
1023 @item %y | |
1024 This stands for the year without century (00-99). | |
1025 @item %Y | |
1026 This stands for the year with century. | |
1027 @item %Z | |
1028 This stands for the time zone abbreviation. | |
1029 @end table | |
1030 @end defun | |
1031 | |
444 | 1032 @defun decode-time &optional specified-time |
428 | 1033 This function converts a time value into calendrical information. The |
444 | 1034 optional @var{specified-time} should be a list of |
1035 (@var{high} @var{low} . @var{ignored}) or (@var{high} . @var{low}), as from | |
1036 @code{current-time} and @code{file-attributes}, or @code{nil} to use the | |
1037 current time. | |
1038 | |
1039 The return value is a list of nine elements, as follows: | |
428 | 1040 |
1041 @example | |
1042 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) | |
1043 @end example | |
1044 | |
1045 Here is what the elements mean: | |
1046 | |
1047 @table @var | |
1048 @item sec | |
1049 The number of seconds past the minute, as an integer between 0 and 59. | |
1050 @item minute | |
1051 The number of minutes past the hour, as an integer between 0 and 59. | |
1052 @item hour | |
1053 The hour of the day, as an integer between 0 and 23. | |
1054 @item day | |
1055 The day of the month, as an integer between 1 and 31. | |
1056 @item month | |
1057 The month of the year, as an integer between 1 and 12. | |
1058 @item year | |
1059 The year, an integer typically greater than 1900. | |
1060 @item dow | |
1061 The day of week, as an integer between 0 and 6, where 0 stands for | |
1062 Sunday. | |
1063 @item dst | |
1064 @code{t} if daylight savings time is effect, otherwise @code{nil}. | |
1065 @item zone | |
1066 An integer indicating the time zone, as the number of seconds east of | |
1067 Greenwich. | |
1068 @end table | |
1069 | |
1070 Note that Common Lisp has different meanings for @var{dow} and | |
1071 @var{zone}. | |
1072 @end defun | |
1073 | |
1074 @defun encode-time seconds minutes hour day month year &optional zone | |
1075 This function is the inverse of @code{decode-time}. It converts seven | |
1076 items of calendrical data into a time value. For the meanings of the | |
1077 arguments, see the table above under @code{decode-time}. | |
1078 | |
1079 Year numbers less than 100 are treated just like other year numbers. If | |
1080 you want them to stand for years above 1900, you must alter them yourself | |
1081 before you call @code{encode-time}. | |
1082 | |
1083 The optional argument @var{zone} defaults to the current time zone and | |
1084 its daylight savings time rules. If specified, it can be either a list | |
1085 (as you would get from @code{current-time-zone}) or an integer (as you | |
1086 would get from @code{decode-time}). The specified zone is used without | |
1087 any further alteration for daylight savings time. | |
1088 @end defun | |
1089 | |
1090 @node Timers | |
1091 @section Timers for Delayed Execution | |
1092 | |
1093 You can set up a timer to call a function at a specified future time. | |
1094 | |
1095 @c All different in FSF 19 | |
1096 @defun add-timeout secs function object &optional resignal | |
1097 This function adds a timeout, to be signaled after the timeout period | |
1098 has elapsed. @var{secs} is a number of seconds, expressed as an integer | |
1099 or a float. @var{function} will be called after that many seconds have | |
1100 elapsed, with one argument, the given @var{object}. If the optional | |
1101 @var{resignal} argument is provided, then after this timeout expires, | |
444 | 1102 @code{add-timeout} will automatically be called again with |
1103 @var{resignal} as the first argument. | |
428 | 1104 |
1105 This function returns an object which is the @dfn{id} of this particular | |
1106 timeout. You can pass that object to @code{disable-timeout} to turn off | |
1107 the timeout before it has been signalled. | |
1108 | |
1109 The number of seconds may be expressed as a floating-point number, in which | |
1110 case some fractional part of a second will be used. Caveat: the usable | |
1111 timeout granularity will vary from system to system. | |
1112 | |
1113 Adding a timeout causes a timeout event to be returned by | |
1114 @code{next-event}, and the function will be invoked by | |
1115 @code{dispatch-event}, so if XEmacs is in a tight loop, the function will | |
1116 not be invoked until the next call to sit-for or until the return to | |
1117 top-level (the same is true of process filters). | |
1118 | |
1119 WARNING: if you are thinking of calling add-timeout from inside of a | |
1120 callback function as a way of resignalling a timeout, think again. There | |
1121 is a race condition. That's why the @var{resignal} argument exists. | |
1122 | |
1123 (NOTE: In FSF Emacs, this function is called @code{run-at-time} and | |
1124 has different semantics.) | |
1125 @end defun | |
1126 | |
1127 @defun disable-timeout id | |
1128 Cancel the requested action for @var{id}, which should be a value | |
1129 previously returned by @code{add-timeout}. This cancels the effect of | |
1130 that call to @code{add-timeout}; the arrival of the specified time will | |
1131 not cause anything special to happen. | |
1132 (NOTE: In FSF Emacs, this function is called @code{cancel-timer}.) | |
1133 @end defun | |
1134 | |
1135 @node Terminal Input | |
1136 @section Terminal Input | |
1137 @cindex terminal input | |
1138 | |
1139 This section describes functions and variables for recording or | |
1140 manipulating terminal input. See @ref{Display}, for related | |
1141 functions. | |
1142 | |
1143 @menu | |
1144 * Input Modes:: Options for how input is processed. | |
1145 * Translating Input:: Low level conversion of some characters or events | |
1146 into others. | |
1147 * Recording Input:: Saving histories of recent or all input events. | |
1148 @end menu | |
1149 | |
1150 @node Input Modes | |
1151 @subsection Input Modes | |
1152 @cindex input modes | |
1153 @cindex terminal input modes | |
1154 | |
444 | 1155 @defun set-input-mode interrupt flow meta &optional quit-char console |
428 | 1156 This function sets the mode for reading keyboard input. If |
1157 @var{interrupt} is non-null, then XEmacs uses input interrupts. If it is | |
1158 @code{nil}, then it uses @sc{cbreak} mode. When XEmacs communicates | |
1159 directly with X, it ignores this argument and uses interrupts if that is | |
1160 the way it knows how to communicate. | |
1161 | |
1162 If @var{flow} is non-@code{nil}, then XEmacs uses @sc{xon/xoff} (@kbd{C-q}, | |
1163 @kbd{C-s}) flow control for output to the terminal. This has no effect except | |
1164 in @sc{cbreak} mode. @xref{Flow Control}. | |
1165 | |
1166 The default setting is system dependent. Some systems always use | |
1167 @sc{cbreak} mode regardless of what is specified. | |
1168 | |
1169 @c Emacs 19 feature | |
1170 The argument @var{meta} controls support for input character codes | |
1171 above 127. If @var{meta} is @code{t}, XEmacs converts characters with | |
1172 the 8th bit set into Meta characters. If @var{meta} is @code{nil}, | |
1173 XEmacs disregards the 8th bit; this is necessary when the terminal uses | |
1174 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, | |
1175 XEmacs uses all 8 bits of input unchanged. This is good for terminals | |
1176 using European 8-bit character sets. | |
1177 | |
1178 @c Emacs 19 feature | |
1179 If @var{quit-char} is non-@code{nil}, it specifies the character to | |
1180 use for quitting. Normally this character is @kbd{C-g}. | |
1181 @xref{Quitting}. | |
1182 @end defun | |
1183 | |
1184 The @code{current-input-mode} function returns the input mode settings | |
1185 XEmacs is currently using. | |
1186 | |
1187 @c Emacs 19 feature | |
444 | 1188 @defun current-input-mode &optional console |
428 | 1189 This function returns current mode for reading keyboard input. It |
1190 returns a list, corresponding to the arguments of @code{set-input-mode}, | |
1191 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in | |
1192 which: | |
1193 @table @var | |
1194 @item interrupt | |
1195 is non-@code{nil} when XEmacs is using interrupt-driven input. If | |
1196 @code{nil}, Emacs is using @sc{cbreak} mode. | |
1197 @item flow | |
1198 is non-@code{nil} if XEmacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) | |
1199 flow control for output to the terminal. This value has no effect | |
1200 unless @var{interrupt} is non-@code{nil}. | |
1201 @item meta | |
1202 is @code{t} if XEmacs treats the eighth bit of input characters as | |
1203 the meta bit; @code{nil} means XEmacs clears the eighth bit of every | |
1204 input character; any other value means XEmacs uses all eight bits as the | |
1205 basic character code. | |
1206 @item quit | |
1207 is the character XEmacs currently uses for quitting, usually @kbd{C-g}. | |
1208 @end table | |
1209 @end defun | |
1210 | |
1211 @node Translating Input | |
1212 @subsection Translating Input Events | |
1213 @cindex translating input events | |
1214 | |
1215 This section describes features for translating input events into other | |
1216 input events before they become part of key sequences. | |
1217 | |
1218 @ignore Not in XEmacs yet. | |
1219 @c Emacs 19 feature | |
1220 @defvar extra-keyboard-modifiers | |
1221 This variable lets Lisp programs ``press'' the modifier keys on the | |
1222 keyboard. The value is a bit mask: | |
1223 | |
1224 @table @asis | |
1225 @item 1 | |
1226 The @key{SHIFT} key. | |
1227 @item 2 | |
1228 The @key{LOCK} key. | |
1229 @item 4 | |
1230 The @key{CTL} key. | |
1231 @item 8 | |
1232 The @key{META} key. | |
1233 @end table | |
1234 | |
1235 Each time the user types a keyboard key, it is altered as if the | |
1236 modifier keys specified in the bit mask were held down. | |
1237 | |
1238 When using X windows, the program can ``press'' any of the modifier | |
1239 keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can | |
1240 be virtually pressed. | |
1241 @end defvar | |
1242 | |
1243 @defvar keyboard-translate-table | |
1244 This variable is the translate table for keyboard characters. It lets | |
1245 you reshuffle the keys on the keyboard without changing any command | |
1246 bindings. Its value must be a string or @code{nil}. | |
1247 | |
1248 If @code{keyboard-translate-table} is a string, then each character read | |
1249 from the keyboard is looked up in this string and the character in the | |
1250 string is used instead. If the string is of length @var{n}, character codes | |
1251 @var{n} and up are untranslated. | |
1252 | |
1253 In the example below, we set @code{keyboard-translate-table} to a | |
1254 string of 128 characters. Then we fill it in to swap the characters | |
1255 @kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. | |
1256 Subsequently, typing @kbd{C-\} has all the usual effects of typing | |
1257 @kbd{C-s}, and vice versa. (@xref{Flow Control} for more information on | |
1258 this subject.) | |
1259 | |
1260 @cindex flow control example | |
1261 @example | |
1262 @group | |
1263 (defun evade-flow-control () | |
1264 "Replace C-s with C-\ and C-q with C-^." | |
1265 (interactive) | |
1266 @end group | |
1267 @group | |
1268 (let ((the-table (make-string 128 0))) | |
1269 (let ((i 0)) | |
1270 (while (< i 128) | |
1271 (aset the-table i i) | |
1272 (setq i (1+ i)))) | |
1273 @end group | |
1274 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.} | |
1275 (aset the-table ?\034 ?\^s) | |
1276 (aset the-table ?\^s ?\034) | |
1277 @group | |
1278 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.} | |
1279 (aset the-table ?\036 ?\^q) | |
1280 (aset the-table ?\^q ?\036) | |
1281 (setq keyboard-translate-table the-table))) | |
1282 @end group | |
1283 @end example | |
1284 | |
1285 Note that this translation is the first thing that happens to a | |
1286 character after it is read from the terminal. Record-keeping features | |
1287 such as @code{recent-keys} and dribble files record the characters after | |
1288 translation. | |
1289 @end defvar | |
1290 | |
444 | 1291 @defun keyboard-translate &rest pairs |
428 | 1292 This function modifies @code{keyboard-translate-table} to translate |
1293 character code @var{from} into character code @var{to}. It creates | |
444 | 1294 or enlarges the translate table if necessary. Multiple |
1295 @var{from}-@var{to} pairs may be specified. | |
428 | 1296 @end defun |
1297 @end ignore | |
1298 | |
1299 @defvar function-key-map | |
1300 This variable holds a keymap that describes the character sequences | |
1301 sent by function keys on an ordinary character terminal. This keymap | |
1302 uses the same data structure as other keymaps, but is used differently: it | |
1303 specifies translations to make while reading events. | |
1304 | |
1305 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector | |
1306 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a | |
1307 key sequence, it is replaced with the events in @var{v}. | |
1308 | |
1309 For example, VT100 terminals send @kbd{@key{ESC} O P} when the | |
1310 keypad PF1 key is pressed. Therefore, we want XEmacs to translate | |
1311 that sequence of events into the single event @code{pf1}. We accomplish | |
1312 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in | |
1313 @code{function-key-map}, when using a VT100. | |
1314 | |
1315 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c | |
1316 @key{ESC} O P}; later the function @code{read-key-sequence} translates | |
1317 this back into @kbd{C-c @key{PF1}}, which it returns as the vector | |
1318 @code{[?\C-c pf1]}. | |
1319 | |
1320 Entries in @code{function-key-map} are ignored if they conflict with | |
1321 bindings made in the minor mode, local, or global keymaps. The intent | |
1322 is that the character sequences that function keys send should not have | |
1323 command bindings in their own right. | |
1324 | |
1325 The value of @code{function-key-map} is usually set up automatically | |
1326 according to the terminal's Terminfo or Termcap entry, but sometimes | |
1327 those need help from terminal-specific Lisp files. XEmacs comes with | |
1328 terminal-specific files for many common terminals; their main purpose is | |
1329 to make entries in @code{function-key-map} beyond those that can be | |
1330 deduced from Termcap and Terminfo. @xref{Terminal-Specific}. | |
1331 | |
1332 Emacs versions 18 and earlier used totally different means of detecting | |
1333 the character sequences that represent function keys. | |
1334 @end defvar | |
1335 | |
1336 @defvar key-translation-map | |
1337 This variable is another keymap used just like @code{function-key-map} | |
1338 to translate input events into other events. It differs from | |
1339 @code{function-key-map} in two ways: | |
1340 | |
1341 @itemize @bullet | |
1342 @item | |
1343 @code{key-translation-map} goes to work after @code{function-key-map} is | |
1344 finished; it receives the results of translation by | |
1345 @code{function-key-map}. | |
1346 | |
1347 @item | |
1348 @code{key-translation-map} overrides actual key bindings. | |
1349 @end itemize | |
1350 | |
1351 The intent of @code{key-translation-map} is for users to map one | |
1352 character set to another, including ordinary characters normally bound | |
1353 to @code{self-insert-command}. | |
1354 @end defvar | |
1355 | |
1356 @cindex key translation function | |
1357 You can use @code{function-key-map} or @code{key-translation-map} for | |
1358 more than simple aliases, by using a function, instead of a key | |
1359 sequence, as the ``translation'' of a key. Then this function is called | |
1360 to compute the translation of that key. | |
1361 | |
1362 The key translation function receives one argument, which is the prompt | |
1363 that was specified in @code{read-key-sequence}---or @code{nil} if the | |
1364 key sequence is being read by the editor command loop. In most cases | |
1365 you can ignore the prompt value. | |
1366 | |
1367 If the function reads input itself, it can have the effect of altering | |
1368 the event that follows. For example, here's how to define @kbd{C-c h} | |
1369 to turn the character that follows into a Hyper character: | |
1370 | |
1371 @example | |
1372 @group | |
1373 (defun hyperify (prompt) | |
1374 (let ((e (read-event))) | |
1375 (vector (if (numberp e) | |
1376 (logior (lsh 1 20) e) | |
1377 (if (memq 'hyper (event-modifiers e)) | |
1378 e | |
1379 (add-event-modifier "H-" e)))))) | |
1380 | |
1381 (defun add-event-modifier (string e) | |
1382 (let ((symbol (if (symbolp e) e (car e)))) | |
1383 (setq symbol (intern (concat string | |
1384 (symbol-name symbol)))) | |
1385 @end group | |
1386 @group | |
1387 (if (symbolp e) | |
1388 symbol | |
1389 (cons symbol (cdr e))))) | |
1390 | |
1391 (define-key function-key-map "\C-ch" 'hyperify) | |
1392 @end group | |
1393 @end example | |
1394 | |
1395 @pindex iso-transl | |
1396 @cindex Latin-1 character set (input) | |
1397 @cindex ISO Latin-1 characters (input) | |
1398 The @file{iso-transl} library uses this feature to provide a way of | |
1399 inputting non-ASCII Latin-1 characters. | |
1400 | |
1401 @node Recording Input | |
1402 @subsection Recording Input | |
1403 | |
1404 @defun recent-keys &optional number | |
1405 This function returns a vector containing recent input events from the | |
1406 keyboard or mouse. By default, 100 events are recorded, which is how | |
1407 many @code{recent-keys} returns. | |
1408 | |
1409 All input events are included, whether or not they were used as parts of | |
1410 key sequences. Thus, you always get the last 100 inputs, not counting | |
1411 keyboard macros. (Events from keyboard macros are excluded because they | |
1412 are less interesting for debugging; it should be enough to see the | |
1413 events that invoked the macros.) | |
1414 | |
1415 If @var{number} is specified, not more than @var{number} events will be | |
1416 returned. You may change the number of stored events using | |
1417 @code{set-recent-keys-ring-size}. | |
1418 @end defun | |
1419 | |
1420 @defun recent-keys-ring-size | |
1421 This function returns the number of recent events stored internally. | |
1422 This is also the maximum number of events @code{recent-keys} can | |
1423 return. By default, 100 events are stored. | |
1424 @end defun | |
1425 | |
1426 @defun set-recent-keys-ring-size size | |
444 | 1427 This function changes the number of events stored by XEmacs and returned |
428 | 1428 by @code{recent-keys}. |
1429 | |
1430 For example, @code{(set-recent-keys-ring-size 250)} will make XEmacs | |
1431 remember last 250 events and will make @code{recent-keys} return last | |
1432 250 events by default. | |
1433 @end defun | |
1434 | |
444 | 1435 @deffn Command open-dribble-file filename |
428 | 1436 @cindex dribble file |
1437 This function opens a @dfn{dribble file} named @var{filename}. When a | |
1438 dribble file is open, each input event from the keyboard or mouse (but | |
1439 not those from keyboard macros) is written in that file. A | |
1440 non-character event is expressed using its printed representation | |
1441 surrounded by @samp{<@dots{}>}. | |
1442 | |
1443 You close the dribble file by calling this function with an argument | |
1444 of @code{nil}. | |
1445 | |
1446 This function is normally used to record the input necessary to | |
1447 trigger an XEmacs bug, for the sake of a bug report. | |
1448 | |
1449 @example | |
1450 @group | |
1451 (open-dribble-file "~/dribble") | |
1452 @result{} nil | |
1453 @end group | |
1454 @end example | |
1455 @end deffn | |
1456 | |
1457 See also the @code{open-termscript} function (@pxref{Terminal Output}). | |
1458 | |
1459 @node Terminal Output | |
1460 @section Terminal Output | |
1461 @cindex terminal output | |
1462 | |
1463 The terminal output functions send output to the terminal or keep | |
1464 track of output sent to the terminal. The function | |
1465 @code{device-baud-rate} tells you what XEmacs thinks is the output speed | |
1466 of the terminal. | |
1467 | |
1468 @defun device-baud-rate &optional device | |
1469 This function's value is the output speed of the terminal associated | |
1470 with @var{device}, as far as XEmacs knows. @var{device} defaults to the | |
1471 selected device (usually the only device) if omitted. Changing this | |
1472 value does not change the speed of actual data transmission, but the | |
1473 value is used for calculations such as padding. This value has no | |
1474 effect for window-system devices. (This is different in FSF Emacs, where | |
1475 the baud rate also affects decisions about whether to scroll part of the | |
1476 screen or repaint, even when using a window system.) | |
1477 | |
1478 The value is measured in bits per second. | |
1479 @end defun | |
1480 | |
1481 XEmacs attempts to automatically initialize the baud rate by querying | |
1482 the terminal. If you are running across a network, however, and | |
1483 different parts of the network work are at different baud rates, the | |
1484 value returned by XEmacs may be different from the value used by your | |
1485 local terminal. Some network protocols communicate the local terminal | |
1486 speed to the remote machine, so that XEmacs and other programs can get | |
1487 the proper value, but others do not. If XEmacs has the wrong value, it | |
1488 makes decisions that are less than optimal. To fix the problem, use | |
1489 @code{set-device-baud-rate}. | |
1490 | |
444 | 1491 @defun set-device-baud-rate device baud-rate |
428 | 1492 This function sets the output speed of @var{device}. See |
1493 @code{device-baud-rate}. @var{device} defaults to the selected device | |
444 | 1494 (usually the only device) if @code{nil}. |
428 | 1495 @end defun |
1496 | |
1497 @defun send-string-to-terminal char-or-string &optional stdout-p device | |
1498 This function sends @var{char-or-string} to the terminal without | |
1499 alteration. Control characters in @var{char-or-string} have | |
1500 terminal-dependent effects. | |
1501 | |
1502 If @var{device} is @code{nil}, this function writes to XEmacs's | |
1503 stderr, or to stdout if @var{stdout-p} is non-@code{nil}. Otherwise, | |
1504 @var{device} should be a tty or stream device, and the function writes | |
1505 to the device's normal or error output, according to @var{stdout-p}. | |
1506 | |
1507 One use of this function is to define function keys on terminals that | |
1508 have downloadable function key definitions. For example, this is how on | |
1509 certain terminals to define function key 4 to move forward four | |
1510 characters (by transmitting the characters @kbd{C-u C-f} to the | |
1511 computer): | |
1512 | |
1513 @example | |
1514 @group | |
1515 (send-string-to-terminal "\eF4\^U\^F") | |
1516 @result{} nil | |
1517 @end group | |
1518 @end example | |
1519 @end defun | |
1520 | |
1521 @deffn Command open-termscript filename | |
1522 @cindex termscript file | |
1523 This function is used to open a @dfn{termscript file} that will record | |
1524 all the characters sent by XEmacs to the terminal. (If there are | |
1525 multiple tty or stream devices, all characters sent to all such devices | |
1526 are recorded.) The function returns @code{nil}. Termscript files are | |
1527 useful for investigating problems where XEmacs garbles the screen, | |
1528 problems that are due to incorrect Termcap entries or to undesirable | |
1529 settings of terminal options more often than to actual XEmacs bugs. | |
1530 Once you are certain which characters were actually output, you can | |
1531 determine reliably whether they correspond to the Termcap specifications | |
1532 in use. | |
1533 | |
1534 A @code{nil} value for @var{filename} stops recording terminal output. | |
1535 | |
1536 See also @code{open-dribble-file} in @ref{Terminal Input}. | |
1537 | |
1538 @example | |
1539 @group | |
1540 (open-termscript "../junk/termscript") | |
1541 @result{} nil | |
1542 @end group | |
1543 @end example | |
1544 @end deffn | |
1545 | |
1546 @ignore Not in XEmacs | |
1547 @node Special Keysyms | |
1548 @section System-Specific X11 Keysyms | |
1549 | |
1550 To define system-specific X11 keysyms, set the variable | |
1551 @code{system-key-alist}. | |
1552 | |
1553 @defvar system-key-alist | |
1554 This variable's value should be an alist with one element for each | |
1555 system-specific keysym. An element has this form: @code{(@var{code} | |
1556 . @var{symbol})}, where @var{code} is the numeric keysym code (not | |
1557 including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the | |
1558 name for the function key. | |
1559 | |
1560 For example @code{(168 . mute-acute)} defines a system-specific key used | |
1561 by HP X servers whose numeric code is (1 << 28) + 168. | |
1562 | |
1563 It is not a problem if the alist defines keysyms for other X servers, as | |
1564 long as they don't conflict with the ones used by the X server actually | |
1565 in use. | |
1566 | |
1567 The variable is always local to the current X terminal and cannot be | |
1568 buffer-local. @xref{Multiple Displays}. | |
1569 @end defvar | |
1570 @end ignore | |
1571 | |
1572 @node Flow Control | |
1573 @section Flow Control | |
1574 @cindex flow control characters | |
1575 | |
1576 This section attempts to answer the question ``Why does XEmacs choose | |
1577 to use flow-control characters in its command character set?'' For a | |
1578 second view on this issue, read the comments on flow control in the | |
1579 @file{emacs/INSTALL} file from the distribution; for help with Termcap | |
1580 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}. | |
1581 | |
1582 @cindex @kbd{C-s} | |
1583 @cindex @kbd{C-q} | |
1584 At one time, most terminals did not need flow control, and none used | |
1585 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of | |
1586 @kbd{C-s} and @kbd{C-q} as command characters was uncontroversial. | |
1587 XEmacs, for economy of keystrokes and portability, used nearly all the | |
1588 @sc{ascii} control characters, with mnemonic meanings when possible; | |
1589 thus, @kbd{C-s} for search and @kbd{C-q} for quote. | |
1590 | |
1591 Later, some terminals were introduced which required these characters | |
1592 for flow control. They were not very good terminals for full-screen | |
1593 editing, so XEmacs maintainers did not pay attention. In later years, | |
1594 flow control with @kbd{C-s} and @kbd{C-q} became widespread among | |
1595 terminals, but by this time it was usually an option. And the majority | |
1596 of users, who can turn flow control off, were unwilling to switch to | |
1597 less mnemonic key bindings for the sake of flow control. | |
1598 | |
1599 So which usage is ``right'', XEmacs's or that of some terminal and | |
1600 concentrator manufacturers? This question has no simple answer. | |
1601 | |
1602 One reason why we are reluctant to cater to the problems caused by | |
1603 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other | |
1604 techniques (albeit less common in practice) for flow control that | |
1605 preserve transparency of the character stream. Note also that their use | |
1606 for flow control is not an official standard. Interestingly, on the | |
1607 model 33 teletype with a paper tape punch (which is very old), @kbd{C-s} | |
1608 and @kbd{C-q} were sent by the computer to turn the punch on and off! | |
1609 | |
1610 As X servers and other window systems replace character-only | |
1611 terminals, this problem is gradually being cured. For the mean time, | |
1612 XEmacs provides a convenient way of enabling flow control if you want it: | |
1613 call the function @code{enable-flow-control}. | |
1614 | |
444 | 1615 @deffn Command enable-flow-control &optional argument |
428 | 1616 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow |
1617 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases | |
1618 for them using @code{keyboard-translate-table} (@pxref{Translating Input}). | |
444 | 1619 |
1620 With optional argument @var{argument} (interactively the prefix | |
1621 argument), enable flow control mode if @var{argument} is positive; else | |
1622 disable it. | |
1623 @end deffn | |
428 | 1624 |
1625 You can use the function @code{enable-flow-control-on} in your | |
1626 @file{.emacs} file to enable flow control automatically on certain | |
1627 terminal types. | |
1628 | |
1629 @defun enable-flow-control-on &rest termtypes | |
1630 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^}, | |
1631 if the terminal type is one of @var{termtypes}. For example: | |
1632 | |
1633 @smallexample | |
1634 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") | |
1635 @end smallexample | |
1636 @end defun | |
1637 | |
1638 Here is how @code{enable-flow-control} does its job: | |
1639 | |
1640 @enumerate | |
1641 @item | |
1642 @cindex @sc{cbreak} | |
1643 It sets @sc{cbreak} mode for terminal input, and tells the operating | |
1644 system to handle flow control, with @code{(set-input-mode nil t)}. | |
1645 | |
1646 @item | |
1647 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and | |
1648 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very | |
1649 lowest level, XEmacs never knows that the characters typed were anything | |
1650 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\} | |
1651 and @kbd{C-^} even when they are input for other commands. | |
1652 @xref{Translating Input}. | |
1653 @end enumerate | |
1654 | |
1655 If the terminal is the source of the flow control characters, then once | |
1656 you enable kernel flow control handling, you probably can make do with | |
1657 less padding than normal for that terminal. You can reduce the amount | |
1658 of padding by customizing the Termcap entry. You can also reduce it by | |
1659 setting @code{baud-rate} to a smaller value so that XEmacs uses a smaller | |
1660 speed when calculating the padding needed. @xref{Terminal Output}. | |
1661 | |
1662 @node Batch Mode | |
1663 @section Batch Mode | |
1664 @cindex batch mode | |
1665 @cindex noninteractive use | |
1666 | |
1667 The command line option @samp{-batch} causes XEmacs to run | |
1668 noninteractively. In this mode, XEmacs does not read commands from the | |
1669 terminal, it does not alter the terminal modes, and it does not expect | |
1670 to be outputting to an erasable screen. The idea is that you specify | |
1671 Lisp programs to run; when they are finished, XEmacs should exit. The | |
1672 way to specify the programs to run is with @samp{-l @var{file}}, which | |
1673 loads the library named @var{file}, and @samp{-f @var{function}}, which | |
1674 calls @var{function} with no arguments. | |
1675 | |
1676 Any Lisp program output that would normally go to the echo area, | |
1677 either using @code{message} or using @code{prin1}, etc., with @code{t} | |
1678 as the stream, goes instead to XEmacs's standard error descriptor when | |
1679 in batch mode. Thus, XEmacs behaves much like a noninteractive | |
1680 application program. (The echo area output that XEmacs itself normally | |
1681 generates, such as command echoing, is suppressed entirely.) | |
1682 | |
1683 @defun noninteractive | |
1684 This function returns non-@code{nil} when XEmacs is running in batch mode. | |
1685 @end defun | |
1686 | |
1687 @defvar noninteractive | |
1688 This variable is non-@code{nil} when XEmacs is running in batch mode. | |
1689 Setting this variable to @code{nil}, however, will not change whether | |
1690 XEmacs is running in batch mode, and will not change the return value | |
1691 of the @code{noninteractive} function. | |
1692 @end defvar |