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