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. @xref{Display}, for
15 additional operating system status information pertaining to the
16 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.
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 When Emacs is started up, it performs the following operations
62 (which are defined in @file{startup.el}):
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 those are scanned
69 in their turn. The files @file{subdirs.el} are normally generated
70 automatically when Emacs is installed.
72 @vindex before-init-time
74 It sets the variable @code{before-init-time} to the value of
75 @code{current-time} (@pxref{Time of Day}). It also sets
76 @code{after-init-time} to @code{nil}, which signals to Lisp programs
77 that Emacs is being initialized.
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 for each supported window system is specified by
89 @code{window-system-initialization-alist}.
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 loads the library @file{site-start}, if it exists. This is not
108 done if the options @samp{-Q} or @samp{--no-site-file} were specified.
109 @cindex @file{site-start.el}
112 It loads your init file (@pxref{Init File}). This is not done if the
113 options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If
114 the @samp{-u} option was specified, Emacs looks for the init file in
115 that user's home directory instead.
118 It loads the library @file{default}, if it exists. This is not done
119 if @code{inhibit-default-init} is non-@code{nil}, nor if the options
120 @samp{-q}, @samp{-Q}, or @samp{--batch} were specified.
121 @cindex @file{default.el}
124 It loads your abbrevs from the file specified by
125 @code{abbrev-file-name}, if that file exists and can be read
126 (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the
127 option @samp{--batch} was specified.
129 @vindex after-init-time
131 It sets the variable @code{after-init-time} to the value of
132 @code{current-time}. This variable was set to @code{nil} earlier;
133 setting it to the current time signals that the initialization phase
134 is over, and, together with @code{before-init-time}, provides the
135 measurement of how long it took.
138 It runs the normal hook @code{after-init-hook}.
141 If the buffer @samp{*scratch*} exists and is still in Fundamental mode
142 (as it should be by default), it sets its major mode according to
143 @code{initial-major-mode}.
146 If started on a text-only terminal, it loads the terminal-specific
147 Lisp library, which is specified by the variable
148 @code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done
149 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
152 It displays the initial echo area message, unless you have suppressed
153 that with @code{inhibit-startup-echo-area-message}.
156 It processes the action arguments from the command line.
159 It now exits if the option @code{--batch} was specified.
162 If @code{initial-buffer-choice} is a string, it visits the file with
163 that name. Furthermore, if the @samp{*scratch*} buffer exists and is
164 empty, it inserts @code{initial-scratch-message} into that buffer.
167 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
170 It calls @code{frame-notice-user-settings}, which modifies the
171 parameters of the selected frame according to whatever the init files
175 It runs @code{window-setup-hook}. @xref{Window Systems}.
178 If the option @code{--daemon} was specified, it calls
179 @code{server-start} and detaches from the controlling terminal.
180 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
183 It displays the @dfn{startup screen}, which is a special buffer that
184 contains information about copyleft and basic Emacs usage. This is
185 not done if @code{initial-buffer-choice} or
186 @code{inhibit-startup-screen} are @code{nil}, nor if the
187 @samp{--no-splash} or @samp{-Q} command-line options were specified.
190 If started by the X session manager, it calls
191 @code{emacs-session-restore} passing it as argument the ID of the
192 previous session. @xref{Session Management}.
195 @defopt inhibit-startup-screen
196 This variable, if non-@code{nil}, inhibits the startup screen. In
197 that case, Emacs typically displays the @samp{*scratch*} buffer; but
198 see @code{initial-buffer-choice}, below.
200 Do not set this variable in the init file of a new user, or in a way
201 that affects more than one user, as that would prevent new users from
202 receiving information about copyleft and basic Emacs usage.
204 @code{inhibit-startup-message} and @code{inhibit-splash-screen} are
205 aliases for this variable.
208 @defopt initial-buffer-choice
209 This variable, if non-@code{nil}, determines a file or buffer for
210 Emacs to display after starting up, instead of the startup screen. If
211 its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. If
212 its value is a string, that specifies the name of a file for Emacs to
216 @defopt inhibit-startup-echo-area-message
217 This variable controls the display of the startup echo area message.
218 You can suppress the startup echo area message by adding text with this
219 form to your init file:
222 (setq inhibit-startup-echo-area-message
223 "@var{your-login-name}")
226 Emacs explicitly checks for an expression as shown above in your init
227 file; your login name must appear in the expression as a Lisp string
228 constant. Other methods of setting
229 @code{inhibit-startup-echo-area-message} to the same value do not
230 inhibit the startup message. This way, you can easily inhibit the
231 message for yourself if you wish, but thoughtless copying of your init
232 file will not inhibit the message for someone else.
235 @defopt initial-scratch-message
236 This variable, if non-@code{nil}, should be a string, which is
237 inserted into the @samp{*scratch*} buffer when Emacs starts up. If it
238 is @code{nil}, the @samp{*scratch*} buffer is empty.
242 @subsection The Init File, @file{.emacs}
244 @cindex @file{.emacs}
246 When you start Emacs, it normally attempts to load your @dfn{init
247 file}. This is either a file named @file{.emacs} or @file{.emacs.el}
248 in your home directory, or a file named @file{init.el} in a
249 subdirectory named @file{.emacs.d} in your home directory. Whichever
250 place you use, you can also compile the file (@pxref{Byte
251 Compilation}); then the actual file loaded will be @file{.emacs.elc}
254 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
255 control whether and where to find the init file; @samp{-q} (and the
256 stronger @samp{-Q}) says not to load an init file, while @samp{-u
257 @var{user}} says to load @var{user}'s init file instead of yours.
258 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
259 option is specified, Emacs uses the @code{LOGNAME} environment
260 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
261 systems) variable, to find your home directory and thus your init
262 file; this way, even if you have su'd, Emacs still loads your own init
263 file. If those environment variables are absent, though, Emacs uses
264 your user-id to find your home directory.
266 @cindex default init file
267 A site may have a @dfn{default init file}, which is the library
268 named @file{default.el}. Emacs finds the @file{default.el} file
269 through the standard search path for libraries (@pxref{How Programs Do
270 Loading}). The Emacs distribution does not come with this file; sites
271 may provide one for local customizations. If the default init file
272 exists, it is loaded whenever you start Emacs, except in batch mode or
273 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
274 file, if any, is loaded first; if it sets @code{inhibit-default-init}
275 to a non-@code{nil} value, then Emacs does not subsequently load the
276 @file{default.el} file.
278 Another file for site-customization is @file{site-start.el}. Emacs
279 loads this @emph{before} the user's init file. You can inhibit the
280 loading of this file with the option @samp{--no-site-file}.
282 @defvar site-run-file
283 This variable specifies the site-customization file to load before the
284 user's init file. Its normal value is @code{"site-start"}. The only
285 way you can change it with real effect is to do so before dumping
289 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
290 examples of how to make various commonly desired customizations in your
293 @defopt inhibit-default-init
294 This variable prevents Emacs from loading the default initialization
295 library file for your session of Emacs. If its value is non-@code{nil},
296 then the default library is not loaded. The default value is
300 @defvar before-init-hook
301 This normal hook is run, once, just before loading all the init files
302 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
303 (The only way to change it with real effect is before dumping Emacs.)
306 @defvar after-init-hook
307 This normal hook is run, once, just after loading all the init files
308 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
309 before loading the terminal-specific library and processing the
310 command-line action arguments.
313 @defvar emacs-startup-hook
314 This normal hook is run, once, just after handling the command line
315 arguments, just before @code{term-setup-hook}.
318 @defvar user-init-file
319 This variable holds the absolute file name of the user's init file. If the
320 actual init file loaded is a compiled file, such as @file{.emacs.elc},
321 the value refers to the corresponding source file.
324 @defvar user-emacs-directory
325 This variable holds the name of the @file{.emacs.d} directory. It is
326 ordinarily @file{~/.emacs.d}, but differs on some platforms.
329 @node Terminal-Specific
330 @subsection Terminal-Specific Initialization
331 @cindex terminal-specific initialization
333 Each terminal type can have its own Lisp library that Emacs loads when
334 run on that type of terminal. The library's name is constructed by
335 concatenating the value of the variable @code{term-file-prefix} and the
336 terminal type (specified by the environment variable @code{TERM}).
337 Normally, @code{term-file-prefix} has the value
338 @code{"term/"}; changing this is not recommended. Emacs finds the file
339 in the normal manner, by searching the @code{load-path} directories, and
340 trying the @samp{.elc} and @samp{.el} suffixes.
343 The usual function of a terminal-specific library is to enable
344 special keys to send sequences that Emacs can recognize. It may also
345 need to set or add to @code{input-decode-map} if the Termcap or
346 Terminfo entry does not specify all the terminal's function keys.
347 @xref{Terminal Input}.
349 When the name of the terminal type contains a hyphen, and no library
350 is found whose name is identical to the terminal's name, Emacs strips
351 from the terminal's name the last hyphen and everything that follows
352 it, and tries again. This process is repeated until Emacs finds a
353 matching library or until there are no more hyphens in the name (the
354 latter means the terminal doesn't have any library specific to it).
355 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
356 libraries, Emacs will try the same library @file{term/aaa.el} for
357 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
358 library can evaluate @code{(getenv "TERM")} to find the full name of
359 the terminal type.@refill
361 Your init file can prevent the loading of the
362 terminal-specific library by setting the variable
363 @code{term-file-prefix} to @code{nil}. This feature is useful when
364 experimenting with your own peculiar customizations.
366 You can also arrange to override some of the actions of the
367 terminal-specific library by setting the variable
368 @code{term-setup-hook}. This is a normal hook which Emacs runs using
369 @code{run-hooks} at the end of Emacs initialization, after loading both
370 your init file and any terminal-specific libraries. You can
371 use this variable to define initializations for terminals that do not
372 have their own libraries. @xref{Hooks}.
374 @defvar term-file-prefix
375 @cindex @code{TERM} environment variable
376 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
377 a terminal-specific initialization file as follows:
380 (load (concat term-file-prefix (getenv "TERM")))
384 You may set the @code{term-file-prefix} variable to @code{nil} in your
385 init file if you do not wish to load the
386 terminal-initialization file. To do this, put the following in
387 your init file: @code{(setq term-file-prefix nil)}.
389 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
390 uses @samp{internal} as the terminal type.
393 @defvar term-setup-hook
394 This variable is a normal hook that Emacs runs after loading your
395 init file, the default initialization file (if any) and the
396 terminal-specific Lisp file.
398 You can use @code{term-setup-hook} to override the definitions made by a
399 terminal-specific file.
402 See @code{window-setup-hook} in @ref{Window Systems}, for a related
405 @node Command-Line Arguments
406 @subsection Command-Line Arguments
407 @cindex command-line arguments
409 You can use command-line arguments to request various actions when you
410 start Emacs. Since you do not need to start Emacs more than once per
411 day, and will often leave your Emacs session running longer than that,
412 command-line arguments are hardly ever used. As a practical matter, it
413 is best to avoid making the habit of using them, since this habit would
414 encourage you to kill and restart Emacs unnecessarily often. These
415 options exist for two reasons: to be compatible with other editors (for
416 invocation by other programs) and to enable shell scripts to run
417 specific Lisp programs.
419 This section describes how Emacs processes command-line arguments,
420 and how you can customize them.
423 (Note that some other editors require you to start afresh each time
424 you want to edit a file. With this kind of editor, you will probably
425 specify the file as a command-line argument. The recommended way to
426 use GNU Emacs is to start it only once, just after you log in, and do
427 all your editing in the same Emacs process. Each time you want to edit
428 a different file, you visit it with the existing Emacs, which eventually
429 comes to have many files in it ready for editing. Usually you do not
430 kill the Emacs until you are about to log out.)
434 This function parses the command line that Emacs was called with,
435 processes it, loads the user's init file and displays the
439 @defvar command-line-processed
440 The value of this variable is @code{t} once the command line has been
443 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
444 this variable to @code{nil} first in order to cause the new dumped Emacs
445 to process its new command-line arguments.
448 @defvar command-switch-alist
449 @cindex switches on command line
450 @cindex options on command line
451 @cindex command-line options
452 The value of this variable is an alist of user-defined command-line
453 options and associated handler functions. This variable exists so you
454 can add elements to it.
456 A @dfn{command-line option} is an argument on the command line, which
463 The elements of the @code{command-switch-alist} look like this:
466 (@var{option} . @var{handler-function})
469 The @sc{car}, @var{option}, is a string, the name of a command-line
470 option (not including the initial hyphen). The @var{handler-function}
471 is called to handle @var{option}, and receives the option name as its
474 In some cases, the option is followed in the command line by an
475 argument. In these cases, the @var{handler-function} can find all the
476 remaining command-line arguments in the variable
477 @code{command-line-args-left}. (The entire list of command-line
478 arguments is in @code{command-line-args}.)
480 The command-line arguments are parsed by the @code{command-line-1}
481 function in the @file{startup.el} file. See also @ref{Emacs
482 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
486 @defvar command-line-args
487 The value of this variable is the list of command-line arguments passed
491 @defvar command-line-args-left
492 The value of this variable is the list of command-line arguments that
493 have not yet been processed. @code{argv} is an alias for this.
496 @defvar command-line-functions
497 This variable's value is a list of functions for handling an
498 unrecognized command-line argument. Each time the next argument to be
499 processed has no special meaning, the functions in this list are called,
500 in order of appearance, until one of them returns a non-@code{nil}
503 These functions are called with no arguments. They can access the
504 command-line argument under consideration through the variable
505 @code{argi}, which is bound temporarily at this point. The remaining
506 arguments (not including the current one) are in the variable
507 @code{command-line-args-left}.
509 When a function recognizes and processes the argument in @code{argi}, it
510 should return a non-@code{nil} value to say it has dealt with that
511 argument. If it has also dealt with some of the following arguments, it
512 can indicate that by deleting them from @code{command-line-args-left}.
514 If all of these functions return @code{nil}, then the argument is used
515 as a file name to visit.
519 @section Getting Out of Emacs
520 @cindex exiting Emacs
522 There are two ways to get out of Emacs: you can kill the Emacs job,
523 which exits permanently, or you can suspend it, which permits you to
524 reenter the Emacs process later. As a practical matter, you seldom kill
525 Emacs---only when you are about to log out. Suspending is much more
529 * Killing Emacs:: Exiting Emacs irreversibly.
530 * Suspending Emacs:: Exiting Emacs reversibly.
534 @comment node-name, next, previous, up
535 @subsection Killing Emacs
536 @cindex killing Emacs
538 Killing Emacs means ending the execution of the Emacs process. The
539 parent process normally resumes control. The low-level primitive for
540 killing Emacs is @code{kill-emacs}.
542 @defun kill-emacs &optional exit-data
543 This function exits the Emacs process and kills it.
545 If @var{exit-data} is an integer, then it is used as the exit status
546 of the Emacs process. (This is useful primarily in batch operation; see
549 If @var{exit-data} is a string, its contents are stuffed into the
550 terminal input buffer so that the shell (or whatever program next reads
551 input) can read them.
554 All the information in the Emacs process, aside from files that have
555 been saved, is lost when the Emacs process is killed. Because killing
556 Emacs inadvertently can lose a lot of work, Emacs queries for
557 confirmation before actually terminating if you have buffers that need
558 saving or subprocesses that are running. This is done in the function
559 @code{save-buffers-kill-emacs}, the higher level function from which
560 @code{kill-emacs} is usually called.
562 @defvar kill-emacs-query-functions
563 After asking the standard questions, @code{save-buffers-kill-emacs}
564 calls the functions in the list @code{kill-emacs-query-functions}, in
565 order of appearance, with no arguments. These functions can ask for
566 additional confirmation from the user. If any of them returns
567 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
568 does not run the remaining functions in this hook. Calling
569 @code{kill-emacs} directly does not run this hook.
572 @defvar kill-emacs-hook
573 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
574 finished with all file saving and confirmation, it calls
575 @code{kill-emacs} which runs the functions in this hook.
576 @code{kill-emacs} does not run this hook in batch mode.
578 @code{kill-emacs} may be invoked directly (that is not via
579 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
580 similar situations where interaction with the user is not possible.
581 Thus, if your hook needs to interact with the user, put it on
582 @code{kill-emacs-query-functions}; if it needs to run regardless of
583 how Emacs is killed, put it on @code{kill-emacs-hook}.
586 @node Suspending Emacs
587 @subsection Suspending Emacs
588 @cindex suspending Emacs
590 On text-only terminals, it is possible to @dfn{suspend Emacs}, which
591 means stopping Emacs temporarily and returning control to its superior
592 process, which is usually the shell. This allows you to resume
593 editing later in the same Emacs process, with the same buffers, the
594 same kill ring, the same undo history, and so on. To resume Emacs,
595 use the appropriate command in the parent shell---most likely
598 @cindex controlling terminal
599 Suspending works only on a terminal device from which the Emacs
600 session was started. We call that device the @dfn{controlling
601 terminal} of the session. Suspending is not allowed if the
602 controlling terminal is a graphical terminal.
604 Some operating systems do not support suspension of jobs; on these
605 systems, ``suspension'' actually creates a new shell temporarily as a
606 subprocess of Emacs. Then you would exit the shell to return to Emacs.
608 @defun suspend-emacs &optional string
609 This function stops Emacs and returns control to the superior process.
610 If and when the superior process resumes Emacs, @code{suspend-emacs}
611 returns @code{nil} to its caller in Lisp.
613 This function works only on the controlling terminal of the Emacs
614 session; to relinquish control of other tty devices, use
615 @code{suspend-tty} (see below). If the Emacs session uses more than
616 one terminal, you must delete the frames on all the other terminals
617 before suspending Emacs, or this function signals an error.
618 @xref{Multiple Terminals}.
620 If @var{string} is non-@code{nil}, its characters are sent to Emacs's
621 superior shell, to be read as terminal input. The characters in
622 @var{string} are not echoed by the superior shell; only the results
625 Before suspending, @code{suspend-emacs} runs the normal hook
626 @code{suspend-hook}. After the user resumes Emacs,
627 @code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}.
630 The next redisplay after resumption will redraw the entire screen,
631 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}.
632 @xref{Refresh Screen}.
634 In the following example, note that @samp{pwd} is not echoed after
635 Emacs is suspended. But it is read and executed by the shell.
644 (add-hook 'suspend-hook
648 (error "Suspend canceled")))))
649 @result{} (lambda nil
650 (or (y-or-n-p "Really suspend? ")
651 (error "Suspend canceled")))
654 (add-hook 'suspend-resume-hook
655 (function (lambda () (message "Resumed!"))))
656 @result{} (lambda nil (message "Resumed!"))
659 (suspend-emacs "pwd")
663 ---------- Buffer: Minibuffer ----------
664 Really suspend? @kbd{y}
665 ---------- Buffer: Minibuffer ----------
669 ---------- Parent Shell ----------
670 lewis@@slug[23] % /user/lewis/manual
675 ---------- Echo Area ----------
682 This variable is a normal hook that Emacs runs before suspending.
685 @defvar suspend-resume-hook
686 This variable is a normal hook that Emacs runs on resuming
690 @defun suspend-tty &optional tty
691 If @var{tty} specifies a terminal device used by Emacs, this function
692 relinquishes the device and restores it to its prior state. Frames
693 that used the device continue to exist, but are not updated and Emacs
694 doesn't read input from them. @var{tty} can be a terminal object, a
695 frame (meaning the terminal for that frame), or @code{nil} (meaning
696 the terminal for the selected frame). @xref{Multiple Terminals}.
698 If @var{tty} is already suspended, this function does nothing.
700 This function runs the hook @code{suspend-tty-functions}, passing the
701 terminal object as an argument to each function.
704 @defun resume-tty &optional tty
705 This function resumes the previously suspended terminal device
706 @var{tty}; @var{tty} can be a terminal object, a frame (meaning the
707 terminal for that frame), or @code{nil} (meaning the terminal for the
710 This function reopens the terminal device, re-initializes it, and
711 redraws its with that terminal's selected frame. It then runs the
712 hook @code{resume-tty-functions}, passing the terminal object as an
713 argument to each function.
715 If the same device is already used by another Emacs terminal, this
716 function signals an error.
719 @defun controlling-tty-p &optional terminal
720 This function returns non-@code{nil} if @var{terminal} is the
721 controlling terminal of the Emacs session; @code{terminal} can be a
722 terminal object, a frame (meaning the terminal for that frame), or
723 @code{nil} (meaning the terminal for the selected frame).
726 @deffn Command suspend-frame
727 This command @dfn{suspends} a frame. For GUI frames, it calls
728 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
729 frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
730 depending on whether the frame is displayed on the controlling
731 terminal device or not.
734 @node System Environment
735 @section Operating System Environment
736 @cindex operating system environment
738 Emacs provides access to variables in the operating system environment
739 through various functions. These variables include the name of the
740 system, the user's @acronym{UID}, and so on.
742 @defvar system-configuration
743 This variable holds the standard GNU configuration name for the
744 hardware/software configuration of your system, as a string. The
745 convenient way to test parts of this string is with
749 @cindex system type and name
751 The value of this variable is a symbol indicating the type of operating
752 system Emacs is operating on. Here is a table of the possible values:
759 Berkeley BSD and its variants.
762 Cygwin, a Posix layer on top of MS-Windows.
768 The GNU system (using the GNU kernel, which consists of the HURD and Mach).
771 A GNU/Linux system---that is, a variant GNU system, using the Linux
772 kernel. (These systems are the ones people often call ``Linux,'' but
773 actually Linux is just the kernel, not the whole system.)
776 A GNU (glibc-based) system with a FreeBSD kernel.
779 Hewlett-Packard HPUX operating system.
782 Silicon Graphics Irix system.
788 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
789 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
796 Microsoft Windows NT and later. The same executable supports Windows
797 9X, but the value of @code{system-type} is @code{windows-nt} in either
802 We do not wish to add new symbols to make finer distinctions unless it
803 is absolutely necessary! In fact, we hope to eliminate some of these
804 alternatives in the future. We recommend using
805 @code{system-configuration} to distinguish between different operating
810 This function returns the name of the machine you are running on.
813 @result{} "www.gnu.org"
817 The symbol @code{system-name} is a variable as well as a function. In
818 fact, the function returns whatever value the variable
819 @code{system-name} currently holds. Thus, you can set the variable
820 @code{system-name} in case Emacs is confused about the name of your
821 system. The variable is also useful for constructing frame titles
822 (@pxref{Frame Titles}).
824 @defvar mail-host-address
825 If this variable is non-@code{nil}, it is used instead of
826 @code{system-name} for purposes of generating email addresses. For
827 example, it is used when constructing the default value of
828 @code{user-mail-address}. @xref{User Identification}. (Since this is
829 done when Emacs starts up, the value actually used is the one saved when
830 Emacs was dumped. @xref{Building Emacs}.)
833 @deffn Command getenv var
834 @cindex environment variable access
835 This function returns the value of the environment variable @var{var},
836 as a string. @var{var} should be a string. If @var{var} is undefined
837 in the environment, @code{getenv} returns @code{nil}. If returns
838 @samp{""} if @var{var} is set but null. Within Emacs, the environment
839 variable values are kept in the Lisp variable @code{process-environment}.
848 lewis@@slug[10] % printenv
849 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
861 @deffn Command setenv variable &optional value
862 This command sets the value of the environment variable named
863 @var{variable} to @var{value}. @var{variable} should be a string.
864 Internally, Emacs Lisp can handle any string. However, normally
865 @var{variable} should be a valid shell identifier, that is, a sequence
866 of letters, digits and underscores, starting with a letter or
867 underscore. Otherwise, errors may occur if subprocesses of Emacs try
868 to access the value of @var{variable}. If @var{value} is omitted or
869 @code{nil}, @code{setenv} removes @var{variable} from the environment.
870 Otherwise, @var{value} should be a string.
872 @code{setenv} works by modifying @code{process-environment}; binding
873 that variable with @code{let} is also reasonable practice.
875 @code{setenv} returns the new value of @var{variable}, or @code{nil}
876 if it removed @var{variable} from the environment.
879 @defvar process-environment
880 This variable is a list of strings, each describing one environment
881 variable. The functions @code{getenv} and @code{setenv} work by means
887 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
888 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
898 If @code{process-environment} contains ``duplicate'' elements that
899 specify the same environment variable, the first of these elements
900 specifies the variable, and the other ``duplicates'' are ignored.
903 @defvar initial-environment
904 This variable holds the list of environment variables Emacs inherited
905 from its parent process. It is computed during startup, see
906 @ref{Startup Summary}.
909 @defvar path-separator
910 This variable holds a string which says which character separates
911 directories in a search path (as found in an environment variable). Its
912 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
916 @defun parse-colon-path path
917 This function takes a search path string such as would be the value of
918 the @code{PATH} environment variable, and splits it at the separators,
919 returning a list of directory names. @code{nil} in this list stands for
920 ``use the current directory.'' Although the function's name says
921 ``colon,'' it actually uses the value of @code{path-separator}.
924 (parse-colon-path ":/foo:/bar")
925 @result{} (nil "/foo/" "/bar/")
929 @defvar invocation-name
930 This variable holds the program name under which Emacs was invoked. The
931 value is a string, and does not include a directory name.
934 @defvar invocation-directory
935 This variable holds the directory from which the Emacs executable was
936 invoked, or perhaps @code{nil} if that directory cannot be determined.
939 @defvar installation-directory
940 If non-@code{nil}, this is a directory within which to look for the
941 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
942 when Emacs can't find those directories in their standard installed
943 locations, but can find them in a directory related somehow to the one
944 containing the Emacs executable.
947 @defun load-average &optional use-float
948 This function returns the current 1-minute, 5-minute, and 15-minute load
951 By default, the values are integers that are 100 times the system load
952 averages, which indicate the average number of processes trying to run.
953 If @var{use-float} is non-@code{nil}, then they are returned
954 as floating point numbers and without multiplying by 100.
956 If it is impossible to obtain the load average, this function signals
957 an error. On some platforms, access to load averages requires
958 installing Emacs as setuid or setgid so that it can read kernel
959 information, and that usually isn't advisable.
961 If the 1-minute load average is available, but the 5- or 15-minute
962 averages are not, this function returns a shortened list containing
963 the available averages.
968 @result{} (169 48 36)
972 @result{} (1.69 0.48 0.36)
976 lewis@@rocky[5] % uptime
977 11:55am up 1 day, 19:37, 3 users,
978 load average: 1.69, 0.48, 0.36
984 This function returns the process @acronym{ID} of the Emacs process,
988 @defvar tty-erase-char
989 This variable holds the erase character that was selected
990 in the system's terminal driver, before Emacs was started.
991 The value is @code{nil} if Emacs is running under a window system.
994 @node User Identification
995 @section User Identification
996 @cindex user identification
998 @defvar init-file-user
999 This variable says which user's init files should be used by
1000 Emacs---or @code{nil} if none. @code{""} stands for the user who
1001 originally logged in. The value reflects command-line options such as
1002 @samp{-q} or @samp{-u @var{user}}.
1004 Lisp packages that load files of customizations, or any other sort of
1005 user profile, should obey this variable in deciding where to find it.
1006 They should load the profile of the user name found in this variable.
1007 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
1008 option was used, then Lisp packages should not load any customization
1009 files or user profile.
1012 @defvar user-mail-address
1013 This holds the nominal email address of the user who is using Emacs.
1014 Emacs normally sets this variable to a default value after reading your
1015 init files, but not if you have already set it. So you can set the
1016 variable to some other value in your init file if you do not
1017 want to use the default value.
1020 @defun user-login-name &optional uid
1021 If you don't specify @var{uid}, this function returns the name under
1022 which the user is logged in. If the environment variable @code{LOGNAME}
1023 is set, that value is used. Otherwise, if the environment variable
1024 @code{USER} is set, that value is used. Otherwise, the value is based
1025 on the effective @acronym{UID}, not the real @acronym{UID}.
1027 If you specify @var{uid}, the value is the user name that corresponds
1028 to @var{uid} (which should be an integer), or @code{nil} if there is
1039 @defun user-real-login-name
1040 This function returns the user name corresponding to Emacs's real
1041 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
1042 environment variables @code{LOGNAME} and @code{USER}.
1045 @defun user-full-name &optional uid
1046 This function returns the full name of the logged-in user---or the value
1047 of the environment variable @code{NAME}, if that is set.
1049 @c "Bil" is the correct spelling.
1053 @result{} "Bil Lewis"
1057 If the Emacs job's user-id does not correspond to any known user (and
1058 provided @code{NAME} is not set), the value is @code{"unknown"}.
1060 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
1061 or a string (a login name). Then @code{user-full-name} returns the full
1062 name corresponding to that user-id or login name. If you specify a
1063 user-id or login name that isn't defined, it returns @code{nil}.
1066 @vindex user-full-name
1067 @vindex user-real-login-name
1068 @vindex user-login-name
1069 The symbols @code{user-login-name}, @code{user-real-login-name} and
1070 @code{user-full-name} are variables as well as functions. The functions
1071 return the same values that the variables hold. These variables allow
1072 you to ``fake out'' Emacs by telling the functions what to return. The
1073 variables are also useful for constructing frame titles (@pxref{Frame
1076 @defun user-real-uid
1077 This function returns the real @acronym{UID} of the user.
1078 The value may be a floating point number.
1089 This function returns the effective @acronym{UID} of the user.
1090 The value may be a floating point number.
1094 @section Time of Day
1096 This section explains how to determine the current time and the time
1099 @defun current-time-string &optional time-value
1100 This function returns the current time and date as a human-readable
1101 string. The format of the string is unvarying; the number of characters
1102 used for each part is always the same, so you can reliably use
1103 @code{substring} to extract pieces of it. It is wise to count the
1104 characters from the beginning of the string rather than from the end, as
1105 additional information may some day be added at the end.
1108 The argument @var{time-value}, if given, specifies a time to format
1109 instead of the current time. The argument should be a list whose first
1110 two elements are integers. Thus, you can use times obtained from
1111 @code{current-time} (see below) and from @code{file-attributes}
1112 (@pxref{Definition of file-attributes}). @var{time-value} can also be
1113 a cons of two integers, but this is considered obsolete.
1117 (current-time-string)
1118 @result{} "Wed Oct 14 22:21:05 1987"
1125 This function returns the system's time value as a list of three
1126 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
1127 @var{high} and @var{low} combine to give the number of seconds since
1128 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1130 @var{high} * 2**16 + @var{low}.
1136 The third element, @var{microsec}, gives the microseconds since the
1137 start of the current second (or 0 for systems that return time with
1138 the resolution of only one second).
1140 The first two elements can be compared with file time values such as you
1141 get with the function @code{file-attributes}.
1142 @xref{Definition of file-attributes}.
1146 @defun current-time-zone &optional time-value
1147 This function returns a list describing the time zone that the user is
1150 The value has the form @code{(@var{offset} @var{name})}. Here
1151 @var{offset} is an integer giving the number of seconds ahead of UTC
1152 (east of Greenwich). A negative value means west of Greenwich. The
1153 second element, @var{name}, is a string giving the name of the time
1154 zone. Both elements change when daylight saving time begins or ends;
1155 if the user has specified a time zone that does not use a seasonal time
1156 adjustment, then the value is constant through time.
1158 If the operating system doesn't supply all the information necessary to
1159 compute the value, the unknown elements of the list are @code{nil}.
1161 The argument @var{time-value}, if given, specifies a time to analyze
1162 instead of the current time. The argument should have the same form
1163 as for @code{current-time-string} (see above). Thus, you can use
1164 times obtained from @code{current-time} (see above) and from
1165 @code{file-attributes}. @xref{Definition of file-attributes}.
1168 @defun set-time-zone-rule tz
1169 This function specifies the local time zone according to @var{tz}. If
1170 @var{tz} is @code{nil}, that means to use an implementation-defined
1171 default time zone. If @var{tz} is @code{t}, that means to use
1172 Universal Time. Otherwise, @var{tz} should be a string specifying a
1176 @defun float-time &optional time-value
1177 This function returns the current time as a floating-point number of
1178 seconds since the epoch. The argument @var{time-value}, if given,
1179 specifies a time to convert instead of the current time. The argument
1180 should have the same form as for @code{current-time-string} (see
1181 above). Thus, it accepts the output of @code{current-time} and
1182 @code{file-attributes}.
1184 @emph{Warning}: Since the result is floating point, it may not be
1185 exact. Do not use this function if precise time stamps are required.
1188 @node Time Conversion
1189 @section Time Conversion
1191 These functions convert time values (lists of two or three integers)
1192 to calendrical information and vice versa. You can get time values
1193 from the functions @code{current-time} (@pxref{Time of Day}) and
1194 @code{file-attributes} (@pxref{Definition of file-attributes}).
1196 Many operating systems are limited to time values that contain 32 bits
1197 of information; these systems typically handle only the times from
1198 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1199 operating systems have larger time values, and can represent times far
1200 in the past or future.
1202 Time conversion functions always use the Gregorian calendar, even
1203 for dates before the Gregorian calendar was introduced. Year numbers
1204 count the number of years since the year 1 B.C., and do not skip zero
1205 as traditional Gregorian years do; for example, the year number
1206 @minus{}37 represents the Gregorian year 38 B.C@.
1208 @defun decode-time &optional time
1209 This function converts a time value into calendrical information. If
1210 you don't specify @var{time}, it decodes the current time. The return
1211 value is a list of nine elements, as follows:
1214 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1217 Here is what the elements mean:
1221 The number of seconds past the minute, as an integer between 0 and 59.
1222 On some operating systems, this is 60 for leap seconds.
1224 The number of minutes past the hour, as an integer between 0 and 59.
1226 The hour of the day, as an integer between 0 and 23.
1228 The day of the month, as an integer between 1 and 31.
1230 The month of the year, as an integer between 1 and 12.
1232 The year, an integer typically greater than 1900.
1234 The day of week, as an integer between 0 and 6, where 0 stands for
1237 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1239 An integer indicating the time zone, as the number of seconds east of
1243 @strong{Common Lisp Note:} Common Lisp has different meanings for
1244 @var{dow} and @var{zone}.
1247 @defun encode-time seconds minutes hour day month year &optional zone
1248 This function is the inverse of @code{decode-time}. It converts seven
1249 items of calendrical data into a time value. For the meanings of the
1250 arguments, see the table above under @code{decode-time}.
1252 Year numbers less than 100 are not treated specially. If you want them
1253 to stand for years above 1900, or years above 2000, you must alter them
1254 yourself before you call @code{encode-time}.
1256 The optional argument @var{zone} defaults to the current time zone and
1257 its daylight saving time rules. If specified, it can be either a list
1258 (as you would get from @code{current-time-zone}), a string as in the
1259 @code{TZ} environment variable, @code{t} for Universal Time, or an
1260 integer (as you would get from @code{decode-time}). The specified
1261 zone is used without any further alteration for daylight saving time.
1263 If you pass more than seven arguments to @code{encode-time}, the first
1264 six are used as @var{seconds} through @var{year}, the last argument is
1265 used as @var{zone}, and the arguments in between are ignored. This
1266 feature makes it possible to use the elements of a list returned by
1267 @code{decode-time} as the arguments to @code{encode-time}, like this:
1270 (apply 'encode-time (decode-time @dots{}))
1273 You can perform simple date arithmetic by using out-of-range values for
1274 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1275 arguments; for example, day 0 means the day preceding the given month.
1277 The operating system puts limits on the range of possible time values;
1278 if you try to encode a time that is out of range, an error results.
1279 For instance, years before 1970 do not work on some systems;
1280 on others, years as early as 1901 do work.
1284 @section Parsing and Formatting Times
1286 These functions convert time values (lists of two or three integers)
1287 to text in a string, and vice versa.
1289 @defun date-to-time string
1290 This function parses the time-string @var{string} and returns the
1291 corresponding time value.
1294 @defun format-time-string format-string &optional time universal
1295 This function converts @var{time} (or the current time, if @var{time} is
1296 omitted) to a string according to @var{format-string}. The argument
1297 @var{format-string} may contain @samp{%}-sequences which say to
1298 substitute parts of the time. Here is a table of what the
1299 @samp{%}-sequences mean:
1303 This stands for the abbreviated name of the day of week.
1305 This stands for the full name of the day of week.
1307 This stands for the abbreviated name of the month.
1309 This stands for the full name of the month.
1311 This is a synonym for @samp{%x %X}.
1313 This has a locale-specific meaning. In the default locale (named C), it
1314 is equivalent to @samp{%A, %B %e, %Y}.
1316 This stands for the day of month, zero-padded.
1318 This is a synonym for @samp{%m/%d/%y}.
1320 This stands for the day of month, blank-padded.
1322 This is a synonym for @samp{%b}.
1324 This stands for the hour (00-23).
1326 This stands for the hour (01-12).
1328 This stands for the day of the year (001-366).
1330 This stands for the hour (0-23), blank padded.
1332 This stands for the hour (1-12), blank padded.
1334 This stands for the month (01-12).
1336 This stands for the minute (00-59).
1338 This stands for a newline.
1340 This stands for @samp{AM} or @samp{PM}, as appropriate.
1342 This is a synonym for @samp{%I:%M:%S %p}.
1344 This is a synonym for @samp{%H:%M}.
1346 This stands for the seconds (00-59).
1348 This stands for a tab character.
1350 This is a synonym for @samp{%H:%M:%S}.
1352 This stands for the week of the year (01-52), assuming that weeks
1355 This stands for the numeric day of week (0-6). Sunday is day 0.
1357 This stands for the week of the year (01-52), assuming that weeks
1360 This has a locale-specific meaning. In the default locale (named
1361 @samp{C}), it is equivalent to @samp{%D}.
1363 This has a locale-specific meaning. In the default locale (named
1364 @samp{C}), it is equivalent to @samp{%T}.
1366 This stands for the year without century (00-99).
1368 This stands for the year with century.
1370 This stands for the time zone abbreviation (e.g., @samp{EST}).
1372 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1375 You can also specify the field width and type of padding for any of
1376 these @samp{%}-sequences. This works as in @code{printf}: you write
1377 the field width as digits in the middle of a @samp{%}-sequences. If you
1378 start the field width with @samp{0}, it means to pad with zeros. If you
1379 start the field width with @samp{_}, it means to pad with spaces.
1381 For example, @samp{%S} specifies the number of seconds since the minute;
1382 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1383 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1384 because that is how @samp{%S} normally pads to two positions.
1386 The characters @samp{E} and @samp{O} act as modifiers when used between
1387 @samp{%} and one of the letters in the table above. @samp{E} specifies
1388 using the current locale's ``alternative'' version of the date and time.
1389 In a Japanese locale, for example, @code{%Ex} might yield a date format
1390 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1391 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1394 @samp{O} means to use the current locale's ``alternative''
1395 representation of numbers, instead of the ordinary decimal digits. This
1396 is allowed with most letters, all the ones that output numbers.
1398 If @var{universal} is non-@code{nil}, that means to describe the time as
1399 Universal Time; @code{nil} means describe it using what Emacs believes
1400 is the local time zone (see @code{current-time-zone}).
1402 This function uses the C library function @code{strftime}
1403 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1404 Manual}) to do most of the work. In order to communicate with that
1405 function, it first encodes its argument using the coding system
1406 specified by @code{locale-coding-system} (@pxref{Locales}); after
1407 @code{strftime} returns the resulting string,
1408 @code{format-time-string} decodes the string using that same coding
1412 @defun seconds-to-time seconds
1413 This function converts @var{seconds}, a floating point number of
1414 seconds since the epoch, to a time value and returns that. To perform
1415 the inverse conversion, use @code{float-time}.
1418 @defun format-seconds format-string seconds
1419 This function converts its argument @var{seconds} into a string of
1420 years, days, hours, etc., according to @var{format-string}. The
1421 argument @var{format-string} may contain @samp{%}-sequences which
1422 control the conversion. Here is a table of what the
1423 @samp{%}-sequences mean:
1428 The integer number of 365-day years.
1431 The integer number of days.
1434 The integer number of hours.
1437 The integer number of minutes.
1440 The integer number of seconds.
1442 Non-printing control flag. When it is used, other specifiers must be
1443 given in the order of decreasing size, i.e.@: years before days, hours
1444 before minutes, etc. Nothing will be produced in the result string to
1445 the left of @samp{%z} until the first non-zero conversion is
1446 encountered. For example, the default format used by
1447 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1448 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1449 will always be produced, but years, days, hours, and minutes will only
1450 be shown if they are non-zero.
1452 Produces a literal @samp{%}.
1455 Upper-case format sequences produce the units in addition to the
1456 numbers, lower-case formats produce only the numbers.
1458 You can also specify the field width by following the @samp{%} with a
1459 number; shorter numbers will be padded with blanks. An optional
1460 period before the width requests zero-padding instead. For example,
1461 @code{"%.3Y"} might produce @code{"004 years"}.
1463 @emph{Warning:} This function works only with values of @var{seconds}
1464 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1465 most-positive-fixnum}).
1468 @node Processor Run Time
1469 @section Processor Run time
1470 @cindex processor run time
1471 @cindex Emacs process run time
1473 Emacs provides several functions and primitives that return time,
1474 both elapsed and processor time, used by the Emacs process.
1476 @defun emacs-uptime &optional format
1477 This function returns a string representing the Emacs
1478 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1479 running. The string is formatted by @code{format-seconds} according
1480 to the optional argument @var{format}. For the available format
1481 descriptors, see @ref{Time Parsing, format-seconds}. If @var{format}
1482 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
1486 @defun get-internal-run-time
1487 This function returns the processor run time used by Emacs as a list
1488 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1489 integers @var{high} and @var{low} combine to give the number of
1492 @var{high} * 2**16 + @var{low}.
1498 The third element, @var{microsec}, gives the microseconds (or 0 for
1499 systems that return time with the resolution of only one second).
1501 Note that the time returned by this function excludes the time Emacs
1502 was not using the processor, and if the Emacs process has several
1503 threads, the returned value is the sum of the processor times used up
1504 by all Emacs threads.
1506 If the system doesn't provide a way to determine the processor run
1507 time, @code{get-internal-run-time} returns the same time as
1508 @code{current-time}.
1511 @defun emacs-init-time
1512 This function returns the duration of the Emacs initialization
1513 (@pxref{Startup Summary}) in seconds, as a string.
1516 @node Time Calculations
1517 @section Time Calculations
1519 These functions perform calendrical computations using time values
1520 (the kind of list that @code{current-time} returns).
1522 @defun time-less-p t1 t2
1523 This returns @code{t} if time value @var{t1} is less than time value
1527 @defun time-subtract t1 t2
1528 This returns the time difference @var{t1} @minus{} @var{t2} between
1529 two time values, in the same format as a time value.
1532 @defun time-add t1 t2
1533 This returns the sum of two time values, one of which ought to
1534 represent a time difference rather than a point in time.
1535 Here is how to add a number of seconds to a time value:
1538 (time-add @var{time} (seconds-to-time @var{seconds}))
1542 @defun time-to-days time
1543 This function returns the number of days between the beginning of year
1547 @defun time-to-day-in-year time
1548 This returns the day number within the year corresponding to @var{time}.
1551 @defun date-leap-year-p year
1552 This function returns @code{t} if @var{year} is a leap year.
1556 @section Timers for Delayed Execution
1559 You can set up a @dfn{timer} to call a function at a specified
1560 future time or after a certain length of idleness.
1562 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1563 can run them only when Emacs could accept output from a subprocess:
1564 namely, while waiting or inside certain primitive functions such as
1565 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1566 timer's execution may be delayed if Emacs is busy. However, the time of
1567 execution is very precise if Emacs is idle.
1569 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1570 function, because quitting out of many timer functions can leave
1571 things in an inconsistent state. This is normally unproblematical
1572 because most timer functions don't do a lot of work. Indeed, for a
1573 timer to call a function that takes substantial time to run is likely
1574 to be annoying. If a timer function needs to allow quitting, it
1575 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1576 a timer function calls @code{accept-process-output} to receive output
1577 from an external process, that call should be wrapped inside
1578 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1581 It is usually a bad idea for timer functions to alter buffer
1582 contents. When they do, they usually should call @code{undo-boundary}
1583 both before and after changing the buffer, to separate the timer's
1584 changes from user commands' changes and prevent a single undo entry
1585 from growing to be quite large.
1587 Timer functions should also avoid calling functions that cause Emacs
1588 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1589 unpredictable effects, since other timers (or even the same timer) can
1590 run while waiting. If a timer function needs to perform an action
1591 after a certain time has elapsed, it can do this by scheduling a new
1594 If a timer function calls functions that can change the match data,
1595 it should save and restore the match data. @xref{Saving Match Data}.
1597 @deffn Command run-at-time time repeat function &rest args
1598 This sets up a timer that calls the function @var{function} with
1599 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1600 (integer or floating point), the timer is scheduled to run again every
1601 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1602 the timer runs only once.
1604 @var{time} may specify an absolute or a relative time.
1606 Absolute times may be specified using a string with a limited variety
1607 of formats, and are taken to be times @emph{today}, even if already in
1608 the past. The recognized forms are @samp{@var{xxxx}},
1609 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1610 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1611 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1612 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1613 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1614 to separate the hour and minute parts.
1616 To specify a relative time as a string, use numbers followed by units.
1621 denotes 1 minute from now.
1623 denotes 65 seconds from now.
1624 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1625 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1628 For relative time values, Emacs considers a month to be exactly thirty
1629 days, and a year to be exactly 365.25 days.
1631 Not all convenient formats are strings. If @var{time} is a number
1632 (integer or floating point), that specifies a relative time measured in
1633 seconds. The result of @code{encode-time} can also be used to specify
1634 an absolute value for @var{time}.
1636 In most cases, @var{repeat} has no effect on when @emph{first} call
1637 takes place---@var{time} alone specifies that. There is one exception:
1638 if @var{time} is @code{t}, then the timer runs whenever the time is a
1639 multiple of @var{repeat} seconds after the epoch. This is useful for
1640 functions like @code{display-time}.
1642 The function @code{run-at-time} returns a timer value that identifies
1643 the particular scheduled future action. You can use this value to call
1644 @code{cancel-timer} (see below).
1647 A repeating timer nominally ought to run every @var{repeat} seconds,
1648 but remember that any invocation of a timer can be late. Lateness of
1649 one repetition has no effect on the scheduled time of the next
1650 repetition. For instance, if Emacs is busy computing for long enough
1651 to cover three scheduled repetitions of the timer, and then starts to
1652 wait, it will immediately call the timer function three times in
1653 immediate succession (presuming no other timers trigger before or
1654 between them). If you want a timer to run again no less than @var{n}
1655 seconds after the last invocation, don't use the @var{repeat} argument.
1656 Instead, the timer function should explicitly reschedule the timer.
1658 @defvar timer-max-repeats
1659 This variable's value specifies the maximum number of times to repeat
1660 calling a timer function in a row, when many previously scheduled
1661 calls were unavoidably delayed.
1664 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1665 Execute @var{body}, but give up after @var{seconds} seconds. If
1666 @var{body} finishes before the time is up, @code{with-timeout} returns
1667 the value of the last form in @var{body}. If, however, the execution of
1668 @var{body} is cut short by the timeout, then @code{with-timeout}
1669 executes all the @var{timeout-forms} and returns the value of the last
1672 This macro works by setting a timer to run after @var{seconds} seconds. If
1673 @var{body} finishes before that time, it cancels the timer. If the
1674 timer actually runs, it terminates execution of @var{body}, then
1675 executes @var{timeout-forms}.
1677 Since timers can run within a Lisp program only when the program calls a
1678 primitive that can wait, @code{with-timeout} cannot stop executing
1679 @var{body} while it is in the midst of a computation---only when it
1680 calls one of those primitives. So use @code{with-timeout} only with a
1681 @var{body} that waits for input, not one that does a long computation.
1684 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1685 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1688 @defun cancel-timer timer
1689 This cancels the requested action for @var{timer}, which should be a
1690 timer---usually, one previously returned by @code{run-at-time} or
1691 @code{run-with-idle-timer}. This cancels the effect of that call to
1692 one of these functions; the arrival of the specified time will not
1693 cause anything special to happen.
1697 @section Idle Timers
1699 Here is how to set up a timer that runs when Emacs is idle for a
1700 certain length of time. Aside from how to set them up, idle timers
1701 work just like ordinary timers.
1703 @deffn Command run-with-idle-timer secs repeat function &rest args
1704 Set up a timer which runs when Emacs has been idle for @var{secs}
1705 seconds. The value of @var{secs} may be an integer or a floating point
1706 number; a value of the type returned by @code{current-idle-time}
1709 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1710 Emacs remains idle for a long enough time. More often @var{repeat} is
1711 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1712 remains idle for @var{secs} seconds.
1714 The function @code{run-with-idle-timer} returns a timer value which you
1715 can use in calling @code{cancel-timer} (@pxref{Timers}).
1719 Emacs becomes ``idle'' when it starts waiting for user input, and it
1720 remains idle until the user provides some input. If a timer is set for
1721 five seconds of idleness, it runs approximately five seconds after Emacs
1722 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1723 will not run again as long as Emacs remains idle, because the duration
1724 of idleness will continue to increase and will not go down to five
1727 Emacs can do various things while idle: garbage collect, autosave or
1728 handle data from a subprocess. But these interludes during idleness do
1729 not interfere with idle timers, because they do not reset the clock of
1730 idleness to zero. An idle timer set for 600 seconds will run when ten
1731 minutes have elapsed since the last user command was finished, even if
1732 subprocess output has been accepted thousands of times within those ten
1733 minutes, and even if there have been garbage collections and autosaves.
1735 When the user supplies input, Emacs becomes non-idle while executing the
1736 input. Then it becomes idle again, and all the idle timers that are
1737 set up to repeat will subsequently run another time, one by one.
1740 @defun current-idle-time
1741 If Emacs is idle, this function returns the length of time Emacs has
1742 been idle, as a list of three integers: @code{(@var{high} @var{low}
1743 @var{microsec})}. The integers @var{high} and @var{low} combine to
1744 give the number of seconds of idleness, which is
1746 @var{high} * 2**16 + @var{low}.
1752 The third element, @var{microsec}, gives the microseconds since the
1753 start of the current second (or 0 for systems that return time with
1754 the resolution of only one second).
1756 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1757 This is a convenient way to test whether Emacs is idle.
1759 The main use of this function is when an idle timer function wants to
1760 ``take a break'' for a while. It can set up another idle timer to
1761 call the same function again, after a few seconds more idleness.
1765 (defvar resume-timer nil
1766 "Timer that `timer-function' used to reschedule itself, or nil.")
1768 (defun timer-function ()
1769 ;; @r{If the user types a command while @code{resume-timer}}
1770 ;; @r{is active, the next time this function is called from}
1771 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1773 (cancel-timer resume-timer))
1774 ...@var{do the work for a while}...
1775 (when @var{taking-a-break}
1777 (run-with-idle-timer
1778 ;; Compute an idle time @var{break-length}
1779 ;; more than the current value.
1780 (time-add (current-idle-time)
1781 (seconds-to-time @var{break-length}))
1787 Some idle timer functions in user Lisp packages have a loop that
1788 does a certain amount of processing each time around, and exits when
1789 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1790 natural but has two problems:
1794 It blocks out all process output (since Emacs accepts process output
1795 only while waiting).
1798 It blocks out any idle timers that ought to run during that time.
1802 To avoid these problems, don't use that technique. Instead, write
1803 such idle timers to reschedule themselves after a brief pause, using
1804 the method in the @code{timer-function} example above.
1806 @node Terminal Input
1807 @section Terminal Input
1808 @cindex terminal input
1810 This section describes functions and variables for recording or
1811 manipulating terminal input. See @ref{Display}, for related
1815 * Input Modes:: Options for how input is processed.
1816 * Recording Input:: Saving histories of recent or all input events.
1820 @subsection Input Modes
1822 @cindex terminal input modes
1824 @defun set-input-mode interrupt flow meta &optional quit-char
1825 This function sets the mode for reading keyboard input. If
1826 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1827 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1828 system-dependent. Some systems always use @sc{cbreak} mode regardless
1829 of what is specified.
1831 When Emacs communicates directly with X, it ignores this argument and
1832 uses interrupts if that is the way it knows how to communicate.
1834 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1835 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1836 has no effect except in @sc{cbreak} mode.
1839 The argument @var{meta} controls support for input character codes
1840 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1841 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1842 Emacs disregards the 8th bit; this is necessary when the terminal uses
1843 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1844 Emacs uses all 8 bits of input unchanged. This is good for terminals
1845 that use 8-bit character sets.
1848 If @var{quit-char} is non-@code{nil}, it specifies the character to
1849 use for quitting. Normally this character is @kbd{C-g}.
1853 The @code{current-input-mode} function returns the input mode settings
1854 Emacs is currently using.
1857 @defun current-input-mode
1858 This function returns the current mode for reading keyboard input. It
1859 returns a list, corresponding to the arguments of @code{set-input-mode},
1860 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1864 is non-@code{nil} when Emacs is using interrupt-driven input. If
1865 @code{nil}, Emacs is using @sc{cbreak} mode.
1867 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1868 flow control for output to the terminal. This value is meaningful only
1869 when @var{interrupt} is @code{nil}.
1871 is @code{t} if Emacs treats the eighth bit of input characters as
1872 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1873 input character; any other value means Emacs uses all eight bits as the
1874 basic character code.
1876 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1880 @node Recording Input
1881 @subsection Recording Input
1882 @cindex recording input
1885 This function returns a vector containing the last 300 input events from
1886 the keyboard or mouse. All input events are included, whether or not
1887 they were used as parts of key sequences. Thus, you always get the last
1888 100 input events, not counting events generated by keyboard macros.
1889 (These are excluded because they are less interesting for debugging; it
1890 should be enough to see the events that invoked the macros.)
1892 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1893 causes this function to return an empty vector immediately afterward.
1896 @deffn Command open-dribble-file filename
1897 @cindex dribble file
1898 This function opens a @dfn{dribble file} named @var{filename}. When a
1899 dribble file is open, each input event from the keyboard or mouse (but
1900 not those from keyboard macros) is written in that file. A
1901 non-character event is expressed using its printed representation
1902 surrounded by @samp{<@dots{}>}.
1904 You close the dribble file by calling this function with an argument
1907 This function is normally used to record the input necessary to
1908 trigger an Emacs bug, for the sake of a bug report.
1912 (open-dribble-file "~/dribble")
1918 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1920 @node Terminal Output
1921 @section Terminal Output
1922 @cindex terminal output
1924 The terminal output functions send output to a text terminal, or keep
1925 track of output sent to the terminal. The variable @code{baud-rate}
1926 tells you what Emacs thinks is the output speed of the terminal.
1929 This variable's value is the output speed of the terminal, as far as
1930 Emacs knows. Setting this variable does not change the speed of actual
1931 data transmission, but the value is used for calculations such as
1934 It also affects decisions about whether to scroll part of the
1935 screen or repaint on text terminals. @xref{Forcing Redisplay},
1936 for the corresponding functionality on graphical terminals.
1938 The value is measured in baud.
1941 If you are running across a network, and different parts of the
1942 network work at different baud rates, the value returned by Emacs may be
1943 different from the value used by your local terminal. Some network
1944 protocols communicate the local terminal speed to the remote machine, so
1945 that Emacs and other programs can get the proper value, but others do
1946 not. If Emacs has the wrong value, it makes decisions that are less
1947 than optimal. To fix the problem, set @code{baud-rate}.
1950 This obsolete function returns the value of the variable
1954 @defun send-string-to-terminal string
1955 This function sends @var{string} to the terminal without alteration.
1956 Control characters in @var{string} have terminal-dependent effects.
1957 This function operates only on text terminals.
1959 One use of this function is to define function keys on terminals that
1960 have downloadable function key definitions. For example, this is how (on
1961 certain terminals) to define function key 4 to move forward four
1962 characters (by transmitting the characters @kbd{C-u C-f} to the
1967 (send-string-to-terminal "\eF4\^U\^F")
1973 @deffn Command open-termscript filename
1974 @cindex termscript file
1975 This function is used to open a @dfn{termscript file} that will record
1976 all the characters sent by Emacs to the terminal. It returns
1977 @code{nil}. Termscript files are useful for investigating problems
1978 where Emacs garbles the screen, problems that are due to incorrect
1979 Termcap entries or to undesirable settings of terminal options more
1980 often than to actual Emacs bugs. Once you are certain which characters
1981 were actually output, you can determine reliably whether they correspond
1982 to the Termcap specifications in use.
1984 You close the termscript file by calling this function with an
1985 argument of @code{nil}.
1987 See also @code{open-dribble-file} in @ref{Recording Input}.
1991 (open-termscript "../junk/termscript")
1998 @section Sound Output
2001 To play sound using Emacs, use the function @code{play-sound}. Only
2002 certain systems are supported; if you call @code{play-sound} on a system
2003 which cannot really do the job, it gives an error. Emacs version 20 and
2004 earlier did not support sound at all.
2006 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
2007 or Sun Audio format (@samp{.au}).
2009 @defun play-sound sound
2010 This function plays a specified sound. The argument, @var{sound}, has
2011 the form @code{(sound @var{properties}...)}, where the @var{properties}
2012 consist of alternating keywords (particular symbols recognized
2013 specially) and values corresponding to them.
2015 Here is a table of the keywords that are currently meaningful in
2016 @var{sound}, and their meanings:
2019 @item :file @var{file}
2020 This specifies the file containing the sound to play.
2021 If the file name is not absolute, it is expanded against
2022 the directory @code{data-directory}.
2024 @item :data @var{data}
2025 This specifies the sound to play without need to refer to a file. The
2026 value, @var{data}, should be a string containing the same bytes as a
2027 sound file. We recommend using a unibyte string.
2029 @item :volume @var{volume}
2030 This specifies how loud to play the sound. It should be a number in the
2031 range of 0 to 1. The default is to use whatever volume has been
2034 @item :device @var{device}
2035 This specifies the system device on which to play the sound, as a
2036 string. The default device is system-dependent.
2039 Before actually playing the sound, @code{play-sound}
2040 calls the functions in the list @code{play-sound-functions}.
2041 Each function is called with one argument, @var{sound}.
2044 @defun play-sound-file file &optional volume device
2045 This function is an alternative interface to playing a sound @var{file}
2046 specifying an optional @var{volume} and @var{device}.
2049 @defvar play-sound-functions
2050 A list of functions to be called before playing a sound. Each function
2051 is called with one argument, a property list that describes the sound.
2055 @section Operating on X11 Keysyms
2058 To define system-specific X11 keysyms, set the variable
2059 @code{system-key-alist}.
2061 @defvar system-key-alist
2062 This variable's value should be an alist with one element for each
2063 system-specific keysym. Each element has the form @code{(@var{code}
2064 . @var{symbol})}, where @var{code} is the numeric keysym code (not
2065 including the ``vendor specific'' bit,
2072 and @var{symbol} is the name for the function key.
2074 For example @code{(168 . mute-acute)} defines a system-specific key (used
2075 by HP X servers) whose numeric code is
2084 It is not crucial to exclude from the alist the keysyms of other X
2085 servers; those do no harm, as long as they don't conflict with the ones
2086 used by the X server actually in use.
2088 The variable is always local to the current terminal, and cannot be
2089 buffer-local. @xref{Multiple Terminals}.
2092 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2094 @defvar x-alt-keysym
2095 @defvarx x-meta-keysym
2096 @defvarx x-hyper-keysym
2097 @defvarx x-super-keysym
2098 The name of the keysym that should stand for the Alt modifier
2099 (respectively, for Meta, Hyper, and Super). For example, here is
2100 how to swap the Meta and Alt modifiers within Emacs:
2102 (setq x-alt-keysym 'meta)
2103 (setq x-meta-keysym 'alt)
2111 The command-line option @samp{-batch} causes Emacs to run
2112 noninteractively. In this mode, Emacs does not read commands from the
2113 terminal, it does not alter the terminal modes, and it does not expect
2114 to be outputting to an erasable screen. The idea is that you specify
2115 Lisp programs to run; when they are finished, Emacs should exit. The
2116 way to specify the programs to run is with @samp{-l @var{file}}, which
2117 loads the library named @var{file}, or @samp{-f @var{function}}, which
2118 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2120 Any Lisp program output that would normally go to the echo area,
2121 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2122 as the stream, goes instead to Emacs's standard error descriptor when
2123 in batch mode. Similarly, input that would normally come from the
2124 minibuffer is read from the standard input descriptor.
2125 Thus, Emacs behaves much like a noninteractive
2126 application program. (The echo area output that Emacs itself normally
2127 generates, such as command echoing, is suppressed entirely.)
2129 @defvar noninteractive
2130 This variable is non-@code{nil} when Emacs is running in batch mode.
2133 @node Session Management
2134 @section Session Management
2135 @cindex session manager
2137 Emacs supports the X Session Management Protocol, which is used to
2138 suspend and restart applications. In the X Window System, a program
2139 called the @dfn{session manager} is responsible for keeping track of
2140 the applications that are running. When the X server shuts down, the
2141 session manager asks applications to save their state, and delays the
2142 actual shutdown until they respond. An application can also cancel
2145 When the session manager restarts a suspended session, it directs
2146 these applications to individually reload their saved state. It does
2147 this by specifying a special command-line argument that says what
2148 saved session to restore. For Emacs, this argument is @samp{--smid
2151 @defvar emacs-save-session-functions
2152 Emacs supports saving state via a hook called
2153 @code{emacs-save-session-functions}. Emacs runs this hook when the
2154 session manager tells it that the window system is shutting down. The
2155 functions are called with no arguments, and with the current buffer
2156 set to a temporary buffer. Each function can use @code{insert} to add
2157 Lisp code to this buffer. At the end, Emacs saves the buffer in a
2158 file, called the @dfn{session file}.
2160 @findex emacs-session-restore
2161 Subsequently, when the session manager restarts Emacs, it loads the
2162 session file automatically (@pxref{Loading}). This is performed by a
2163 function named @code{emacs-session-restore}, which is called during
2164 startup. @xref{Startup Summary}.
2166 If a function in @code{emacs-save-session-functions} returns
2167 non-@code{nil}, Emacs tells the session manager to cancel the
2171 Here is an example that just inserts some text into @samp{*scratch*} when
2172 Emacs is restarted by the session manager.
2176 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2180 (defun save-yourself-test ()
2181 (insert "(save-excursion
2182 (switch-to-buffer \"*scratch*\")
2183 (insert \"I am restored\"))")
2189 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7