Fix previous fix of Bug#5849.
[emacs.git] / doc / lispref / os.texi
blob7d05f8f346824abb54cd0583e1d3b97b18d3d6d5
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4 @c   Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/os
7 @node System Interface, Packaging, Display, 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.  @xref{Display}, for
15 additional operating system status information pertaining to the
16 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
25                           calendrical data and vice versa.
26 * Time Parsing::        Converting a time from numeric form to text
27                           and vice versa.
28 * Processor Run Time::  Getting the run time used by Emacs.
29 * Time Calculations::   Adding, subtracting, comparing times, etc.
30 * Timers::              Setting a timer to call a function at a certain time.
31 * Idle Timers::         Setting a timer to call a function when Emacs has
32                           been idle for a certain length of time.
33 * Terminal Input::      Accessing and recording terminal input.
34 * Terminal Output::     Controlling and recording terminal output.
35 * Sound Output::        Playing sounds on the computer's speaker.
36 * X11 Keysyms::         Operating on key symbols for X Windows.
37 * Batch Mode::          Running Emacs without terminal interaction.
38 * Session Management::  Saving and restoring state with X Session Management.
39 * Dynamic Libraries::   On-demand loading of support libraries.
40 @end menu
42 @node Starting Up
43 @section Starting Up Emacs
45   This section describes what Emacs does when it is started, and how you
46 can customize these actions.
48 @menu
49 * Startup Summary::         Sequence of actions Emacs performs at startup.
50 * Init File::               Details on reading the init file.
51 * Terminal-Specific::       How the terminal-specific Lisp file is read.
52 * Command-Line Arguments::  How command-line arguments are processed,
53                               and how you can customize them.
54 @end menu
56 @node Startup Summary
57 @subsection Summary: Sequence of Actions at Startup
58 @cindex initialization of Emacs
59 @cindex startup of Emacs
60 @cindex @file{startup.el}
62   When Emacs is started up, it performs the following operations
63 (which are defined in @file{startup.el}):
65 @enumerate
66 @item
67 It adds subdirectories to @code{load-path}, by running the file named
68 @file{subdirs.el} in each directory in the list.  Normally, this file
69 adds the directory's subdirectories to the list, and those are scanned
70 in their turn.  The files @file{subdirs.el} are normally generated
71 automatically when Emacs is installed.
73 @vindex before-init-time
74 @item
75 It sets the variable @code{before-init-time} to the value of
76 @code{current-time} (@pxref{Time of Day}).  It also sets
77 @code{after-init-time} to @code{nil}, which signals to Lisp programs
78 that Emacs is being initialized.
80 @vindex initial-window-system@r{, and startup}
81 @vindex window-system-initialization-alist
82 @item
83 It loads the initialization library for the window system specified by
84 the variable @code{initial-window-system} (@pxref{Window Systems,
85 initial-window-system}).  This library's name is
86 @file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
87 value of @code{initial-window-system}.  From that library, it calls
88 the appropriate initialization function.  The initialization function
89 for each supported window system is specified by
90 @code{window-system-initialization-alist}.
92 @item
93 It sets the language environment and the terminal coding system,
94 if requested by environment variables such as @code{LANG}.
96 @item
97 It processes the initial options.  (Some of them are handled
98 even earlier than this.)
100 @item
101 It runs the normal hook @code{before-init-hook}.
103 @item
104 It initializes the window frame and faces, if appropriate, and turns
105 on the menu bar and tool bar, if the initial frame needs them.
107 @item
108 It loads the library @file{site-start}, if it exists.  This is not
109 done if the options @samp{-Q} or @samp{--no-site-file} were specified.
110 @cindex @file{site-start.el}
112 @item
113 It loads your init file (@pxref{Init File}).  This is not done if the
114 options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified.  If
115 the @samp{-u} option was specified, Emacs looks for the init file in
116 that user's home directory instead.
118 @item
119 It loads the library @file{default}, if it exists.  This is not done
120 if @code{inhibit-default-init} is non-@code{nil}, nor if the options
121 @samp{-q}, @samp{-Q}, or @samp{--batch} were specified.
122 @cindex @file{default.el}
124 @item
125 It loads your abbrevs from the file specified by
126 @code{abbrev-file-name}, if that file exists and can be read
127 (@pxref{Abbrev Files, abbrev-file-name}).  This is not done if the
128 option @samp{--batch} was specified.
130 @vindex after-init-time
131 @item
132 It sets the variable @code{after-init-time} to the value of
133 @code{current-time}.  This variable was set to @code{nil} earlier;
134 setting it to the current time signals that the initialization phase
135 is over, and, together with @code{before-init-time}, provides the
136 measurement of how long it took.
138 @item
139 It runs the normal hook @code{after-init-hook}.
141 @item
142 If the buffer @samp{*scratch*} exists and is still in Fundamental mode
143 (as it should be by default), it sets its major mode according to
144 @code{initial-major-mode}.
146 @item
147 If started on a text-only terminal, it loads the terminal-specific
148 Lisp library, which is specified by the variable
149 @code{term-file-prefix} (@pxref{Terminal-Specific}).  This is not done
150 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
152 @item
153 It displays the initial echo area message, unless you have suppressed
154 that with @code{inhibit-startup-echo-area-message}.
156 @item
157 It processes the action arguments from the command line.
159 @item
160 It now exits if the option @code{--batch} was specified.
162 @item
163 If @code{initial-buffer-choice} is a string, it visits the file with
164 that name.  Furthermore, if the @samp{*scratch*} buffer exists and is
165 empty, it inserts @code{initial-scratch-message} into that buffer.
167 @item
168 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
170 @item
171 It calls @code{frame-notice-user-settings}, which modifies the
172 parameters of the selected frame according to whatever the init files
173 specify.
175 @item
176 It runs @code{window-setup-hook}.  @xref{Window Systems}.
178 @item
179 If the option @code{--daemon} was specified, it calls
180 @code{server-start} and detaches from the controlling terminal.
181 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
183 @item
184 It displays the @dfn{startup screen}, which is a special buffer that
185 contains information about copyleft and basic Emacs usage.  This is
186 not done if @code{initial-buffer-choice} or
187 @code{inhibit-startup-screen} are @code{nil}, nor if the
188 @samp{--no-splash} or @samp{-Q} command-line options were specified.
190 @item
191 If started by the X session manager, it calls
192 @code{emacs-session-restore} passing it as argument the ID of the
193 previous session.  @xref{Session Management}.
194 @end enumerate
196 @defopt inhibit-startup-screen
197 This variable, if non-@code{nil}, inhibits the startup screen.  In
198 that case, Emacs typically displays the @samp{*scratch*} buffer; but
199 see @code{initial-buffer-choice}, below.
201 Do not set this variable in the init file of a new user, or in a way
202 that affects more than one user, as that would prevent new users from
203 receiving information about copyleft and basic Emacs usage.
205 @vindex inhibit-startup-message
206 @vindex inhibit-splash-screen
207 @code{inhibit-startup-message} and @code{inhibit-splash-screen} are
208 aliases for this variable.
209 @end defopt
211 @defopt initial-buffer-choice
212 This variable, if non-@code{nil}, determines a file or buffer for
213 Emacs to display after starting up, instead of the startup screen.  If
214 its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.  If
215 its value is a string, that specifies the name of a file for Emacs to
216 visit.
217 @end defopt
219 @defopt inhibit-startup-echo-area-message
220 This variable controls the display of the startup echo area message.
221 You can suppress the startup echo area message by adding text with this
222 form to your init file:
224 @example
225 (setq inhibit-startup-echo-area-message
226       "@var{your-login-name}")
227 @end example
229 Emacs explicitly checks for an expression as shown above in your init
230 file; your login name must appear in the expression as a Lisp string
231 constant.  Other methods of setting
232 @code{inhibit-startup-echo-area-message} to the same value do not
233 inhibit the startup message.  This way, you can easily inhibit the
234 message for yourself if you wish, but thoughtless copying of your init
235 file will not inhibit the message for someone else.
236 @end defopt
238 @defopt initial-scratch-message
239 This variable, if non-@code{nil}, should be a string, which is
240 inserted into the @samp{*scratch*} buffer when Emacs starts up.  If it
241 is @code{nil}, the @samp{*scratch*} buffer is empty.
242 @end defopt
244 @node Init File
245 @subsection The Init File, @file{.emacs}
246 @cindex init file
247 @cindex @file{.emacs}
249   When you start Emacs, it normally attempts to load your @dfn{init
250 file}.  This is either a file named @file{.emacs} or @file{.emacs.el}
251 in your home directory, or a file named @file{init.el} in a
252 subdirectory named @file{.emacs.d} in your home directory.  Whichever
253 place you use, you can also compile the file (@pxref{Byte
254 Compilation}); then the actual file loaded will be @file{.emacs.elc}
255 or @file{init.elc}.
257   The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
258 control whether and where to find the init file; @samp{-q} (and the
259 stronger @samp{-Q}) says not to load an init file, while @samp{-u
260 @var{user}} says to load @var{user}'s init file instead of yours.
261 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}.  If neither
262 option is specified, Emacs uses the @code{LOGNAME} environment
263 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
264 systems) variable, to find your home directory and thus your init
265 file; this way, even if you have su'd, Emacs still loads your own init
266 file.  If those environment variables are absent, though, Emacs uses
267 your user-id to find your home directory.
269 @cindex default init file
270   A site may have a @dfn{default init file}, which is the library
271 named @file{default.el}.  Emacs finds the @file{default.el} file
272 through the standard search path for libraries (@pxref{How Programs Do
273 Loading}).  The Emacs distribution does not come with this file; sites
274 may provide one for local customizations.  If the default init file
275 exists, it is loaded whenever you start Emacs, except in batch mode or
276 if @samp{-q} (or @samp{-Q}) is specified.  But your own personal init
277 file, if any, is loaded first; if it sets @code{inhibit-default-init}
278 to a non-@code{nil} value, then Emacs does not subsequently load the
279 @file{default.el} file.
281   Another file for site-customization is @file{site-start.el}.  Emacs
282 loads this @emph{before} the user's init file.  You can inhibit the
283 loading of this file with the option @samp{--no-site-file}.
285 @defopt site-run-file
286 This variable specifies the site-customization file to load before the
287 user's init file.  Its normal value is @code{"site-start"}.  The only
288 way you can change it with real effect is to do so before dumping
289 Emacs.
290 @end defopt
292   @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
293 examples of how to make various commonly desired customizations in your
294 @file{.emacs} file.
296 @defopt inhibit-default-init
297 This variable prevents Emacs from loading the default initialization
298 library file for your session of Emacs.  If its value is non-@code{nil},
299 then the default library is not loaded.  The default value is
300 @code{nil}.
301 @end defopt
303 @defvar before-init-hook
304 This normal hook is run, once, just before loading all the init files
305 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
306 (The only way to change it with real effect is before dumping Emacs.)
307 @end defvar
309 @defvar after-init-hook
310 This normal hook is run, once, just after loading all the init files
311 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
312 before loading the terminal-specific library and processing the
313 command-line action arguments.
314 @end defvar
316 @defvar emacs-startup-hook
317 This normal hook is run, once, just after handling the command line
318 arguments, just before @code{term-setup-hook}.
319 @end defvar
321 @defvar user-init-file
322 This variable holds the absolute file name of the user's init file.  If the
323 actual init file loaded is a compiled file, such as @file{.emacs.elc},
324 the value refers to the corresponding source file.
325 @end defvar
327 @defvar user-emacs-directory
328 This variable holds the name of the @file{.emacs.d} directory.  It is
329 ordinarily @file{~/.emacs.d}, but differs on some platforms.
330 @end defvar
332 @node Terminal-Specific
333 @subsection Terminal-Specific Initialization
334 @cindex terminal-specific initialization
336   Each terminal type can have its own Lisp library that Emacs loads when
337 run on that type of terminal.  The library's name is constructed by
338 concatenating the value of the variable @code{term-file-prefix} and the
339 terminal type (specified by the environment variable @code{TERM}).
340 Normally, @code{term-file-prefix} has the value
341 @code{"term/"}; changing this is not recommended.  Emacs finds the file
342 in the normal manner, by searching the @code{load-path} directories, and
343 trying the @samp{.elc} and @samp{.el} suffixes.
345 @cindex Termcap
346   The usual function of a terminal-specific library is to enable
347 special keys to send sequences that Emacs can recognize.  It may also
348 need to set or add to @code{input-decode-map} if the Termcap or
349 Terminfo entry does not specify all the terminal's function keys.
350 @xref{Terminal Input}.
352   When the name of the terminal type contains a hyphen, and no library
353 is found whose name is identical to the terminal's name, Emacs strips
354 from the terminal's name the last hyphen and everything that follows
355 it, and tries again.  This process is repeated until Emacs finds a
356 matching library or until there are no more hyphens in the name (the
357 latter means the terminal doesn't have any library specific to it).
358 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
359 libraries, Emacs will try the same library @file{term/aaa.el} for
360 terminal types @samp{aaa-48} and @samp{aaa-30-rv}.  If necessary, the
361 library can evaluate @code{(getenv "TERM")} to find the full name of
362 the terminal type.@refill
364   Your init file can prevent the loading of the
365 terminal-specific library by setting the variable
366 @code{term-file-prefix} to @code{nil}.  This feature is useful when
367 experimenting with your own peculiar customizations.
369   You can also arrange to override some of the actions of the
370 terminal-specific library by setting the variable
371 @code{term-setup-hook}.  This is a normal hook which Emacs runs using
372 @code{run-hooks} at the end of Emacs initialization, after loading both
373 your init file and any terminal-specific libraries.  You can
374 use this variable to define initializations for terminals that do not
375 have their own libraries.  @xref{Hooks}.
377 @defvar term-file-prefix
378 @cindex @code{TERM} environment variable
379 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
380 a terminal-specific initialization file as follows:
382 @example
383 (load (concat term-file-prefix (getenv "TERM")))
384 @end example
386 @noindent
387 You may set the @code{term-file-prefix} variable to @code{nil} in your
388 init file if you do not wish to load the
389 terminal-initialization file.  To do this, put the following in
390 your init file: @code{(setq term-file-prefix nil)}.
392 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
393 uses @samp{internal} as the terminal type.
394 @end defvar
396 @defvar term-setup-hook
397 This variable is a normal hook that Emacs runs after loading your
398 init file, the default initialization file (if any) and the
399 terminal-specific Lisp file.
401 You can use @code{term-setup-hook} to override the definitions made by a
402 terminal-specific file.
403 @end defvar
405   See @code{window-setup-hook} in @ref{Window Systems}, for a related
406 feature.
408 @node Command-Line Arguments
409 @subsection Command-Line Arguments
410 @cindex command-line arguments
412   You can use command-line arguments to request various actions when you
413 start Emacs.  Since you do not need to start Emacs more than once per
414 day, and will often leave your Emacs session running longer than that,
415 command-line arguments are hardly ever used.  As a practical matter, it
416 is best to avoid making the habit of using them, since this habit would
417 encourage you to kill and restart Emacs unnecessarily often.  These
418 options exist for two reasons: to be compatible with other editors (for
419 invocation by other programs) and to enable shell scripts to run
420 specific Lisp programs.
422   This section describes how Emacs processes command-line arguments,
423 and how you can customize them.
425 @ignore
426   (Note that some other editors require you to start afresh each time
427 you want to edit a file.  With this kind of editor, you will probably
428 specify the file as a command-line argument.  The recommended way to
429 use GNU Emacs is to start it only once, just after you log in, and do
430 all your editing in the same Emacs process.  Each time you want to edit
431 a different file, you visit it with the existing Emacs, which eventually
432 comes to have many files in it ready for editing.  Usually you do not
433 kill the Emacs until you are about to log out.)
434 @end ignore
436 @defun command-line
437 This function parses the command line that Emacs was called with,
438 processes it, loads the user's init file and displays the
439 startup messages.
440 @end defun
442 @defvar command-line-processed
443 The value of this variable is @code{t} once the command line has been
444 processed.
446 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
447 this variable to @code{nil} first in order to cause the new dumped Emacs
448 to process its new command-line arguments.
449 @end defvar
451 @defvar command-switch-alist
452 @cindex switches on command line
453 @cindex options on command line
454 @cindex command-line options
455 The value of this variable is an alist of user-defined command-line
456 options and associated handler functions.  This variable exists so you
457 can add elements to it.
459 A @dfn{command-line option} is an argument on the command line, which
460 has the form:
462 @example
463 -@var{option}
464 @end example
466 The elements of the @code{command-switch-alist} look like this:
468 @example
469 (@var{option} . @var{handler-function})
470 @end example
472 The @sc{car}, @var{option}, is a string, the name of a command-line
473 option (not including the initial hyphen).  The @var{handler-function}
474 is called to handle @var{option}, and receives the option name as its
475 sole argument.
477 In some cases, the option is followed in the command line by an
478 argument.  In these cases, the @var{handler-function} can find all the
479 remaining command-line arguments in the variable
480 @code{command-line-args-left}.  (The entire list of command-line
481 arguments is in @code{command-line-args}.)
483 The command-line arguments are parsed by the @code{command-line-1}
484 function in the @file{startup.el} file.  See also @ref{Emacs
485 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
486 GNU Emacs Manual}.
487 @end defvar
489 @defvar command-line-args
490 The value of this variable is the list of command-line arguments passed
491 to Emacs.
492 @end defvar
494 @defvar command-line-args-left
495 @vindex argv
496 The value of this variable is the list of command-line arguments that
497 have not yet been processed.  @code{argv} is an alias for this.
498 @end defvar
500 @defvar command-line-functions
501 This variable's value is a list of functions for handling an
502 unrecognized command-line argument.  Each time the next argument to be
503 processed has no special meaning, the functions in this list are called,
504 in order of appearance, until one of them returns a non-@code{nil}
505 value.
507 These functions are called with no arguments.  They can access the
508 command-line argument under consideration through the variable
509 @code{argi}, which is bound temporarily at this point.  The remaining
510 arguments (not including the current one) are in the variable
511 @code{command-line-args-left}.
513 When a function recognizes and processes the argument in @code{argi}, it
514 should return a non-@code{nil} value to say it has dealt with that
515 argument.  If it has also dealt with some of the following arguments, it
516 can indicate that by deleting them from @code{command-line-args-left}.
518 If all of these functions return @code{nil}, then the argument is used
519 as a file name to visit.
520 @end defvar
522 @node Getting Out
523 @section Getting Out of Emacs
524 @cindex exiting Emacs
526   There are two ways to get out of Emacs: you can kill the Emacs job,
527 which exits permanently, or you can suspend it, which permits you to
528 reenter the Emacs process later.  As a practical matter, you seldom kill
529 Emacs---only when you are about to log out.  Suspending is much more
530 common.
532 @menu
533 * Killing Emacs::        Exiting Emacs irreversibly.
534 * Suspending Emacs::     Exiting Emacs reversibly.
535 @end menu
537 @node Killing Emacs
538 @comment  node-name,  next,  previous,  up
539 @subsection Killing Emacs
540 @cindex killing Emacs
542   Killing Emacs means ending the execution of the Emacs process.  The
543 parent process normally resumes control.  The low-level primitive for
544 killing Emacs is @code{kill-emacs}.
546 @deffn Command kill-emacs &optional exit-data
547 This command calls the hook @code{kill-emacs-hook}, then exits the
548 Emacs process and kills it.
550 If @var{exit-data} is an integer, that is used as the exit status of
551 the Emacs process.  (This is useful primarily in batch operation; see
552 @ref{Batch Mode}.)
554 If @var{exit-data} is a string, its contents are stuffed into the
555 terminal input buffer so that the shell (or whatever program next reads
556 input) can read them.
557 @end deffn
559 @cindex SIGTERM
560 @cindex SIGHUP
561 @cindex SIGINT
562 @cindex operating system signal
563   The @code{kill-emacs} function is normally called via the
564 higher-level command @kbd{C-x C-c}
565 (@code{save-buffers-kill-terminal}).  @xref{Exiting,,, emacs, The GNU
566 Emacs Manual}.  It is also called automatically if Emacs receives a
567 @code{SIGTERM} or @code{SIGHUP} operating system signal (e.g. when the
568 controlling terminal is disconnected), or if it receives a
569 @code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}).
571 @defvar kill-emacs-hook
572 This normal hook is run by @code{kill-emacs}, before it kills Emacs.
574 Because @code{kill-emacs} can be called in situations where user
575 interaction is impossible (e.g. when the terminal is disconnected),
576 functions on this hook should not attempt to interact with the user.
577 If you want to interact with the user when Emacs is shutting down, use
578 @code{kill-emacs-query-functions}, described below.
579 @end defvar
581   When Emacs is killed, all the information in the Emacs process,
582 aside from files that have been saved, is lost.  Because killing Emacs
583 inadvertently can lose a lot of work, the
584 @code{save-buffers-kill-terminal} command queries for confirmation if
585 you have buffers that need saving or subprocesses that are running.
586 It also runs the abnormal hook @code{kill-emacs-query-functions}:
588 @defvar kill-emacs-query-functions
589 When @code{save-buffers-kill-terminal} is killing Emacs, it calls the
590 functions in this hook, after asking the standard questions and before
591 calling @code{kill-emacs}.  The functions are called in order of
592 appearance, with no arguments.  Each function can ask for additional
593 confirmation from the user.  If any of them returns @code{nil},
594 @code{save-buffers-kill-emacs} does not kill Emacs, and does not run
595 the remaining functions in this hook.  Calling @code{kill-emacs}
596 directly does not run this hook.
597 @end defvar
599 @node Suspending Emacs
600 @subsection Suspending Emacs
601 @cindex suspending Emacs
603   On text-only terminals, it is possible to @dfn{suspend Emacs}, which
604 means stopping Emacs temporarily and returning control to its superior
605 process, which is usually the shell.  This allows you to resume
606 editing later in the same Emacs process, with the same buffers, the
607 same kill ring, the same undo history, and so on.  To resume Emacs,
608 use the appropriate command in the parent shell---most likely
609 @code{fg}.
611 @cindex controlling terminal
612   Suspending works only on a terminal device from which the Emacs
613 session was started.  We call that device the @dfn{controlling
614 terminal} of the session.  Suspending is not allowed if the
615 controlling terminal is a graphical terminal.
617   Some operating systems do not support suspension of jobs; on these
618 systems, ``suspension'' actually creates a new shell temporarily as a
619 subprocess of Emacs.  Then you would exit the shell to return to Emacs.
621 @deffn Command suspend-emacs &optional string
622 This function stops Emacs and returns control to the superior process.
623 If and when the superior process resumes Emacs, @code{suspend-emacs}
624 returns @code{nil} to its caller in Lisp.
626 This function works only on the controlling terminal of the Emacs
627 session; to relinquish control of other tty devices, use
628 @code{suspend-tty} (see below).  If the Emacs session uses more than
629 one terminal, you must delete the frames on all the other terminals
630 before suspending Emacs, or this function signals an error.
631 @xref{Multiple Terminals}.
633 If @var{string} is non-@code{nil}, its characters are sent to Emacs's
634 superior shell, to be read as terminal input.  The characters in
635 @var{string} are not echoed by the superior shell; only the results
636 appear.
638 Before suspending, @code{suspend-emacs} runs the normal hook
639 @code{suspend-hook}.  After the user resumes Emacs,
640 @code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}.
641 @xref{Hooks}.
643 The next redisplay after resumption will redraw the entire screen,
644 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}.
645 @xref{Refresh Screen}.
647 In the following example, note that @samp{pwd} is not echoed after
648 Emacs is suspended.  But it is read and executed by the shell.
650 @smallexample
651 @group
652 (suspend-emacs)
653      @result{} nil
654 @end group
656 @group
657 (add-hook 'suspend-hook
658           (function (lambda ()
659                       (or (y-or-n-p
660                             "Really suspend? ")
661                           (error "Suspend canceled")))))
662      @result{} (lambda nil
663           (or (y-or-n-p "Really suspend? ")
664               (error "Suspend canceled")))
665 @end group
666 @group
667 (add-hook 'suspend-resume-hook
668           (function (lambda () (message "Resumed!"))))
669      @result{} (lambda nil (message "Resumed!"))
670 @end group
671 @group
672 (suspend-emacs "pwd")
673      @result{} nil
674 @end group
675 @group
676 ---------- Buffer: Minibuffer ----------
677 Really suspend? @kbd{y}
678 ---------- Buffer: Minibuffer ----------
679 @end group
681 @group
682 ---------- Parent Shell ----------
683 lewis@@slug[23] % /user/lewis/manual
684 lewis@@slug[24] % fg
685 @end group
687 @group
688 ---------- Echo Area ----------
689 Resumed!
690 @end group
691 @end smallexample
692 @end deffn
694 @defvar suspend-hook
695 This variable is a normal hook that Emacs runs before suspending.
696 @end defvar
698 @defvar suspend-resume-hook
699 This variable is a normal hook that Emacs runs on resuming
700 after a suspension.
701 @end defvar
703 @defun suspend-tty &optional tty
704 If @var{tty} specifies a terminal device used by Emacs, this function
705 relinquishes the device and restores it to its prior state.  Frames
706 that used the device continue to exist, but are not updated and Emacs
707 doesn't read input from them.  @var{tty} can be a terminal object, a
708 frame (meaning the terminal for that frame), or @code{nil} (meaning
709 the terminal for the selected frame).  @xref{Multiple Terminals}.
711 If @var{tty} is already suspended, this function does nothing.
713 @vindex suspend-tty-functions
714 This function runs the hook @code{suspend-tty-functions}, passing the
715 terminal object as an argument to each function.
716 @end defun
718 @defun resume-tty &optional tty
719 This function resumes the previously suspended terminal device
720 @var{tty}; @var{tty} can be a terminal object, a frame (meaning the
721 terminal for that frame), or @code{nil} (meaning the terminal for the
722 selected frame).
724 @vindex resume-tty-functions
725 This function reopens the terminal device, re-initializes it, and
726 redraws its with that terminal's selected frame.  It then runs the
727 hook @code{resume-tty-functions}, passing the terminal object as an
728 argument to each function.
730 If the same device is already used by another Emacs terminal, this
731 function signals an error.
732 @end defun
734 @defun controlling-tty-p &optional terminal
735 This function returns non-@code{nil} if @var{terminal} is the
736 controlling terminal of the Emacs session; @code{terminal} can be a
737 terminal object, a frame (meaning the terminal for that frame), or
738 @code{nil} (meaning the terminal for the selected frame).
739 @end defun
741 @deffn Command suspend-frame
742 This command @dfn{suspends} a frame.  For GUI frames, it calls
743 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
744 frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
745 depending on whether the frame is displayed on the controlling
746 terminal device or not.
747 @end deffn
749 @node System Environment
750 @section Operating System Environment
751 @cindex operating system environment
753   Emacs provides access to variables in the operating system environment
754 through various functions.  These variables include the name of the
755 system, the user's @acronym{UID}, and so on.
757 @defvar system-configuration
758 This variable holds the standard GNU configuration name for the
759 hardware/software configuration of your system, as a string.  The
760 convenient way to test parts of this string is with
761 @code{string-match}.
762 @end defvar
764 @cindex system type and name
765 @defvar system-type
766 The value of this variable is a symbol indicating the type of operating
767 system Emacs is operating on.  Here is a table of the possible values:
769 @table @code
770 @item aix
771 IBM's AIX.
773 @item berkeley-unix
774 Berkeley BSD and its variants.
776 @item cygwin
777 Cygwin, a Posix layer on top of MS-Windows.
779 @item darwin
780 Darwin (Mac OS X).
782 @item gnu
783 The GNU system (using the GNU kernel, which consists of the HURD and Mach).
785 @item gnu/linux
786 A GNU/Linux system---that is, a variant GNU system, using the Linux
787 kernel.  (These systems are the ones people often call ``Linux,'' but
788 actually Linux is just the kernel, not the whole system.)
790 @item gnu/kfreebsd
791 A GNU (glibc-based) system with a FreeBSD kernel.
793 @item hpux
794 Hewlett-Packard HPUX operating system.
796 @item irix
797 Silicon Graphics Irix system.
799 @item ms-dos
800 Microsoft MS-DOS ``operating system.''  Emacs compiled with DJGPP for
801 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
802 MS-Windows.
804 @item usg-unix-v
805 AT&T Unix System V.
807 @item windows-nt
808 Microsoft Windows NT and later.  The same executable supports Windows
809 9X, but the value of @code{system-type} is @code{windows-nt} in either
810 case.
812 @end table
814 We do not wish to add new symbols to make finer distinctions unless it
815 is absolutely necessary!  In fact, we hope to eliminate some of these
816 alternatives in the future.  We recommend using
817 @code{system-configuration} to distinguish between different operating
818 systems.
819 @end defvar
821 @defun system-name
822 This function returns the name of the machine you are running on.
823 @example
824 (system-name)
825      @result{} "www.gnu.org"
826 @end example
827 @end defun
829   The symbol @code{system-name} is a variable as well as a function.  In
830 fact, the function returns whatever value the variable
831 @code{system-name} currently holds.  Thus, you can set the variable
832 @code{system-name} in case Emacs is confused about the name of your
833 system.  The variable is also useful for constructing frame titles
834 (@pxref{Frame Titles}).
836 @defopt mail-host-address
837 If this variable is non-@code{nil}, it is used instead of
838 @code{system-name} for purposes of generating email addresses.  For
839 example, it is used when constructing the default value of
840 @code{user-mail-address}.  @xref{User Identification}.  (Since this is
841 done when Emacs starts up, the value actually used is the one saved when
842 Emacs was dumped.  @xref{Building Emacs}.)
843 @end defopt
845 @deffn Command getenv var &optional frame
846 @cindex environment variable access
847 This function returns the value of the environment variable @var{var},
848 as a string.  @var{var} should be a string.  If @var{var} is undefined
849 in the environment, @code{getenv} returns @code{nil}.  If returns
850 @samp{""} if @var{var} is set but null.  Within Emacs, the environment
851 variable values are kept in the Lisp variable @code{process-environment}.
853 @example
854 @group
855 (getenv "USER")
856      @result{} "lewis"
857 @end group
859 @group
860 lewis@@slug[10] % printenv
861 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
862 USER=lewis
863 @end group
864 @group
865 TERM=ibmapa16
866 SHELL=/bin/csh
867 HOME=/user/lewis
868 @end group
869 @end example
870 @end deffn
872 @c Emacs 19 feature
873 @deffn Command setenv variable &optional value
874 This command sets the value of the environment variable named
875 @var{variable} to @var{value}.  @var{variable} should be a string.
876 Internally, Emacs Lisp can handle any string.  However, normally
877 @var{variable} should be a valid shell identifier, that is, a sequence
878 of letters, digits and underscores, starting with a letter or
879 underscore.  Otherwise, errors may occur if subprocesses of Emacs try
880 to access the value of @var{variable}.  If @var{value} is omitted or
881 @code{nil}, @code{setenv} removes @var{variable} from the environment.
882 Otherwise, @var{value} should be a string.
884 @code{setenv} works by modifying @code{process-environment}; binding
885 that variable with @code{let} is also reasonable practice.
887 @code{setenv} returns the new value of @var{variable}, or @code{nil}
888 if it removed @var{variable} from the environment.
889 @end deffn
891 @defvar process-environment
892 This variable is a list of strings, each describing one environment
893 variable.  The functions @code{getenv} and @code{setenv} work by means
894 of this variable.
896 @smallexample
897 @group
898 process-environment
899 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
900     "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
901     "USER=lewis"
902 @end group
903 @group
904     "TERM=ibmapa16"
905     "SHELL=/bin/csh"
906     "HOME=/user/lewis")
907 @end group
908 @end smallexample
910 If @code{process-environment} contains ``duplicate'' elements that
911 specify the same environment variable, the first of these elements
912 specifies the variable, and the other ``duplicates'' are ignored.
913 @end defvar
915 @defvar initial-environment
916 This variable holds the list of environment variables Emacs inherited
917 from its parent process.  It is computed during startup, see
918 @ref{Startup Summary}.
919 @end defvar
921 @defvar path-separator
922 This variable holds a string which says which character separates
923 directories in a search path (as found in an environment variable).  Its
924 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
925 and MS-Windows.
926 @end defvar
928 @defun parse-colon-path path
929 This function takes a search path string such as would be the value of
930 the @code{PATH} environment variable, and splits it at the separators,
931 returning a list of directory names.  @code{nil} in this list stands for
932 ``use the current directory.''  Although the function's name says
933 ``colon,'' it actually uses the value of @code{path-separator}.
935 @example
936 (parse-colon-path ":/foo:/bar")
937      @result{} (nil "/foo/" "/bar/")
938 @end example
939 @end defun
941 @defvar invocation-name
942 This variable holds the program name under which Emacs was invoked.  The
943 value is a string, and does not include a directory name.
944 @end defvar
946 @defvar invocation-directory
947 This variable holds the directory from which the Emacs executable was
948 invoked, or perhaps @code{nil} if that directory cannot be determined.
949 @end defvar
951 @defvar installation-directory
952 If non-@code{nil}, this is a directory within which to look for the
953 @file{lib-src} and @file{etc} subdirectories.  This is non-@code{nil}
954 when Emacs can't find those directories in their standard installed
955 locations, but can find them in a directory related somehow to the one
956 containing the Emacs executable.
957 @end defvar
959 @defun load-average &optional use-float
960 This function returns the current 1-minute, 5-minute, and 15-minute load
961 averages, in a list.
963 By default, the values are integers that are 100 times the system load
964 averages, which indicate the average number of processes trying to run.
965 If @var{use-float} is non-@code{nil}, then they are returned
966 as floating point numbers and without multiplying by 100.
968 If it is impossible to obtain the load average, this function signals
969 an error.  On some platforms, access to load averages requires
970 installing Emacs as setuid or setgid so that it can read kernel
971 information, and that usually isn't advisable.
973 If the 1-minute load average is available, but the 5- or 15-minute
974 averages are not, this function returns a shortened list containing
975 the available averages.
977 @example
978 @group
979 (load-average)
980      @result{} (169 48 36)
981 @end group
982 @group
983 (load-average t)
984      @result{} (1.69 0.48 0.36)
985 @end group
987 @group
988 lewis@@rocky[5] % uptime
989  11:55am  up 1 day, 19:37,  3 users,
990  load average: 1.69, 0.48, 0.36
991 @end group
992 @end example
993 @end defun
995 @defun emacs-pid
996 This function returns the process @acronym{ID} of the Emacs process,
997 as an integer.
998 @end defun
1000 @defvar tty-erase-char
1001 This variable holds the erase character that was selected
1002 in the system's terminal driver, before Emacs was started.
1003 The value is @code{nil} if Emacs is running under a window system.
1004 @end defvar
1006 @node User Identification
1007 @section User Identification
1008 @cindex user identification
1010 @defvar init-file-user
1011 This variable says which user's init files should be used by
1012 Emacs---or @code{nil} if none.  @code{""} stands for the user who
1013 originally logged in.  The value reflects command-line options such as
1014 @samp{-q} or @samp{-u @var{user}}.
1016 Lisp packages that load files of customizations, or any other sort of
1017 user profile, should obey this variable in deciding where to find it.
1018 They should load the profile of the user name found in this variable.
1019 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
1020 option was used, then Lisp packages should not load any customization
1021 files or user profile.
1022 @end defvar
1024 @defopt user-mail-address
1025 This holds the nominal email address of the user who is using Emacs.
1026 Emacs normally sets this variable to a default value after reading your
1027 init files, but not if you have already set it.  So you can set the
1028 variable to some other value in your init file if you do not
1029 want to use the default value.
1030 @end defopt
1032 @defun user-login-name &optional uid
1033 If you don't specify @var{uid}, this function returns the name under
1034 which the user is logged in.  If the environment variable @code{LOGNAME}
1035 is set, that value is used.  Otherwise, if the environment variable
1036 @code{USER} is set, that value is used.  Otherwise, the value is based
1037 on the effective @acronym{UID}, not the real @acronym{UID}.
1039 If you specify @var{uid}, the value is the user name that corresponds
1040 to @var{uid} (which should be an integer), or @code{nil} if there is
1041 no such user.
1043 @example
1044 @group
1045 (user-login-name)
1046      @result{} "lewis"
1047 @end group
1048 @end example
1049 @end defun
1051 @defun user-real-login-name
1052 This function returns the user name corresponding to Emacs's real
1053 @acronym{UID}.  This ignores the effective @acronym{UID} and ignores the
1054 environment variables @code{LOGNAME} and @code{USER}.
1055 @end defun
1057 @defun user-full-name &optional uid
1058 This function returns the full name of the logged-in user---or the value
1059 of the environment variable @code{NAME}, if that is set.
1061 @c "Bil" is the correct spelling.
1062 @example
1063 @group
1064 (user-full-name)
1065      @result{} "Bil Lewis"
1066 @end group
1067 @end example
1069 If the Emacs job's user-id does not correspond to any known user (and
1070 provided @code{NAME} is not set), the value is @code{"unknown"}.
1072 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
1073 or a string (a login name).  Then @code{user-full-name} returns the full
1074 name corresponding to that user-id or login name.  If you specify a
1075 user-id or login name that isn't defined, it returns @code{nil}.
1076 @end defun
1078 @vindex user-full-name
1079 @vindex user-real-login-name
1080 @vindex user-login-name
1081   The symbols @code{user-login-name}, @code{user-real-login-name} and
1082 @code{user-full-name} are variables as well as functions.  The functions
1083 return the same values that the variables hold.  These variables allow
1084 you to ``fake out'' Emacs by telling the functions what to return.  The
1085 variables are also useful for constructing frame titles (@pxref{Frame
1086 Titles}).
1088 @defun user-real-uid
1089 This function returns the real @acronym{UID} of the user.
1090 The value may be a floating point number.
1092 @example
1093 @group
1094 (user-real-uid)
1095      @result{} 19
1096 @end group
1097 @end example
1098 @end defun
1100 @defun user-uid
1101 This function returns the effective @acronym{UID} of the user.
1102 The value may be a floating point number.
1103 @end defun
1105 @node Time of Day
1106 @section Time of Day
1108   This section explains how to determine the current time and the time
1109 zone.
1111 @defun current-time-string &optional time-value
1112 This function returns the current time and date as a human-readable
1113 string.  The format of the string is unvarying; the number of characters
1114 used for each part is always the same, so you can reliably use
1115 @code{substring} to extract pieces of it.  It is wise to count the
1116 characters from the beginning of the string rather than from the end, as
1117 additional information may some day be added at the end.
1119 The argument @var{time-value}, if given, specifies a time to format
1120 instead of the current time.  This argument should have the same form
1121 as the times obtained from @code{current-time} (see below) and from
1122 @code{file-attributes} (@pxref{Definition of file-attributes}).  It
1123 should be a list whose first two elements are integers; a third
1124 (microsecond) element, if present, is ignored.  @var{time-value} can
1125 also be a cons of two integers, but this usage is obsolete.
1127 @example
1128 @group
1129 (current-time-string)
1130      @result{} "Wed Oct 14 22:21:05 1987"
1131 @end group
1132 @end example
1133 @end defun
1135 @defun current-time
1136 This function returns the system's time value as a list of three
1137 integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
1138 @var{high} and @var{low} combine to give the number of seconds since
1139 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1140 @ifnottex
1141 @var{high} * 2**16 + @var{low}.
1142 @end ifnottex
1143 @tex
1144 $high*2^{16}+low$.
1145 @end tex
1147 The third element, @var{microsec}, gives the microseconds since the
1148 start of the current second (or 0 for systems that return time with
1149 the resolution of only one second).
1151 The first two elements can be compared with file time values such as you
1152 get with the function @code{file-attributes}.
1153 @xref{Definition of file-attributes}.
1154 @end defun
1156 @defun float-time &optional time-value
1157 This function returns the current time as a floating-point number of
1158 seconds since the epoch.  The argument @var{time-value}, if given,
1159 specifies a time to convert instead of the current time.  The argument
1160 should have the same form as for @code{current-time-string} (see
1161 above).  Thus, it accepts the output of @code{current-time} and
1162 @code{file-attributes} (@pxref{Definition of file-attributes}).
1164 @emph{Warning}: Since the result is floating point, it may not be
1165 exact.  Do not use this function if precise time stamps are required.
1166 @end defun
1168 @defun current-time-zone &optional time-value
1169 This function returns a list describing the time zone that the user is
1172 The value has the form @code{(@var{offset} @var{name})}.  Here
1173 @var{offset} is an integer giving the number of seconds ahead of UTC
1174 (east of Greenwich).  A negative value means west of Greenwich.  The
1175 second element, @var{name}, is a string giving the name of the time
1176 zone.  Both elements change when daylight saving time begins or ends;
1177 if the user has specified a time zone that does not use a seasonal time
1178 adjustment, then the value is constant through time.
1180 If the operating system doesn't supply all the information necessary to
1181 compute the value, the unknown elements of the list are @code{nil}.
1183 The argument @var{time-value}, if given, specifies a time to analyze
1184 instead of the current time.  The argument should have the same form
1185 as for @code{current-time-string} (see above).  Thus, you can use
1186 times obtained from @code{current-time} (see above) and from
1187 @code{file-attributes}.  @xref{Definition of file-attributes}.
1188 @end defun
1190 The current time zone is determined by the @samp{TZ} environment
1191 variable.  @xref{System Environment}.  For example, you can tell Emacs
1192 to use universal time with @code{(setenv "TZ" "UTC0")}.  If @samp{TZ}
1193 is not in the environment, Emacs uses a platform-dependent default
1194 time zone.
1196 @node Time Conversion
1197 @section Time Conversion
1199   These functions convert time values (lists of two or three integers)
1200 to calendrical information and vice versa.  You can get time values
1201 from the functions @code{current-time} (@pxref{Time of Day}) and
1202 @code{file-attributes} (@pxref{Definition of file-attributes}).
1204   Many 32-bit operating systems are limited to time values that contain 32 bits
1205 of information; these systems typically handle only the times from
1206 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, 64-bit
1207 and some 32-bit operating systems have larger time values, and can
1208 represent times far in the past or future.
1210   Time conversion functions always use the Gregorian calendar, even
1211 for dates before the Gregorian calendar was introduced.  Year numbers
1212 count the number of years since the year 1 B.C., and do not skip zero
1213 as traditional Gregorian years do; for example, the year number
1214 @minus{}37 represents the Gregorian year 38 B.C@.
1216 @defun decode-time &optional time
1217 This function converts a time value into calendrical information.  If
1218 you don't specify @var{time}, it decodes the current time.  The return
1219 value is a list of nine elements, as follows:
1221 @example
1222 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1223 @end example
1225 Here is what the elements mean:
1227 @table @var
1228 @item seconds
1229 The number of seconds past the minute, as an integer between 0 and 59.
1230 On some operating systems, this is 60 for leap seconds.
1231 @item minutes
1232 The number of minutes past the hour, as an integer between 0 and 59.
1233 @item hour
1234 The hour of the day, as an integer between 0 and 23.
1235 @item day
1236 The day of the month, as an integer between 1 and 31.
1237 @item month
1238 The month of the year, as an integer between 1 and 12.
1239 @item year
1240 The year, an integer typically greater than 1900.
1241 @item dow
1242 The day of week, as an integer between 0 and 6, where 0 stands for
1243 Sunday.
1244 @item dst
1245 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1246 @item zone
1247 An integer indicating the time zone, as the number of seconds east of
1248 Greenwich.
1249 @end table
1251 @strong{Common Lisp Note:} Common Lisp has different meanings for
1252 @var{dow} and @var{zone}.
1253 @end defun
1255 @defun encode-time seconds minutes hour day month year &optional zone
1256 This function is the inverse of @code{decode-time}.  It converts seven
1257 items of calendrical data into a time value.  For the meanings of the
1258 arguments, see the table above under @code{decode-time}.
1260 Year numbers less than 100 are not treated specially.  If you want them
1261 to stand for years above 1900, or years above 2000, you must alter them
1262 yourself before you call @code{encode-time}.
1264 The optional argument @var{zone} defaults to the current time zone and
1265 its daylight saving time rules.  If specified, it can be either a list
1266 (as you would get from @code{current-time-zone}), a string as in the
1267 @code{TZ} environment variable, @code{t} for Universal Time, or an
1268 integer (as you would get from @code{decode-time}).  The specified
1269 zone is used without any further alteration for daylight saving time.
1271 If you pass more than seven arguments to @code{encode-time}, the first
1272 six are used as @var{seconds} through @var{year}, the last argument is
1273 used as @var{zone}, and the arguments in between are ignored.  This
1274 feature makes it possible to use the elements of a list returned by
1275 @code{decode-time} as the arguments to @code{encode-time}, like this:
1277 @example
1278 (apply 'encode-time (decode-time @dots{}))
1279 @end example
1281 You can perform simple date arithmetic by using out-of-range values for
1282 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1283 arguments; for example, day 0 means the day preceding the given month.
1285 The operating system puts limits on the range of possible time values;
1286 if you try to encode a time that is out of range, an error results.
1287 For instance, years before 1970 do not work on some systems;
1288 on others, years as early as 1901 do work.
1289 @end defun
1291 @node Time Parsing
1292 @section Parsing and Formatting Times
1294   These functions convert time values (lists of two or three integers)
1295 to text in a string, and vice versa.
1297 @defun date-to-time string
1298 This function parses the time-string @var{string} and returns the
1299 corresponding time value.
1300 @end defun
1302 @defun format-time-string format-string &optional time universal
1303 This function converts @var{time} (or the current time, if @var{time} is
1304 omitted) to a string according to @var{format-string}.  The argument
1305 @var{format-string} may contain @samp{%}-sequences which say to
1306 substitute parts of the time.  Here is a table of what the
1307 @samp{%}-sequences mean:
1309 @table @samp
1310 @item %a
1311 This stands for the abbreviated name of the day of week.
1312 @item %A
1313 This stands for the full name of the day of week.
1314 @item %b
1315 This stands for the abbreviated name of the month.
1316 @item %B
1317 This stands for the full name of the month.
1318 @item %c
1319 This is a synonym for @samp{%x %X}.
1320 @item %C
1321 This has a locale-specific meaning.  In the default locale (named C), it
1322 is equivalent to @samp{%A, %B %e, %Y}.
1323 @item %d
1324 This stands for the day of month, zero-padded.
1325 @item %D
1326 This is a synonym for @samp{%m/%d/%y}.
1327 @item %e
1328 This stands for the day of month, blank-padded.
1329 @item %h
1330 This is a synonym for @samp{%b}.
1331 @item %H
1332 This stands for the hour (00-23).
1333 @item %I
1334 This stands for the hour (01-12).
1335 @item %j
1336 This stands for the day of the year (001-366).
1337 @item %k
1338 This stands for the hour (0-23), blank padded.
1339 @item %l
1340 This stands for the hour (1-12), blank padded.
1341 @item %m
1342 This stands for the month (01-12).
1343 @item %M
1344 This stands for the minute (00-59).
1345 @item %n
1346 This stands for a newline.
1347 @item %N
1348 This stands for the nanoseconds (000000000-999999999).  To ask for
1349 fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for
1350 microseconds, etc.  Any excess digits are discarded, without rounding.
1351 Currently Emacs time stamps are at best microsecond resolution so the
1352 last three digits generated by plain @samp{%N} are always zero.
1353 @item %p
1354 This stands for @samp{AM} or @samp{PM}, as appropriate.
1355 @item %r
1356 This is a synonym for @samp{%I:%M:%S %p}.
1357 @item %R
1358 This is a synonym for @samp{%H:%M}.
1359 @item %S
1360 This stands for the seconds (00-59).
1361 @item %t
1362 This stands for a tab character.
1363 @item %T
1364 This is a synonym for @samp{%H:%M:%S}.
1365 @item %U
1366 This stands for the week of the year (01-52), assuming that weeks
1367 start on Sunday.
1368 @item %w
1369 This stands for the numeric day of week (0-6).  Sunday is day 0.
1370 @item %W
1371 This stands for the week of the year (01-52), assuming that weeks
1372 start on Monday.
1373 @item %x
1374 This has a locale-specific meaning.  In the default locale (named
1375 @samp{C}), it is equivalent to @samp{%D}.
1376 @item %X
1377 This has a locale-specific meaning.  In the default locale (named
1378 @samp{C}), it is equivalent to @samp{%T}.
1379 @item %y
1380 This stands for the year without century (00-99).
1381 @item %Y
1382 This stands for the year with century.
1383 @item %Z
1384 This stands for the time zone abbreviation (e.g., @samp{EST}).
1385 @item %z
1386 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1387 @end table
1389 You can also specify the field width and type of padding for any of
1390 these @samp{%}-sequences.  This works as in @code{printf}: you write
1391 the field width as digits in the middle of a @samp{%}-sequences.  If you
1392 start the field width with @samp{0}, it means to pad with zeros.  If you
1393 start the field width with @samp{_}, it means to pad with spaces.
1395 For example, @samp{%S} specifies the number of seconds since the minute;
1396 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1397 pad with spaces to 3 positions.  Plain @samp{%3S} pads with zeros,
1398 because that is how @samp{%S} normally pads to two positions.
1400 The characters @samp{E} and @samp{O} act as modifiers when used between
1401 @samp{%} and one of the letters in the table above.  @samp{E} specifies
1402 using the current locale's ``alternative'' version of the date and time.
1403 In a Japanese locale, for example, @code{%Ex} might yield a date format
1404 based on the Japanese Emperors' reigns.  @samp{E} is allowed in
1405 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1406 @samp{%EY}.
1408 @samp{O} means to use the current locale's ``alternative''
1409 representation of numbers, instead of the ordinary decimal digits.  This
1410 is allowed with most letters, all the ones that output numbers.
1412 If @var{universal} is non-@code{nil}, that means to describe the time as
1413 Universal Time; @code{nil} means describe it using what Emacs believes
1414 is the local time zone (see @code{current-time-zone}).
1416 This function uses the C library function @code{strftime}
1417 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1418 Manual}) to do most of the work.  In order to communicate with that
1419 function, it first encodes its argument using the coding system
1420 specified by @code{locale-coding-system} (@pxref{Locales}); after
1421 @code{strftime} returns the resulting string,
1422 @code{format-time-string} decodes the string using that same coding
1423 system.
1424 @end defun
1426 @defun seconds-to-time seconds
1427 This function converts @var{seconds}, a floating point number of
1428 seconds since the epoch, to a time value and returns that.  To perform
1429 the inverse conversion, use @code{float-time}.
1430 @end defun
1432 @defun format-seconds format-string seconds
1433 This function converts its argument @var{seconds} into a string of
1434 years, days, hours, etc., according to @var{format-string}.  The
1435 argument @var{format-string} may contain @samp{%}-sequences which
1436 control the conversion.  Here is a table of what the
1437 @samp{%}-sequences mean:
1439 @table @samp
1440 @item %y
1441 @itemx %Y
1442 The integer number of 365-day years.
1443 @item %d
1444 @itemx %D
1445 The integer number of days.
1446 @item %h
1447 @itemx %H
1448 The integer number of hours.
1449 @item %m
1450 @itemx %M
1451 The integer number of minutes.
1452 @item %s
1453 @itemx %S
1454 The integer number of seconds.
1455 @item %z
1456 Non-printing control flag.  When it is used, other specifiers must be
1457 given in the order of decreasing size, i.e.@: years before days, hours
1458 before minutes, etc.  Nothing will be produced in the result string to
1459 the left of @samp{%z} until the first non-zero conversion is
1460 encountered.  For example, the default format used by
1461 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1462 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1463 will always be produced, but years, days, hours, and minutes will only
1464 be shown if they are non-zero.
1465 @item %%
1466 Produces a literal @samp{%}.
1467 @end table
1469 Upper-case format sequences produce the units in addition to the
1470 numbers, lower-case formats produce only the numbers.
1472 You can also specify the field width by following the @samp{%} with a
1473 number; shorter numbers will be padded with blanks.  An optional
1474 period before the width requests zero-padding instead.  For example,
1475 @code{"%.3Y"} might produce @code{"004 years"}.
1477 @emph{Warning:} This function works only with values of @var{seconds}
1478 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1479 most-positive-fixnum}).
1480 @end defun
1482 @node Processor Run Time
1483 @section Processor Run time
1484 @cindex processor run time
1485 @cindex Emacs process run time
1487   Emacs provides several functions and primitives that return time,
1488 both elapsed and processor time, used by the Emacs process.
1490 @deffn Command emacs-uptime &optional format
1491 This function returns a string representing the Emacs
1492 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1493 running.  The string is formatted by @code{format-seconds} according
1494 to the optional argument @var{format}.  For the available format
1495 descriptors, see @ref{Time Parsing, format-seconds}.  If @var{format}
1496 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
1497 %z%S"}.
1499 When called interactively, it prints the uptime in the echo area.
1500 @end deffn
1502 @defun get-internal-run-time
1503 This function returns the processor run time used by Emacs as a list
1504 of three integers: @code{(@var{high} @var{low} @var{microsec})}.  The
1505 integers @var{high} and @var{low} combine to give the number of
1506 seconds, which is
1507 @ifnottex
1508 @var{high} * 2**16 + @var{low}.
1509 @end ifnottex
1510 @tex
1511 $high*2^{16}+low$.
1512 @end tex
1514 The third element, @var{microsec}, gives the microseconds (or 0 for
1515 systems that return time with the resolution of only one second).
1517 Note that the time returned by this function excludes the time Emacs
1518 was not using the processor, and if the Emacs process has several
1519 threads, the returned value is the sum of the processor times used up
1520 by all Emacs threads.
1522 If the system doesn't provide a way to determine the processor run
1523 time, @code{get-internal-run-time} returns the same time as
1524 @code{current-time}.
1525 @end defun
1527 @deffn Command emacs-init-time
1528 This function returns the duration of the Emacs initialization
1529 (@pxref{Startup Summary}) in seconds, as a string.  When called
1530 interactively, it prints the duration in the echo area.
1531 @end deffn
1533 @node Time Calculations
1534 @section Time Calculations
1536   These functions perform calendrical computations using time values
1537 (the kind of list that @code{current-time} returns).
1539 @defun time-less-p t1 t2
1540 This returns @code{t} if time value @var{t1} is less than time value
1541 @var{t2}.
1542 @end defun
1544 @defun time-subtract t1 t2
1545 This returns the time difference @var{t1} @minus{} @var{t2} between
1546 two time values, in the same format as a time value.
1547 @end defun
1549 @defun time-add t1 t2
1550 This returns the sum of two time values, one of which ought to
1551 represent a time difference rather than a point in time.
1552 Here is how to add a number of seconds to a time value:
1554 @example
1555 (time-add @var{time} (seconds-to-time @var{seconds}))
1556 @end example
1557 @end defun
1559 @defun time-to-days time
1560 This function returns the number of days between the beginning of year
1561 1 and @var{time}.
1562 @end defun
1564 @defun time-to-day-in-year time
1565 This returns the day number within the year corresponding to @var{time}.
1566 @end defun
1568 @defun date-leap-year-p year
1569 This function returns @code{t} if @var{year} is a leap year.
1570 @end defun
1572 @node Timers
1573 @section Timers for Delayed Execution
1574 @cindex timer
1576   You can set up a @dfn{timer} to call a function at a specified
1577 future time or after a certain length of idleness.
1579   Emacs cannot run timers at any arbitrary point in a Lisp program; it
1580 can run them only when Emacs could accept output from a subprocess:
1581 namely, while waiting or inside certain primitive functions such as
1582 @code{sit-for} or @code{read-event} which @emph{can} wait.  Therefore, a
1583 timer's execution may be delayed if Emacs is busy.  However, the time of
1584 execution is very precise if Emacs is idle.
1586   Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1587 function, because quitting out of many timer functions can leave
1588 things in an inconsistent state.  This is normally unproblematical
1589 because most timer functions don't do a lot of work.  Indeed, for a
1590 timer to call a function that takes substantial time to run is likely
1591 to be annoying.  If a timer function needs to allow quitting, it
1592 should use @code{with-local-quit} (@pxref{Quitting}).  For example, if
1593 a timer function calls @code{accept-process-output} to receive output
1594 from an external process, that call should be wrapped inside
1595 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1596 process hangs.
1598   It is usually a bad idea for timer functions to alter buffer
1599 contents.  When they do, they usually should call @code{undo-boundary}
1600 both before and after changing the buffer, to separate the timer's
1601 changes from user commands' changes and prevent a single undo entry
1602 from growing to be quite large.
1604   Timer functions should also avoid calling functions that cause Emacs
1605 to wait, such as @code{sit-for} (@pxref{Waiting}).  This can lead to
1606 unpredictable effects, since other timers (or even the same timer) can
1607 run while waiting.  If a timer function needs to perform an action
1608 after a certain time has elapsed, it can do this by scheduling a new
1609 timer.
1611   If a timer function calls functions that can change the match data,
1612 it should save and restore the match data.  @xref{Saving Match Data}.
1614 @deffn Command run-at-time time repeat function &rest args
1615 This sets up a timer that calls the function @var{function} with
1616 arguments @var{args} at time @var{time}.  If @var{repeat} is a number
1617 (integer or floating point), the timer is scheduled to run again every
1618 @var{repeat} seconds after @var{time}.  If @var{repeat} is @code{nil},
1619 the timer runs only once.
1621 @var{time} may specify an absolute or a relative time.
1623 Absolute times may be specified using a string with a limited variety
1624 of formats, and are taken to be times @emph{today}, even if already in
1625 the past.  The recognized forms are @samp{@var{xxxx}},
1626 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1627 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1628 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1629 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1630 @samp{@var{xx}:@var{xx}PM}.  A period can be used instead of a colon
1631 to separate the hour and minute parts.
1633 To specify a relative time as a string, use numbers followed by units.
1634 For example:
1636 @table @samp
1637 @item 1 min
1638 denotes 1 minute from now.
1639 @item 1 min 5 sec
1640 denotes 65 seconds from now.
1641 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1642 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1643 @end table
1645 For relative time values, Emacs considers a month to be exactly thirty
1646 days, and a year to be exactly 365.25 days.
1648 Not all convenient formats are strings.  If @var{time} is a number
1649 (integer or floating point), that specifies a relative time measured in
1650 seconds.  The result of @code{encode-time} can also be used to specify
1651 an absolute value for @var{time}.
1653 In most cases, @var{repeat} has no effect on when @emph{first} call
1654 takes place---@var{time} alone specifies that.  There is one exception:
1655 if @var{time} is @code{t}, then the timer runs whenever the time is a
1656 multiple of @var{repeat} seconds after the epoch.  This is useful for
1657 functions like @code{display-time}.
1659 The function @code{run-at-time} returns a timer value that identifies
1660 the particular scheduled future action.  You can use this value to call
1661 @code{cancel-timer} (see below).
1662 @end deffn
1664   A repeating timer nominally ought to run every @var{repeat} seconds,
1665 but remember that any invocation of a timer can be late.  Lateness of
1666 one repetition has no effect on the scheduled time of the next
1667 repetition.  For instance, if Emacs is busy computing for long enough
1668 to cover three scheduled repetitions of the timer, and then starts to
1669 wait, it will immediately call the timer function three times in
1670 immediate succession (presuming no other timers trigger before or
1671 between them).  If you want a timer to run again no less than @var{n}
1672 seconds after the last invocation, don't use the @var{repeat} argument.
1673 Instead, the timer function should explicitly reschedule the timer.
1675 @defvar timer-max-repeats
1676 This variable's value specifies the maximum number of times to repeat
1677 calling a timer function in a row, when many previously scheduled
1678 calls were unavoidably delayed.
1679 @end defvar
1681 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1682 Execute @var{body}, but give up after @var{seconds} seconds.  If
1683 @var{body} finishes before the time is up, @code{with-timeout} returns
1684 the value of the last form in @var{body}.  If, however, the execution of
1685 @var{body} is cut short by the timeout, then @code{with-timeout}
1686 executes all the @var{timeout-forms} and returns the value of the last
1687 of them.
1689 This macro works by setting a timer to run after @var{seconds} seconds.  If
1690 @var{body} finishes before that time, it cancels the timer.  If the
1691 timer actually runs, it terminates execution of @var{body}, then
1692 executes @var{timeout-forms}.
1694 Since timers can run within a Lisp program only when the program calls a
1695 primitive that can wait, @code{with-timeout} cannot stop executing
1696 @var{body} while it is in the midst of a computation---only when it
1697 calls one of those primitives.  So use @code{with-timeout} only with a
1698 @var{body} that waits for input, not one that does a long computation.
1699 @end defmac
1701   The function @code{y-or-n-p-with-timeout} provides a simple way to use
1702 a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
1703 Queries}.
1705 @defun cancel-timer timer
1706 This cancels the requested action for @var{timer}, which should be a
1707 timer---usually, one previously returned by @code{run-at-time} or
1708 @code{run-with-idle-timer}.  This cancels the effect of that call to
1709 one of these functions; the arrival of the specified time will not
1710 cause anything special to happen.
1711 @end defun
1713 @node Idle Timers
1714 @section Idle Timers
1716   Here is how to set up a timer that runs when Emacs is idle for a
1717 certain length of time.  Aside from how to set them up, idle timers
1718 work just like ordinary timers.
1720 @deffn Command run-with-idle-timer secs repeat function &rest args
1721 Set up a timer which runs when Emacs has been idle for @var{secs}
1722 seconds.  The value of @var{secs} may be an integer or a floating point
1723 number; a value of the type returned by @code{current-idle-time}
1724 is also allowed.
1726 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1727 Emacs remains idle for a long enough time.  More often @var{repeat} is
1728 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1729 remains idle for @var{secs} seconds.
1731 The function @code{run-with-idle-timer} returns a timer value which you
1732 can use in calling @code{cancel-timer} (@pxref{Timers}).
1733 @end deffn
1735 @cindex idleness
1736   Emacs becomes ``idle'' when it starts waiting for user input, and it
1737 remains idle until the user provides some input.  If a timer is set for
1738 five seconds of idleness, it runs approximately five seconds after Emacs
1739 first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
1740 will not run again as long as Emacs remains idle, because the duration
1741 of idleness will continue to increase and will not go down to five
1742 seconds again.
1744   Emacs can do various things while idle: garbage collect, autosave or
1745 handle data from a subprocess.  But these interludes during idleness do
1746 not interfere with idle timers, because they do not reset the clock of
1747 idleness to zero.  An idle timer set for 600 seconds will run when ten
1748 minutes have elapsed since the last user command was finished, even if
1749 subprocess output has been accepted thousands of times within those ten
1750 minutes, and even if there have been garbage collections and autosaves.
1752   When the user supplies input, Emacs becomes non-idle while executing the
1753 input.  Then it becomes idle again, and all the idle timers that are
1754 set up to repeat will subsequently run another time, one by one.
1756 @c Emacs 19 feature
1757 @defun current-idle-time
1758 If Emacs is idle, this function returns the length of time Emacs has
1759 been idle, as a list of three integers: @code{(@var{high} @var{low}
1760 @var{microsec})}.  The integers @var{high} and @var{low} combine to
1761 give the number of seconds of idleness, which is
1762 @ifnottex
1763 @var{high} * 2**16 + @var{low}.
1764 @end ifnottex
1765 @tex
1766 $high*2^{16}+low$.
1767 @end tex
1769 The third element, @var{microsec}, gives the microseconds since the
1770 start of the current second (or 0 for systems that return time with
1771 the resolution of only one second).
1773 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1774 This is a convenient way to test whether Emacs is idle.
1776 The main use of this function is when an idle timer function wants to
1777 ``take a break'' for a while.  It can set up another idle timer to
1778 call the same function again, after a few seconds more idleness.
1779 Here's an example:
1781 @smallexample
1782 (defvar resume-timer nil
1783   "Timer that `timer-function' used to reschedule itself, or nil.")
1785 (defun timer-function ()
1786   ;; @r{If the user types a command while @code{resume-timer}}
1787   ;; @r{is active, the next time this function is called from}
1788   ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1789   (when resume-timer
1790     (cancel-timer resume-timer))
1791   ...@var{do the work for a while}...
1792   (when @var{taking-a-break}
1793     (setq resume-timer
1794           (run-with-idle-timer
1795             ;; Compute an idle time @var{break-length}
1796             ;; more than the current value.
1797             (time-add (current-idle-time)
1798                       (seconds-to-time @var{break-length}))
1799             nil
1800             'timer-function))))
1801 @end smallexample
1802 @end defun
1804   Some idle timer functions in user Lisp packages have a loop that
1805 does a certain amount of processing each time around, and exits when
1806 @code{(input-pending-p)} is non-@code{nil}.  That approach seems very
1807 natural but has two problems:
1809 @itemize
1810 @item
1811 It blocks out all process output (since Emacs accepts process output
1812 only while waiting).
1814 @item
1815 It blocks out any idle timers that ought to run during that time.
1816 @end itemize
1818 @noindent
1819 To avoid these problems, don't use that technique.  Instead, write
1820 such idle timers to reschedule themselves after a brief pause, using
1821 the method in the @code{timer-function} example above.
1823 @node Terminal Input
1824 @section Terminal Input
1825 @cindex terminal input
1827   This section describes functions and variables for recording or
1828 manipulating terminal input.  See @ref{Display}, for related
1829 functions.
1831 @menu
1832 * Input Modes::         Options for how input is processed.
1833 * Recording Input::     Saving histories of recent or all input events.
1834 @end menu
1836 @node Input Modes
1837 @subsection Input Modes
1838 @cindex input modes
1839 @cindex terminal input modes
1841 @defun set-input-mode interrupt flow meta &optional quit-char
1842 This function sets the mode for reading keyboard input.  If
1843 @var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
1844 @code{nil}, then it uses @sc{cbreak} mode.  The default setting is
1845 system-dependent.  Some systems always use @sc{cbreak} mode regardless
1846 of what is specified.
1848 When Emacs communicates directly with X, it ignores this argument and
1849 uses interrupts if that is the way it knows how to communicate.
1851 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1852 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal.  This
1853 has no effect except in @sc{cbreak} mode.
1855 @c Emacs 19 feature
1856 The argument @var{meta} controls support for input character codes
1857 above 127.  If @var{meta} is @code{t}, Emacs converts characters with
1858 the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
1859 Emacs disregards the 8th bit; this is necessary when the terminal uses
1860 it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
1861 Emacs uses all 8 bits of input unchanged.  This is good for terminals
1862 that use 8-bit character sets.
1864 @c Emacs 19 feature
1865 If @var{quit-char} is non-@code{nil}, it specifies the character to
1866 use for quitting.  Normally this character is @kbd{C-g}.
1867 @xref{Quitting}.
1868 @end defun
1870 The @code{current-input-mode} function returns the input mode settings
1871 Emacs is currently using.
1873 @c Emacs 19 feature
1874 @defun current-input-mode
1875 This function returns the current mode for reading keyboard input.  It
1876 returns a list, corresponding to the arguments of @code{set-input-mode},
1877 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1878 which:
1879 @table @var
1880 @item interrupt
1881 is non-@code{nil} when Emacs is using interrupt-driven input.  If
1882 @code{nil}, Emacs is using @sc{cbreak} mode.
1883 @item flow
1884 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1885 flow control for output to the terminal.  This value is meaningful only
1886 when @var{interrupt} is @code{nil}.
1887 @item meta
1888 is @code{t} if Emacs treats the eighth bit of input characters as
1889 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1890 input character; any other value means Emacs uses all eight bits as the
1891 basic character code.
1892 @item quit
1893 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1894 @end table
1895 @end defun
1897 @node Recording Input
1898 @subsection Recording Input
1899 @cindex recording input
1901 @defun recent-keys
1902 This function returns a vector containing the last 300 input events from
1903 the keyboard or mouse.  All input events are included, whether or not
1904 they were used as parts of key sequences.  Thus, you always get the last
1905 100 input events, not counting events generated by keyboard macros.
1906 (These are excluded because they are less interesting for debugging; it
1907 should be enough to see the events that invoked the macros.)
1909 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1910 causes this function to return an empty vector immediately afterward.
1911 @end defun
1913 @deffn Command open-dribble-file filename
1914 @cindex dribble file
1915 This function opens a @dfn{dribble file} named @var{filename}.  When a
1916 dribble file is open, each input event from the keyboard or mouse (but
1917 not those from keyboard macros) is written in that file.  A
1918 non-character event is expressed using its printed representation
1919 surrounded by @samp{<@dots{}>}.
1921 You close the dribble file by calling this function with an argument
1922 of @code{nil}.
1924 This function is normally used to record the input necessary to
1925 trigger an Emacs bug, for the sake of a bug report.
1927 @example
1928 @group
1929 (open-dribble-file "~/dribble")
1930      @result{} nil
1931 @end group
1932 @end example
1933 @end deffn
1935   See also the @code{open-termscript} function (@pxref{Terminal Output}).
1937 @node Terminal Output
1938 @section Terminal Output
1939 @cindex terminal output
1941   The terminal output functions send output to a text terminal, or keep
1942 track of output sent to the terminal.  The variable @code{baud-rate}
1943 tells you what Emacs thinks is the output speed of the terminal.
1945 @defopt baud-rate
1946 This variable's value is the output speed of the terminal, as far as
1947 Emacs knows.  Setting this variable does not change the speed of actual
1948 data transmission, but the value is used for calculations such as
1949 padding.
1951   It also affects decisions about whether to scroll part of the
1952 screen or repaint on text terminals.  @xref{Forcing Redisplay},
1953 for the corresponding functionality on graphical terminals.
1955 The value is measured in baud.
1956 @end defopt
1958   If you are running across a network, and different parts of the
1959 network work at different baud rates, the value returned by Emacs may be
1960 different from the value used by your local terminal.  Some network
1961 protocols communicate the local terminal speed to the remote machine, so
1962 that Emacs and other programs can get the proper value, but others do
1963 not.  If Emacs has the wrong value, it makes decisions that are less
1964 than optimal.  To fix the problem, set @code{baud-rate}.
1966 @defun send-string-to-terminal string &optional terminal
1967 This function sends @var{string} to @var{terminal} without alteration.
1968 Control characters in @var{string} have terminal-dependent effects.
1969 This function operates only on text terminals.  @var{terminal} may be
1970 a terminal object, a frame, or @code{nil} for the selected frame's
1971 terminal.  In batch mode, @var{string} is sent to @code{stdout} when
1972 @var{terminal} is @code{nil}.
1974 One use of this function is to define function keys on terminals that
1975 have downloadable function key definitions.  For example, this is how (on
1976 certain terminals) to define function key 4 to move forward four
1977 characters (by transmitting the characters @kbd{C-u C-f} to the
1978 computer):
1980 @example
1981 @group
1982 (send-string-to-terminal "\eF4\^U\^F")
1983      @result{} nil
1984 @end group
1985 @end example
1986 @end defun
1988 @deffn Command open-termscript filename
1989 @cindex termscript file
1990 This function is used to open a @dfn{termscript file} that will record
1991 all the characters sent by Emacs to the terminal.  It returns
1992 @code{nil}.  Termscript files are useful for investigating problems
1993 where Emacs garbles the screen, problems that are due to incorrect
1994 Termcap entries or to undesirable settings of terminal options more
1995 often than to actual Emacs bugs.  Once you are certain which characters
1996 were actually output, you can determine reliably whether they correspond
1997 to the Termcap specifications in use.
1999 You close the termscript file by calling this function with an
2000 argument of @code{nil}.
2002 See also @code{open-dribble-file} in @ref{Recording Input}.
2004 @example
2005 @group
2006 (open-termscript "../junk/termscript")
2007      @result{} nil
2008 @end group
2009 @end example
2010 @end deffn
2012 @node Sound Output
2013 @section Sound Output
2014 @cindex sound
2016   To play sound using Emacs, use the function @code{play-sound}.  Only
2017 certain systems are supported; if you call @code{play-sound} on a system
2018 which cannot really do the job, it gives an error.  Emacs version 20 and
2019 earlier did not support sound at all.
2021   The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
2022 or Sun Audio format (@samp{.au}).
2024 @defun play-sound sound
2025 This function plays a specified sound.  The argument, @var{sound}, has
2026 the form @code{(sound @var{properties}...)}, where the @var{properties}
2027 consist of alternating keywords (particular symbols recognized
2028 specially) and values corresponding to them.
2030 Here is a table of the keywords that are currently meaningful in
2031 @var{sound}, and their meanings:
2033 @table @code
2034 @item :file @var{file}
2035 This specifies the file containing the sound to play.
2036 If the file name is not absolute, it is expanded against
2037 the directory @code{data-directory}.
2039 @item :data @var{data}
2040 This specifies the sound to play without need to refer to a file.  The
2041 value, @var{data}, should be a string containing the same bytes as a
2042 sound file.  We recommend using a unibyte string.
2044 @item :volume @var{volume}
2045 This specifies how loud to play the sound.  It should be a number in the
2046 range of 0 to 1.  The default is to use whatever volume has been
2047 specified before.
2049 @item :device @var{device}
2050 This specifies the system device on which to play the sound, as a
2051 string.  The default device is system-dependent.
2052 @end table
2054 Before actually playing the sound, @code{play-sound}
2055 calls the functions in the list @code{play-sound-functions}.
2056 Each function is called with one argument, @var{sound}.
2057 @end defun
2059 @defun play-sound-file file &optional volume device
2060 This function is an alternative interface to playing a sound @var{file}
2061 specifying an optional @var{volume} and @var{device}.
2062 @end defun
2064 @defvar play-sound-functions
2065 A list of functions to be called before playing a sound.  Each function
2066 is called with one argument, a property list that describes the sound.
2067 @end defvar
2069 @node X11 Keysyms
2070 @section Operating on X11 Keysyms
2071 @cindex X11 keysyms
2073 To define system-specific X11 keysyms, set the variable
2074 @code{system-key-alist}.
2076 @defvar system-key-alist
2077 This variable's value should be an alist with one element for each
2078 system-specific keysym.  Each element has the form @code{(@var{code}
2079 . @var{symbol})}, where @var{code} is the numeric keysym code (not
2080 including the ``vendor specific'' bit,
2081 @ifnottex
2082 -2**28),
2083 @end ifnottex
2084 @tex
2085 $-2^{28}$),
2086 @end tex
2087 and @var{symbol} is the name for the function key.
2089 For example @code{(168 . mute-acute)} defines a system-specific key (used
2090 by HP X servers) whose numeric code is
2091 @ifnottex
2092 -2**28
2093 @end ifnottex
2094 @tex
2095 $-2^{28}$
2096 @end tex
2097 + 168.
2099 It is not crucial to exclude from the alist the keysyms of other X
2100 servers; those do no harm, as long as they don't conflict with the ones
2101 used by the X server actually in use.
2103 The variable is always local to the current terminal, and cannot be
2104 buffer-local.  @xref{Multiple Terminals}.
2105 @end defvar
2107 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2109 @defvar x-alt-keysym
2110 @defvarx x-meta-keysym
2111 @defvarx x-hyper-keysym
2112 @defvarx x-super-keysym
2113 The name of the keysym that should stand for the Alt modifier
2114 (respectively, for Meta, Hyper, and Super).  For example, here is
2115 how to swap the Meta and Alt modifiers within Emacs:
2116 @lisp
2117 (setq x-alt-keysym 'meta)
2118 (setq x-meta-keysym 'alt)
2119 @end lisp
2120 @end defvar
2122 @node Batch Mode
2123 @section Batch Mode
2124 @cindex batch mode
2126   The command-line option @samp{-batch} causes Emacs to run
2127 noninteractively.  In this mode, Emacs does not read commands from the
2128 terminal, it does not alter the terminal modes, and it does not expect
2129 to be outputting to an erasable screen.  The idea is that you specify
2130 Lisp programs to run; when they are finished, Emacs should exit.  The
2131 way to specify the programs to run is with @samp{-l @var{file}}, which
2132 loads the library named @var{file}, or @samp{-f @var{function}}, which
2133 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2135   Any Lisp program output that would normally go to the echo area,
2136 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2137 as the stream, goes instead to Emacs's standard error descriptor when
2138 in batch mode.  Similarly, input that would normally come from the
2139 minibuffer is read from the standard input descriptor.
2140 Thus, Emacs behaves much like a noninteractive
2141 application program.  (The echo area output that Emacs itself normally
2142 generates, such as command echoing, is suppressed entirely.)
2144 @defvar noninteractive
2145 This variable is non-@code{nil} when Emacs is running in batch mode.
2146 @end defvar
2148 @node Session Management
2149 @section Session Management
2150 @cindex session manager
2152 Emacs supports the X Session Management Protocol, which is used to
2153 suspend and restart applications.  In the X Window System, a program
2154 called the @dfn{session manager} is responsible for keeping track of
2155 the applications that are running.  When the X server shuts down, the
2156 session manager asks applications to save their state, and delays the
2157 actual shutdown until they respond.  An application can also cancel
2158 the shutdown.
2160 When the session manager restarts a suspended session, it directs
2161 these applications to individually reload their saved state.  It does
2162 this by specifying a special command-line argument that says what
2163 saved session to restore.  For Emacs, this argument is @samp{--smid
2164 @var{session}}.
2166 @defvar emacs-save-session-functions
2167 Emacs supports saving state via a hook called
2168 @code{emacs-save-session-functions}.  Emacs runs this hook when the
2169 session manager tells it that the window system is shutting down.  The
2170 functions are called with no arguments, and with the current buffer
2171 set to a temporary buffer.  Each function can use @code{insert} to add
2172 Lisp code to this buffer.  At the end, Emacs saves the buffer in a
2173 file, called the @dfn{session file}.
2175 @findex emacs-session-restore
2176 Subsequently, when the session manager restarts Emacs, it loads the
2177 session file automatically (@pxref{Loading}).  This is performed by a
2178 function named @code{emacs-session-restore}, which is called during
2179 startup.  @xref{Startup Summary}.
2181 If a function in @code{emacs-save-session-functions} returns
2182 non-@code{nil}, Emacs tells the session manager to cancel the
2183 shutdown.
2184 @end defvar
2186 Here is an example that just inserts some text into @samp{*scratch*} when
2187 Emacs is restarted by the session manager.
2189 @example
2190 @group
2191 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2192 @end group
2194 @group
2195 (defun save-yourself-test ()
2196   (insert "(save-current-buffer
2197   (switch-to-buffer \"*scratch*\")
2198   (insert \"I am restored\"))")
2199   nil)
2200 @end group
2201 @end example
2203 @node Dynamic Libraries
2204 @section Dynamically Loaded Libraries
2205 @cindex dynamic libraries
2207   A @dfn{dynamically loaded library} is a library that is loaded on
2208 demand, when its facilities are first needed.  Emacs supports such
2209 on-demand loading of support libraries for some of its features.
2211 @defvar dynamic-library-alist
2212 This is an alist of dynamic libraries and external library files
2213 implementing them.
2215 Each element is a list of the form
2216 @w{@code{(@var{library} @var{files}@dots{})}}, where the @code{car} is
2217 a symbol representing a supported external library, and the rest are
2218 strings giving alternate filenames for that library.
2220 Emacs tries to load the library from the files in the order they
2221 appear in the list; if none is found, the running session of Emacs
2222 won't have access to that library, and the features that depend on the
2223 library will be unavailable.
2225 Image support on some platforms uses this facility.  Here's an example
2226 of setting this variable for supporting images on MS-Windows:
2228 @lisp
2229 (setq dynamic-library-alist
2230       '((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll")
2231         (png "libpng12d.dll" "libpng12.dll" "libpng.dll"
2232          "libpng13d.dll" "libpng13.dll")
2233         (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll" "jpeg.dll")
2234         (tiff "libtiff3.dll" "libtiff.dll")
2235         (gif "giflib4.dll" "libungif4.dll" "libungif.dll")
2236         (svg "librsvg-2-2.dll")
2237         (gdk-pixbuf "libgdk_pixbuf-2.0-0.dll")
2238         (glib "libglib-2.0-0.dll")
2239         (gobject "libgobject-2.0-0.dll")))
2240 @end lisp
2242 Note that image types @code{pbm} and @code{xbm} do not need entries in
2243 this variable because they do not depend on external libraries and are
2244 always available in Emacs.
2246 Also note that this variable is not meant to be a generic facility for
2247 accessing external libraries; only those already known by Emacs can
2248 be loaded through it.
2250 This variable is ignored if the given @var{library} is statically
2251 linked into Emacs.
2252 @end defvar