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