2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/os
7 @node System Interface, Antinews, 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,
14 @xref{Building Emacs}, for related information. See also
15 @ref{Display}, for additional operating system status information
16 pertaining to the terminal and the screen.
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
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.
42 @section Starting Up Emacs
44 This section describes what Emacs does when it is started, and how you
45 can customize these actions.
48 * Startup Summary:: Sequence of actions Emacs performs at startup.
49 * Init File:: Details on reading the init file (@file{.emacs}).
50 * Terminal-Specific:: How the terminal-specific Lisp file is read.
51 * Command-Line Arguments:: How command-line arguments are processed,
52 and how you can customize them.
56 @subsection Summary: Sequence of Actions at Startup
57 @cindex initialization of Emacs
58 @cindex startup of Emacs
59 @cindex @file{startup.el}
61 The order of operations performed (in @file{startup.el}) by Emacs when
62 it is started up is as follows:
66 It adds subdirectories to @code{load-path}, by running the file named
67 @file{subdirs.el} in each directory in the list. Normally this file
68 adds the directory's subdirectories to the list, and these will be
69 scanned in their turn. The files @file{subdirs.el} are normally
70 generated automatically by Emacs installation.
72 @vindex before-init-time
74 It records in the variable @code{before-init-time} the value of
75 @code{current-time} (@pxref{Time of Day}). It also sets
76 @code{after-init-time} to @code{nil}, so as to signal Lisp programs
77 that Emacs initialization is in progress.
79 @vindex initial-window-system@r{, and startup}
80 @vindex window-system-initialization-alist
82 It loads the initialization library for the window system specified by
83 the variable @code{initial-window-system} (@pxref{Window Systems,
84 initial-window-system}). This library's name is
85 @file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
86 value of @code{initial-window-system}. From that library, it calls
87 the appropriate initialization function. The initialization function
88 is specified by @code{window-system-initialization-alist}, for each
89 supported window system.
92 It sets the language environment and the terminal coding system,
93 if requested by environment variables such as @code{LANG}.
96 It processes the initial options. (Some of them are handled
97 even earlier than this.)
100 It runs the normal hook @code{before-init-hook}.
103 It initializes the window frame and faces, if appropriate, and turns
104 on the menu bar and tool bar, if the initial frame needs them.
107 It registers the default colors for text-only terminals.
110 It loads the library @file{site-start} (if any), unless the option
111 @samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
112 name is usually @file{site-start.el}.
113 @cindex @file{site-start.el}
116 It loads your init file (usually @file{~/.emacs}), unless the option
117 @samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
118 specified on the command line. The @samp{-u} option can specify
119 another user whose home directory should be used instead of @file{~}.
122 It loads the library @file{default} (if any), unless
123 @code{inhibit-default-init} is non-@code{nil}. (This is not done in
124 @samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
125 command line.) The library's file name is usually @file{default.el}.
126 @cindex @file{default.el}
129 It loads your abbrevs from the file specified by
130 @code{abbrev-file-name} (@pxref{Abbrev Files, abbrev-file-name}), if
131 that file exists and can be read. (This is not done in @samp{-batch}
134 @vindex after-init-time
136 It records in the variable @code{after-init-time} the value of
137 @code{current-time}. This variable was set to @code{nil} at the
138 beginning of the Emacs session initialization (see above), so setting
139 it to the current time both signals that the initialization phase is
140 over, and, together with @code{before-init-time}, provides the
141 measurement of how long it took.
144 It runs the normal hook @code{after-init-hook}.
147 It sets the major mode according to @code{initial-major-mode}, provided
148 the buffer @samp{*scratch*} is still current and still in Fundamental
152 It loads the terminal-specific Lisp library, if any, except when in
153 batch mode or when the variable @code{initial-window-system} (see
154 above) specifies a non-@code{nil} window system. The name of this
155 library is computed from the value of the variable
156 @code{term-file-prefix}; for the details, see @ref{Terminal-Specific}.
158 If the value of @code{term-file-prefix} is @code{nil}, this step is skipped.
161 It displays the initial echo area message, unless you have suppressed
162 that with @code{inhibit-startup-echo-area-message}.
165 It processes the action arguments from the command line.
168 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
171 It calls @code{frame-notice-user-settings}, which modifies the
172 parameters of the selected frame according to whatever the init files
176 It runs @code{window-setup-hook}. @xref{Window Systems}.
179 It displays copyleft, nonwarranty, and basic use information, provided
180 the value of @code{inhibit-startup-screen} is @code{nil}, you didn't
181 specify @samp{--no-splash} or @samp{-Q}.
184 If the command-line arguments specified @option{--daemon}, @c FIXME: xref
185 it calls @code{server-start} (@pxref{Emacs Server,,, emacs, The GNU
189 If started by the X session manager, it calls
190 @code{emacs-session-restore} passing it as argument the ID of the
191 previous session. @c FIXME: add an xref to the Emacs manual!
194 @defopt inhibit-startup-screen
195 This variable inhibits the initial startup messages (the nonwarranty,
196 etc.). If it is non-@code{nil}, then the messages are not printed.
198 This variable exists so you can set it in your personal init file, once
199 you are familiar with the contents of the startup message. Do not set
200 this variable in the init file of a new user, or in a way that affects
201 more than one user, because that would prevent new users from receiving
202 the information they are supposed to see.
204 @code{inhibit-startup-message} is an alias for this variable, for
208 @defopt inhibit-startup-echo-area-message
209 This variable controls the display of the startup echo area message.
210 You can suppress the startup echo area message by adding text with this
211 form to your init file:
214 (setq inhibit-startup-echo-area-message
215 "@var{your-login-name}")
218 Emacs explicitly checks for an expression as shown above in your init
219 file; your login name must appear in the expression as a Lisp string
220 constant. Other methods of setting
221 @code{inhibit-startup-echo-area-message} to the same value do not
222 inhibit the startup message.
224 This way, you can easily inhibit the message for yourself if you wish,
225 but thoughtless copying of your init file will not inhibit the message
230 @subsection The Init File, @file{.emacs}
232 @cindex @file{.emacs}
234 When you start Emacs, it normally attempts to load your @dfn{init
235 file}, a file in your home directory. Its normal name is
236 @file{.emacs}, but you can also call it @file{.emacs.el}.
237 Alternatively, you can use a file named @file{init.el} in a
238 subdirectory @file{.emacs.d}. Whichever place you use, you can also
239 compile the file (@pxref{Byte Compilation}); then the actual file
240 loaded will be @file{.emacs.elc} or @file{init.elc}.
242 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
243 control whether and where to find the init file; @samp{-q} (and the
244 stronger @samp{-Q}) says not to load an init file, while @samp{-u
245 @var{user}} says to load @var{user}'s init file instead of yours.
246 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
247 option is specified, Emacs uses the @code{LOGNAME} environment
248 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
249 systems) variable, to find your home directory and thus your init
250 file; this way, even if you have su'd, Emacs still loads your own init
251 file. If those environment variables are absent, though, Emacs uses
252 your user-id to find your home directory.
254 @cindex default init file
255 A site may have a @dfn{default init file}, which is the library
256 named @file{default.el}. Emacs finds the @file{default.el} file
257 through the standard search path for libraries (@pxref{How Programs Do
258 Loading}). The Emacs distribution does not come with this file; sites
259 may provide one for local customizations. If the default init file
260 exists, it is loaded whenever you start Emacs, except in batch mode or
261 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
262 file, if any, is loaded first; if it sets @code{inhibit-default-init}
263 to a non-@code{nil} value, then Emacs does not subsequently load the
264 @file{default.el} file.
266 Another file for site-customization is @file{site-start.el}. Emacs
267 loads this @emph{before} the user's init file. You can inhibit the
268 loading of this file with the option @samp{--no-site-file}.
270 @defvar site-run-file
271 This variable specifies the site-customization file to load before the
272 user's init file. Its normal value is @code{"site-start"}. The only
273 way you can change it with real effect is to do so before dumping
277 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
278 examples of how to make various commonly desired customizations in your
281 @defopt inhibit-default-init
282 This variable prevents Emacs from loading the default initialization
283 library file for your session of Emacs. If its value is non-@code{nil},
284 then the default library is not loaded. The default value is
288 @defvar before-init-hook
289 This normal hook is run, once, just before loading all the init files
290 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
291 (The only way to change it with real effect is before dumping Emacs.)
294 @defvar after-init-hook
295 This normal hook is run, once, just after loading all the init files
296 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
297 before loading the terminal-specific library and processing the
298 command-line action arguments.
301 @defvar emacs-startup-hook
302 This normal hook is run, once, just after handling the command line
303 arguments, just before @code{term-setup-hook}.
306 @defvar user-init-file
307 This variable holds the absolute file name of the user's init file. If the
308 actual init file loaded is a compiled file, such as @file{.emacs.elc},
309 the value refers to the corresponding source file.
312 @defvar user-emacs-directory
313 This variable holds the name of the @file{.emacs.d} directory. It is
314 ordinarily @file{~/.emacs.d}, but differs on some platforms.
317 @node Terminal-Specific
318 @subsection Terminal-Specific Initialization
319 @cindex terminal-specific initialization
321 Each terminal type can have its own Lisp library that Emacs loads when
322 run on that type of terminal. The library's name is constructed by
323 concatenating the value of the variable @code{term-file-prefix} and the
324 terminal type (specified by the environment variable @code{TERM}).
325 Normally, @code{term-file-prefix} has the value
326 @code{"term/"}; changing this is not recommended. Emacs finds the file
327 in the normal manner, by searching the @code{load-path} directories, and
328 trying the @samp{.elc} and @samp{.el} suffixes.
331 The usual function of a terminal-specific library is to enable
332 special keys to send sequences that Emacs can recognize. It may also
333 need to set or add to @code{input-decode-map} if the Termcap or
334 Terminfo entry does not specify all the terminal's function keys.
335 @xref{Terminal Input}.
337 When the name of the terminal type contains a hyphen, and no library
338 is found whose name is identical to the terminal's name, Emacs strips
339 from the terminal's name the last hyphen and everything that follows
340 it, and tries again. This process is repeated until Emacs finds a
341 matching library or until there are no more hyphens in the name (the
342 latter means the terminal doesn't have any library specific to it).
343 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
344 libraries, Emacs will try the same library @file{term/aaa.el} for
345 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
346 library can evaluate @code{(getenv "TERM")} to find the full name of
347 the terminal type.@refill
349 Your init file can prevent the loading of the
350 terminal-specific library by setting the variable
351 @code{term-file-prefix} to @code{nil}. This feature is useful when
352 experimenting with your own peculiar customizations.
354 You can also arrange to override some of the actions of the
355 terminal-specific library by setting the variable
356 @code{term-setup-hook}. This is a normal hook which Emacs runs using
357 @code{run-hooks} at the end of Emacs initialization, after loading both
358 your init file and any terminal-specific libraries. You can
359 use this variable to define initializations for terminals that do not
360 have their own libraries. @xref{Hooks}.
362 @defvar term-file-prefix
363 @cindex @code{TERM} environment variable
364 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
365 a terminal-specific initialization file as follows:
368 (load (concat term-file-prefix (getenv "TERM")))
372 You may set the @code{term-file-prefix} variable to @code{nil} in your
373 init file if you do not wish to load the
374 terminal-initialization file. To do this, put the following in
375 your init file: @code{(setq term-file-prefix nil)}.
377 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
378 uses @samp{internal} as the terminal type.
381 @defvar term-setup-hook
382 This variable is a normal hook that Emacs runs after loading your
383 init file, the default initialization file (if any) and the
384 terminal-specific Lisp file.
386 You can use @code{term-setup-hook} to override the definitions made by a
387 terminal-specific file.
390 See @code{window-setup-hook} in @ref{Window Systems}, for a related
393 @node Command-Line Arguments
394 @subsection Command-Line Arguments
395 @cindex command-line arguments
397 You can use command-line arguments to request various actions when you
398 start Emacs. Since you do not need to start Emacs more than once per
399 day, and will often leave your Emacs session running longer than that,
400 command-line arguments are hardly ever used. As a practical matter, it
401 is best to avoid making the habit of using them, since this habit would
402 encourage you to kill and restart Emacs unnecessarily often. These
403 options exist for two reasons: to be compatible with other editors (for
404 invocation by other programs) and to enable shell scripts to run
405 specific Lisp programs.
407 This section describes how Emacs processes command-line arguments,
408 and how you can customize them.
411 (Note that some other editors require you to start afresh each time
412 you want to edit a file. With this kind of editor, you will probably
413 specify the file as a command-line argument. The recommended way to
414 use GNU Emacs is to start it only once, just after you log in, and do
415 all your editing in the same Emacs process. Each time you want to edit
416 a different file, you visit it with the existing Emacs, which eventually
417 comes to have many files in it ready for editing. Usually you do not
418 kill the Emacs until you are about to log out.)
422 This function parses the command line that Emacs was called with,
423 processes it, loads the user's init file and displays the
427 @defvar command-line-processed
428 The value of this variable is @code{t} once the command line has been
431 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
432 this variable to @code{nil} first in order to cause the new dumped Emacs
433 to process its new command-line arguments.
436 @defvar command-switch-alist
437 @cindex switches on command line
438 @cindex options on command line
439 @cindex command-line options
440 The value of this variable is an alist of user-defined command-line
441 options and associated handler functions. This variable exists so you
442 can add elements to it.
444 A @dfn{command-line option} is an argument on the command line, which
451 The elements of the @code{command-switch-alist} look like this:
454 (@var{option} . @var{handler-function})
457 The @sc{car}, @var{option}, is a string, the name of a command-line
458 option (not including the initial hyphen). The @var{handler-function}
459 is called to handle @var{option}, and receives the option name as its
462 In some cases, the option is followed in the command line by an
463 argument. In these cases, the @var{handler-function} can find all the
464 remaining command-line arguments in the variable
465 @code{command-line-args-left}. (The entire list of command-line
466 arguments is in @code{command-line-args}.)
468 The command-line arguments are parsed by the @code{command-line-1}
469 function in the @file{startup.el} file. See also @ref{Emacs
470 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
474 @defvar command-line-args
475 The value of this variable is the list of command-line arguments passed
479 @defvar command-line-functions
480 This variable's value is a list of functions for handling an
481 unrecognized command-line argument. Each time the next argument to be
482 processed has no special meaning, the functions in this list are called,
483 in order of appearance, until one of them returns a non-@code{nil}
486 These functions are called with no arguments. They can access the
487 command-line argument under consideration through the variable
488 @code{argi}, which is bound temporarily at this point. The remaining
489 arguments (not including the current one) are in the variable
490 @code{command-line-args-left}.
492 When a function recognizes and processes the argument in @code{argi}, it
493 should return a non-@code{nil} value to say it has dealt with that
494 argument. If it has also dealt with some of the following arguments, it
495 can indicate that by deleting them from @code{command-line-args-left}.
497 If all of these functions return @code{nil}, then the argument is used
498 as a file name to visit.
502 @section Getting Out of Emacs
503 @cindex exiting Emacs
505 There are two ways to get out of Emacs: you can kill the Emacs job,
506 which exits permanently, or you can suspend it, which permits you to
507 reenter the Emacs process later. As a practical matter, you seldom kill
508 Emacs---only when you are about to log out. Suspending is much more
512 * Killing Emacs:: Exiting Emacs irreversibly.
513 * Suspending Emacs:: Exiting Emacs reversibly.
517 @comment node-name, next, previous, up
518 @subsection Killing Emacs
519 @cindex killing Emacs
521 Killing Emacs means ending the execution of the Emacs process. The
522 parent process normally resumes control. The low-level primitive for
523 killing Emacs is @code{kill-emacs}.
525 @defun kill-emacs &optional exit-data
526 This function exits the Emacs process and kills it.
528 If @var{exit-data} is an integer, then it is used as the exit status
529 of the Emacs process. (This is useful primarily in batch operation; see
532 If @var{exit-data} is a string, its contents are stuffed into the
533 terminal input buffer so that the shell (or whatever program next reads
534 input) can read them.
537 All the information in the Emacs process, aside from files that have
538 been saved, is lost when the Emacs process is killed. Because killing
539 Emacs inadvertently can lose a lot of work, Emacs queries for
540 confirmation before actually terminating if you have buffers that need
541 saving or subprocesses that are running. This is done in the function
542 @code{save-buffers-kill-emacs}, the higher level function from which
543 @code{kill-emacs} is usually called.
545 @defvar kill-emacs-query-functions
546 After asking the standard questions, @code{save-buffers-kill-emacs}
547 calls the functions in the list @code{kill-emacs-query-functions}, in
548 order of appearance, with no arguments. These functions can ask for
549 additional confirmation from the user. If any of them returns
550 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
551 does not run the remaining functions in this hook. Calling
552 @code{kill-emacs} directly does not run this hook.
555 @defvar kill-emacs-hook
556 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
557 finished with all file saving and confirmation, it calls
558 @code{kill-emacs} which runs the functions in this hook.
559 @code{kill-emacs} does not run this hook in batch mode.
561 @code{kill-emacs} may be invoked directly (that is not via
562 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
563 similar situations where interaction with the user is not possible.
564 Thus, if your hook needs to interact with the user, put it on
565 @code{kill-emacs-query-functions}; if it needs to run regardless of
566 how Emacs is killed, put it on @code{kill-emacs-hook}.
569 @node Suspending Emacs
570 @subsection Suspending Emacs
571 @cindex suspending Emacs
573 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
574 control to its superior process, which is usually the shell. This
575 allows you to resume editing later in the same Emacs process, with the
576 same buffers, the same kill ring, the same undo history, and so on. To
577 resume Emacs, use the appropriate command in the parent shell---most
580 @cindex controlling terminal
581 Suspending works only on a terminal device from which the Emacs
582 session was started. We call that device the @dfn{controlling
583 terminal} of the session.
585 Some operating systems do not support suspension of jobs; on these
586 systems, ``suspension'' actually creates a new shell temporarily as a
587 subprocess of Emacs. Then you would exit the shell to return to Emacs.
589 Suspension is not useful with window systems, because the Emacs job
590 may not have a parent that can resume it again, and in any case you can
591 give input to some other job such as a shell merely by moving to a
592 different window. Therefore, suspending is not allowed when Emacs is using
593 a window system (X, MS Windows).
595 @defun suspend-emacs &optional string
596 This function stops Emacs and returns control to the superior process.
597 If and when the superior process resumes Emacs, @code{suspend-emacs}
598 returns @code{nil} to its caller in Lisp.
600 This function works only on the controlling terminal of the Emacs
601 session; to relinquish control of other tty devices, use
602 @code{suspend-tty} (see below). If the Emacs session uses more than
603 one terminal device, you will need to delete the frames on all the
604 other devices before suspending Emacs, otherwise this function signals
607 If @var{string} is non-@code{nil}, its characters are sent to be read
608 as terminal input by Emacs's superior shell. The characters in
609 @var{string} are not echoed by the superior shell; only the results
612 Before suspending, @code{suspend-emacs} runs the normal hook
615 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
616 @code{suspend-resume-hook}. @xref{Hooks}.
618 The next redisplay after resumption will redraw the entire screen,
619 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
620 (@pxref{Refresh Screen}).
622 In the following example, note that @samp{pwd} is not echoed after
623 Emacs is suspended. But it is read and executed by the shell.
632 (add-hook 'suspend-hook
636 (error "Suspend canceled")))))
637 @result{} (lambda nil
638 (or (y-or-n-p "Really suspend? ")
639 (error "Suspend canceled")))
642 (add-hook 'suspend-resume-hook
643 (function (lambda () (message "Resumed!"))))
644 @result{} (lambda nil (message "Resumed!"))
647 (suspend-emacs "pwd")
651 ---------- Buffer: Minibuffer ----------
652 Really suspend? @kbd{y}
653 ---------- Buffer: Minibuffer ----------
657 ---------- Parent Shell ----------
658 lewis@@slug[23] % /user/lewis/manual
663 ---------- Echo Area ----------
670 This variable is a normal hook that Emacs runs before suspending.
673 @defvar suspend-resume-hook
674 This variable is a normal hook that Emacs runs on resuming
678 @defun suspend-tty &optional tty
679 If @var{tty} specifies a terminal device used by Emacs, this function
680 relinquishes the device and restores it to its prior state. Frames
681 that used the device continue to exist, but are not updated and Emacs
682 doesn't read input from them. If @var{tty} is a frame, it means that
683 frame's terminal; if it is @code{nil}, the function uses the selected
684 frame's terminal. If @var{tty} is already suspended, the function
687 This function runs the hook @code{suspend-tty-functions} (each
688 function gets one argument, the terminal that corresponds to
692 @defun resume-tty &optional tty
693 Resume the previously suspended terminal device @var{tty}. If
694 @var{tty} is a frame, it means resume that frame's terminal;
695 @code{nil} means the selected frame.
697 This function reopens the terminal device, re-initializes it, and
698 redraws its with that terminal's selected frame. It then runs the
699 hook @code{resume-tty-functions}, passing each function the terminal
700 which corresponds to @var{tty}.
702 If the same device is already used by another Emacs terminal, this
703 function signals an error.
706 @defun controlling-tty-p &optional terminal
707 This function returns non-@code{nil} if @var{terminal} is the
708 controlling terminal device of the Emacs session.
711 @deffn Command suspend-frame
712 This command @dfn{suspends} a frame. For GUI frames, it calls
713 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
714 frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
715 depending on whether the frame is displayed on the controlling
716 terminal device or not.
719 @node System Environment
720 @section Operating System Environment
721 @cindex operating system environment
723 Emacs provides access to variables in the operating system environment
724 through various functions. These variables include the name of the
725 system, the user's @acronym{UID}, and so on.
727 @defvar system-configuration
728 This variable holds the standard GNU configuration name for the
729 hardware/software configuration of your system, as a string. The
730 convenient way to test parts of this string is with
734 @cindex system type and name
736 The value of this variable is a symbol indicating the type of operating
737 system Emacs is operating on. Here is a table of the possible values:
744 Berkeley BSD and its variants.
747 Cygwin, a Posix layer on top of MS-Windows.
753 The GNU system (using the GNU kernel, which consists of the HURD and Mach).
756 A GNU/Linux system---that is, a variant GNU system, using the Linux
757 kernel. (These systems are the ones people often call ``Linux,'' but
758 actually Linux is just the kernel, not the whole system.)
761 A GNU (glibc-based) system with a FreeBSD kernel.
764 Hewlett-Packard HPUX operating system.
767 Silicon Graphics Irix system.
773 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
774 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
781 Microsoft Windows NT and later. The same executable supports Windows
782 9X, but the value of @code{system-type} is @code{windows-nt} in either
787 We do not wish to add new symbols to make finer distinctions unless it
788 is absolutely necessary! In fact, we hope to eliminate some of these
789 alternatives in the future. We recommend using
790 @code{system-configuration} to distinguish between different operating
795 This function returns the name of the machine you are running on.
798 @result{} "www.gnu.org"
802 The symbol @code{system-name} is a variable as well as a function. In
803 fact, the function returns whatever value the variable
804 @code{system-name} currently holds. Thus, you can set the variable
805 @code{system-name} in case Emacs is confused about the name of your
806 system. The variable is also useful for constructing frame titles
807 (@pxref{Frame Titles}).
809 @defvar mail-host-address
810 If this variable is non-@code{nil}, it is used instead of
811 @code{system-name} for purposes of generating email addresses. For
812 example, it is used when constructing the default value of
813 @code{user-mail-address}. @xref{User Identification}. (Since this is
814 done when Emacs starts up, the value actually used is the one saved when
815 Emacs was dumped. @xref{Building Emacs}.)
818 @deffn Command getenv var
819 @cindex environment variable access
820 This function returns the value of the environment variable @var{var},
821 as a string. @var{var} should be a string. If @var{var} is undefined
822 in the environment, @code{getenv} returns @code{nil}. If returns
823 @samp{""} if @var{var} is set but null. Within Emacs, the environment
824 variable values are kept in the Lisp variable @code{process-environment}.
833 lewis@@slug[10] % printenv
834 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
846 @deffn Command setenv variable &optional value
847 This command sets the value of the environment variable named
848 @var{variable} to @var{value}. @var{variable} should be a string.
849 Internally, Emacs Lisp can handle any string. However, normally
850 @var{variable} should be a valid shell identifier, that is, a sequence
851 of letters, digits and underscores, starting with a letter or
852 underscore. Otherwise, errors may occur if subprocesses of Emacs try
853 to access the value of @var{variable}. If @var{value} is omitted or
854 @code{nil}, @code{setenv} removes @var{variable} from the environment.
855 Otherwise, @var{value} should be a string.
857 @code{setenv} works by modifying @code{process-environment}; binding
858 that variable with @code{let} is also reasonable practice.
860 @code{setenv} returns the new value of @var{variable}, or @code{nil}
861 if it removed @var{variable} from the environment.
864 @defvar process-environment
865 This variable is a list of strings, each describing one environment
866 variable. The functions @code{getenv} and @code{setenv} work by means
872 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
873 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
883 If @code{process-environment} contains ``duplicate'' elements that
884 specify the same environment variable, the first of these elements
885 specifies the variable, and the other ``duplicates'' are ignored.
888 @defvar initial-environment
889 This variable holds the list of environment variables Emacs inherited
890 from its parent process. It is computed during startup, see
891 @ref{Startup Summary}.
894 @defvar path-separator
895 This variable holds a string which says which character separates
896 directories in a search path (as found in an environment variable). Its
897 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
901 @defun parse-colon-path path
902 This function takes a search path string such as would be the value of
903 the @code{PATH} environment variable, and splits it at the separators,
904 returning a list of directory names. @code{nil} in this list stands for
905 ``use the current directory.'' Although the function's name says
906 ``colon,'' it actually uses the value of @code{path-separator}.
909 (parse-colon-path ":/foo:/bar")
910 @result{} (nil "/foo/" "/bar/")
914 @defvar invocation-name
915 This variable holds the program name under which Emacs was invoked. The
916 value is a string, and does not include a directory name.
919 @defvar invocation-directory
920 This variable holds the directory from which the Emacs executable was
921 invoked, or perhaps @code{nil} if that directory cannot be determined.
924 @defvar installation-directory
925 If non-@code{nil}, this is a directory within which to look for the
926 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
927 when Emacs can't find those directories in their standard installed
928 locations, but can find them in a directory related somehow to the one
929 containing the Emacs executable.
932 @defun load-average &optional use-float
933 This function returns the current 1-minute, 5-minute, and 15-minute load
936 By default, the values are integers that are 100 times the system load
937 averages, which indicate the average number of processes trying to run.
938 If @var{use-float} is non-@code{nil}, then they are returned
939 as floating point numbers and without multiplying by 100.
941 If it is impossible to obtain the load average, this function signals
942 an error. On some platforms, access to load averages requires
943 installing Emacs as setuid or setgid so that it can read kernel
944 information, and that usually isn't advisable.
946 If the 1-minute load average is available, but the 5- or 15-minute
947 averages are not, this function returns a shortened list containing
948 the available averages.
953 @result{} (169 48 36)
957 @result{} (1.69 0.48 0.36)
961 lewis@@rocky[5] % uptime
962 11:55am up 1 day, 19:37, 3 users,
963 load average: 1.69, 0.48, 0.36
969 This function returns the process @acronym{ID} of the Emacs process,
973 @defvar tty-erase-char
974 This variable holds the erase character that was selected
975 in the system's terminal driver, before Emacs was started.
976 The value is @code{nil} if Emacs is running under a window system.
979 @node User Identification
980 @section User Identification
981 @cindex user identification
983 @defvar init-file-user
984 This variable says which user's init files should be used by
985 Emacs---or @code{nil} if none. @code{""} stands for the user who
986 originally logged in. The value reflects command-line options such as
987 @samp{-q} or @samp{-u @var{user}}.
989 Lisp packages that load files of customizations, or any other sort of
990 user profile, should obey this variable in deciding where to find it.
991 They should load the profile of the user name found in this variable.
992 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
993 option was used, then Lisp packages should not load any customization
994 files or user profile.
997 @defvar user-mail-address
998 This holds the nominal email address of the user who is using Emacs.
999 Emacs normally sets this variable to a default value after reading your
1000 init files, but not if you have already set it. So you can set the
1001 variable to some other value in your init file if you do not
1002 want to use the default value.
1005 @defun user-login-name &optional uid
1006 If you don't specify @var{uid}, this function returns the name under
1007 which the user is logged in. If the environment variable @code{LOGNAME}
1008 is set, that value is used. Otherwise, if the environment variable
1009 @code{USER} is set, that value is used. Otherwise, the value is based
1010 on the effective @acronym{UID}, not the real @acronym{UID}.
1012 If you specify @var{uid}, the value is the user name that corresponds
1013 to @var{uid} (which should be an integer), or @code{nil} if there is
1024 @defun user-real-login-name
1025 This function returns the user name corresponding to Emacs's real
1026 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
1027 environment variables @code{LOGNAME} and @code{USER}.
1030 @defun user-full-name &optional uid
1031 This function returns the full name of the logged-in user---or the value
1032 of the environment variable @code{NAME}, if that is set.
1034 @c "Bil" is the correct spelling.
1038 @result{} "Bil Lewis"
1042 If the Emacs job's user-id does not correspond to any known user (and
1043 provided @code{NAME} is not set), the value is @code{"unknown"}.
1045 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
1046 or a string (a login name). Then @code{user-full-name} returns the full
1047 name corresponding to that user-id or login name. If you specify a
1048 user-id or login name that isn't defined, it returns @code{nil}.
1051 @vindex user-full-name
1052 @vindex user-real-login-name
1053 @vindex user-login-name
1054 The symbols @code{user-login-name}, @code{user-real-login-name} and
1055 @code{user-full-name} are variables as well as functions. The functions
1056 return the same values that the variables hold. These variables allow
1057 you to ``fake out'' Emacs by telling the functions what to return. The
1058 variables are also useful for constructing frame titles (@pxref{Frame
1061 @defun user-real-uid
1062 This function returns the real @acronym{UID} of the user.
1063 The value may be a floating point number.
1074 This function returns the effective @acronym{UID} of the user.
1075 The value may be a floating point number.
1079 @section Time of Day
1081 This section explains how to determine the current time and the time
1084 @defun current-time-string &optional time-value
1085 This function returns the current time and date as a human-readable
1086 string. The format of the string is unvarying; the number of characters
1087 used for each part is always the same, so you can reliably use
1088 @code{substring} to extract pieces of it. It is wise to count the
1089 characters from the beginning of the string rather than from the end, as
1090 additional information may some day be added at the end.
1093 The argument @var{time-value}, if given, specifies a time to format
1094 instead of the current time. The argument should be a list whose first
1095 two elements are integers. Thus, you can use times obtained from
1096 @code{current-time} (see below) and from @code{file-attributes}
1097 (@pxref{Definition of file-attributes}). @var{time-value} can also be
1098 a cons of two integers, but this is considered obsolete.
1102 (current-time-string)
1103 @result{} "Wed Oct 14 22:21:05 1987"
1110 This function returns the system's time value as a list of three
1111 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
1112 @var{high} and @var{low} combine to give the number of seconds since
1113 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1115 @var{high} * 2**16 + @var{low}.
1121 The third element, @var{microsec}, gives the microseconds since the
1122 start of the current second (or 0 for systems that return time with
1123 the resolution of only one second).
1125 The first two elements can be compared with file time values such as you
1126 get with the function @code{file-attributes}.
1127 @xref{Definition of file-attributes}.
1131 @defun current-time-zone &optional time-value
1132 This function returns a list describing the time zone that the user is
1135 The value has the form @code{(@var{offset} @var{name})}. Here
1136 @var{offset} is an integer giving the number of seconds ahead of UTC
1137 (east of Greenwich). A negative value means west of Greenwich. The
1138 second element, @var{name}, is a string giving the name of the time
1139 zone. Both elements change when daylight saving time begins or ends;
1140 if the user has specified a time zone that does not use a seasonal time
1141 adjustment, then the value is constant through time.
1143 If the operating system doesn't supply all the information necessary to
1144 compute the value, the unknown elements of the list are @code{nil}.
1146 The argument @var{time-value}, if given, specifies a time to analyze
1147 instead of the current time. The argument should have the same form
1148 as for @code{current-time-string} (see above). Thus, you can use
1149 times obtained from @code{current-time} (see above) and from
1150 @code{file-attributes}. @xref{Definition of file-attributes}.
1153 @defun set-time-zone-rule tz
1154 This function specifies the local time zone according to @var{tz}. If
1155 @var{tz} is @code{nil}, that means to use an implementation-defined
1156 default time zone. If @var{tz} is @code{t}, that means to use
1157 Universal Time. Otherwise, @var{tz} should be a string specifying a
1161 @defun float-time &optional time-value
1162 This function returns the current time as a floating-point number of
1163 seconds since the epoch. The argument @var{time-value}, if given,
1164 specifies a time to convert instead of the current time. The argument
1165 should have the same form as for @code{current-time-string} (see
1166 above). Thus, it accepts the output of @code{current-time} and
1167 @code{file-attributes}.
1169 @emph{Warning}: Since the result is floating point, it may not be
1170 exact. Do not use this function if precise time stamps are required.
1173 @node Time Conversion
1174 @section Time Conversion
1176 These functions convert time values (lists of two or three integers)
1177 to calendrical information and vice versa. You can get time values
1178 from the functions @code{current-time} (@pxref{Time of Day}) and
1179 @code{file-attributes} (@pxref{Definition of file-attributes}).
1181 Many operating systems are limited to time values that contain 32 bits
1182 of information; these systems typically handle only the times from
1183 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1184 operating systems have larger time values, and can represent times far
1185 in the past or future.
1187 Time conversion functions always use the Gregorian calendar, even
1188 for dates before the Gregorian calendar was introduced. Year numbers
1189 count the number of years since the year 1 B.C., and do not skip zero
1190 as traditional Gregorian years do; for example, the year number
1191 @minus{}37 represents the Gregorian year 38 B.C@.
1193 @defun decode-time &optional time
1194 This function converts a time value into calendrical information. If
1195 you don't specify @var{time}, it decodes the current time. The return
1196 value is a list of nine elements, as follows:
1199 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1202 Here is what the elements mean:
1206 The number of seconds past the minute, as an integer between 0 and 59.
1207 On some operating systems, this is 60 for leap seconds.
1209 The number of minutes past the hour, as an integer between 0 and 59.
1211 The hour of the day, as an integer between 0 and 23.
1213 The day of the month, as an integer between 1 and 31.
1215 The month of the year, as an integer between 1 and 12.
1217 The year, an integer typically greater than 1900.
1219 The day of week, as an integer between 0 and 6, where 0 stands for
1222 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1224 An integer indicating the time zone, as the number of seconds east of
1228 @strong{Common Lisp Note:} Common Lisp has different meanings for
1229 @var{dow} and @var{zone}.
1232 @defun encode-time seconds minutes hour day month year &optional zone
1233 This function is the inverse of @code{decode-time}. It converts seven
1234 items of calendrical data into a time value. For the meanings of the
1235 arguments, see the table above under @code{decode-time}.
1237 Year numbers less than 100 are not treated specially. If you want them
1238 to stand for years above 1900, or years above 2000, you must alter them
1239 yourself before you call @code{encode-time}.
1241 The optional argument @var{zone} defaults to the current time zone and
1242 its daylight saving time rules. If specified, it can be either a list
1243 (as you would get from @code{current-time-zone}), a string as in the
1244 @code{TZ} environment variable, @code{t} for Universal Time, or an
1245 integer (as you would get from @code{decode-time}). The specified
1246 zone is used without any further alteration for daylight saving time.
1248 If you pass more than seven arguments to @code{encode-time}, the first
1249 six are used as @var{seconds} through @var{year}, the last argument is
1250 used as @var{zone}, and the arguments in between are ignored. This
1251 feature makes it possible to use the elements of a list returned by
1252 @code{decode-time} as the arguments to @code{encode-time}, like this:
1255 (apply 'encode-time (decode-time @dots{}))
1258 You can perform simple date arithmetic by using out-of-range values for
1259 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1260 arguments; for example, day 0 means the day preceding the given month.
1262 The operating system puts limits on the range of possible time values;
1263 if you try to encode a time that is out of range, an error results.
1264 For instance, years before 1970 do not work on some systems;
1265 on others, years as early as 1901 do work.
1269 @section Parsing and Formatting Times
1271 These functions convert time values (lists of two or three integers)
1272 to text in a string, and vice versa.
1274 @defun date-to-time string
1275 This function parses the time-string @var{string} and returns the
1276 corresponding time value.
1279 @defun format-time-string format-string &optional time universal
1280 This function converts @var{time} (or the current time, if @var{time} is
1281 omitted) to a string according to @var{format-string}. The argument
1282 @var{format-string} may contain @samp{%}-sequences which say to
1283 substitute parts of the time. Here is a table of what the
1284 @samp{%}-sequences mean:
1288 This stands for the abbreviated name of the day of week.
1290 This stands for the full name of the day of week.
1292 This stands for the abbreviated name of the month.
1294 This stands for the full name of the month.
1296 This is a synonym for @samp{%x %X}.
1298 This has a locale-specific meaning. In the default locale (named C), it
1299 is equivalent to @samp{%A, %B %e, %Y}.
1301 This stands for the day of month, zero-padded.
1303 This is a synonym for @samp{%m/%d/%y}.
1305 This stands for the day of month, blank-padded.
1307 This is a synonym for @samp{%b}.
1309 This stands for the hour (00-23).
1311 This stands for the hour (01-12).
1313 This stands for the day of the year (001-366).
1315 This stands for the hour (0-23), blank padded.
1317 This stands for the hour (1-12), blank padded.
1319 This stands for the month (01-12).
1321 This stands for the minute (00-59).
1323 This stands for a newline.
1325 This stands for @samp{AM} or @samp{PM}, as appropriate.
1327 This is a synonym for @samp{%I:%M:%S %p}.
1329 This is a synonym for @samp{%H:%M}.
1331 This stands for the seconds (00-59).
1333 This stands for a tab character.
1335 This is a synonym for @samp{%H:%M:%S}.
1337 This stands for the week of the year (01-52), assuming that weeks
1340 This stands for the numeric day of week (0-6). Sunday is day 0.
1342 This stands for the week of the year (01-52), assuming that weeks
1345 This has a locale-specific meaning. In the default locale (named
1346 @samp{C}), it is equivalent to @samp{%D}.
1348 This has a locale-specific meaning. In the default locale (named
1349 @samp{C}), it is equivalent to @samp{%T}.
1351 This stands for the year without century (00-99).
1353 This stands for the year with century.
1355 This stands for the time zone abbreviation (e.g., @samp{EST}).
1357 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1360 You can also specify the field width and type of padding for any of
1361 these @samp{%}-sequences. This works as in @code{printf}: you write
1362 the field width as digits in the middle of a @samp{%}-sequences. If you
1363 start the field width with @samp{0}, it means to pad with zeros. If you
1364 start the field width with @samp{_}, it means to pad with spaces.
1366 For example, @samp{%S} specifies the number of seconds since the minute;
1367 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1368 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1369 because that is how @samp{%S} normally pads to two positions.
1371 The characters @samp{E} and @samp{O} act as modifiers when used between
1372 @samp{%} and one of the letters in the table above. @samp{E} specifies
1373 using the current locale's ``alternative'' version of the date and time.
1374 In a Japanese locale, for example, @code{%Ex} might yield a date format
1375 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1376 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1379 @samp{O} means to use the current locale's ``alternative''
1380 representation of numbers, instead of the ordinary decimal digits. This
1381 is allowed with most letters, all the ones that output numbers.
1383 If @var{universal} is non-@code{nil}, that means to describe the time as
1384 Universal Time; @code{nil} means describe it using what Emacs believes
1385 is the local time zone (see @code{current-time-zone}).
1387 This function uses the C library function @code{strftime}
1388 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1389 Manual}) to do most of the work. In order to communicate with that
1390 function, it first encodes its argument using the coding system
1391 specified by @code{locale-coding-system} (@pxref{Locales}); after
1392 @code{strftime} returns the resulting string,
1393 @code{format-time-string} decodes the string using that same coding
1397 @defun seconds-to-time seconds
1398 This function converts @var{seconds}, a floating point number of
1399 seconds since the epoch, to a time value and returns that. To perform
1400 the inverse conversion, use @code{float-time}.
1403 @defun format-seconds format-string seconds
1404 This function converts its argument @var{seconds} into a string of
1405 years, days, hours, etc., according to @var{format-string}. The
1406 argument @var{format-string} may contain @samp{%}-sequences which
1407 control the conversion. Here is a table of what the
1408 @samp{%}-sequences mean:
1413 The integer number of 365-day years.
1416 The integer number of days.
1419 The integer number of hours.
1422 The integer number of minutes.
1425 The integer number of seconds.
1427 Non-printing control flag. When it is used, other specifiers must be
1428 given in the order of decreasing size, i.e.@: years before days, hours
1429 before minutes, etc. Nothing will be produced in the result string to
1430 the left of @samp{%z} until the first non-zero conversion is
1431 encountered. For example, the default format used by
1432 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1433 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1434 will always be produced, but years, days, hours, and minutes will only
1435 be shown if they are non-zero.
1437 Produces a literal @samp{%}.
1440 Upper-case format sequences produce the units in addition to the
1441 numbers, lower-case formats produce only the numbers.
1443 You can also specify the field width by following the @samp{%} with a
1444 number; shorter numbers will be padded with blanks. An optional
1445 period before the width requests zero-padding instead. For example,
1446 @code{"%.3Y"} might produce @code{"004 years"}.
1448 @emph{Warning:} This function works only with values of @var{seconds}
1449 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1450 most-positive-fixnum}).
1453 @node Processor Run Time
1454 @section Processor Run time
1455 @cindex processor run time
1456 @cindex Emacs process run time
1458 Emacs provides several functions and primitives that return time,
1459 both elapsed and processor time, used by the Emacs process.
1461 @defun emacs-uptime &optional format
1462 This function returns a string representing the Emacs
1463 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1464 running. The string is formatted by @code{format-seconds} according
1465 to the optional argument @var{format}. For the available format
1466 descriptors, see @ref{Time Parsing, format-seconds}. If @var{format}
1467 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
1471 @defun get-internal-run-time
1472 This function returns the processor run time used by Emacs as a list
1473 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1474 integers @var{high} and @var{low} combine to give the number of
1477 @var{high} * 2**16 + @var{low}.
1483 The third element, @var{microsec}, gives the microseconds (or 0 for
1484 systems that return time with the resolution of only one second).
1486 Note that the time returned by this function excludes the time Emacs
1487 was not using the processor, and if the Emacs process has several
1488 threads, the returned value is the sum of the processor times used up
1489 by all Emacs threads.
1491 If the system doesn't provide a way to determine the processor run
1492 time, @code{get-internal-run-time} returns the same time as
1493 @code{current-time}.
1496 @defun emacs-init-time
1497 This function returns the duration of the Emacs initialization
1498 (@pxref{Startup Summary}) in seconds, as a string.
1501 @node Time Calculations
1502 @section Time Calculations
1504 These functions perform calendrical computations using time values
1505 (the kind of list that @code{current-time} returns).
1507 @defun time-less-p t1 t2
1508 This returns @code{t} if time value @var{t1} is less than time value
1512 @defun time-subtract t1 t2
1513 This returns the time difference @var{t1} @minus{} @var{t2} between
1514 two time values, in the same format as a time value.
1517 @defun time-add t1 t2
1518 This returns the sum of two time values, one of which ought to
1519 represent a time difference rather than a point in time.
1520 Here is how to add a number of seconds to a time value:
1523 (time-add @var{time} (seconds-to-time @var{seconds}))
1527 @defun time-to-days time
1528 This function returns the number of days between the beginning of year
1532 @defun time-to-day-in-year time
1533 This returns the day number within the year corresponding to @var{time}.
1536 @defun date-leap-year-p year
1537 This function returns @code{t} if @var{year} is a leap year.
1541 @section Timers for Delayed Execution
1544 You can set up a @dfn{timer} to call a function at a specified
1545 future time or after a certain length of idleness.
1547 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1548 can run them only when Emacs could accept output from a subprocess:
1549 namely, while waiting or inside certain primitive functions such as
1550 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1551 timer's execution may be delayed if Emacs is busy. However, the time of
1552 execution is very precise if Emacs is idle.
1554 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1555 function, because quitting out of many timer functions can leave
1556 things in an inconsistent state. This is normally unproblematical
1557 because most timer functions don't do a lot of work. Indeed, for a
1558 timer to call a function that takes substantial time to run is likely
1559 to be annoying. If a timer function needs to allow quitting, it
1560 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1561 a timer function calls @code{accept-process-output} to receive output
1562 from an external process, that call should be wrapped inside
1563 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1566 It is usually a bad idea for timer functions to alter buffer
1567 contents. When they do, they usually should call @code{undo-boundary}
1568 both before and after changing the buffer, to separate the timer's
1569 changes from user commands' changes and prevent a single undo entry
1570 from growing to be quite large.
1572 Timer functions should also avoid calling functions that cause Emacs
1573 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1574 unpredictable effects, since other timers (or even the same timer) can
1575 run while waiting. If a timer function needs to perform an action
1576 after a certain time has elapsed, it can do this by scheduling a new
1579 If a timer function calls functions that can change the match data,
1580 it should save and restore the match data. @xref{Saving Match Data}.
1582 @deffn Command run-at-time time repeat function &rest args
1583 This sets up a timer that calls the function @var{function} with
1584 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1585 (integer or floating point), the timer is scheduled to run again every
1586 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1587 the timer runs only once.
1589 @var{time} may specify an absolute or a relative time.
1591 Absolute times may be specified using a string with a limited variety
1592 of formats, and are taken to be times @emph{today}, even if already in
1593 the past. The recognized forms are @samp{@var{xxxx}},
1594 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1595 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1596 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1597 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1598 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1599 to separate the hour and minute parts.
1601 To specify a relative time as a string, use numbers followed by units.
1606 denotes 1 minute from now.
1608 denotes 65 seconds from now.
1609 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1610 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1613 For relative time values, Emacs considers a month to be exactly thirty
1614 days, and a year to be exactly 365.25 days.
1616 Not all convenient formats are strings. If @var{time} is a number
1617 (integer or floating point), that specifies a relative time measured in
1618 seconds. The result of @code{encode-time} can also be used to specify
1619 an absolute value for @var{time}.
1621 In most cases, @var{repeat} has no effect on when @emph{first} call
1622 takes place---@var{time} alone specifies that. There is one exception:
1623 if @var{time} is @code{t}, then the timer runs whenever the time is a
1624 multiple of @var{repeat} seconds after the epoch. This is useful for
1625 functions like @code{display-time}.
1627 The function @code{run-at-time} returns a timer value that identifies
1628 the particular scheduled future action. You can use this value to call
1629 @code{cancel-timer} (see below).
1632 A repeating timer nominally ought to run every @var{repeat} seconds,
1633 but remember that any invocation of a timer can be late. Lateness of
1634 one repetition has no effect on the scheduled time of the next
1635 repetition. For instance, if Emacs is busy computing for long enough
1636 to cover three scheduled repetitions of the timer, and then starts to
1637 wait, it will immediately call the timer function three times in
1638 immediate succession (presuming no other timers trigger before or
1639 between them). If you want a timer to run again no less than @var{n}
1640 seconds after the last invocation, don't use the @var{repeat} argument.
1641 Instead, the timer function should explicitly reschedule the timer.
1643 @defvar timer-max-repeats
1644 This variable's value specifies the maximum number of times to repeat
1645 calling a timer function in a row, when many previously scheduled
1646 calls were unavoidably delayed.
1649 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1650 Execute @var{body}, but give up after @var{seconds} seconds. If
1651 @var{body} finishes before the time is up, @code{with-timeout} returns
1652 the value of the last form in @var{body}. If, however, the execution of
1653 @var{body} is cut short by the timeout, then @code{with-timeout}
1654 executes all the @var{timeout-forms} and returns the value of the last
1657 This macro works by setting a timer to run after @var{seconds} seconds. If
1658 @var{body} finishes before that time, it cancels the timer. If the
1659 timer actually runs, it terminates execution of @var{body}, then
1660 executes @var{timeout-forms}.
1662 Since timers can run within a Lisp program only when the program calls a
1663 primitive that can wait, @code{with-timeout} cannot stop executing
1664 @var{body} while it is in the midst of a computation---only when it
1665 calls one of those primitives. So use @code{with-timeout} only with a
1666 @var{body} that waits for input, not one that does a long computation.
1669 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1670 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1673 @defun cancel-timer timer
1674 This cancels the requested action for @var{timer}, which should be a
1675 timer---usually, one previously returned by @code{run-at-time} or
1676 @code{run-with-idle-timer}. This cancels the effect of that call to
1677 one of these functions; the arrival of the specified time will not
1678 cause anything special to happen.
1682 @section Idle Timers
1684 Here is how to set up a timer that runs when Emacs is idle for a
1685 certain length of time. Aside from how to set them up, idle timers
1686 work just like ordinary timers.
1688 @deffn Command run-with-idle-timer secs repeat function &rest args
1689 Set up a timer which runs when Emacs has been idle for @var{secs}
1690 seconds. The value of @var{secs} may be an integer or a floating point
1691 number; a value of the type returned by @code{current-idle-time}
1694 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1695 Emacs remains idle for a long enough time. More often @var{repeat} is
1696 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1697 remains idle for @var{secs} seconds.
1699 The function @code{run-with-idle-timer} returns a timer value which you
1700 can use in calling @code{cancel-timer} (@pxref{Timers}).
1704 Emacs becomes ``idle'' when it starts waiting for user input, and it
1705 remains idle until the user provides some input. If a timer is set for
1706 five seconds of idleness, it runs approximately five seconds after Emacs
1707 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1708 will not run again as long as Emacs remains idle, because the duration
1709 of idleness will continue to increase and will not go down to five
1712 Emacs can do various things while idle: garbage collect, autosave or
1713 handle data from a subprocess. But these interludes during idleness do
1714 not interfere with idle timers, because they do not reset the clock of
1715 idleness to zero. An idle timer set for 600 seconds will run when ten
1716 minutes have elapsed since the last user command was finished, even if
1717 subprocess output has been accepted thousands of times within those ten
1718 minutes, and even if there have been garbage collections and autosaves.
1720 When the user supplies input, Emacs becomes non-idle while executing the
1721 input. Then it becomes idle again, and all the idle timers that are
1722 set up to repeat will subsequently run another time, one by one.
1725 @defun current-idle-time
1726 If Emacs is idle, this function returns the length of time Emacs has
1727 been idle, as a list of three integers: @code{(@var{high} @var{low}
1728 @var{microsec})}. The integers @var{high} and @var{low} combine to
1729 give the number of seconds of idleness, which is
1731 @var{high} * 2**16 + @var{low}.
1737 The third element, @var{microsec}, gives the microseconds since the
1738 start of the current second (or 0 for systems that return time with
1739 the resolution of only one second).
1741 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1742 This is a convenient way to test whether Emacs is idle.
1744 The main use of this function is when an idle timer function wants to
1745 ``take a break'' for a while. It can set up another idle timer to
1746 call the same function again, after a few seconds more idleness.
1750 (defvar resume-timer nil
1751 "Timer that `timer-function' used to reschedule itself, or nil.")
1753 (defun timer-function ()
1754 ;; @r{If the user types a command while @code{resume-timer}}
1755 ;; @r{is active, the next time this function is called from}
1756 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1758 (cancel-timer resume-timer))
1759 ...@var{do the work for a while}...
1760 (when @var{taking-a-break}
1762 (run-with-idle-timer
1763 ;; Compute an idle time @var{break-length}
1764 ;; more than the current value.
1765 (time-add (current-idle-time)
1766 (seconds-to-time @var{break-length}))
1772 Some idle timer functions in user Lisp packages have a loop that
1773 does a certain amount of processing each time around, and exits when
1774 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1775 natural but has two problems:
1779 It blocks out all process output (since Emacs accepts process output
1780 only while waiting).
1783 It blocks out any idle timers that ought to run during that time.
1787 To avoid these problems, don't use that technique. Instead, write
1788 such idle timers to reschedule themselves after a brief pause, using
1789 the method in the @code{timer-function} example above.
1791 @node Terminal Input
1792 @section Terminal Input
1793 @cindex terminal input
1795 This section describes functions and variables for recording or
1796 manipulating terminal input. See @ref{Display}, for related
1800 * Input Modes:: Options for how input is processed.
1801 * Recording Input:: Saving histories of recent or all input events.
1805 @subsection Input Modes
1807 @cindex terminal input modes
1809 @defun set-input-mode interrupt flow meta &optional quit-char
1810 This function sets the mode for reading keyboard input. If
1811 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1812 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1813 system-dependent. Some systems always use @sc{cbreak} mode regardless
1814 of what is specified.
1816 When Emacs communicates directly with X, it ignores this argument and
1817 uses interrupts if that is the way it knows how to communicate.
1819 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1820 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1821 has no effect except in @sc{cbreak} mode.
1824 The argument @var{meta} controls support for input character codes
1825 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1826 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1827 Emacs disregards the 8th bit; this is necessary when the terminal uses
1828 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1829 Emacs uses all 8 bits of input unchanged. This is good for terminals
1830 that use 8-bit character sets.
1833 If @var{quit-char} is non-@code{nil}, it specifies the character to
1834 use for quitting. Normally this character is @kbd{C-g}.
1838 The @code{current-input-mode} function returns the input mode settings
1839 Emacs is currently using.
1842 @defun current-input-mode
1843 This function returns the current mode for reading keyboard input. It
1844 returns a list, corresponding to the arguments of @code{set-input-mode},
1845 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1849 is non-@code{nil} when Emacs is using interrupt-driven input. If
1850 @code{nil}, Emacs is using @sc{cbreak} mode.
1852 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1853 flow control for output to the terminal. This value is meaningful only
1854 when @var{interrupt} is @code{nil}.
1856 is @code{t} if Emacs treats the eighth bit of input characters as
1857 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1858 input character; any other value means Emacs uses all eight bits as the
1859 basic character code.
1861 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1865 @node Recording Input
1866 @subsection Recording Input
1867 @cindex recording input
1870 This function returns a vector containing the last 300 input events from
1871 the keyboard or mouse. All input events are included, whether or not
1872 they were used as parts of key sequences. Thus, you always get the last
1873 100 input events, not counting events generated by keyboard macros.
1874 (These are excluded because they are less interesting for debugging; it
1875 should be enough to see the events that invoked the macros.)
1877 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1878 causes this function to return an empty vector immediately afterward.
1881 @deffn Command open-dribble-file filename
1882 @cindex dribble file
1883 This function opens a @dfn{dribble file} named @var{filename}. When a
1884 dribble file is open, each input event from the keyboard or mouse (but
1885 not those from keyboard macros) is written in that file. A
1886 non-character event is expressed using its printed representation
1887 surrounded by @samp{<@dots{}>}.
1889 You close the dribble file by calling this function with an argument
1892 This function is normally used to record the input necessary to
1893 trigger an Emacs bug, for the sake of a bug report.
1897 (open-dribble-file "~/dribble")
1903 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1905 @node Terminal Output
1906 @section Terminal Output
1907 @cindex terminal output
1909 The terminal output functions send output to a text terminal, or keep
1910 track of output sent to the terminal. The variable @code{baud-rate}
1911 tells you what Emacs thinks is the output speed of the terminal.
1914 This variable's value is the output speed of the terminal, as far as
1915 Emacs knows. Setting this variable does not change the speed of actual
1916 data transmission, but the value is used for calculations such as
1919 It also affects decisions about whether to scroll part of the
1920 screen or repaint on text terminals. @xref{Forcing Redisplay},
1921 for the corresponding functionality on graphical terminals.
1923 The value is measured in baud.
1926 If you are running across a network, and different parts of the
1927 network work at different baud rates, the value returned by Emacs may be
1928 different from the value used by your local terminal. Some network
1929 protocols communicate the local terminal speed to the remote machine, so
1930 that Emacs and other programs can get the proper value, but others do
1931 not. If Emacs has the wrong value, it makes decisions that are less
1932 than optimal. To fix the problem, set @code{baud-rate}.
1935 This obsolete function returns the value of the variable
1939 @defun send-string-to-terminal string
1940 This function sends @var{string} to the terminal without alteration.
1941 Control characters in @var{string} have terminal-dependent effects.
1942 This function operates only on text terminals.
1944 One use of this function is to define function keys on terminals that
1945 have downloadable function key definitions. For example, this is how (on
1946 certain terminals) to define function key 4 to move forward four
1947 characters (by transmitting the characters @kbd{C-u C-f} to the
1952 (send-string-to-terminal "\eF4\^U\^F")
1958 @deffn Command open-termscript filename
1959 @cindex termscript file
1960 This function is used to open a @dfn{termscript file} that will record
1961 all the characters sent by Emacs to the terminal. It returns
1962 @code{nil}. Termscript files are useful for investigating problems
1963 where Emacs garbles the screen, problems that are due to incorrect
1964 Termcap entries or to undesirable settings of terminal options more
1965 often than to actual Emacs bugs. Once you are certain which characters
1966 were actually output, you can determine reliably whether they correspond
1967 to the Termcap specifications in use.
1969 You close the termscript file by calling this function with an
1970 argument of @code{nil}.
1972 See also @code{open-dribble-file} in @ref{Recording Input}.
1976 (open-termscript "../junk/termscript")
1983 @section Sound Output
1986 To play sound using Emacs, use the function @code{play-sound}. Only
1987 certain systems are supported; if you call @code{play-sound} on a system
1988 which cannot really do the job, it gives an error. Emacs version 20 and
1989 earlier did not support sound at all.
1991 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1992 or Sun Audio format (@samp{.au}).
1994 @defun play-sound sound
1995 This function plays a specified sound. The argument, @var{sound}, has
1996 the form @code{(sound @var{properties}...)}, where the @var{properties}
1997 consist of alternating keywords (particular symbols recognized
1998 specially) and values corresponding to them.
2000 Here is a table of the keywords that are currently meaningful in
2001 @var{sound}, and their meanings:
2004 @item :file @var{file}
2005 This specifies the file containing the sound to play.
2006 If the file name is not absolute, it is expanded against
2007 the directory @code{data-directory}.
2009 @item :data @var{data}
2010 This specifies the sound to play without need to refer to a file. The
2011 value, @var{data}, should be a string containing the same bytes as a
2012 sound file. We recommend using a unibyte string.
2014 @item :volume @var{volume}
2015 This specifies how loud to play the sound. It should be a number in the
2016 range of 0 to 1. The default is to use whatever volume has been
2019 @item :device @var{device}
2020 This specifies the system device on which to play the sound, as a
2021 string. The default device is system-dependent.
2024 Before actually playing the sound, @code{play-sound}
2025 calls the functions in the list @code{play-sound-functions}.
2026 Each function is called with one argument, @var{sound}.
2029 @defun play-sound-file file &optional volume device
2030 This function is an alternative interface to playing a sound @var{file}
2031 specifying an optional @var{volume} and @var{device}.
2034 @defvar play-sound-functions
2035 A list of functions to be called before playing a sound. Each function
2036 is called with one argument, a property list that describes the sound.
2040 @section Operating on X11 Keysyms
2043 To define system-specific X11 keysyms, set the variable
2044 @code{system-key-alist}.
2046 @defvar system-key-alist
2047 This variable's value should be an alist with one element for each
2048 system-specific keysym. Each element has the form @code{(@var{code}
2049 . @var{symbol})}, where @var{code} is the numeric keysym code (not
2050 including the ``vendor specific'' bit,
2057 and @var{symbol} is the name for the function key.
2059 For example @code{(168 . mute-acute)} defines a system-specific key (used
2060 by HP X servers) whose numeric code is
2069 It is not crucial to exclude from the alist the keysyms of other X
2070 servers; those do no harm, as long as they don't conflict with the ones
2071 used by the X server actually in use.
2073 The variable is always local to the current terminal, and cannot be
2074 buffer-local. @xref{Multiple Displays}.
2077 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2079 @defvar x-alt-keysym
2080 @defvarx x-meta-keysym
2081 @defvarx x-hyper-keysym
2082 @defvarx x-super-keysym
2083 The name of the keysym that should stand for the Alt modifier
2084 (respectively, for Meta, Hyper, and Super). For example, here is
2085 how to swap the Meta and Alt modifiers within Emacs:
2087 (setq x-alt-keysym 'meta)
2088 (setq x-meta-keysym 'alt)
2096 The command-line option @samp{-batch} causes Emacs to run
2097 noninteractively. In this mode, Emacs does not read commands from the
2098 terminal, it does not alter the terminal modes, and it does not expect
2099 to be outputting to an erasable screen. The idea is that you specify
2100 Lisp programs to run; when they are finished, Emacs should exit. The
2101 way to specify the programs to run is with @samp{-l @var{file}}, which
2102 loads the library named @var{file}, or @samp{-f @var{function}}, which
2103 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2105 Any Lisp program output that would normally go to the echo area,
2106 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2107 as the stream, goes instead to Emacs's standard error descriptor when
2108 in batch mode. Similarly, input that would normally come from the
2109 minibuffer is read from the standard input descriptor.
2110 Thus, Emacs behaves much like a noninteractive
2111 application program. (The echo area output that Emacs itself normally
2112 generates, such as command echoing, is suppressed entirely.)
2114 @defvar noninteractive
2115 This variable is non-@code{nil} when Emacs is running in batch mode.
2118 @node Session Management
2119 @section Session Management
2120 @cindex session manager
2122 Emacs supports the X Session Management Protocol for suspension and
2123 restart of applications. In the X Window System, a program called the
2124 @dfn{session manager} has the responsibility to keep track of the
2125 applications that are running. During shutdown, the session manager
2126 asks applications to save their state, and delays the actual shutdown
2127 until they respond. An application can also cancel the shutdown.
2129 When the session manager restarts a suspended session, it directs
2130 these applications to individually reload their saved state. It does
2131 this by specifying a special command-line argument that says what
2132 saved session to restore. For Emacs, this argument is @samp{--smid
2135 @defvar emacs-save-session-functions
2136 Emacs supports saving state by using a hook called
2137 @code{emacs-save-session-functions}. Each function in this hook is
2138 called when the session manager tells Emacs that the window system is
2139 shutting down. The functions are called with no arguments and with the
2140 current buffer set to a temporary buffer. Each function can use
2141 @code{insert} to add Lisp code to this buffer. At the end, Emacs
2142 saves the buffer in a file that a subsequent Emacs invocation will
2143 load in order to restart the saved session.
2145 If a function in @code{emacs-save-session-functions} returns
2146 non-@code{nil}, Emacs tells the session manager to cancel the
2150 Here is an example that just inserts some text into @samp{*scratch*} when
2151 Emacs is restarted by the session manager.
2155 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2159 (defun save-yourself-test ()
2160 (insert "(save-excursion
2161 (switch-to-buffer \"*scratch*\")
2162 (insert \"I am restored\"))")
2168 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7