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:
750 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
753 A GNU/Linux system---that is, a variant GNU system, using the Linux
754 kernel. (These systems are the ones people often call ``Linux,'' but
755 actually Linux is just the kernel, not the whole system.)
758 Hewlett-Packard HPUX operating system.
761 Silicon Graphics Irix system.
764 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
765 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
772 Microsoft Windows NT and later. The same executable supports Windows
773 9X, but the value of @code{system-type} is @code{windows-nt} in either
778 We do not wish to add new symbols to make finer distinctions unless it
779 is absolutely necessary! In fact, we hope to eliminate some of these
780 alternatives in the future. We recommend using
781 @code{system-configuration} to distinguish between different operating
786 This function returns the name of the machine you are running on.
789 @result{} "www.gnu.org"
793 The symbol @code{system-name} is a variable as well as a function. In
794 fact, the function returns whatever value the variable
795 @code{system-name} currently holds. Thus, you can set the variable
796 @code{system-name} in case Emacs is confused about the name of your
797 system. The variable is also useful for constructing frame titles
798 (@pxref{Frame Titles}).
800 @defvar mail-host-address
801 If this variable is non-@code{nil}, it is used instead of
802 @code{system-name} for purposes of generating email addresses. For
803 example, it is used when constructing the default value of
804 @code{user-mail-address}. @xref{User Identification}. (Since this is
805 done when Emacs starts up, the value actually used is the one saved when
806 Emacs was dumped. @xref{Building Emacs}.)
809 @deffn Command getenv var
810 @cindex environment variable access
811 This function returns the value of the environment variable @var{var},
812 as a string. @var{var} should be a string. If @var{var} is undefined
813 in the environment, @code{getenv} returns @code{nil}. If returns
814 @samp{""} if @var{var} is set but null. Within Emacs, the environment
815 variable values are kept in the Lisp variable @code{process-environment}.
824 lewis@@slug[10] % printenv
825 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
837 @deffn Command setenv variable &optional value
838 This command sets the value of the environment variable named
839 @var{variable} to @var{value}. @var{variable} should be a string.
840 Internally, Emacs Lisp can handle any string. However, normally
841 @var{variable} should be a valid shell identifier, that is, a sequence
842 of letters, digits and underscores, starting with a letter or
843 underscore. Otherwise, errors may occur if subprocesses of Emacs try
844 to access the value of @var{variable}. If @var{value} is omitted or
845 @code{nil}, @code{setenv} removes @var{variable} from the environment.
846 Otherwise, @var{value} should be a string.
848 @code{setenv} works by modifying @code{process-environment}; binding
849 that variable with @code{let} is also reasonable practice.
851 @code{setenv} returns the new value of @var{variable}, or @code{nil}
852 if it removed @var{variable} from the environment.
855 @defvar process-environment
856 This variable is a list of strings, each describing one environment
857 variable. The functions @code{getenv} and @code{setenv} work by means
863 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
864 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
874 If @code{process-environment} contains ``duplicate'' elements that
875 specify the same environment variable, the first of these elements
876 specifies the variable, and the other ``duplicates'' are ignored.
879 @defun environment &optional frame
880 This is a convenience function that returns the value of
881 @code{process-environment} after removing unset and duplicate
882 variables from it. The optional argument @var{frame}, which should be
883 a frame, means return the list of environment variables in effect for
884 that frame. The value this function returns is a copy, so changing it
885 will have no effect on the environment variables passed to
889 @defvar initial-environment
890 This variable holds the list of environment variables Emacs inherited
891 from its parent process. It is computed during startup, see
892 @ref{Startup Summary}.
895 @defvar path-separator
896 This variable holds a string which says which character separates
897 directories in a search path (as found in an environment variable). Its
898 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
902 @defun parse-colon-path path
903 This function takes a search path string such as would be the value of
904 the @code{PATH} environment variable, and splits it at the separators,
905 returning a list of directory names. @code{nil} in this list stands for
906 ``use the current directory.'' Although the function's name says
907 ``colon,'' it actually uses the value of @code{path-separator}.
910 (parse-colon-path ":/foo:/bar")
911 @result{} (nil "/foo/" "/bar/")
915 @defvar invocation-name
916 This variable holds the program name under which Emacs was invoked. The
917 value is a string, and does not include a directory name.
920 @defvar invocation-directory
921 This variable holds the directory from which the Emacs executable was
922 invoked, or perhaps @code{nil} if that directory cannot be determined.
925 @defvar installation-directory
926 If non-@code{nil}, this is a directory within which to look for the
927 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
928 when Emacs can't find those directories in their standard installed
929 locations, but can find them in a directory related somehow to the one
930 containing the Emacs executable.
933 @defun load-average &optional use-float
934 This function returns the current 1-minute, 5-minute, and 15-minute load
937 By default, the values are integers that are 100 times the system load
938 averages, which indicate the average number of processes trying to run.
939 If @var{use-float} is non-@code{nil}, then they are returned
940 as floating point numbers and without multiplying by 100.
942 If it is impossible to obtain the load average, this function signals
943 an error. On some platforms, access to load averages requires
944 installing Emacs as setuid or setgid so that it can read kernel
945 information, and that usually isn't advisable.
947 If the 1-minute load average is available, but the 5- or 15-minute
948 averages are not, this function returns a shortened list containing
949 the available averages.
954 @result{} (169 48 36)
958 @result{} (1.69 0.48 0.36)
962 lewis@@rocky[5] % uptime
963 11:55am up 1 day, 19:37, 3 users,
964 load average: 1.69, 0.48, 0.36
970 This function returns the process @acronym{ID} of the Emacs process,
974 @defvar tty-erase-char
975 This variable holds the erase character that was selected
976 in the system's terminal driver, before Emacs was started.
977 The value is @code{nil} if Emacs is running under a window system.
980 @node User Identification
981 @section User Identification
982 @cindex user identification
984 @defvar init-file-user
985 This variable says which user's init files should be used by
986 Emacs---or @code{nil} if none. @code{""} stands for the user who
987 originally logged in. The value reflects command-line options such as
988 @samp{-q} or @samp{-u @var{user}}.
990 Lisp packages that load files of customizations, or any other sort of
991 user profile, should obey this variable in deciding where to find it.
992 They should load the profile of the user name found in this variable.
993 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
994 option was used, then Lisp packages should not load any customization
995 files or user profile.
998 @defvar user-mail-address
999 This holds the nominal email address of the user who is using Emacs.
1000 Emacs normally sets this variable to a default value after reading your
1001 init files, but not if you have already set it. So you can set the
1002 variable to some other value in your init file if you do not
1003 want to use the default value.
1006 @defun user-login-name &optional uid
1007 If you don't specify @var{uid}, this function returns the name under
1008 which the user is logged in. If the environment variable @code{LOGNAME}
1009 is set, that value is used. Otherwise, if the environment variable
1010 @code{USER} is set, that value is used. Otherwise, the value is based
1011 on the effective @acronym{UID}, not the real @acronym{UID}.
1013 If you specify @var{uid}, the value is the user name that corresponds
1014 to @var{uid} (which should be an integer), or @code{nil} if there is
1025 @defun user-real-login-name
1026 This function returns the user name corresponding to Emacs's real
1027 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
1028 environment variables @code{LOGNAME} and @code{USER}.
1031 @defun user-full-name &optional uid
1032 This function returns the full name of the logged-in user---or the value
1033 of the environment variable @code{NAME}, if that is set.
1035 @c "Bil" is the correct spelling.
1039 @result{} "Bil Lewis"
1043 If the Emacs job's user-id does not correspond to any known user (and
1044 provided @code{NAME} is not set), the value is @code{"unknown"}.
1046 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
1047 or a string (a login name). Then @code{user-full-name} returns the full
1048 name corresponding to that user-id or login name. If you specify a
1049 user-id or login name that isn't defined, it returns @code{nil}.
1052 @vindex user-full-name
1053 @vindex user-real-login-name
1054 @vindex user-login-name
1055 The symbols @code{user-login-name}, @code{user-real-login-name} and
1056 @code{user-full-name} are variables as well as functions. The functions
1057 return the same values that the variables hold. These variables allow
1058 you to ``fake out'' Emacs by telling the functions what to return. The
1059 variables are also useful for constructing frame titles (@pxref{Frame
1062 @defun user-real-uid
1063 This function returns the real @acronym{UID} of the user.
1064 The value may be a floating point number.
1075 This function returns the effective @acronym{UID} of the user.
1076 The value may be a floating point number.
1080 @section Time of Day
1082 This section explains how to determine the current time and the time
1085 @defun current-time-string &optional time-value
1086 This function returns the current time and date as a human-readable
1087 string. The format of the string is unvarying; the number of characters
1088 used for each part is always the same, so you can reliably use
1089 @code{substring} to extract pieces of it. It is wise to count the
1090 characters from the beginning of the string rather than from the end, as
1091 additional information may some day be added at the end.
1094 The argument @var{time-value}, if given, specifies a time to format
1095 instead of the current time. The argument should be a list whose first
1096 two elements are integers. Thus, you can use times obtained from
1097 @code{current-time} (see below) and from @code{file-attributes}
1098 (@pxref{Definition of file-attributes}). @var{time-value} can also be
1099 a cons of two integers, but this is considered obsolete.
1103 (current-time-string)
1104 @result{} "Wed Oct 14 22:21:05 1987"
1111 This function returns the system's time value as a list of three
1112 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
1113 @var{high} and @var{low} combine to give the number of seconds since
1114 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1116 @var{high} * 2**16 + @var{low}.
1122 The third element, @var{microsec}, gives the microseconds since the
1123 start of the current second (or 0 for systems that return time with
1124 the resolution of only one second).
1126 The first two elements can be compared with file time values such as you
1127 get with the function @code{file-attributes}.
1128 @xref{Definition of file-attributes}.
1132 @defun current-time-zone &optional time-value
1133 This function returns a list describing the time zone that the user is
1136 The value has the form @code{(@var{offset} @var{name})}. Here
1137 @var{offset} is an integer giving the number of seconds ahead of UTC
1138 (east of Greenwich). A negative value means west of Greenwich. The
1139 second element, @var{name}, is a string giving the name of the time
1140 zone. Both elements change when daylight saving time begins or ends;
1141 if the user has specified a time zone that does not use a seasonal time
1142 adjustment, then the value is constant through time.
1144 If the operating system doesn't supply all the information necessary to
1145 compute the value, the unknown elements of the list are @code{nil}.
1147 The argument @var{time-value}, if given, specifies a time to analyze
1148 instead of the current time. The argument should have the same form
1149 as for @code{current-time-string} (see above). Thus, you can use
1150 times obtained from @code{current-time} (see above) and from
1151 @code{file-attributes}. @xref{Definition of file-attributes}.
1154 @defun set-time-zone-rule tz
1155 This function specifies the local time zone according to @var{tz}. If
1156 @var{tz} is @code{nil}, that means to use an implementation-defined
1157 default time zone. If @var{tz} is @code{t}, that means to use
1158 Universal Time. Otherwise, @var{tz} should be a string specifying a
1162 @defun float-time &optional time-value
1163 This function returns the current time as a floating-point number of
1164 seconds since the epoch. The argument @var{time-value}, if given,
1165 specifies a time to convert instead of the current time. The argument
1166 should have the same form as for @code{current-time-string} (see
1167 above). Thus, it accepts the output of @code{current-time} and
1168 @code{file-attributes}.
1170 @emph{Warning}: Since the result is floating point, it may not be
1171 exact. Do not use this function if precise time stamps are required.
1174 @node Time Conversion
1175 @section Time Conversion
1177 These functions convert time values (lists of two or three integers)
1178 to calendrical information and vice versa. You can get time values
1179 from the functions @code{current-time} (@pxref{Time of Day}) and
1180 @code{file-attributes} (@pxref{Definition of file-attributes}).
1182 Many operating systems are limited to time values that contain 32 bits
1183 of information; these systems typically handle only the times from
1184 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1185 operating systems have larger time values, and can represent times far
1186 in the past or future.
1188 Time conversion functions always use the Gregorian calendar, even
1189 for dates before the Gregorian calendar was introduced. Year numbers
1190 count the number of years since the year 1 B.C., and do not skip zero
1191 as traditional Gregorian years do; for example, the year number
1192 @minus{}37 represents the Gregorian year 38 B.C@.
1194 @defun decode-time &optional time
1195 This function converts a time value into calendrical information. If
1196 you don't specify @var{time}, it decodes the current time. The return
1197 value is a list of nine elements, as follows:
1200 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1203 Here is what the elements mean:
1207 The number of seconds past the minute, as an integer between 0 and 59.
1208 On some operating systems, this is 60 for leap seconds.
1210 The number of minutes past the hour, as an integer between 0 and 59.
1212 The hour of the day, as an integer between 0 and 23.
1214 The day of the month, as an integer between 1 and 31.
1216 The month of the year, as an integer between 1 and 12.
1218 The year, an integer typically greater than 1900.
1220 The day of week, as an integer between 0 and 6, where 0 stands for
1223 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1225 An integer indicating the time zone, as the number of seconds east of
1229 @strong{Common Lisp Note:} Common Lisp has different meanings for
1230 @var{dow} and @var{zone}.
1233 @defun encode-time seconds minutes hour day month year &optional zone
1234 This function is the inverse of @code{decode-time}. It converts seven
1235 items of calendrical data into a time value. For the meanings of the
1236 arguments, see the table above under @code{decode-time}.
1238 Year numbers less than 100 are not treated specially. If you want them
1239 to stand for years above 1900, or years above 2000, you must alter them
1240 yourself before you call @code{encode-time}.
1242 The optional argument @var{zone} defaults to the current time zone and
1243 its daylight saving time rules. If specified, it can be either a list
1244 (as you would get from @code{current-time-zone}), a string as in the
1245 @code{TZ} environment variable, @code{t} for Universal Time, or an
1246 integer (as you would get from @code{decode-time}). The specified
1247 zone is used without any further alteration for daylight saving time.
1249 If you pass more than seven arguments to @code{encode-time}, the first
1250 six are used as @var{seconds} through @var{year}, the last argument is
1251 used as @var{zone}, and the arguments in between are ignored. This
1252 feature makes it possible to use the elements of a list returned by
1253 @code{decode-time} as the arguments to @code{encode-time}, like this:
1256 (apply 'encode-time (decode-time @dots{}))
1259 You can perform simple date arithmetic by using out-of-range values for
1260 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1261 arguments; for example, day 0 means the day preceding the given month.
1263 The operating system puts limits on the range of possible time values;
1264 if you try to encode a time that is out of range, an error results.
1265 For instance, years before 1970 do not work on some systems;
1266 on others, years as early as 1901 do work.
1270 @section Parsing and Formatting Times
1272 These functions convert time values (lists of two or three integers)
1273 to text in a string, and vice versa.
1275 @defun date-to-time string
1276 This function parses the time-string @var{string} and returns the
1277 corresponding time value.
1280 @defun format-time-string format-string &optional time universal
1281 This function converts @var{time} (or the current time, if @var{time} is
1282 omitted) to a string according to @var{format-string}. The argument
1283 @var{format-string} may contain @samp{%}-sequences which say to
1284 substitute parts of the time. Here is a table of what the
1285 @samp{%}-sequences mean:
1289 This stands for the abbreviated name of the day of week.
1291 This stands for the full name of the day of week.
1293 This stands for the abbreviated name of the month.
1295 This stands for the full name of the month.
1297 This is a synonym for @samp{%x %X}.
1299 This has a locale-specific meaning. In the default locale (named C), it
1300 is equivalent to @samp{%A, %B %e, %Y}.
1302 This stands for the day of month, zero-padded.
1304 This is a synonym for @samp{%m/%d/%y}.
1306 This stands for the day of month, blank-padded.
1308 This is a synonym for @samp{%b}.
1310 This stands for the hour (00-23).
1312 This stands for the hour (01-12).
1314 This stands for the day of the year (001-366).
1316 This stands for the hour (0-23), blank padded.
1318 This stands for the hour (1-12), blank padded.
1320 This stands for the month (01-12).
1322 This stands for the minute (00-59).
1324 This stands for a newline.
1326 This stands for @samp{AM} or @samp{PM}, as appropriate.
1328 This is a synonym for @samp{%I:%M:%S %p}.
1330 This is a synonym for @samp{%H:%M}.
1332 This stands for the seconds (00-59).
1334 This stands for a tab character.
1336 This is a synonym for @samp{%H:%M:%S}.
1338 This stands for the week of the year (01-52), assuming that weeks
1341 This stands for the numeric day of week (0-6). Sunday is day 0.
1343 This stands for the week of the year (01-52), assuming that weeks
1346 This has a locale-specific meaning. In the default locale (named
1347 @samp{C}), it is equivalent to @samp{%D}.
1349 This has a locale-specific meaning. In the default locale (named
1350 @samp{C}), it is equivalent to @samp{%T}.
1352 This stands for the year without century (00-99).
1354 This stands for the year with century.
1356 This stands for the time zone abbreviation (e.g., @samp{EST}).
1358 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1361 You can also specify the field width and type of padding for any of
1362 these @samp{%}-sequences. This works as in @code{printf}: you write
1363 the field width as digits in the middle of a @samp{%}-sequences. If you
1364 start the field width with @samp{0}, it means to pad with zeros. If you
1365 start the field width with @samp{_}, it means to pad with spaces.
1367 For example, @samp{%S} specifies the number of seconds since the minute;
1368 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1369 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1370 because that is how @samp{%S} normally pads to two positions.
1372 The characters @samp{E} and @samp{O} act as modifiers when used between
1373 @samp{%} and one of the letters in the table above. @samp{E} specifies
1374 using the current locale's ``alternative'' version of the date and time.
1375 In a Japanese locale, for example, @code{%Ex} might yield a date format
1376 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1377 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1380 @samp{O} means to use the current locale's ``alternative''
1381 representation of numbers, instead of the ordinary decimal digits. This
1382 is allowed with most letters, all the ones that output numbers.
1384 If @var{universal} is non-@code{nil}, that means to describe the time as
1385 Universal Time; @code{nil} means describe it using what Emacs believes
1386 is the local time zone (see @code{current-time-zone}).
1388 This function uses the C library function @code{strftime}
1389 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1390 Manual}) to do most of the work. In order to communicate with that
1391 function, it first encodes its argument using the coding system
1392 specified by @code{locale-coding-system} (@pxref{Locales}); after
1393 @code{strftime} returns the resulting string,
1394 @code{format-time-string} decodes the string using that same coding
1398 @defun seconds-to-time seconds
1399 This function converts @var{seconds}, a floating point number of
1400 seconds since the epoch, to a time value and returns that. To perform
1401 the inverse conversion, use @code{float-time}.
1404 @defun format-seconds format-string seconds
1405 This function converts its argument @var{seconds} into a string of
1406 years, days, hours, etc., according to @var{format-string}. The
1407 argument @var{format-string} may contain @samp{%}-sequences which
1408 control the conversion. Here is a table of what the
1409 @samp{%}-sequences mean:
1414 The integer number of 365-day years.
1417 The integer number of days.
1420 The integer number of hours.
1423 The integer number of minutes.
1426 The integer number of seconds.
1428 Non-printing control flag. When it is used, other specifiers must be
1429 given in the order of decreasing size, i.e.@: years before days, hours
1430 before minutes, etc. Nothing will be produced in the result string to
1431 the left of @samp{%z} until the first non-zero conversion is
1432 encountered. For example, the default format used by
1433 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1434 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1435 will always be produced, but years, days, hours, and minutes will only
1436 be shown if they are non-zero.
1438 Produces a literal @samp{%}.
1441 Upper-case format sequences produce the units in addition to the
1442 numbers, lower-case formats produce only the numbers.
1444 You can also specify the field width by following the @samp{%} with a
1445 number; shorter numbers will be padded with blanks. An optional
1446 period before the width requests zero-padding instead. For example,
1447 @code{"%.3Y"} might produce @code{"004 years"}.
1449 @emph{Warning:} This function works only with values of @var{seconds}
1450 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1451 most-positive-fixnum}).
1454 @node Processor Run Time
1455 @section Processor Run time
1456 @cindex processor run time
1457 @cindex Emacs process run time
1459 Emacs provides several functions and primitives that return time,
1460 both elapsed and processor time, used by the Emacs process.
1462 @defun emacs-uptime &optional format
1463 This function returns a string representing the Emacs
1464 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1465 running. The string is formatted by @code{format-seconds} according
1466 to the optional argument @var{format}. For the available format
1467 descriptors, see @ref{Time Parsing, format-seconds}. If @var{format}
1468 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
1472 @defun get-internal-run-time
1473 This function returns the processor run time used by Emacs as a list
1474 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1475 integers @var{high} and @var{low} combine to give the number of
1478 @var{high} * 2**16 + @var{low}.
1484 The third element, @var{microsec}, gives the microseconds (or 0 for
1485 systems that return time with the resolution of only one second).
1487 Note that the time returned by this function excludes the time Emacs
1488 was not using the processor, and if the Emacs process has several
1489 threads, the returned value is the sum of the processor times used up
1490 by all Emacs threads.
1492 If the system doesn't provide a way to determine the processor run
1493 time, @code{get-internal-run-time} returns the same time as
1494 @code{current-time}.
1497 @defun emacs-init-time
1498 This function returns the duration of the Emacs initialization
1499 (@pxref{Startup Summary}) in seconds, as a string.
1502 @node Time Calculations
1503 @section Time Calculations
1505 These functions perform calendrical computations using time values
1506 (the kind of list that @code{current-time} returns).
1508 @defun time-less-p t1 t2
1509 This returns @code{t} if time value @var{t1} is less than time value
1513 @defun time-subtract t1 t2
1514 This returns the time difference @var{t1} @minus{} @var{t2} between
1515 two time values, in the same format as a time value.
1518 @defun time-add t1 t2
1519 This returns the sum of two time values, one of which ought to
1520 represent a time difference rather than a point in time.
1521 Here is how to add a number of seconds to a time value:
1524 (time-add @var{time} (seconds-to-time @var{seconds}))
1528 @defun time-to-days time
1529 This function returns the number of days between the beginning of year
1533 @defun time-to-day-in-year time
1534 This returns the day number within the year corresponding to @var{time}.
1537 @defun date-leap-year-p year
1538 This function returns @code{t} if @var{year} is a leap year.
1542 @section Timers for Delayed Execution
1545 You can set up a @dfn{timer} to call a function at a specified
1546 future time or after a certain length of idleness.
1548 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1549 can run them only when Emacs could accept output from a subprocess:
1550 namely, while waiting or inside certain primitive functions such as
1551 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1552 timer's execution may be delayed if Emacs is busy. However, the time of
1553 execution is very precise if Emacs is idle.
1555 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1556 function, because quitting out of many timer functions can leave
1557 things in an inconsistent state. This is normally unproblematical
1558 because most timer functions don't do a lot of work. Indeed, for a
1559 timer to call a function that takes substantial time to run is likely
1560 to be annoying. If a timer function needs to allow quitting, it
1561 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1562 a timer function calls @code{accept-process-output} to receive output
1563 from an external process, that call should be wrapped inside
1564 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1567 It is usually a bad idea for timer functions to alter buffer
1568 contents. When they do, they usually should call @code{undo-boundary}
1569 both before and after changing the buffer, to separate the timer's
1570 changes from user commands' changes and prevent a single undo entry
1571 from growing to be quite large.
1573 Timer functions should also avoid calling functions that cause Emacs
1574 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1575 unpredictable effects, since other timers (or even the same timer) can
1576 run while waiting. If a timer function needs to perform an action
1577 after a certain time has elapsed, it can do this by scheduling a new
1580 If a timer function calls functions that can change the match data,
1581 it should save and restore the match data. @xref{Saving Match Data}.
1583 @deffn Command run-at-time time repeat function &rest args
1584 This sets up a timer that calls the function @var{function} with
1585 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1586 (integer or floating point), the timer is scheduled to run again every
1587 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1588 the timer runs only once.
1590 @var{time} may specify an absolute or a relative time.
1592 Absolute times may be specified using a string with a limited variety
1593 of formats, and are taken to be times @emph{today}, even if already in
1594 the past. The recognized forms are @samp{@var{xxxx}},
1595 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1596 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1597 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1598 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1599 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1600 to separate the hour and minute parts.
1602 To specify a relative time as a string, use numbers followed by units.
1607 denotes 1 minute from now.
1609 denotes 65 seconds from now.
1610 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1611 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1614 For relative time values, Emacs considers a month to be exactly thirty
1615 days, and a year to be exactly 365.25 days.
1617 Not all convenient formats are strings. If @var{time} is a number
1618 (integer or floating point), that specifies a relative time measured in
1619 seconds. The result of @code{encode-time} can also be used to specify
1620 an absolute value for @var{time}.
1622 In most cases, @var{repeat} has no effect on when @emph{first} call
1623 takes place---@var{time} alone specifies that. There is one exception:
1624 if @var{time} is @code{t}, then the timer runs whenever the time is a
1625 multiple of @var{repeat} seconds after the epoch. This is useful for
1626 functions like @code{display-time}.
1628 The function @code{run-at-time} returns a timer value that identifies
1629 the particular scheduled future action. You can use this value to call
1630 @code{cancel-timer} (see below).
1633 A repeating timer nominally ought to run every @var{repeat} seconds,
1634 but remember that any invocation of a timer can be late. Lateness of
1635 one repetition has no effect on the scheduled time of the next
1636 repetition. For instance, if Emacs is busy computing for long enough
1637 to cover three scheduled repetitions of the timer, and then starts to
1638 wait, it will immediately call the timer function three times in
1639 immediate succession (presuming no other timers trigger before or
1640 between them). If you want a timer to run again no less than @var{n}
1641 seconds after the last invocation, don't use the @var{repeat} argument.
1642 Instead, the timer function should explicitly reschedule the timer.
1644 @defvar timer-max-repeats
1645 This variable's value specifies the maximum number of times to repeat
1646 calling a timer function in a row, when many previously scheduled
1647 calls were unavoidably delayed.
1650 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1651 Execute @var{body}, but give up after @var{seconds} seconds. If
1652 @var{body} finishes before the time is up, @code{with-timeout} returns
1653 the value of the last form in @var{body}. If, however, the execution of
1654 @var{body} is cut short by the timeout, then @code{with-timeout}
1655 executes all the @var{timeout-forms} and returns the value of the last
1658 This macro works by setting a timer to run after @var{seconds} seconds. If
1659 @var{body} finishes before that time, it cancels the timer. If the
1660 timer actually runs, it terminates execution of @var{body}, then
1661 executes @var{timeout-forms}.
1663 Since timers can run within a Lisp program only when the program calls a
1664 primitive that can wait, @code{with-timeout} cannot stop executing
1665 @var{body} while it is in the midst of a computation---only when it
1666 calls one of those primitives. So use @code{with-timeout} only with a
1667 @var{body} that waits for input, not one that does a long computation.
1670 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1671 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1674 @defun cancel-timer timer
1675 This cancels the requested action for @var{timer}, which should be a
1676 timer---usually, one previously returned by @code{run-at-time} or
1677 @code{run-with-idle-timer}. This cancels the effect of that call to
1678 one of these functions; the arrival of the specified time will not
1679 cause anything special to happen.
1683 @section Idle Timers
1685 Here is how to set up a timer that runs when Emacs is idle for a
1686 certain length of time. Aside from how to set them up, idle timers
1687 work just like ordinary timers.
1689 @deffn Command run-with-idle-timer secs repeat function &rest args
1690 Set up a timer which runs when Emacs has been idle for @var{secs}
1691 seconds. The value of @var{secs} may be an integer or a floating point
1692 number; a value of the type returned by @code{current-idle-time}
1695 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1696 Emacs remains idle for a long enough time. More often @var{repeat} is
1697 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1698 remains idle for @var{secs} seconds.
1700 The function @code{run-with-idle-timer} returns a timer value which you
1701 can use in calling @code{cancel-timer} (@pxref{Timers}).
1705 Emacs becomes ``idle'' when it starts waiting for user input, and it
1706 remains idle until the user provides some input. If a timer is set for
1707 five seconds of idleness, it runs approximately five seconds after Emacs
1708 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1709 will not run again as long as Emacs remains idle, because the duration
1710 of idleness will continue to increase and will not go down to five
1713 Emacs can do various things while idle: garbage collect, autosave or
1714 handle data from a subprocess. But these interludes during idleness do
1715 not interfere with idle timers, because they do not reset the clock of
1716 idleness to zero. An idle timer set for 600 seconds will run when ten
1717 minutes have elapsed since the last user command was finished, even if
1718 subprocess output has been accepted thousands of times within those ten
1719 minutes, and even if there have been garbage collections and autosaves.
1721 When the user supplies input, Emacs becomes non-idle while executing the
1722 input. Then it becomes idle again, and all the idle timers that are
1723 set up to repeat will subsequently run another time, one by one.
1726 @defun current-idle-time
1727 If Emacs is idle, this function returns the length of time Emacs has
1728 been idle, as a list of three integers: @code{(@var{high} @var{low}
1729 @var{microsec})}. The integers @var{high} and @var{low} combine to
1730 give the number of seconds of idleness, which is
1732 @var{high} * 2**16 + @var{low}.
1738 The third element, @var{microsec}, gives the microseconds since the
1739 start of the current second (or 0 for systems that return time with
1740 the resolution of only one second).
1742 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1743 This is a convenient way to test whether Emacs is idle.
1745 The main use of this function is when an idle timer function wants to
1746 ``take a break'' for a while. It can set up another idle timer to
1747 call the same function again, after a few seconds more idleness.
1751 (defvar resume-timer nil
1752 "Timer that `timer-function' used to reschedule itself, or nil.")
1754 (defun timer-function ()
1755 ;; @r{If the user types a command while @code{resume-timer}}
1756 ;; @r{is active, the next time this function is called from}
1757 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1759 (cancel-timer resume-timer))
1760 ...@var{do the work for a while}...
1761 (when @var{taking-a-break}
1763 (run-with-idle-timer
1764 ;; Compute an idle time @var{break-length}
1765 ;; more than the current value.
1766 (time-add (current-idle-time)
1767 (seconds-to-time @var{break-length}))
1773 Some idle timer functions in user Lisp packages have a loop that
1774 does a certain amount of processing each time around, and exits when
1775 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1776 natural but has two problems:
1780 It blocks out all process output (since Emacs accepts process output
1781 only while waiting).
1784 It blocks out any idle timers that ought to run during that time.
1788 To avoid these problems, don't use that technique. Instead, write
1789 such idle timers to reschedule themselves after a brief pause, using
1790 the method in the @code{timer-function} example above.
1792 @node Terminal Input
1793 @section Terminal Input
1794 @cindex terminal input
1796 This section describes functions and variables for recording or
1797 manipulating terminal input. See @ref{Display}, for related
1801 * Input Modes:: Options for how input is processed.
1802 * Recording Input:: Saving histories of recent or all input events.
1806 @subsection Input Modes
1808 @cindex terminal input modes
1810 @defun set-input-mode interrupt flow meta &optional quit-char
1811 This function sets the mode for reading keyboard input. If
1812 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1813 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1814 system-dependent. Some systems always use @sc{cbreak} mode regardless
1815 of what is specified.
1817 When Emacs communicates directly with X, it ignores this argument and
1818 uses interrupts if that is the way it knows how to communicate.
1820 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1821 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1822 has no effect except in @sc{cbreak} mode.
1825 The argument @var{meta} controls support for input character codes
1826 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1827 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1828 Emacs disregards the 8th bit; this is necessary when the terminal uses
1829 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1830 Emacs uses all 8 bits of input unchanged. This is good for terminals
1831 that use 8-bit character sets.
1834 If @var{quit-char} is non-@code{nil}, it specifies the character to
1835 use for quitting. Normally this character is @kbd{C-g}.
1839 The @code{current-input-mode} function returns the input mode settings
1840 Emacs is currently using.
1843 @defun current-input-mode
1844 This function returns the current mode for reading keyboard input. It
1845 returns a list, corresponding to the arguments of @code{set-input-mode},
1846 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1850 is non-@code{nil} when Emacs is using interrupt-driven input. If
1851 @code{nil}, Emacs is using @sc{cbreak} mode.
1853 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1854 flow control for output to the terminal. This value is meaningful only
1855 when @var{interrupt} is @code{nil}.
1857 is @code{t} if Emacs treats the eighth bit of input characters as
1858 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1859 input character; any other value means Emacs uses all eight bits as the
1860 basic character code.
1862 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1866 @node Recording Input
1867 @subsection Recording Input
1868 @cindex recording input
1871 This function returns a vector containing the last 300 input events from
1872 the keyboard or mouse. All input events are included, whether or not
1873 they were used as parts of key sequences. Thus, you always get the last
1874 100 input events, not counting events generated by keyboard macros.
1875 (These are excluded because they are less interesting for debugging; it
1876 should be enough to see the events that invoked the macros.)
1878 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1879 causes this function to return an empty vector immediately afterward.
1882 @deffn Command open-dribble-file filename
1883 @cindex dribble file
1884 This function opens a @dfn{dribble file} named @var{filename}. When a
1885 dribble file is open, each input event from the keyboard or mouse (but
1886 not those from keyboard macros) is written in that file. A
1887 non-character event is expressed using its printed representation
1888 surrounded by @samp{<@dots{}>}.
1890 You close the dribble file by calling this function with an argument
1893 This function is normally used to record the input necessary to
1894 trigger an Emacs bug, for the sake of a bug report.
1898 (open-dribble-file "~/dribble")
1904 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1906 @node Terminal Output
1907 @section Terminal Output
1908 @cindex terminal output
1910 The terminal output functions send output to a text terminal, or keep
1911 track of output sent to the terminal. The variable @code{baud-rate}
1912 tells you what Emacs thinks is the output speed of the terminal.
1915 This variable's value is the output speed of the terminal, as far as
1916 Emacs knows. Setting this variable does not change the speed of actual
1917 data transmission, but the value is used for calculations such as
1920 It also affects decisions about whether to scroll part of the
1921 screen or repaint on text terminals. @xref{Forcing Redisplay},
1922 for the corresponding functionality on graphical terminals.
1924 The value is measured in baud.
1927 If you are running across a network, and different parts of the
1928 network work at different baud rates, the value returned by Emacs may be
1929 different from the value used by your local terminal. Some network
1930 protocols communicate the local terminal speed to the remote machine, so
1931 that Emacs and other programs can get the proper value, but others do
1932 not. If Emacs has the wrong value, it makes decisions that are less
1933 than optimal. To fix the problem, set @code{baud-rate}.
1936 This obsolete function returns the value of the variable
1940 @defun send-string-to-terminal string
1941 This function sends @var{string} to the terminal without alteration.
1942 Control characters in @var{string} have terminal-dependent effects.
1943 This function operates only on text terminals.
1945 One use of this function is to define function keys on terminals that
1946 have downloadable function key definitions. For example, this is how (on
1947 certain terminals) to define function key 4 to move forward four
1948 characters (by transmitting the characters @kbd{C-u C-f} to the
1953 (send-string-to-terminal "\eF4\^U\^F")
1959 @deffn Command open-termscript filename
1960 @cindex termscript file
1961 This function is used to open a @dfn{termscript file} that will record
1962 all the characters sent by Emacs to the terminal. It returns
1963 @code{nil}. Termscript files are useful for investigating problems
1964 where Emacs garbles the screen, problems that are due to incorrect
1965 Termcap entries or to undesirable settings of terminal options more
1966 often than to actual Emacs bugs. Once you are certain which characters
1967 were actually output, you can determine reliably whether they correspond
1968 to the Termcap specifications in use.
1970 You close the termscript file by calling this function with an
1971 argument of @code{nil}.
1973 See also @code{open-dribble-file} in @ref{Recording Input}.
1977 (open-termscript "../junk/termscript")
1984 @section Sound Output
1987 To play sound using Emacs, use the function @code{play-sound}. Only
1988 certain systems are supported; if you call @code{play-sound} on a system
1989 which cannot really do the job, it gives an error. Emacs version 20 and
1990 earlier did not support sound at all.
1992 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1993 or Sun Audio format (@samp{.au}).
1995 @defun play-sound sound
1996 This function plays a specified sound. The argument, @var{sound}, has
1997 the form @code{(sound @var{properties}...)}, where the @var{properties}
1998 consist of alternating keywords (particular symbols recognized
1999 specially) and values corresponding to them.
2001 Here is a table of the keywords that are currently meaningful in
2002 @var{sound}, and their meanings:
2005 @item :file @var{file}
2006 This specifies the file containing the sound to play.
2007 If the file name is not absolute, it is expanded against
2008 the directory @code{data-directory}.
2010 @item :data @var{data}
2011 This specifies the sound to play without need to refer to a file. The
2012 value, @var{data}, should be a string containing the same bytes as a
2013 sound file. We recommend using a unibyte string.
2015 @item :volume @var{volume}
2016 This specifies how loud to play the sound. It should be a number in the
2017 range of 0 to 1. The default is to use whatever volume has been
2020 @item :device @var{device}
2021 This specifies the system device on which to play the sound, as a
2022 string. The default device is system-dependent.
2025 Before actually playing the sound, @code{play-sound}
2026 calls the functions in the list @code{play-sound-functions}.
2027 Each function is called with one argument, @var{sound}.
2030 @defun play-sound-file file &optional volume device
2031 This function is an alternative interface to playing a sound @var{file}
2032 specifying an optional @var{volume} and @var{device}.
2035 @defvar play-sound-functions
2036 A list of functions to be called before playing a sound. Each function
2037 is called with one argument, a property list that describes the sound.
2041 @section Operating on X11 Keysyms
2044 To define system-specific X11 keysyms, set the variable
2045 @code{system-key-alist}.
2047 @defvar system-key-alist
2048 This variable's value should be an alist with one element for each
2049 system-specific keysym. Each element has the form @code{(@var{code}
2050 . @var{symbol})}, where @var{code} is the numeric keysym code (not
2051 including the ``vendor specific'' bit,
2058 and @var{symbol} is the name for the function key.
2060 For example @code{(168 . mute-acute)} defines a system-specific key (used
2061 by HP X servers) whose numeric code is
2070 It is not crucial to exclude from the alist the keysyms of other X
2071 servers; those do no harm, as long as they don't conflict with the ones
2072 used by the X server actually in use.
2074 The variable is always local to the current terminal, and cannot be
2075 buffer-local. @xref{Multiple Displays}.
2078 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2080 @defvar x-alt-keysym
2081 @defvarx x-meta-keysym
2082 @defvarx x-hyper-keysym
2083 @defvarx x-super-keysym
2084 The name of the keysym that should stand for the Alt modifier
2085 (respectively, for Meta, Hyper, and Super). For example, here is
2086 how to swap the Meta and Alt modifiers within Emacs:
2088 (setq x-alt-keysym 'meta)
2089 (setq x-meta-keysym 'alt)
2097 The command-line option @samp{-batch} causes Emacs to run
2098 noninteractively. In this mode, Emacs does not read commands from the
2099 terminal, it does not alter the terminal modes, and it does not expect
2100 to be outputting to an erasable screen. The idea is that you specify
2101 Lisp programs to run; when they are finished, Emacs should exit. The
2102 way to specify the programs to run is with @samp{-l @var{file}}, which
2103 loads the library named @var{file}, or @samp{-f @var{function}}, which
2104 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2106 Any Lisp program output that would normally go to the echo area,
2107 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2108 as the stream, goes instead to Emacs's standard error descriptor when
2109 in batch mode. Similarly, input that would normally come from the
2110 minibuffer is read from the standard input descriptor.
2111 Thus, Emacs behaves much like a noninteractive
2112 application program. (The echo area output that Emacs itself normally
2113 generates, such as command echoing, is suppressed entirely.)
2115 @defvar noninteractive
2116 This variable is non-@code{nil} when Emacs is running in batch mode.
2119 @node Session Management
2120 @section Session Management
2121 @cindex session manager
2123 Emacs supports the X Session Management Protocol for suspension and
2124 restart of applications. In the X Window System, a program called the
2125 @dfn{session manager} has the responsibility to keep track of the
2126 applications that are running. During shutdown, the session manager
2127 asks applications to save their state, and delays the actual shutdown
2128 until they respond. An application can also cancel the shutdown.
2130 When the session manager restarts a suspended session, it directs
2131 these applications to individually reload their saved state. It does
2132 this by specifying a special command-line argument that says what
2133 saved session to restore. For Emacs, this argument is @samp{--smid
2136 @defvar emacs-save-session-functions
2137 Emacs supports saving state by using a hook called
2138 @code{emacs-save-session-functions}. Each function in this hook is
2139 called when the session manager tells Emacs that the window system is
2140 shutting down. The functions are called with no arguments and with the
2141 current buffer set to a temporary buffer. Each function can use
2142 @code{insert} to add Lisp code to this buffer. At the end, Emacs
2143 saves the buffer in a file that a subsequent Emacs invocation will
2144 load in order to restart the saved session.
2146 If a function in @code{emacs-save-session-functions} returns
2147 non-@code{nil}, Emacs tells the session manager to cancel the
2151 Here is an example that just inserts some text into @samp{*scratch*} when
2152 Emacs is restarted by the session manager.
2156 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2160 (defun save-yourself-test ()
2161 (insert "(save-excursion
2162 (switch-to-buffer \"*scratch*\")
2163 (insert \"I am restored\"))")
2169 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7