Mercurial > emacs
annotate lispref/os.texi @ 59384:a1edc5959dcf
* macfns.c: Include sys/param.h.
[TARGET_API_MAC_CARBON] (mac_nav_event_callback): New declaration
and function.
[TARGET_API_MAC_CARBON] (Fx_file_dialog): Use MAXPATHLEN for size
of filename string. Set event callback function when creating
dialog boxes. Add code conversions for filenames. Don't dispose
apple event descriptor record if failed to create it.
* macterm.c: Include sys/param.h.
[USE_CARBON_EVENTS] (mac_handle_window_event): Add handler for
kEventWindowUpdate.
(install_window_handler) [USE_CARBON_EVENTS]: Register it.
(do_ae_open_documents) [TARGET_API_MAC_CARBON]: Get FSRef instead
of FSSpec from apple event descriptor record.
(do_ae_open_documents) [TARGET_API_MAC_CARBON]: Use MAXPATHLEN for
size of filename string.
[TARGET_API_MAC_CARBON] (mac_do_receive_drag): Likewise.
[TARGET_API_MAC_CARBON] (mac_do_receive_drag): Return error when a
file dialog is in action.
[TARGET_API_MAC_CARBON] (mac_do_track_drag): Likewise. Reject
only when there are no filename items. Set background color
before (un)highlighting the window below the dragged items.
(XTread_socket) [!USE_CARBON_EVENTS]: Don't call do_window_update.
author | Steven Tamm <steventamm@mac.com> |
---|---|
date | Thu, 06 Jan 2005 02:53:39 +0000 |
parents | 08777d10acff |
children | 70a8ca9b81e0 f6b4d0ebf147 |
rev | line source |
---|---|
6558 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
56353 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
4 @c Free Software Foundation, Inc. |
6558 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/os | |
26211 | 7 @node System Interface, Antinews, Calendar, Top |
6558 | 8 @chapter Operating System Interface |
9 | |
10 This chapter is about starting and getting out of Emacs, access to | |
9009 | 11 values in the operating system environment, and terminal input, output, |
6558 | 12 and flow control. |
13 | |
14 @xref{Building Emacs}, for related information. See also | |
15 @ref{Display}, for additional operating system status information | |
16 pertaining to the terminal and the screen. | |
17 | |
18 @menu | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
19 * Starting Up:: Customizing Emacs startup processing. |
6558 | 20 * Getting Out:: How exiting works (permanent or temporary). |
21 * System Environment:: Distinguish the name and kind of system. | |
22 * User Identification:: Finding the name and user id of the user. | |
23 * Time of Day:: Getting the current time. | |
12067 | 24 * Time Conversion:: Converting a time from numeric form to a string, or |
25 to calendrical data (or vice versa). | |
57989
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
26 * Processor Run Time:: Getting the run time used by Emacs. |
43037
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
27 * Time Calculations:: Adding, subtracting, comparing times, etc. |
6558 | 28 * Timers:: Setting a timer to call a function at a certain time. |
29 * Terminal Input:: Recording terminal input for debugging. | |
30 * Terminal Output:: Recording terminal output for debugging. | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
31 * Sound Output:: Playing sounds on the computer's speaker. |
46228 | 32 * X11 Keysyms:: Operating on key symbols for X Windows |
6558 | 33 * Flow Control:: How to turn output flow control on or off. |
34 * Batch Mode:: Running Emacs without terminal interaction. | |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
35 * Session Management:: Saving and restoring state with X Session Management. |
6558 | 36 @end menu |
37 | |
38 @node Starting Up | |
39 @section Starting Up Emacs | |
40 | |
41 This section describes what Emacs does when it is started, and how you | |
42 can customize these actions. | |
43 | |
44 @menu | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
45 * Startup Summary:: Sequence of actions Emacs performs at startup. |
6558 | 46 * Init File:: Details on reading the init file (@file{.emacs}). |
47 * Terminal-Specific:: How the terminal-specific Lisp file is read. | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
48 * Command-Line Arguments:: How command-line arguments are processed, |
6558 | 49 and how you can customize them. |
50 @end menu | |
51 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
52 @node Startup Summary |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
53 @subsection Summary: Sequence of Actions at Startup |
6558 | 54 @cindex initialization |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
55 @cindex startup of Emacs |
6558 | 56 @cindex @file{startup.el} |
57 | |
58 The order of operations performed (in @file{startup.el}) by Emacs when | |
59 it is started up is as follows: | |
60 | |
61 @enumerate | |
62 @item | |
28603
cb9db16dba12
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27765
diff
changeset
|
63 It adds subdirectories to @code{load-path}, by running the file named |
cb9db16dba12
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27765
diff
changeset
|
64 @file{subdirs.el} in each directory in the list. Normally this file |
cb9db16dba12
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27765
diff
changeset
|
65 adds the directory's subdirectories to the list, and these will be |
cb9db16dba12
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27765
diff
changeset
|
66 scanned in their turn. The files @file{subdirs.el} are normally |
cb9db16dba12
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27765
diff
changeset
|
67 generated automatically by Emacs installation. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
68 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
69 @item |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
70 It sets the language environment and the terminal coding system, |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
71 if requested by environment variables such as @code{LANG}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
72 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
73 @item |
6558 | 74 It loads the initialization library for the window system, if you are |
75 using a window system. This library's name is | |
76 @file{term/@var{windowsystem}-win.el}. | |
77 | |
78 @item | |
12098 | 79 It processes the initial options. (Some of them are handled |
80 even earlier than this.) | |
81 | |
82 @item | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
83 It initializes the window frame and faces, if appropriate. |
6558 | 84 |
85 @item | |
86 It runs the normal hook @code{before-init-hook}. | |
87 | |
88 @item | |
89 It loads the library @file{site-start}, unless the option | |
90 @samp{-no-site-file} was specified. The library's file name is usually | |
91 @file{site-start.el}. | |
92 @cindex @file{site-start.el} | |
93 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
94 @item |
26242 | 95 It loads your init file (usually @file{~/.emacs}), unless @samp{-q}, |
96 @samp{-no-init-file}, or @samp{-batch} was specified on the command line. | |
97 The @samp{-u} option can specify another user whose home directory | |
98 should be used instead of @file{~}. | |
6558 | 99 |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
100 @item |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
101 It loads the library @file{default}, unless @code{inhibit-default-init} |
6558 | 102 is non-@code{nil}. (This is not done in @samp{-batch} mode or if |
9009 | 103 @samp{-q} was specified on the command line.) The library's file name |
104 is usually @file{default.el}. | |
6558 | 105 @cindex @file{default.el} |
106 | |
107 @item | |
108 It runs the normal hook @code{after-init-hook}. | |
109 | |
110 @item | |
111 It sets the major mode according to @code{initial-major-mode}, provided | |
112 the buffer @samp{*scratch*} is still current and still in Fundamental | |
113 mode. | |
114 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
115 @item |
6558 | 116 It loads the terminal-specific Lisp file, if any, except when in batch |
117 mode or using a window system. | |
118 | |
119 @item | |
120 It displays the initial echo area message, unless you have suppressed | |
121 that with @code{inhibit-startup-echo-area-message}. | |
122 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
123 @item |
12098 | 124 It processes the action arguments from the command line. |
6558 | 125 |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
126 @item |
27353
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
127 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. |
6558 | 128 |
129 @item | |
130 It calls @code{frame-notice-user-settings}, which modifies the | |
131 parameters of the selected frame according to whatever the init files | |
132 specify. | |
133 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
134 @item |
6558 | 135 It runs @code{window-setup-hook}. @xref{Window Systems}. |
136 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
137 @item |
9009 | 138 It displays copyleft, nonwarranty, and basic use information, provided |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
139 there were no remaining command-line arguments (a few steps above), |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
140 the value of @code{inhibit-startup-message} is @code{nil}, and the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
141 buffer is still empty. |
6558 | 142 @end enumerate |
143 | |
144 @defopt inhibit-startup-message | |
145 This variable inhibits the initial startup messages (the nonwarranty, | |
146 etc.). If it is non-@code{nil}, then the messages are not printed. | |
147 | |
148 This variable exists so you can set it in your personal init file, once | |
149 you are familiar with the contents of the startup message. Do not set | |
150 this variable in the init file of a new user, or in a way that affects | |
151 more than one user, because that would prevent new users from receiving | |
152 the information they are supposed to see. | |
153 @end defopt | |
154 | |
155 @defopt inhibit-startup-echo-area-message | |
156 This variable controls the display of the startup echo area message. | |
157 You can suppress the startup echo area message by adding text with this | |
25875 | 158 form to your init file: |
6558 | 159 |
160 @example | |
161 (setq inhibit-startup-echo-area-message | |
162 "@var{your-login-name}") | |
163 @end example | |
164 | |
25875 | 165 Emacs explicitly checks for an expression as shown above in your init |
166 file; your login name must appear in the expression as a Lisp string | |
167 constant. Other methods of setting | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
168 @code{inhibit-startup-echo-area-message} to the same value do not |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
169 inhibit the startup message. |
6558 | 170 |
171 This way, you can easily inhibit the message for yourself if you wish, | |
25875 | 172 but thoughtless copying of your init file will not inhibit the message |
173 for someone else. | |
6558 | 174 @end defopt |
175 | |
176 @node Init File | |
25875 | 177 @subsection The Init File, @file{.emacs} |
6558 | 178 @cindex init file |
179 @cindex @file{.emacs} | |
180 | |
25875 | 181 When you start Emacs, it normally attempts to load your @dfn{init |
182 file}, a file in your home directory. Its normal name is @file{.emacs}, | |
183 but you can alternatively call it @file{.emacs.el}, which enables you to | |
184 byte-compile it (@pxref{Byte Compilation}); then the actual file loaded | |
185 will be @file{.emacs.elc}. | |
186 | |
187 The command-line switches @samp{-q} and @samp{-u} control whether and | |
188 where to find the init file; @samp{-q} says not to load an init file, | |
189 and @samp{-u @var{user}} says to load @var{user}'s init file instead of | |
190 yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If | |
191 neither option is specified, Emacs uses the @code{LOGNAME} environment | |
192 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS | |
193 systems) variable, to find your home directory and thus your init file; | |
194 this way, even if you have su'd, Emacs still loads your own init file. | |
195 If those environment variables are absent, though, Emacs uses your | |
196 user-id to find your home directory. | |
6558 | 197 |
198 @cindex default init file | |
199 A site may have a @dfn{default init file}, which is the library named | |
200 @file{default.el}. Emacs finds the @file{default.el} file through the | |
201 standard search path for libraries (@pxref{How Programs Do Loading}). | |
202 The Emacs distribution does not come with this file; sites may provide | |
203 one for local customizations. If the default init file exists, it is | |
204 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is | |
205 specified. But your own personal init file, if any, is loaded first; if | |
206 it sets @code{inhibit-default-init} to a non-@code{nil} value, then | |
207 Emacs does not subsequently load the @file{default.el} file. | |
208 | |
209 Another file for site-customization is @file{site-start.el}. Emacs | |
210 loads this @emph{before} the user's init file. You can inhibit the | |
211 loading of this file with the option @samp{-no-site-file}. | |
212 | |
12098 | 213 @defvar site-run-file |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
214 This variable specifies the site-customization file to load before the |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
215 user's init file. Its normal value is @code{"site-start"}. The only |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
216 way you can change it with real effect is to do so before dumping |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
217 Emacs. |
12098 | 218 @end defvar |
219 | |
50475
b65aa1d740eb
Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents:
49549
diff
changeset
|
220 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for |
6558 | 221 examples of how to make various commonly desired customizations in your |
222 @file{.emacs} file. | |
223 | |
224 @defopt inhibit-default-init | |
225 This variable prevents Emacs from loading the default initialization | |
226 library file for your session of Emacs. If its value is non-@code{nil}, | |
227 then the default library is not loaded. The default value is | |
228 @code{nil}. | |
229 @end defopt | |
230 | |
231 @defvar before-init-hook | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
232 This normal hook is run, once, just before loading all the init files |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
233 (the user's init file, @file{default.el}, and/or @file{site-start.el}). |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
234 (The only way to change it with real effect is before dumping Emacs.) |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
235 @end defvar |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
236 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
237 @defvar after-init-hook |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
238 This normal hook is run, once, just after loading all the init files |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
239 (the user's init file, @file{default.el}, and/or @file{site-start.el}), |
27353
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
240 before loading the terminal-specific library and processing the |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
241 command-line action arguments. |
27353
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
242 @end defvar |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
243 |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
244 @defvar emacs-startup-hook |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
245 @tindex emacs-startup-hook |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
246 This normal hook is run, once, just after handling the command line |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
247 arguments, just before @code{term-setup-hook}. |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
248 @end defvar |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
249 |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
250 @defvar user-init-file |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
251 @tindex user-init-file |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
252 This variable holds the absolute file name of the user's init file. If the |
27353
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
253 actual init file loaded is a compiled file, such as @file{.emacs.elc}, |
611b3854d888
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
254 the value refers to the corresponding source file. |
6558 | 255 @end defvar |
256 | |
257 @node Terminal-Specific | |
258 @subsection Terminal-Specific Initialization | |
259 @cindex terminal-specific initialization | |
260 | |
261 Each terminal type can have its own Lisp library that Emacs loads when | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
262 run on that type of terminal. The library's name is constructed by |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
263 concatenating the value of the variable @code{term-file-prefix} and the |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
264 terminal type (specified by the environment variable @code{TERM}). |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
265 Normally, @code{term-file-prefix} has the value |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
266 @code{"term/"}; changing this is not recommended. Emacs finds the file |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
267 in the normal manner, by searching the @code{load-path} directories, and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
268 trying the @samp{.elc} and @samp{.el} suffixes. |
6558 | 269 |
270 The usual function of a terminal-specific library is to enable special | |
271 keys to send sequences that Emacs can recognize. It may also need to | |
272 set or add to @code{function-key-map} if the Termcap entry does not | |
273 specify all the terminal's function keys. @xref{Terminal Input}. | |
274 | |
275 @cindex Termcap | |
276 When the name of the terminal type contains a hyphen, only the part of | |
277 the name before the first hyphen is significant in choosing the library | |
278 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use | |
279 the @file{term/aaa} library. If necessary, the library can evaluate | |
280 @code{(getenv "TERM")} to find the full name of the terminal | |
281 type.@refill | |
282 | |
25875 | 283 Your init file can prevent the loading of the |
6558 | 284 terminal-specific library by setting the variable |
285 @code{term-file-prefix} to @code{nil}. This feature is useful when | |
286 experimenting with your own peculiar customizations. | |
287 | |
288 You can also arrange to override some of the actions of the | |
289 terminal-specific library by setting the variable | |
290 @code{term-setup-hook}. This is a normal hook which Emacs runs using | |
291 @code{run-hooks} at the end of Emacs initialization, after loading both | |
25875 | 292 your init file and any terminal-specific libraries. You can |
6558 | 293 use this variable to define initializations for terminals that do not |
294 have their own libraries. @xref{Hooks}. | |
295 | |
296 @defvar term-file-prefix | |
297 @cindex @code{TERM} environment variable | |
298 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads | |
299 a terminal-specific initialization file as follows: | |
300 | |
301 @example | |
302 (load (concat term-file-prefix (getenv "TERM"))) | |
303 @end example | |
304 | |
305 @noindent | |
306 You may set the @code{term-file-prefix} variable to @code{nil} in your | |
25875 | 307 init file if you do not wish to load the |
6558 | 308 terminal-initialization file. To do this, put the following in |
25875 | 309 your init file: @code{(setq term-file-prefix nil)}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
310 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
311 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
312 uses @samp{internal} as the terminal type. |
6558 | 313 @end defvar |
314 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
315 @defvar term-setup-hook |
9009 | 316 This variable is a normal hook that Emacs runs after loading your |
25875 | 317 init file, the default initialization file (if any) and the |
6558 | 318 terminal-specific Lisp file. |
319 | |
320 You can use @code{term-setup-hook} to override the definitions made by a | |
321 terminal-specific file. | |
322 @end defvar | |
323 | |
324 See @code{window-setup-hook} in @ref{Window Systems}, for a related | |
325 feature. | |
326 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
327 @node Command-Line Arguments |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
328 @subsection Command-Line Arguments |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
329 @cindex command-line arguments |
6558 | 330 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
331 You can use command-line arguments to request various actions when you |
6558 | 332 start Emacs. Since you do not need to start Emacs more than once per |
333 day, and will often leave your Emacs session running longer than that, | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
334 command-line arguments are hardly ever used. As a practical matter, it |
6558 | 335 is best to avoid making the habit of using them, since this habit would |
336 encourage you to kill and restart Emacs unnecessarily often. These | |
337 options exist for two reasons: to be compatible with other editors (for | |
338 invocation by other programs) and to enable shell scripts to run | |
339 specific Lisp programs. | |
340 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
341 This section describes how Emacs processes command-line arguments, |
6558 | 342 and how you can customize them. |
343 | |
344 @ignore | |
345 (Note that some other editors require you to start afresh each time | |
346 you want to edit a file. With this kind of editor, you will probably | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
347 specify the file as a command-line argument. The recommended way to |
6558 | 348 use GNU Emacs is to start it only once, just after you log in, and do |
349 all your editing in the same Emacs process. Each time you want to edit | |
350 a different file, you visit it with the existing Emacs, which eventually | |
351 comes to have many files in it ready for editing. Usually you do not | |
352 kill the Emacs until you are about to log out.) | |
353 @end ignore | |
354 | |
355 @defun command-line | |
9009 | 356 This function parses the command line that Emacs was called with, |
25875 | 357 processes it, loads the user's init file and displays the |
9009 | 358 startup messages. |
6558 | 359 @end defun |
360 | |
361 @defvar command-line-processed | |
362 The value of this variable is @code{t} once the command line has been | |
363 processed. | |
364 | |
365 If you redump Emacs by calling @code{dump-emacs}, you may wish to set | |
366 this variable to @code{nil} first in order to cause the new dumped Emacs | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
367 to process its new command-line arguments. |
6558 | 368 @end defvar |
369 | |
370 @defvar command-switch-alist | |
371 @cindex switches on command line | |
372 @cindex options on command line | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
373 @cindex command-line options |
6558 | 374 The value of this variable is an alist of user-defined command-line |
375 options and associated handler functions. This variable exists so you | |
376 can add elements to it. | |
377 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
378 A @dfn{command-line option} is an argument on the command line, which |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
379 has the form: |
6558 | 380 |
381 @example | |
382 -@var{option} | |
383 @end example | |
384 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
385 The elements of the @code{command-switch-alist} look like this: |
6558 | 386 |
387 @example | |
388 (@var{option} . @var{handler-function}) | |
389 @end example | |
390 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
391 The @sc{car}, @var{option}, is a string, the name of a command-line |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
392 option (not including the initial hyphen). The @var{handler-function} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
393 is called to handle @var{option}, and receives the option name as its |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
394 sole argument. |
6558 | 395 |
396 In some cases, the option is followed in the command line by an | |
397 argument. In these cases, the @var{handler-function} can find all the | |
398 remaining command-line arguments in the variable | |
399 @code{command-line-args-left}. (The entire list of command-line | |
400 arguments is in @code{command-line-args}.) | |
401 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
402 The command-line arguments are parsed by the @code{command-line-1} |
6558 | 403 function in the @file{startup.el} file. See also @ref{Command |
50475
b65aa1d740eb
Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents:
49549
diff
changeset
|
404 Arguments, , Command Line Arguments, emacs, The GNU Emacs Manual}. |
6558 | 405 @end defvar |
406 | |
407 @defvar command-line-args | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
408 The value of this variable is the list of command-line arguments passed |
6558 | 409 to Emacs. |
410 @end defvar | |
411 | |
412 @defvar command-line-functions | |
413 This variable's value is a list of functions for handling an | |
414 unrecognized command-line argument. Each time the next argument to be | |
415 processed has no special meaning, the functions in this list are called, | |
9009 | 416 in order of appearance, until one of them returns a non-@code{nil} |
6558 | 417 value. |
418 | |
419 These functions are called with no arguments. They can access the | |
420 command-line argument under consideration through the variable | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
421 @code{argi}, which is bound temporarily at this point. The remaining |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
422 arguments (not including the current one) are in the variable |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
423 @code{command-line-args-left}. |
6558 | 424 |
425 When a function recognizes and processes the argument in @code{argi}, it | |
426 should return a non-@code{nil} value to say it has dealt with that | |
427 argument. If it has also dealt with some of the following arguments, it | |
428 can indicate that by deleting them from @code{command-line-args-left}. | |
429 | |
430 If all of these functions return @code{nil}, then the argument is used | |
431 as a file name to visit. | |
432 @end defvar | |
433 | |
434 @node Getting Out | |
435 @section Getting Out of Emacs | |
436 @cindex exiting Emacs | |
437 | |
438 There are two ways to get out of Emacs: you can kill the Emacs job, | |
439 which exits permanently, or you can suspend it, which permits you to | |
440 reenter the Emacs process later. As a practical matter, you seldom kill | |
441 Emacs---only when you are about to log out. Suspending is much more | |
442 common. | |
443 | |
444 @menu | |
445 * Killing Emacs:: Exiting Emacs irreversibly. | |
446 * Suspending Emacs:: Exiting Emacs reversibly. | |
447 @end menu | |
448 | |
449 @node Killing Emacs | |
450 @comment node-name, next, previous, up | |
451 @subsection Killing Emacs | |
452 @cindex killing Emacs | |
453 | |
454 Killing Emacs means ending the execution of the Emacs process. The | |
455 parent process normally resumes control. The low-level primitive for | |
456 killing Emacs is @code{kill-emacs}. | |
457 | |
458 @defun kill-emacs &optional exit-data | |
459 This function exits the Emacs process and kills it. | |
460 | |
461 If @var{exit-data} is an integer, then it is used as the exit status | |
462 of the Emacs process. (This is useful primarily in batch operation; see | |
463 @ref{Batch Mode}.) | |
464 | |
465 If @var{exit-data} is a string, its contents are stuffed into the | |
466 terminal input buffer so that the shell (or whatever program next reads | |
467 input) can read them. | |
468 @end defun | |
469 | |
470 All the information in the Emacs process, aside from files that have | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
471 been saved, is lost when the Emacs process is killed. Because killing |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
472 Emacs inadvertently can lose a lot of work, Emacs queries for |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
473 confirmation before actually terminating if you have buffers that need |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
474 saving or subprocesses that are running. This is done in the function |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
475 @code{save-buffers-kill-emacs}, the higher level function from which |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
476 @code{kill-emacs} is usually called. |
6558 | 477 |
478 @defvar kill-emacs-query-functions | |
479 After asking the standard questions, @code{save-buffers-kill-emacs} | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
480 calls the functions in the list @code{kill-emacs-query-functions}, in |
6558 | 481 order of appearance, with no arguments. These functions can ask for |
482 additional confirmation from the user. If any of them returns | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
483 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
484 does not run the remaining functions in this hook. Calling |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
485 @code{kill-emacs} directly does not run this hook. |
6558 | 486 @end defvar |
487 | |
488 @defvar kill-emacs-hook | |
489 This variable is a normal hook; once @code{save-buffers-kill-emacs} is | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
490 finished with all file saving and confirmation, it calls |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
491 @code{kill-emacs} which runs the functions in this hook. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
492 @code{kill-emacs} does not run this hook in batch mode. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
493 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
494 @code{kill-emacs} may be invoked directly (that is not via |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
495 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
496 similar situations where interaction with the user is not possible. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
497 Thus, if your hook needs to interact with the user, put it on |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
498 @code{kill-emacs-query-functions}; if it needs to run regardless of |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
499 how Emacs is killed, put it on @code{kill-emacs-hook}. |
6558 | 500 @end defvar |
501 | |
502 @node Suspending Emacs | |
503 @subsection Suspending Emacs | |
504 @cindex suspending Emacs | |
505 | |
506 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning | |
507 control to its superior process, which is usually the shell. This | |
508 allows you to resume editing later in the same Emacs process, with the | |
509 same buffers, the same kill ring, the same undo history, and so on. To | |
510 resume Emacs, use the appropriate command in the parent shell---most | |
511 likely @code{fg}. | |
512 | |
513 Some operating systems do not support suspension of jobs; on these | |
514 systems, ``suspension'' actually creates a new shell temporarily as a | |
515 subprocess of Emacs. Then you would exit the shell to return to Emacs. | |
516 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
517 Suspension is not useful with window systems, because the Emacs job |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
518 may not have a parent that can resume it again, and in any case you can |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
519 give input to some other job such as a shell merely by moving to a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
520 different window. Therefore, suspending is not allowed when Emacs is using |
35476 | 521 a window system (X or MS Windows). |
6558 | 522 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
523 @defun suspend-emacs &optional string |
6558 | 524 This function stops Emacs and returns control to the superior process. |
525 If and when the superior process resumes Emacs, @code{suspend-emacs} | |
526 returns @code{nil} to its caller in Lisp. | |
527 | |
528 If @var{string} is non-@code{nil}, its characters are sent to be read | |
529 as terminal input by Emacs's superior shell. The characters in | |
530 @var{string} are not echoed by the superior shell; only the results | |
531 appear. | |
532 | |
533 Before suspending, @code{suspend-emacs} runs the normal hook | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
534 @code{suspend-hook}. |
6558 | 535 |
9009 | 536 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook |
6558 | 537 @code{suspend-resume-hook}. @xref{Hooks}. |
538 | |
539 The next redisplay after resumption will redraw the entire screen, | |
540 unless the variable @code{no-redraw-on-reenter} is non-@code{nil} | |
541 (@pxref{Refresh Screen}). | |
542 | |
543 In the following example, note that @samp{pwd} is not echoed after | |
544 Emacs is suspended. But it is read and executed by the shell. | |
545 | |
546 @smallexample | |
547 @group | |
548 (suspend-emacs) | |
549 @result{} nil | |
550 @end group | |
551 | |
552 @group | |
553 (add-hook 'suspend-hook | |
554 (function (lambda () | |
555 (or (y-or-n-p | |
556 "Really suspend? ") | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
557 (error "Suspend canceled"))))) |
6558 | 558 @result{} (lambda nil |
559 (or (y-or-n-p "Really suspend? ") | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
560 (error "Suspend canceled"))) |
6558 | 561 @end group |
562 @group | |
563 (add-hook 'suspend-resume-hook | |
564 (function (lambda () (message "Resumed!")))) | |
565 @result{} (lambda nil (message "Resumed!")) | |
566 @end group | |
567 @group | |
568 (suspend-emacs "pwd") | |
569 @result{} nil | |
570 @end group | |
571 @group | |
572 ---------- Buffer: Minibuffer ---------- | |
573 Really suspend? @kbd{y} | |
574 ---------- Buffer: Minibuffer ---------- | |
575 @end group | |
576 | |
577 @group | |
578 ---------- Parent Shell ---------- | |
579 lewis@@slug[23] % /user/lewis/manual | |
580 lewis@@slug[24] % fg | |
581 @end group | |
582 | |
583 @group | |
584 ---------- Echo Area ---------- | |
585 Resumed! | |
586 @end group | |
587 @end smallexample | |
588 @end defun | |
589 | |
590 @defvar suspend-hook | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
591 This variable is a normal hook that Emacs runs before suspending. |
6558 | 592 @end defvar |
593 | |
594 @defvar suspend-resume-hook | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
595 This variable is a normal hook that Emacs runs on resuming |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
596 after a suspension. |
6558 | 597 @end defvar |
598 | |
599 @node System Environment | |
600 @section Operating System Environment | |
601 @cindex operating system environment | |
602 | |
603 Emacs provides access to variables in the operating system environment | |
604 through various functions. These variables include the name of the | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
605 system, the user's @acronym{UID}, and so on. |
6558 | 606 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
607 @defvar system-configuration |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
608 This variable holds the GNU configuration name for the hardware/software |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
609 configuration of your system, as a string. The convenient way to test |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
610 parts of this string is with @code{string-match}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
611 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
612 |
6558 | 613 @defvar system-type |
12098 | 614 The value of this variable is a symbol indicating the type of operating |
615 system Emacs is operating on. Here is a table of the possible values: | |
6558 | 616 |
617 @table @code | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
618 @item alpha-vms |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
619 VMS on the Alpha. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
620 |
6558 | 621 @item aix-v3 |
622 AIX. | |
623 | |
624 @item berkeley-unix | |
625 Berkeley BSD. | |
626 | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
627 @item cygwin |
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
628 Cygwin. |
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
629 |
12098 | 630 @item dgux |
631 Data General DGUX operating system. | |
632 | |
633 @item gnu | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
634 the GNU system (using the GNU kernel, which consists of the HURD and Mach). |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
635 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
636 @item gnu/linux |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
637 A GNU/Linux system---that is, a variant GNU system, using the Linux |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
638 kernel. (These systems are the ones people often call ``Linux,'' but |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
639 actually Linux is just the kernel, not the whole system.) |
12098 | 640 |
6558 | 641 @item hpux |
12098 | 642 Hewlett-Packard HPUX operating system. |
6558 | 643 |
644 @item irix | |
645 Silicon Graphics Irix system. | |
646 | |
12098 | 647 @item ms-dos |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
648 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
649 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
650 MS-Windows. |
12098 | 651 |
652 @item next-mach | |
653 NeXT Mach-based system. | |
7277
6a2af30d33fe
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
654 |
6558 | 655 @item rtu |
656 Masscomp RTU, UCB universe. | |
657 | |
658 @item unisoft-unix | |
659 UniSoft UniPlus. | |
660 | |
661 @item usg-unix-v | |
662 AT&T System V. | |
663 | |
664 @item vax-vms | |
665 VAX VMS. | |
666 | |
12098 | 667 @item windows-nt |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
668 Microsoft windows NT. The same executable supports Windows 9X, but the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
669 value of @code{system-type} is @code{windows-nt} in either case. |
12098 | 670 |
6558 | 671 @item xenix |
672 SCO Xenix 386. | |
673 @end table | |
674 | |
675 We do not wish to add new symbols to make finer distinctions unless it | |
676 is absolutely necessary! In fact, we hope to eliminate some of these | |
677 alternatives in the future. We recommend using | |
678 @code{system-configuration} to distinguish between different operating | |
679 systems. | |
680 @end defvar | |
681 | |
682 @defun system-name | |
683 This function returns the name of the machine you are running on. | |
684 @example | |
685 (system-name) | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
686 @result{} "www.gnu.org" |
6558 | 687 @end example |
688 @end defun | |
689 | |
12067 | 690 The symbol @code{system-name} is a variable as well as a function. In |
691 fact, the function returns whatever value the variable | |
692 @code{system-name} currently holds. Thus, you can set the variable | |
693 @code{system-name} in case Emacs is confused about the name of your | |
694 system. The variable is also useful for constructing frame titles | |
695 (@pxref{Frame Titles}). | |
696 | |
697 @defvar mail-host-address | |
698 If this variable is non-@code{nil}, it is used instead of | |
699 @code{system-name} for purposes of generating email addresses. For | |
700 example, it is used when constructing the default value of | |
701 @code{user-mail-address}. @xref{User Identification}. (Since this is | |
702 done when Emacs starts up, the value actually used is the one saved when | |
703 Emacs was dumped. @xref{Building Emacs}.) | |
704 @end defvar | |
705 | |
32839 | 706 @deffn Command getenv var |
6558 | 707 @cindex environment variable access |
708 This function returns the value of the environment variable @var{var}, | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
709 as a string. @var{var} should be a string. If @var{var} is undefined |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
710 in the environment, @code{getenv} returns @code{nil}. If returns |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
711 @samp{""} if @var{var} is set but null. Within Emacs, the environment |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
712 variable values are kept in the Lisp variable @code{process-environment}. |
6558 | 713 |
714 @example | |
715 @group | |
716 (getenv "USER") | |
717 @result{} "lewis" | |
718 @end group | |
719 | |
720 @group | |
721 lewis@@slug[10] % printenv | |
722 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin | |
723 USER=lewis | |
724 @end group | |
725 @group | |
726 TERM=ibmapa16 | |
727 SHELL=/bin/csh | |
728 HOME=/user/lewis | |
729 @end group | |
730 @end example | |
32924 | 731 @end deffn |
6558 | 732 |
733 @c Emacs 19 feature | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
734 @deffn Command setenv variable &optional value |
6558 | 735 This command sets the value of the environment variable named |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
736 @var{variable} to @var{value}. @var{variable} should be a string. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
737 Internally, Emacs Lisp can handle any string. However, normally |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
738 @var{variable} should be a valid shell identifier, that is, a sequence |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
739 of letters, digits and underscores, starting with a letter or |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
740 underscore. Otherwise, errors may occur if subprocesses of Emacs try |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
741 to access the value of @var{variable}. If @var{value} is omitted or |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
742 @code{nil}, @code{setenv} removes @var{variable} from the environment. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
743 Otherwise, @var{value} should be a string. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
744 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
745 @code{setenv} works by modifying @code{process-environment}; binding |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
746 that variable with @code{let} is also reasonable practice. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
747 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
748 @code{setenv} returns the new value of @var{variable}, or @code{nil} |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
749 if it removed @var{variable} from the environment. |
6558 | 750 @end deffn |
751 | |
752 @defvar process-environment | |
753 This variable is a list of strings, each describing one environment | |
754 variable. The functions @code{getenv} and @code{setenv} work by means | |
755 of this variable. | |
756 | |
757 @smallexample | |
758 @group | |
759 process-environment | |
760 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp" | |
761 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
762 "USER=lewis" |
6558 | 763 @end group |
764 @group | |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
765 "TERM=ibmapa16" |
6558 | 766 "SHELL=/bin/csh" |
767 "HOME=/user/lewis") | |
768 @end group | |
769 @end smallexample | |
40311
a3a9223b152f
Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents:
39221
diff
changeset
|
770 |
a3a9223b152f
Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents:
39221
diff
changeset
|
771 If @code{process-environment} contains ``duplicate'' elements that |
a3a9223b152f
Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents:
39221
diff
changeset
|
772 specify the same environment variable, the first of these elements |
a3a9223b152f
Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents:
39221
diff
changeset
|
773 specifies the variable, and the other ``duplicates'' are ignored. |
6558 | 774 @end defvar |
775 | |
12098 | 776 @defvar path-separator |
777 This variable holds a string which says which character separates | |
778 directories in a search path (as found in an environment variable). Its | |
779 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
780 and MS-Windows. |
12098 | 781 @end defvar |
782 | |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
783 @defun parse-colon-path path |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
784 @tindex parse-colon-path |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
785 This function takes a search path string such as would be the value of |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
786 the @code{PATH} environment variable, and splits it at the separators, |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
787 returning a list of directory names. @code{nil} in this list stands for |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
788 ``use the current directory.'' Although the function's name says |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
789 ``colon,'' it actually uses the value of @code{path-separator}. |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
790 |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
791 @example |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
792 (parse-colon-path ":/foo:/bar") |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
793 @result{} (nil "/foo/" "/bar/") |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
794 @end example |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
795 @end defun |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28603
diff
changeset
|
796 |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
797 @defvar invocation-name |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
798 This variable holds the program name under which Emacs was invoked. The |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
799 value is a string, and does not include a directory name. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
800 @end defvar |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
801 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
802 @defvar invocation-directory |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
803 This variable holds the directory from which the Emacs executable was |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
804 invoked, or perhaps @code{nil} if that directory cannot be determined. |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
805 @end defvar |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
806 |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
807 @defvar installation-directory |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
808 If non-@code{nil}, this is a directory within which to look for the |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
809 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
810 when Emacs can't find those directories in their standard installed |
9009 | 811 locations, but can find them in a directory related somehow to the one |
812 containing the Emacs executable. | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
813 @end defvar |
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
814 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
815 @defun load-average &optional use-float |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
816 This function returns the current 1-minute, 5-minute, and 15-minute load |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
817 averages, in a list. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
818 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
819 By default, the values are integers that are 100 times the system load |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
820 averages, which indicate the average number of processes trying to run. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
821 If @var{use-float} is non-@code{nil}, then they are returned |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
822 as floating point numbers and without multiplying by 100. |
6558 | 823 |
52842
1cc25f9733cf
(System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents:
52783
diff
changeset
|
824 If it is impossible to obtain the load average, this function signals |
1cc25f9733cf
(System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents:
52783
diff
changeset
|
825 an error. On some platforms, access to load averages requires |
1cc25f9733cf
(System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents:
52783
diff
changeset
|
826 installing Emacs as setuid or setgid so that it can read kernel |
1cc25f9733cf
(System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents:
52783
diff
changeset
|
827 information, and that usually isn't advisable. |
52783 | 828 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
829 If the 1-minute load average is available, but the 5- or 15-minute |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
830 averages are not, this function returns a shortened list containing |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
831 the available averages. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
832 |
6558 | 833 @example |
834 @group | |
835 (load-average) | |
836 @result{} (169 48 36) | |
837 @end group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
838 @group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
839 (load-average t) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
840 @result{} (1.69 0.48 0.36) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
841 @end group |
6558 | 842 |
843 @group | |
844 lewis@@rocky[5] % uptime | |
845 11:55am up 1 day, 19:37, 3 users, | |
846 load average: 1.69, 0.48, 0.36 | |
847 @end group | |
848 @end example | |
849 @end defun | |
850 | |
851 @defun emacs-pid | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
852 This function returns the process @acronym{ID} of the Emacs process, |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
853 as an integer. |
6558 | 854 @end defun |
855 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
856 @defvar tty-erase-char |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
857 This variable holds the erase character that was selected |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
858 in the system's terminal driver, before Emacs was started. |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
859 The value is @code{nil} if Emacs is running under a window system. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
860 @end defvar |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
861 |
6558 | 862 @defun setprv privilege-name &optional setp getprv |
863 This function sets or resets a VMS privilege. (It does not exist on | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
864 other systems.) The first argument is the privilege name, as a string. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
865 The second argument, @var{setp}, is @code{t} or @code{nil}, indicating |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
866 whether the privilege is to be turned on or off. Its default is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
867 @code{nil}. The function returns @code{t} if successful, @code{nil} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
868 otherwise. |
6558 | 869 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
870 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv} |
6558 | 871 does not change the privilege, but returns @code{t} or @code{nil} |
872 indicating whether the privilege is currently enabled. | |
873 @end defun | |
874 | |
875 @node User Identification | |
876 @section User Identification | |
877 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
878 @defvar init-file-user |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
879 This variable says which user's init files should be used by |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
880 Emacs---or @code{nil} if none. @code{""} stands for the user who |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
881 originally logged in. The value reflects command-line options such as |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
882 @samp{-q} or @samp{-u @var{user}}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
883 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
884 Lisp packages that load files of customizations, or any other sort of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
885 user profile, should obey this variable in deciding where to find it. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
886 They should load the profile of the user name found in this variable. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
887 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
888 option was used, then Lisp packages should not load any customization |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
889 files or user profile. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
890 @end defvar |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
891 |
12067 | 892 @defvar user-mail-address |
893 This holds the nominal email address of the user who is using Emacs. | |
13367
a3e8c1d2492f
Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
894 Emacs normally sets this variable to a default value after reading your |
a3e8c1d2492f
Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
895 init files, but not if you have already set it. So you can set the |
25875 | 896 variable to some other value in your init file if you do not |
13367
a3e8c1d2492f
Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
897 want to use the default value. |
12067 | 898 @end defvar |
899 | |
900 @defun user-login-name &optional uid | |
901 If you don't specify @var{uid}, this function returns the name under | |
902 which the user is logged in. If the environment variable @code{LOGNAME} | |
903 is set, that value is used. Otherwise, if the environment variable | |
904 @code{USER} is set, that value is used. Otherwise, the value is based | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
905 on the effective @acronym{UID}, not the real @acronym{UID}. |
12067 | 906 |
907 If you specify @var{uid}, the value is the user name that corresponds | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
908 to @var{uid} (which should be an integer), or @code{nil} if there is |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
909 no such user. |
6558 | 910 |
911 @example | |
912 @group | |
913 (user-login-name) | |
914 @result{} "lewis" | |
915 @end group | |
916 @end example | |
917 @end defun | |
918 | |
919 @defun user-real-login-name | |
920 This function returns the user name corresponding to Emacs's real | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
921 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the |
6558 | 922 environment variables @code{LOGNAME} and @code{USER}. |
923 @end defun | |
924 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
925 @defun user-full-name &optional uid |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
926 This function returns the full name of the logged-in user---or the value |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
927 of the environment variable @code{NAME}, if that is set. |
6558 | 928 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
929 @c "Bil" is the correct spelling. |
6558 | 930 @example |
931 @group | |
932 (user-full-name) | |
933 @result{} "Bil Lewis" | |
934 @end group | |
935 @end example | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
936 |
24848 | 937 If the Emacs job's user-id does not correspond to any known user (and |
938 provided @code{NAME} is not set), the value is @code{"unknown"}. | |
939 | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
940 If @var{uid} is non-@code{nil}, then it should be a number (a user-id) |
24848 | 941 or a string (a login name). Then @code{user-full-name} returns the full |
942 name corresponding to that user-id or login name. If you specify a | |
943 user-id or login name that isn't defined, it returns @code{nil}. | |
6558 | 944 @end defun |
945 | |
12067 | 946 @vindex user-full-name |
947 @vindex user-real-login-name | |
948 @vindex user-login-name | |
949 The symbols @code{user-login-name}, @code{user-real-login-name} and | |
950 @code{user-full-name} are variables as well as functions. The functions | |
951 return the same values that the variables hold. These variables allow | |
952 you to ``fake out'' Emacs by telling the functions what to return. The | |
953 variables are also useful for constructing frame titles (@pxref{Frame | |
954 Titles}). | |
955 | |
6558 | 956 @defun user-real-uid |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
957 This function returns the real @acronym{UID} of the user. |
51918
9fbd3ef3087d
(User Identification): user-uid, user-real-uid can return float.
Richard M. Stallman <rms@gnu.org>
parents:
50654
diff
changeset
|
958 The value may be a floating point number. |
6558 | 959 |
960 @example | |
961 @group | |
962 (user-real-uid) | |
963 @result{} 19 | |
964 @end group | |
965 @end example | |
966 @end defun | |
967 | |
968 @defun user-uid | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
969 This function returns the effective @acronym{UID} of the user. |
51918
9fbd3ef3087d
(User Identification): user-uid, user-real-uid can return float.
Richard M. Stallman <rms@gnu.org>
parents:
50654
diff
changeset
|
970 The value may be a floating point number. |
6558 | 971 @end defun |
972 | |
973 @node Time of Day | |
974 @section Time of Day | |
975 | |
976 This section explains how to determine the current time and the time | |
977 zone. | |
978 | |
979 @defun current-time-string &optional time-value | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
980 This function returns the current time and date as a human-readable |
6558 | 981 string. The format of the string is unvarying; the number of characters |
982 used for each part is always the same, so you can reliably use | |
12098 | 983 @code{substring} to extract pieces of it. It is wise to count the |
984 characters from the beginning of the string rather than from the end, as | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
985 additional information may some day be added at the end. |
6558 | 986 |
987 @c Emacs 19 feature | |
988 The argument @var{time-value}, if given, specifies a time to format | |
12098 | 989 instead of the current time. The argument should be a list whose first |
990 two elements are integers. Thus, you can use times obtained from | |
991 @code{current-time} (see below) and from @code{file-attributes} | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
992 (@pxref{Definition of file-attributes}). @var{time-value} can also be |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
993 a cons of two integers, but this is considered obsolete. |
6558 | 994 |
995 @example | |
996 @group | |
997 (current-time-string) | |
998 @result{} "Wed Oct 14 22:21:05 1987" | |
999 @end group | |
1000 @end example | |
1001 @end defun | |
1002 | |
1003 @c Emacs 19 feature | |
1004 @defun current-time | |
1005 This function returns the system's time value as a list of three | |
1006 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers | |
1007 @var{high} and @var{low} combine to give the number of seconds since | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1008 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is |
27193 | 1009 @ifnottex |
6558 | 1010 @var{high} * 2**16 + @var{low}. |
27193 | 1011 @end ifnottex |
6558 | 1012 @tex |
9009 | 1013 $high*2^{16}+low$. |
6558 | 1014 @end tex |
1015 | |
1016 The third element, @var{microsec}, gives the microseconds since the | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1017 start of the current second (or 0 for systems that return time with |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1018 the resolution of only one second). |
6558 | 1019 |
1020 The first two elements can be compared with file time values such as you | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1021 get with the function @code{file-attributes}. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1022 @xref{Definition of file-attributes}. |
6558 | 1023 @end defun |
1024 | |
1025 @c Emacs 19 feature | |
1026 @defun current-time-zone &optional time-value | |
1027 This function returns a list describing the time zone that the user is | |
1028 in. | |
1029 | |
1030 The value has the form @code{(@var{offset} @var{name})}. Here | |
1031 @var{offset} is an integer giving the number of seconds ahead of UTC | |
1032 (east of Greenwich). A negative value means west of Greenwich. The | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1033 second element, @var{name}, is a string giving the name of the time |
6558 | 1034 zone. Both elements change when daylight savings time begins or ends; |
1035 if the user has specified a time zone that does not use a seasonal time | |
1036 adjustment, then the value is constant through time. | |
1037 | |
1038 If the operating system doesn't supply all the information necessary to | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1039 compute the value, the unknown elements of the list are @code{nil}. |
6558 | 1040 |
1041 The argument @var{time-value}, if given, specifies a time to analyze | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1042 instead of the current time. The argument should have the same form |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1043 as for @code{current-time-string} (see above). Thus, you can use |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1044 times obtained from @code{current-time} (see above) and from |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1045 @code{file-attributes}. @xref{Definition of file-attributes}. |
12067 | 1046 @end defun |
1047 | |
53433
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1048 @defun set-time-zone-rule tz |
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1049 This function specifies the local time zone according to @var{tz}. If |
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1050 @var{tz} is @code{nil}, that means to use an implementation-defined |
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1051 default time zone. If @var{tz} is @code{t}, that means to use |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1052 Universal Time. Otherwise, @var{tz} should be a string specifying a |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1053 time zone rule. |
53433
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1054 @end defun |
5bf3c4457aa3
(Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents:
52978
diff
changeset
|
1055 |
39202
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1056 @defun float-time &optional time-value |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1057 This function returns the current time as a floating-point number of |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1058 seconds since the epoch. The argument @var{time-value}, if given, |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1059 specifies a time to convert instead of the current time. The argument |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1060 should have the same form as for @code{current-time-string} (see |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1061 above). Thus, it accepts the output of @code{current-time} and |
39202
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1062 @code{file-attributes}. |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1063 |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1064 @emph{Warning}: Since the result is floating point, it may not be |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1065 exact. Do not use this function if precise time stamps are required. |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1066 @end defun |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1067 |
12067 | 1068 @node Time Conversion |
1069 @section Time Conversion | |
1070 | |
1071 These functions convert time values (lists of two or three integers) | |
1072 to strings or to calendrical information. There is also a function to | |
1073 convert calendrical information to a time value. You can get time | |
1074 values from the functions @code{current-time} (@pxref{Time of Day}) and | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1075 @code{file-attributes} (@pxref{Definition of file-attributes}). |
12067 | 1076 |
15778
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1077 Many operating systems are limited to time values that contain 32 bits |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1078 of information; these systems typically handle only the times from |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1079 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1080 operating systems have larger time values, and can represent times far |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1081 in the past or future. |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1082 |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1083 Time conversion functions always use the Gregorian calendar, even for |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1084 dates before the Gregorian calendar was introduced. Year numbers count |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1085 the number of years since the year 1 B.C., and do not skip zero as |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1086 traditional Gregorian years do; for example, the year number @minus{}37 |
15778
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1087 represents the Gregorian year 38 B.C@. |
c96cee4f8be8
Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents:
15762
diff
changeset
|
1088 |
43037
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1089 @defun date-to-time string |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1090 This function parses the time-string @var{string} and returns the |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1091 corresponding time value. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1092 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1093 |
26242 | 1094 @defun format-time-string format-string &optional time universal |
1095 This function converts @var{time} (or the current time, if @var{time} is | |
1096 omitted) to a string according to @var{format-string}. The argument | |
1097 @var{format-string} may contain @samp{%}-sequences which say to | |
1098 substitute parts of the time. Here is a table of what the | |
1099 @samp{%}-sequences mean: | |
12067 | 1100 |
1101 @table @samp | |
1102 @item %a | |
1103 This stands for the abbreviated name of the day of week. | |
1104 @item %A | |
1105 This stands for the full name of the day of week. | |
1106 @item %b | |
1107 This stands for the abbreviated name of the month. | |
1108 @item %B | |
1109 This stands for the full name of the month. | |
1110 @item %c | |
1111 This is a synonym for @samp{%x %X}. | |
1112 @item %C | |
12098 | 1113 This has a locale-specific meaning. In the default locale (named C), it |
1114 is equivalent to @samp{%A, %B %e, %Y}. | |
12067 | 1115 @item %d |
1116 This stands for the day of month, zero-padded. | |
1117 @item %D | |
1118 This is a synonym for @samp{%m/%d/%y}. | |
1119 @item %e | |
1120 This stands for the day of month, blank-padded. | |
1121 @item %h | |
1122 This is a synonym for @samp{%b}. | |
1123 @item %H | |
1124 This stands for the hour (00-23). | |
1125 @item %I | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1126 This stands for the hour (01-12). |
12067 | 1127 @item %j |
1128 This stands for the day of the year (001-366). | |
1129 @item %k | |
1130 This stands for the hour (0-23), blank padded. | |
1131 @item %l | |
1132 This stands for the hour (1-12), blank padded. | |
1133 @item %m | |
1134 This stands for the month (01-12). | |
1135 @item %M | |
1136 This stands for the minute (00-59). | |
1137 @item %n | |
1138 This stands for a newline. | |
1139 @item %p | |
1140 This stands for @samp{AM} or @samp{PM}, as appropriate. | |
1141 @item %r | |
1142 This is a synonym for @samp{%I:%M:%S %p}. | |
1143 @item %R | |
1144 This is a synonym for @samp{%H:%M}. | |
1145 @item %S | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1146 This stands for the seconds (00-59). |
12067 | 1147 @item %t |
1148 This stands for a tab character. | |
1149 @item %T | |
1150 This is a synonym for @samp{%H:%M:%S}. | |
1151 @item %U | |
1152 This stands for the week of the year (01-52), assuming that weeks | |
1153 start on Sunday. | |
1154 @item %w | |
1155 This stands for the numeric day of week (0-6). Sunday is day 0. | |
1156 @item %W | |
1157 This stands for the week of the year (01-52), assuming that weeks | |
1158 start on Monday. | |
1159 @item %x | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1160 This has a locale-specific meaning. In the default locale (named |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1161 @samp{C}), it is equivalent to @samp{%D}. |
12067 | 1162 @item %X |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1163 This has a locale-specific meaning. In the default locale (named |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1164 @samp{C}), it is equivalent to @samp{%T}. |
12067 | 1165 @item %y |
1166 This stands for the year without century (00-99). | |
1167 @item %Y | |
1168 This stands for the year with century. | |
1169 @item %Z | |
1170 This stands for the time zone abbreviation. | |
1171 @end table | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1172 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1173 You can also specify the field width and type of padding for any of |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1174 these @samp{%}-sequences. This works as in @code{printf}: you write |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1175 the field width as digits in the middle of a @samp{%}-sequences. If you |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1176 start the field width with @samp{0}, it means to pad with zeros. If you |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1177 start the field width with @samp{_}, it means to pad with spaces. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1178 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1179 For example, @samp{%S} specifies the number of seconds since the minute; |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1180 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1181 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1182 because that is how @samp{%S} normally pads to two positions. |
26242 | 1183 |
1184 The characters @samp{E} and @samp{O} act as modifiers when used between | |
1185 @samp{%} and one of the letters in the table above. @samp{E} specifies | |
26288 | 1186 using the current locale's ``alternative'' version of the date and time. |
1187 In a Japanese locale, for example, @code{%Ex} might yield a date format | |
1188 based on the Japanese Emperors' reigns. @samp{E} is allowed in | |
1189 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and | |
1190 @samp{%EY}. | |
26242 | 1191 |
26288 | 1192 @samp{O} means to use the current locale's ``alternative'' |
1193 representation of numbers, instead of the ordinary decimal digits. This | |
1194 is allowed with most letters, all the ones that output numbers. | |
26242 | 1195 |
1196 If @var{universal} is non-@code{nil}, that means to describe the time as | |
1197 Universal Time; @code{nil} means describe it using what Emacs believes | |
1198 is the local time zone (see @code{current-time-zone}). | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1199 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1200 This function uses the C library function @code{strftime} to do most of |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1201 the work. In order to communicate with that function, it first encodes |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1202 its argument using the coding system specified by |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1203 @code{locale-coding-system} (@pxref{Locales}); after @code{strftime} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1204 returns the resulting string, @code{format-time-string} decodes the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
26288
diff
changeset
|
1205 string using that same coding system. |
12067 | 1206 @end defun |
1207 | |
43037
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1208 @defun seconds-to-time seconds |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1209 This function converts @var{seconds}, a floating point number of |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1210 seconds since the epoch, to a time value and returns that. To perform |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1211 the inverse conversion, use @code{float-time}. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1212 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1213 |
51992
8a1df18a9368
(Time Conversion): decode-time arg is optional.
Richard M. Stallman <rms@gnu.org>
parents:
51918
diff
changeset
|
1214 @defun decode-time &optional time |
8a1df18a9368
(Time Conversion): decode-time arg is optional.
Richard M. Stallman <rms@gnu.org>
parents:
51918
diff
changeset
|
1215 This function converts a time value into calendrical information. If |
8a1df18a9368
(Time Conversion): decode-time arg is optional.
Richard M. Stallman <rms@gnu.org>
parents:
51918
diff
changeset
|
1216 you don't specify @var{time}, it decodes the current time. The return |
8a1df18a9368
(Time Conversion): decode-time arg is optional.
Richard M. Stallman <rms@gnu.org>
parents:
51918
diff
changeset
|
1217 value is a list of nine elements, as follows: |
12067 | 1218 |
1219 @example | |
1220 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) | |
1221 @end example | |
1222 | |
1223 Here is what the elements mean: | |
1224 | |
1225 @table @var | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1226 @item seconds |
12067 | 1227 The number of seconds past the minute, as an integer between 0 and 59. |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1228 On some operating systems, this is 60 for leap seconds. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1229 @item minutes |
12067 | 1230 The number of minutes past the hour, as an integer between 0 and 59. |
1231 @item hour | |
1232 The hour of the day, as an integer between 0 and 23. | |
1233 @item day | |
1234 The day of the month, as an integer between 1 and 31. | |
1235 @item month | |
1236 The month of the year, as an integer between 1 and 12. | |
1237 @item year | |
1238 The year, an integer typically greater than 1900. | |
1239 @item dow | |
1240 The day of week, as an integer between 0 and 6, where 0 stands for | |
1241 Sunday. | |
1242 @item dst | |
1243 @code{t} if daylight savings time is effect, otherwise @code{nil}. | |
1244 @item zone | |
12098 | 1245 An integer indicating the time zone, as the number of seconds east of |
1246 Greenwich. | |
12067 | 1247 @end table |
1248 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1249 @strong{Common Lisp Note:} Common Lisp has different meanings for |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1250 @var{dow} and @var{zone}. |
12067 | 1251 @end defun |
1252 | |
27765
277138d0f9f1
Remove @dots from encode-time header.
Dave Love <fx@gnu.org>
parents:
27370
diff
changeset
|
1253 @defun encode-time seconds minutes hour day month year &optional zone |
12067 | 1254 This function is the inverse of @code{decode-time}. It converts seven |
12098 | 1255 items of calendrical data into a time value. For the meanings of the |
1256 arguments, see the table above under @code{decode-time}. | |
12067 | 1257 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1258 Year numbers less than 100 are not treated specially. If you want them |
27370
70846ee19545
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27353
diff
changeset
|
1259 to stand for years above 1900, or years above 2000, you must alter them |
70846ee19545
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27353
diff
changeset
|
1260 yourself before you call @code{encode-time}. |
12067 | 1261 |
1262 The optional argument @var{zone} defaults to the current time zone and | |
1263 its daylight savings time rules. If specified, it can be either a list | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1264 (as you would get from @code{current-time-zone}), a string as in the |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1265 @code{TZ} environment variable, @code{t} for Universal Time, or an |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1266 integer (as you would get from @code{decode-time}). The specified |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1267 zone is used without any further alteration for daylight savings time. |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1268 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1269 If you pass more than seven arguments to @code{encode-time}, the first |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1270 six are used as @var{seconds} through @var{year}, the last argument is |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1271 used as @var{zone}, and the arguments in between are ignored. This |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1272 feature makes it possible to use the elements of a list returned by |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1273 @code{decode-time} as the arguments to @code{encode-time}, like this: |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1274 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1275 @example |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1276 (apply 'encode-time (decode-time @dots{})) |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1277 @end example |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1278 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1279 You can perform simple date arithmetic by using out-of-range values for |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1280 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1281 arguments; for example, day 0 means the day preceding the given month. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1282 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1283 The operating system puts limits on the range of possible time values; |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1284 if you try to encode a time that is out of range, an error results. |
52189
8cec82e55147
(Time Conversion): For encode-time, explain limits on year.
Richard M. Stallman <rms@gnu.org>
parents:
51992
diff
changeset
|
1285 For instance, years before 1970 do not work on some systems; |
8cec82e55147
(Time Conversion): For encode-time, explain limits on year.
Richard M. Stallman <rms@gnu.org>
parents:
51992
diff
changeset
|
1286 on others, years as early as 1901 do work. |
6558 | 1287 @end defun |
1288 | |
57989
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1289 @node Processor Run Time |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1290 @section Processor Run time |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1291 |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1292 @defun get-internal-run-time |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1293 This function returns the processor run time used by Emacs as a list |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1294 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1295 integers @var{high} and @var{low} combine to give the number of |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1296 seconds, which is |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1297 @ifnottex |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1298 @var{high} * 2**16 + @var{low}. |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1299 @end ifnottex |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1300 @tex |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1301 $high*2^{16}+low$. |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1302 @end tex |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1303 |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1304 The third element, @var{microsec}, gives the microseconds (or 0 for |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1305 systems that return time with the resolution of only one second). |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1306 |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1307 If the system doesn't provide a way to determine the processor run |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1308 time, get-internal-run-time returns the same time as current-time. |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1309 @end defun |
2f160b3f3283
(Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents:
56617
diff
changeset
|
1310 |
43037
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1311 @node Time Calculations |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1312 @section Time Calculations |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1313 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1314 These functions perform calendrical computations using time values |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1315 (the kind of list that @code{current-time} returns). |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1316 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1317 @defun time-less-p t1 t2 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1318 This returns @code{t} if time value @var{t1} is less than time value |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1319 @var{t2}. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1320 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1321 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1322 @defun time-subtract t1 t2 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1323 This returns the time difference @var{t1} @minus{} @var{t2} between |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1324 two time values, in the same format as a time value. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1325 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1326 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1327 @defun time-add t1 t2 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1328 This returns the sum of two time values, one of which ought to |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1329 represent a time difference rather than a point in time. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1330 Here is how to add a number of seconds to a time value: |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1331 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1332 @example |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1333 (time-add @var{time} (seconds-to-time @var{seconds})) |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1334 @end example |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1335 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1336 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1337 @defun time-to-days time |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1338 This function returns the number of days between the beginning of year |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1339 1 and @var{time}. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1340 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1341 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1342 @defun time-to-day-in-year time |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1343 This returns the day number within the year corresponding to @var{time}. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1344 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1345 |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1346 @defun date-leap-year-p year |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1347 This function returns @code{t} if @var{year} is a leap year. |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1348 @end defun |
2f863ec2724c
Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents:
40311
diff
changeset
|
1349 |
6558 | 1350 @node Timers |
12098 | 1351 @section Timers for Delayed Execution |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1352 @cindex timer |
6558 | 1353 |
50654
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1354 You can set up a @dfn{timer} to call a function at a specified |
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1355 future time or after a certain length of idleness. |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1356 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1357 Emacs cannot run timers at any arbitrary point in a Lisp program; it |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1358 can run them only when Emacs could accept output from a subprocess: |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1359 namely, while waiting or inside certain primitive functions such as |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1360 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1361 timer's execution may be delayed if Emacs is busy. However, the time of |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1362 execution is very precise if Emacs is idle. |
6558 | 1363 |
50654
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1364 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer |
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1365 function, because quitting out of many timer functions can leave |
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1366 things in an inconsistent state. This is normally unproblematical |
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1367 because most timer functions don't do a lot of work. Indeed, for a |
54037 | 1368 timer to call a function that takes substantial time to run is likely |
50654
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1369 to be annoying. |
07caa9606def
(Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents:
50475
diff
changeset
|
1370 |
59270
08777d10acff
(Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents:
59190
diff
changeset
|
1371 It is usually a bad idea for timer functions to alter buffer |
08777d10acff
(Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents:
59190
diff
changeset
|
1372 contents. When they do, they usually should call @code{undo-boundary} |
08777d10acff
(Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents:
59190
diff
changeset
|
1373 both before and after changing the buffer, to separate the timer's |
08777d10acff
(Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents:
59190
diff
changeset
|
1374 changes from user commands' changes. |
59190
6142d449ffb8
(Timers): Discuss timers vs editing the buffer and undo.
Richard M. Stallman <rms@gnu.org>
parents:
57989
diff
changeset
|
1375 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1376 @deffn Command run-at-time time repeat function &rest args |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1377 This sets up a timer that calls the function @var{function} with |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1378 arguments @var{args} at time @var{time}. If @var{repeat} is a number |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1379 (integer or floating point), the timer also runs every @var{repeat} |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1380 seconds after that. If @var{repeat} is @code{nil}, the timer runs |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1381 only once. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1382 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1383 @var{time} may specify an absolute or a relative time. |
6558 | 1384 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1385 Absolute times may be specified in a wide variety of formats; this |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1386 function tries to accept all the commonly used date formats. The most |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1387 convenient formats are strings. Valid such formats include these two, |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1388 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1389 @example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1390 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1391 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1392 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1393 @end example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1394 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1395 @noindent |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1396 where in both examples all fields are numbers; the format that |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1397 @code{current-time-string} returns is also allowed, and many others |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1398 as well. |
6558 | 1399 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1400 To specify a relative time as a string, use numbers followed by units. |
6558 | 1401 For example: |
1402 | |
1403 @table @samp | |
1404 @item 1 min | |
1405 denotes 1 minute from now. | |
1406 @item 1 min 5 sec | |
1407 denotes 65 seconds from now. | |
1408 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year | |
1409 denotes exactly 103 months, 123 days, and 10862 seconds from now. | |
1410 @end table | |
1411 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1412 For relative time values, Emacs considers a month to be exactly thirty |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1413 days, and a year to be exactly 365.25 days. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1414 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1415 Not all convenient formats are strings. If @var{time} is a number |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1416 (integer or floating point), that specifies a relative time measured |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1417 in seconds. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1418 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1419 In most cases, @var{repeat} has no effect on when @emph{first} call |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1420 takes place---@var{time} alone specifies that. There is one exception: |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1421 if @var{time} is @code{t}, then the timer runs whenever the time is a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1422 multiple of @var{repeat} seconds after the epoch. This is useful for |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1423 functions like @code{display-time}. |
9009 | 1424 |
1425 The function @code{run-at-time} returns a timer value that identifies | |
1426 the particular scheduled future action. You can use this value to call | |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1427 @code{cancel-timer} (see below). |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1428 @end deffn |
6558 | 1429 |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1430 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1431 Execute @var{body}, but give up after @var{seconds} seconds. If |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1432 @var{body} finishes before the time is up, @code{with-timeout} returns |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1433 the value of the last form in @var{body}. If, however, the execution of |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1434 @var{body} is cut short by the timeout, then @code{with-timeout} |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1435 executes all the @var{timeout-forms} and returns the value of the last |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1436 of them. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1437 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1438 This macro works by setting a timer to run after @var{seconds} seconds. If |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1439 @var{body} finishes before that time, it cancels the timer. If the |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1440 timer actually runs, it terminates execution of @var{body}, then |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1441 executes @var{timeout-forms}. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1442 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1443 Since timers can run within a Lisp program only when the program calls a |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1444 primitive that can wait, @code{with-timeout} cannot stop executing |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1445 @var{body} while it is in the midst of a computation---only when it |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1446 calls one of those primitives. So use @code{with-timeout} only with a |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1447 @var{body} that waits for input, not one that does a long computation. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1448 @end defmac |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1449 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1450 The function @code{y-or-n-p-with-timeout} provides a simple way to use |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1451 a timer to avoid waiting too long for an answer. @xref{Yes-or-No |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1452 Queries}. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1453 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1454 @deffn Command run-with-idle-timer secs repeat function &rest args |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1455 Set up a timer which runs when Emacs has been idle for @var{secs} |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1456 seconds. The value of @var{secs} may be an integer or a floating point |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1457 number. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1458 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1459 If @var{repeat} is @code{nil}, the timer runs just once, the first time |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1460 Emacs remains idle for a long enough time. More often @var{repeat} is |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1461 non-@code{nil}, which means to run the timer @emph{each time} Emacs |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1462 remains idle for @var{secs} seconds. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1463 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1464 The function @code{run-with-idle-timer} returns a timer value which you |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1465 can use in calling @code{cancel-timer} (see below). |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1466 @end deffn |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1467 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1468 @cindex idleness |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1469 Emacs becomes ``idle'' when it starts waiting for user input, and it |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1470 remains idle until the user provides some input. If a timer is set for |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1471 five seconds of idleness, it runs approximately five seconds after Emacs |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1472 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1473 will not run again as long as Emacs remains idle, because the duration |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1474 of idleness will continue to increase and will not go down to five |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1475 seconds again. |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1476 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1477 Emacs can do various things while idle: garbage collect, autosave or |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1478 handle data from a subprocess. But these interludes during idleness do |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1479 not interfere with idle timers, because they do not reset the clock of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1480 idleness to zero. An idle timer set for 600 seconds will run when ten |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1481 minutes have elapsed since the last user command was finished, even if |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1482 subprocess output has been accepted thousands of times within those ten |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1483 minutes, and even if there have been garbage collections and autosaves. |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1484 |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1485 When the user supplies input, Emacs becomes non-idle while executing the |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1486 input. Then it becomes idle again, and all the idle timers that are |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1487 set up to repeat will subsequently run another time, one by one. |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1488 |
6558 | 1489 @defun cancel-timer timer |
1490 Cancel the requested action for @var{timer}, which should be a value | |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1491 previously returned by @code{run-at-time} or @code{run-with-idle-timer}. |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1492 This cancels the effect of that call to one of these functions; the |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1493 arrival of the specified time will not cause anything special to happen. |
6558 | 1494 @end defun |
1495 | |
1496 @node Terminal Input | |
1497 @section Terminal Input | |
1498 @cindex terminal input | |
1499 | |
1500 This section describes functions and variables for recording or | |
1501 manipulating terminal input. See @ref{Display}, for related | |
1502 functions. | |
1503 | |
1504 @menu | |
1505 * Input Modes:: Options for how input is processed. | |
1506 * Translating Input:: Low level conversion of some characters or events | |
1507 into others. | |
1508 * Recording Input:: Saving histories of recent or all input events. | |
1509 @end menu | |
1510 | |
1511 @node Input Modes | |
1512 @subsection Input Modes | |
1513 @cindex input modes | |
1514 @cindex terminal input modes | |
1515 | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1516 @defun set-input-mode interrupt flow meta &optional quit-char |
6558 | 1517 This function sets the mode for reading keyboard input. If |
1518 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1519 @code{nil}, then it uses @sc{cbreak} mode. The default setting is |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1520 system-dependent. Some systems always use @sc{cbreak} mode regardless |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1521 of what is specified. |
6558 | 1522 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1523 When Emacs communicates directly with X, it ignores this argument and |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1524 uses interrupts if that is the way it knows how to communicate. |
6558 | 1525 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1526 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1527 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1528 has no effect except in @sc{cbreak} mode. @xref{Flow Control}. |
6558 | 1529 |
1530 @c Emacs 19 feature | |
1531 The argument @var{meta} controls support for input character codes | |
1532 above 127. If @var{meta} is @code{t}, Emacs converts characters with | |
1533 the 8th bit set into Meta characters. If @var{meta} is @code{nil}, | |
1534 Emacs disregards the 8th bit; this is necessary when the terminal uses | |
1535 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, | |
1536 Emacs uses all 8 bits of input unchanged. This is good for terminals | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1537 that use 8-bit character sets. |
6558 | 1538 |
1539 @c Emacs 19 feature | |
1540 If @var{quit-char} is non-@code{nil}, it specifies the character to | |
1541 use for quitting. Normally this character is @kbd{C-g}. | |
1542 @xref{Quitting}. | |
1543 @end defun | |
1544 | |
1545 The @code{current-input-mode} function returns the input mode settings | |
1546 Emacs is currently using. | |
1547 | |
1548 @c Emacs 19 feature | |
1549 @defun current-input-mode | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1550 This function returns the current mode for reading keyboard input. It |
6558 | 1551 returns a list, corresponding to the arguments of @code{set-input-mode}, |
1552 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in | |
1553 which: | |
1554 @table @var | |
1555 @item interrupt | |
1556 is non-@code{nil} when Emacs is using interrupt-driven input. If | |
1557 @code{nil}, Emacs is using @sc{cbreak} mode. | |
1558 @item flow | |
1559 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1560 flow control for output to the terminal. This value is meaningful only |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1561 when @var{interrupt} is @code{nil}. |
6558 | 1562 @item meta |
12098 | 1563 is @code{t} if Emacs treats the eighth bit of input characters as |
6558 | 1564 the meta bit; @code{nil} means Emacs clears the eighth bit of every |
1565 input character; any other value means Emacs uses all eight bits as the | |
1566 basic character code. | |
1567 @item quit | |
1568 is the character Emacs currently uses for quitting, usually @kbd{C-g}. | |
1569 @end table | |
1570 @end defun | |
1571 | |
1572 @node Translating Input | |
1573 @subsection Translating Input Events | |
1574 @cindex translating input events | |
1575 | |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1576 This section describes features for translating input events into |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1577 other input events before they become part of key sequences. These |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1578 features apply to each event in the order they are described here: each |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1579 event is first modified according to @code{extra-keyboard-modifiers}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1580 then translated through @code{keyboard-translate-table} (if applicable), |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1581 and finally decoded with the specified keyboard coding system. If it is |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1582 being read as part of a key sequence, it is then added to the sequence |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1583 being read; then subsequences containing it are checked first with |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1584 @code{function-key-map} and then with @code{key-translation-map}. |
6558 | 1585 |
1586 @c Emacs 19 feature | |
1587 @defvar extra-keyboard-modifiers | |
1588 This variable lets Lisp programs ``press'' the modifier keys on the | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1589 keyboard. The value is a character. Only the modifiers of the |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1590 character matter. Each time the user types a keyboard key, it is |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1591 altered as if those modifier keys were held down. For instance, if |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1592 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1593 keyboard input characters typed during the scope of the binding will |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1594 have the control and meta modifiers applied to them. The character |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1595 @code{?\C-@@}, equivalent to the integer 0, does not count as a control |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1596 character for this purpose, but as a character with no modifiers. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1597 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1598 modification. |
6558 | 1599 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1600 When using a window system, the program can ``press'' any of the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1601 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1602 keys can be virtually pressed. |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1603 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1604 Note that this variable applies only to events that really come from |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1605 the keyboard, and has no effect on mouse events or any other events. |
6558 | 1606 @end defvar |
1607 | |
1608 @defvar keyboard-translate-table | |
1609 This variable is the translate table for keyboard characters. It lets | |
1610 you reshuffle the keys on the keyboard without changing any command | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1611 bindings. Its value is normally a char-table, or else @code{nil}. |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1612 (It can also be a string or vector, but this is considered obsolete.) |
6558 | 1613 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1614 If @code{keyboard-translate-table} is a char-table |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1615 (@pxref{Char-Tables}), then each character read from the keyboard is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1616 looked up in this char-table. If the value found there is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1617 non-@code{nil}, then it is used instead of the actual input character. |
6558 | 1618 |
1619 In the example below, we set @code{keyboard-translate-table} to a | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1620 char-table. Then we fill it in to swap the characters @kbd{C-s} and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1621 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1622 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice |
25479 | 1623 versa. (@xref{Flow Control}, for more information on this subject.) |
6558 | 1624 |
1625 @cindex flow control example | |
1626 @example | |
1627 @group | |
1628 (defun evade-flow-control () | |
1629 "Replace C-s with C-\ and C-q with C-^." | |
1630 (interactive) | |
1631 @end group | |
1632 @group | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1633 (setq keyboard-translate-table |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1634 (make-char-table 'keyboard-translate-table nil)) |
6558 | 1635 @end group |
1636 @group | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1637 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1638 (aset keyboard-translate-table ?\034 ?\^s) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1639 (aset keyboard-translate-table ?\^s ?\034) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1640 @end group |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1641 @group |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1642 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1643 (aset keyboard-translate-table ?\036 ?\^q) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1644 (aset keyboard-translate-table ?\^q ?\036)) |
6558 | 1645 @end group |
1646 @end example | |
1647 | |
1648 Note that this translation is the first thing that happens to a | |
1649 character after it is read from the terminal. Record-keeping features | |
1650 such as @code{recent-keys} and dribble files record the characters after | |
1651 translation. | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1652 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1653 Note also that this translation is done before the characters are |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1654 supplied to input methods (@pxref{Input Methods}). Use |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1655 @code{translation-table-for-input} (@pxref{Translation of Characters}), |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1656 if you want to translate characters after input methods operate. |
6558 | 1657 @end defvar |
1658 | |
1659 @defun keyboard-translate from to | |
1660 This function modifies @code{keyboard-translate-table} to translate | |
1661 character code @var{from} into character code @var{to}. It creates | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1662 the keyboard translate table if necessary. |
6558 | 1663 @end defun |
1664 | |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1665 The remaining translation features translate subsequences of key |
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1666 sequences being read. They are implemented in @code{read-key-sequence} |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1667 and have no effect on input read with @code{read-event}. |
15762
9305e83c313d
Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents:
13367
diff
changeset
|
1668 |
6558 | 1669 @defvar function-key-map |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1670 This variable holds a keymap that describes the character sequences sent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1671 by function keys on an ordinary character terminal. This keymap has the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1672 same structure as other keymaps, but is used differently: it specifies |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1673 translations to make while reading key sequences, rather than bindings |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1674 for key sequences. |
6558 | 1675 |
1676 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector | |
1677 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a | |
1678 key sequence, it is replaced with the events in @var{v}. | |
1679 | |
1680 For example, VT100 terminals send @kbd{@key{ESC} O P} when the | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1681 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate |
6558 | 1682 that sequence of events into the single event @code{pf1}. We accomplish |
1683 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in | |
1684 @code{function-key-map}, when using a VT100. | |
1685 | |
1686 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c | |
1687 @key{ESC} O P}; later the function @code{read-key-sequence} translates | |
1688 this back into @kbd{C-c @key{PF1}}, which it returns as the vector | |
1689 @code{[?\C-c pf1]}. | |
1690 | |
1691 Entries in @code{function-key-map} are ignored if they conflict with | |
1692 bindings made in the minor mode, local, or global keymaps. The intent | |
1693 is that the character sequences that function keys send should not have | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1694 command bindings in their own right---but if they do, the ordinary |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1695 bindings take priority. |
6558 | 1696 |
1697 The value of @code{function-key-map} is usually set up automatically | |
1698 according to the terminal's Terminfo or Termcap entry, but sometimes | |
1699 those need help from terminal-specific Lisp files. Emacs comes with | |
1700 terminal-specific files for many common terminals; their main purpose is | |
1701 to make entries in @code{function-key-map} beyond those that can be | |
1702 deduced from Termcap and Terminfo. @xref{Terminal-Specific}. | |
1703 @end defvar | |
1704 | |
1705 @defvar key-translation-map | |
1706 This variable is another keymap used just like @code{function-key-map} | |
1707 to translate input events into other events. It differs from | |
1708 @code{function-key-map} in two ways: | |
1709 | |
1710 @itemize @bullet | |
1711 @item | |
1712 @code{key-translation-map} goes to work after @code{function-key-map} is | |
1713 finished; it receives the results of translation by | |
1714 @code{function-key-map}. | |
1715 | |
1716 @item | |
56617
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1717 Non-prefix bindings in @code{key-translation-map} override actual key |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1718 bindings. For example, if @kbd{C-x f} has a non-prefix binding in |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1719 @code{key-translation-map}, that translation takes effect even though |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1720 @kbd{C-x f} also has a key binding in the global map. |
6558 | 1721 @end itemize |
1722 | |
56617
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1723 Note however that actual key bindings can have an effect on |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1724 @code{key-translation-map}, even though they are overridden by it. |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1725 Indeed, actual key bindings override @code{function-key-map} and thus |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1726 may alter the key sequence that @code{key-translation-map} receives. |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1727 Clearly, it is better to avoid to avoid this type of situation. |
8685ad649821
(Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents:
56369
diff
changeset
|
1728 |
6558 | 1729 The intent of @code{key-translation-map} is for users to map one |
1730 character set to another, including ordinary characters normally bound | |
1731 to @code{self-insert-command}. | |
1732 @end defvar | |
1733 | |
1734 @cindex key translation function | |
1735 You can use @code{function-key-map} or @code{key-translation-map} for | |
1736 more than simple aliases, by using a function, instead of a key | |
1737 sequence, as the ``translation'' of a key. Then this function is called | |
1738 to compute the translation of that key. | |
1739 | |
1740 The key translation function receives one argument, which is the prompt | |
1741 that was specified in @code{read-key-sequence}---or @code{nil} if the | |
1742 key sequence is being read by the editor command loop. In most cases | |
1743 you can ignore the prompt value. | |
1744 | |
1745 If the function reads input itself, it can have the effect of altering | |
1746 the event that follows. For example, here's how to define @kbd{C-c h} | |
1747 to turn the character that follows into a Hyper character: | |
1748 | |
1749 @example | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1750 @group |
6558 | 1751 (defun hyperify (prompt) |
1752 (let ((e (read-event))) | |
1753 (vector (if (numberp e) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
1754 (logior (lsh 1 24) e) |
6558 | 1755 (if (memq 'hyper (event-modifiers e)) |
1756 e | |
1757 (add-event-modifier "H-" e)))))) | |
1758 | |
1759 (defun add-event-modifier (string e) | |
1760 (let ((symbol (if (symbolp e) e (car e)))) | |
1761 (setq symbol (intern (concat string | |
1762 (symbol-name symbol)))) | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1763 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1764 @group |
6558 | 1765 (if (symbolp e) |
1766 symbol | |
1767 (cons symbol (cdr e))))) | |
1768 | |
1769 (define-key function-key-map "\C-ch" 'hyperify) | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1770 @end group |
6558 | 1771 @end example |
1772 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1773 Finally, if you have enabled keyboard character set decoding using |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1774 @code{set-keyboard-coding-system}, decoding is done after the |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1775 translations listed above. @xref{Terminal I/O Encoding}. In future |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1776 Emacs versions, character set decoding may be done before the other |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1777 translations. |
6558 | 1778 |
1779 @node Recording Input | |
1780 @subsection Recording Input | |
1781 | |
1782 @defun recent-keys | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1783 This function returns a vector containing the last 100 input events from |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1784 the keyboard or mouse. All input events are included, whether or not |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1785 they were used as parts of key sequences. Thus, you always get the last |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1786 100 input events, not counting events generated by keyboard macros. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1787 (These are excluded because they are less interesting for debugging; it |
9009 | 1788 should be enough to see the events that invoked the macros.) |
39202
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1789 |
557aaff6fb23
(Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents:
36873
diff
changeset
|
1790 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) |
39221
68b26e98aef6
Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents:
39202
diff
changeset
|
1791 causes this function to return an empty vector immediately afterward. |
6558 | 1792 @end defun |
1793 | |
26242 | 1794 @deffn Command open-dribble-file filename |
6558 | 1795 @cindex dribble file |
1796 This function opens a @dfn{dribble file} named @var{filename}. When a | |
1797 dribble file is open, each input event from the keyboard or mouse (but | |
1798 not those from keyboard macros) is written in that file. A | |
1799 non-character event is expressed using its printed representation | |
1800 surrounded by @samp{<@dots{}>}. | |
1801 | |
1802 You close the dribble file by calling this function with an argument | |
1803 of @code{nil}. | |
1804 | |
1805 This function is normally used to record the input necessary to | |
1806 trigger an Emacs bug, for the sake of a bug report. | |
1807 | |
1808 @example | |
1809 @group | |
1810 (open-dribble-file "~/dribble") | |
1811 @result{} nil | |
1812 @end group | |
1813 @end example | |
1814 @end deffn | |
1815 | |
1816 See also the @code{open-termscript} function (@pxref{Terminal Output}). | |
1817 | |
1818 @node Terminal Output | |
1819 @section Terminal Output | |
1820 @cindex terminal output | |
1821 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1822 The terminal output functions send output to the terminal, or keep |
6558 | 1823 track of output sent to the terminal. The variable @code{baud-rate} |
1824 tells you what Emacs thinks is the output speed of the terminal. | |
1825 | |
1826 @defvar baud-rate | |
1827 This variable's value is the output speed of the terminal, as far as | |
1828 Emacs knows. Setting this variable does not change the speed of actual | |
1829 data transmission, but the value is used for calculations such as | |
1830 padding. It also affects decisions about whether to scroll part of the | |
9009 | 1831 screen or repaint---even when using a window system. (We designed it |
6558 | 1832 this way despite the fact that a window system has no true ``output |
1833 speed'', to give you a way to tune these decisions.) | |
1834 | |
1835 The value is measured in baud. | |
1836 @end defvar | |
1837 | |
1838 If you are running across a network, and different parts of the | |
1839 network work at different baud rates, the value returned by Emacs may be | |
1840 different from the value used by your local terminal. Some network | |
1841 protocols communicate the local terminal speed to the remote machine, so | |
1842 that Emacs and other programs can get the proper value, but others do | |
1843 not. If Emacs has the wrong value, it makes decisions that are less | |
1844 than optimal. To fix the problem, set @code{baud-rate}. | |
1845 | |
1846 @defun baud-rate | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1847 This obsolete function returns the value of the variable |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1848 @code{baud-rate}. |
6558 | 1849 @end defun |
1850 | |
1851 @defun send-string-to-terminal string | |
1852 This function sends @var{string} to the terminal without alteration. | |
1853 Control characters in @var{string} have terminal-dependent effects. | |
1854 | |
1855 One use of this function is to define function keys on terminals that | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1856 have downloadable function key definitions. For example, this is how (on |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1857 certain terminals) to define function key 4 to move forward four |
6558 | 1858 characters (by transmitting the characters @kbd{C-u C-f} to the |
1859 computer): | |
1860 | |
1861 @example | |
1862 @group | |
1863 (send-string-to-terminal "\eF4\^U\^F") | |
1864 @result{} nil | |
1865 @end group | |
1866 @end example | |
1867 @end defun | |
1868 | |
1869 @deffn Command open-termscript filename | |
1870 @cindex termscript file | |
1871 This function is used to open a @dfn{termscript file} that will record | |
1872 all the characters sent by Emacs to the terminal. It returns | |
1873 @code{nil}. Termscript files are useful for investigating problems | |
1874 where Emacs garbles the screen, problems that are due to incorrect | |
1875 Termcap entries or to undesirable settings of terminal options more | |
1876 often than to actual Emacs bugs. Once you are certain which characters | |
1877 were actually output, you can determine reliably whether they correspond | |
1878 to the Termcap specifications in use. | |
1879 | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1880 You close the termscript file by calling this function with an |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1881 argument of @code{nil}. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1882 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
1883 See also @code{open-dribble-file} in @ref{Recording Input}. |
6558 | 1884 |
1885 @example | |
1886 @group | |
1887 (open-termscript "../junk/termscript") | |
1888 @result{} nil | |
1889 @end group | |
1890 @end example | |
1891 @end deffn | |
1892 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1893 @node Sound Output |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1894 @section Sound Output |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1895 @cindex sound |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1896 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1897 To play sound using Emacs, use the function @code{play-sound}. Only |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1898 certain systems are supported; if you call @code{play-sound} on a system |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1899 which cannot really do the job, it gives an error. Emacs version 20 and |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1900 earlier did not support sound at all. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1901 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1902 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1903 or Sun Audio format (@samp{.au}). |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1904 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1905 @tindex play-sound |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1906 @defun play-sound sound |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1907 This function plays a specified sound. The argument, @var{sound}, has |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1908 the form @code{(sound @var{properties}...)}, where the @var{properties} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1909 consist of alternating keywords (particular symbols recognized |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1910 specially) and values corresponding to them. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1911 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1912 Here is a table of the keywords that are currently meaningful in |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1913 @var{sound}, and their meanings: |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1914 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1915 @table @code |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1916 @item :file @var{file} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1917 This specifies the file containing the sound to play. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1918 If the file name is not absolute, it is expanded against |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1919 the directory @code{data-directory}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1920 |
27259
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
1921 @item :data @var{data} |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
1922 This specifies the sound to play without need to refer to a file. The |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
1923 value, @var{data}, should be a string containing the same bytes as a |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
1924 sound file. We recommend using a unibyte string. |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
1925 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1926 @item :volume @var{volume} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1927 This specifies how loud to play the sound. It should be a number in the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1928 range of 0 to 1. The default is to use whatever volume has been |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1929 specified before. |
33951
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1930 |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1931 @item :device @var{device} |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1932 This specifies the system device on which to play the sound, as a |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1933 string. The default device is system-dependent. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1934 @end table |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1935 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1936 Before actually playing the sound, @code{play-sound} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1937 calls the functions in the list @code{play-sound-functions}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1938 Each function is called with one argument, @var{sound}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1939 @end defun |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1940 |
33951
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1941 @defun play-sound-file file &optional volume device |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1942 @tindex play-sound-file |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1943 This function is an alternative interface to playing a sound @var{file} |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1944 specifying an optional @var{volume} and @var{device}. |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1945 @end defun |
ac7551c36926
Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents:
32924
diff
changeset
|
1946 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1947 @tindex play-sound-functions |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1948 @defvar play-sound-functions |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1949 A list of functions to be called before playing a sound. Each function |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1950 is called with one argument, a property list that describes the sound. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1951 @end defvar |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1952 |
46228 | 1953 @node X11 Keysyms |
1954 @section Operating on X11 Keysyms | |
6558 | 1955 |
1956 To define system-specific X11 keysyms, set the variable | |
1957 @code{system-key-alist}. | |
1958 | |
1959 @defvar system-key-alist | |
1960 This variable's value should be an alist with one element for each | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1961 system-specific keysym. Each element has the form @code{(@var{code} |
6558 | 1962 . @var{symbol})}, where @var{code} is the numeric keysym code (not |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
1963 including the ``vendor specific'' bit, |
27193 | 1964 @ifnottex |
24934 | 1965 -2**28), |
27193 | 1966 @end ifnottex |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
1967 @tex |
24934 | 1968 $-2^{28}$), |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1969 @end tex |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1970 and @var{symbol} is the name for the function key. |
6558 | 1971 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1972 For example @code{(168 . mute-acute)} defines a system-specific key (used |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
1973 by HP X servers) whose numeric code is |
27193 | 1974 @ifnottex |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1975 -2**28 |
27193 | 1976 @end ifnottex |
49549
99be3a1e2589
Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents:
47870
diff
changeset
|
1977 @tex |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1978 $-2^{28}$ |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1979 @end tex |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1980 + 168. |
6558 | 1981 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1982 It is not crucial to exclude from the alist the keysyms of other X |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1983 servers; those do no harm, as long as they don't conflict with the ones |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1984 used by the X server actually in use. |
12067 | 1985 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1986 The variable is always local to the current terminal, and cannot be |
12067 | 1987 buffer-local. @xref{Multiple Displays}. |
6558 | 1988 @end defvar |
1989 | |
46228 | 1990 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: |
1991 | |
1992 @defvar x-alt-keysym | |
1993 @defvarx x-meta-keysym | |
1994 @defvarx x-hyper-keysym | |
1995 @defvarx x-super-keysym | |
1996 The name of the keysym that should stand for the Alt modifier | |
1997 (respectively, for Meta, Hyper, and Super). For example, here is | |
1998 how to swap the Meta and Alt modifiers within Emacs: | |
1999 @lisp | |
2000 (setq x-alt-keysym 'meta) | |
2001 (setq x-meta-keysym 'alt) | |
2002 @end lisp | |
2003 @end defvar | |
2004 | |
6558 | 2005 @node Flow Control |
2006 @section Flow Control | |
2007 @cindex flow control characters | |
2008 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2009 This section attempts to answer the question ``Why does Emacs use |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2010 flow-control characters in its command character set?'' For a second |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2011 view on this issue, read the comments on flow control in the |
6558 | 2012 @file{emacs/INSTALL} file from the distribution; for help with Termcap |
2013 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}. | |
2014 | |
2015 @cindex @kbd{C-s} | |
2016 @cindex @kbd{C-q} | |
2017 At one time, most terminals did not need flow control, and none used | |
2018 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2019 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2020 was natural and uncontroversial. With so many commands needing key |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52842
diff
changeset
|
2021 assignments, of course we assigned meanings to nearly all @acronym{ASCII} |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2022 control characters. |
6558 | 2023 |
2024 Later, some terminals were introduced which required these characters | |
2025 for flow control. They were not very good terminals for full-screen | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2026 editing, so Emacs maintainers ignored them. In later years, flow |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2027 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2028 but by this time it was usually an option. And the majority of Emacs |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2029 users, who can turn flow control off, did not want to switch to less |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2030 mnemonic key bindings for the sake of flow control. |
6558 | 2031 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2032 So which usage is ``right''---Emacs's or that of some terminal and |
6558 | 2033 concentrator manufacturers? This question has no simple answer. |
2034 | |
2035 One reason why we are reluctant to cater to the problems caused by | |
2036 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other | |
2037 techniques (albeit less common in practice) for flow control that | |
2038 preserve transparency of the character stream. Note also that their use | |
2039 for flow control is not an official standard. Interestingly, on the | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2040 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2041 @kbd{C-q} were sent by the computer to turn the punch on and off! |
6558 | 2042 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2043 As window systems and PC terminal emulators replace character-only |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2044 terminals, the flow control problem is gradually disappearing. For the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2045 mean time, Emacs provides a convenient way of enabling flow control if |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2046 you want it: call the function @code{enable-flow-control}. |
6558 | 2047 |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2048 @deffn Command enable-flow-control &optional arg |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2049 When @var{arg} is a positive integer, this function enables use of |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2050 @kbd{C-s} and @kbd{C-q} for output flow control, and provides the |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2051 characters @kbd{C-\} and @kbd{C-^} as aliases for them using |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2052 @code{keyboard-translate-table} (@pxref{Translating Input}). |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2053 |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2054 When @var{arg} is a negative integer or zero, it disables these |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2055 features. When @var{arg} is @code{nil} or omitted, it toggles. |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2056 Interactively, @var{arg} is the prefix argument. If non-@code{nil}, |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2057 its numeric value is used. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
20103
diff
changeset
|
2058 @end deffn |
6558 | 2059 |
2060 You can use the function @code{enable-flow-control-on} in your | |
25875 | 2061 init file to enable flow control automatically on certain |
6558 | 2062 terminal types. |
2063 | |
2064 @defun enable-flow-control-on &rest termtypes | |
2065 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^}, | |
2066 if the terminal type is one of @var{termtypes}. For example: | |
2067 | |
2068 @smallexample | |
2069 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") | |
2070 @end smallexample | |
2071 @end defun | |
2072 | |
2073 Here is how @code{enable-flow-control} does its job: | |
2074 | |
2075 @enumerate | |
2076 @item | |
2077 @cindex @sc{cbreak} | |
2078 It sets @sc{cbreak} mode for terminal input, and tells the operating | |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2079 system to handle flow control. This is done using @code{set-input-mode}. |
6558 | 2080 |
2081 @item | |
2082 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and | |
9009 | 2083 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very |
6558 | 2084 lowest level, Emacs never knows that the characters typed were anything |
2085 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\} | |
2086 and @kbd{C-^} even when they are input for other commands. | |
2087 @xref{Translating Input}. | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
2088 @end enumerate |
6558 | 2089 |
2090 If the terminal is the source of the flow control characters, then once | |
2091 you enable kernel flow control handling, you probably can make do with | |
2092 less padding than normal for that terminal. You can reduce the amount | |
2093 of padding by customizing the Termcap entry. You can also reduce it by | |
2094 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller | |
2095 speed when calculating the padding needed. @xref{Terminal Output}. | |
2096 | |
2097 @node Batch Mode | |
2098 @section Batch Mode | |
2099 @cindex batch mode | |
2100 @cindex noninteractive use | |
2101 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
2102 The command-line option @samp{-batch} causes Emacs to run |
6558 | 2103 noninteractively. In this mode, Emacs does not read commands from the |
2104 terminal, it does not alter the terminal modes, and it does not expect | |
2105 to be outputting to an erasable screen. The idea is that you specify | |
2106 Lisp programs to run; when they are finished, Emacs should exit. The | |
2107 way to specify the programs to run is with @samp{-l @var{file}}, which | |
2108 loads the library named @var{file}, and @samp{-f @var{function}}, which | |
2109 calls @var{function} with no arguments. | |
2110 | |
2111 Any Lisp program output that would normally go to the echo area, | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25479
diff
changeset
|
2112 either using @code{message}, or using @code{prin1}, etc., with @code{t} |
12098 | 2113 as the stream, goes instead to Emacs's standard error descriptor when |
36873 | 2114 in batch mode. Similarly, input that would normally come from the |
2115 minibuffer is read from the standard input descriptor. | |
2116 Thus, Emacs behaves much like a noninteractive | |
6558 | 2117 application program. (The echo area output that Emacs itself normally |
2118 generates, such as command echoing, is suppressed entirely.) | |
2119 | |
2120 @defvar noninteractive | |
2121 This variable is non-@code{nil} when Emacs is running in batch mode. | |
2122 @end defvar | |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2123 |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2124 @node Session Management |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2125 @section Session Management |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2126 @cindex session manager |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2127 |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2128 Emacs supports the X Session Management Protocol for suspension and |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2129 restart of applications. In the X Window System, a program called the |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2130 @dfn{session manager} has the responsibility to keep track of the |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2131 applications that are running. During shutdown, the session manager |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2132 asks applications to save their state, and delays the actual shutdown |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2133 until they respond. An application can also cancel the shutdown. |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2134 |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2135 When the session manager restarts a suspended session, it directs |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2136 these applications to individually reload their saved state. It does |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2137 this by specifying a special command-line argument that says what |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2138 saved session to restore. For Emacs, this argument is @samp{--smid |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2139 @var{session}}. |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2140 |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2141 @defvar emacs-save-session-functions |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2142 @tindex emacs-save-session-functions |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2143 Emacs supports saving state by using a hook called |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2144 @code{emacs-save-session-functions}. Each function in this hook is |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2145 called when the session manager tells Emacs that the window system is |
56369
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2146 shutting down. The functions are called with no arguments and with the |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2147 current buffer set to a temporary buffer. Each function can use |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2148 @code{insert} to add Lisp code to this buffer. At the end, Emacs |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2149 saves the buffer in a file that a subsequent Emacs invocation will |
6578797626ea
Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
56353
diff
changeset
|
2150 load in order to restart the saved session. |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2151 |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2152 If a function in @code{emacs-save-session-functions} returns |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2153 non-@code{nil}, Emacs tells the session manager to cancel the |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2154 shutdown. |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2155 @end defvar |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2156 |
56353 | 2157 Here is an example that just inserts some text into @samp{*scratch*} when |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2158 Emacs is restarted by the session manager. |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2159 |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2160 @example |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2161 @group |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2162 (add-hook 'emacs-save-session-functions 'save-yourself-test) |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2163 @end group |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2164 |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2165 @group |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2166 (defun save-yourself-test () |
43829
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2167 (insert "(save-excursion |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2168 (switch-to-buffer \"*scratch*\") |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2169 (insert \"I am restored\"))") |
7e937c00ff00
Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents:
43822
diff
changeset
|
2170 nil) |
43822
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2171 @end group |
340b4384f4ac
(Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents:
43037
diff
changeset
|
2172 @end example |
52401 | 2173 |
2174 @ignore | |
2175 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7 | |
2176 @end ignore |