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