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