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 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}. This library's name is
84 @file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
85 value of @code{initial-window-system}. From that library, it calls
86 the appropriate initialization function. The initialization function
87 is specified by @code{window-system-initialization-alist}, for each
88 supported window system.
91 It sets the language environment and the terminal coding system,
92 if requested by environment variables such as @code{LANG}.
95 It processes the initial options. (Some of them are handled
96 even earlier than this.)
99 It runs the normal hook @code{before-init-hook}.
102 It initializes the window frame and faces, if appropriate, and turns
103 on the menu bar and tool bar, if the initial frame needs them.
106 It registers the default colors for text-only terminals.
109 It loads the library @file{site-start} (if any), unless the option
110 @samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
111 name is usually @file{site-start.el}.
112 @cindex @file{site-start.el}
115 It loads your init file (usually @file{~/.emacs}), unless the option
116 @samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
117 specified on the command line. The @samp{-u} option can specify
118 another user whose home directory should be used instead of @file{~}.
121 It loads the library @file{default} (if any), unless
122 @code{inhibit-default-init} is non-@code{nil}. (This is not done in
123 @samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
124 command line.) The library's file name is usually @file{default.el}.
125 @cindex @file{default.el}
128 It loads your abbrevs from the file specified by
129 @code{abbrev-file-name} (@pxref{Abbrev Files, abbrev-file-name}), if
130 that file exists and can be read. (This is not done in @samp{-batch}
133 @vindex after-init-time
135 It records in the variable @code{after-init-time} the value of
136 @code{current-time}. This variable was set to @code{nil} at the
137 beginning of the Emacs session initialization (see above), so setting
138 it to the current time both signals that the initialization phase is
139 over, and, together with @code{before-init-time}, provides the
140 measurement of how long it took.
143 It runs the normal hook @code{after-init-hook}.
146 It sets the major mode according to @code{initial-major-mode}, provided
147 the buffer @samp{*scratch*} is still current and still in Fundamental
151 It loads the terminal-specific Lisp library, if any, except when in
152 batch mode or when the variable @code{initial-window-system} (see
153 above) specifies a non-@code{nil} window system. The name of this
154 library is computed from the value of the variable
155 @code{term-file-prefix}; for the details, see @ref{Terminal-Specific}.
157 If the value of @code{term-file-prefix} is @code{nil}, this step is skipped.
160 It displays the initial echo area message, unless you have suppressed
161 that with @code{inhibit-startup-echo-area-message}.
164 It processes the action arguments from the command line.
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 It displays copyleft, nonwarranty, and basic use information, provided
179 the value of @code{inhibit-startup-screen} is @code{nil}, you didn't
180 specify @samp{--no-splash} or @samp{-Q}.
183 If the command-line arguments specified @option{--daemon}, @c FIXME: xref
184 it calls @code{server-start} (@pxref{Emacs Server,,, emacs, The GNU
188 If started by the X session manager, it calls
189 @code{emacs-session-restore} passing it as argument the ID of the
190 previous session. @c FIXME: add an xref to the Emacs manual!
193 @defopt inhibit-startup-screen
194 This variable inhibits the initial startup messages (the nonwarranty,
195 etc.). If it is non-@code{nil}, then the messages are not printed.
197 This variable exists so you can set it in your personal init file, once
198 you are familiar with the contents of the startup message. Do not set
199 this variable in the init file of a new user, or in a way that affects
200 more than one user, because that would prevent new users from receiving
201 the information they are supposed to see.
203 @code{inhibit-startup-message} is an alias for this variable, for
207 @defopt inhibit-startup-echo-area-message
208 This variable controls the display of the startup echo area message.
209 You can suppress the startup echo area message by adding text with this
210 form to your init file:
213 (setq inhibit-startup-echo-area-message
214 "@var{your-login-name}")
217 Emacs explicitly checks for an expression as shown above in your init
218 file; your login name must appear in the expression as a Lisp string
219 constant. Other methods of setting
220 @code{inhibit-startup-echo-area-message} to the same value do not
221 inhibit the startup message.
223 This way, you can easily inhibit the message for yourself if you wish,
224 but thoughtless copying of your init file will not inhibit the message
229 @subsection The Init File, @file{.emacs}
231 @cindex @file{.emacs}
233 When you start Emacs, it normally attempts to load your @dfn{init
234 file}, a file in your home directory. Its normal name is
235 @file{.emacs}, but you can also call it @file{.emacs.el}.
236 Alternatively, you can use a file named @file{init.el} in a
237 subdirectory @file{.emacs.d}. Whichever place you use, you can also
238 compile the file (@pxref{Byte Compilation}); then the actual file
239 loaded will be @file{.emacs.elc} or @file{init.elc}.
241 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
242 control whether and where to find the init file; @samp{-q} (and the
243 stronger @samp{-Q}) says not to load an init file, while @samp{-u
244 @var{user}} says to load @var{user}'s init file instead of yours.
245 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
246 option is specified, Emacs uses the @code{LOGNAME} environment
247 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
248 systems) variable, to find your home directory and thus your init
249 file; this way, even if you have su'd, Emacs still loads your own init
250 file. If those environment variables are absent, though, Emacs uses
251 your user-id to find your home directory.
253 @cindex default init file
254 A site may have a @dfn{default init file}, which is the library
255 named @file{default.el}. Emacs finds the @file{default.el} file
256 through the standard search path for libraries (@pxref{How Programs Do
257 Loading}). The Emacs distribution does not come with this file; sites
258 may provide one for local customizations. If the default init file
259 exists, it is loaded whenever you start Emacs, except in batch mode or
260 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
261 file, if any, is loaded first; if it sets @code{inhibit-default-init}
262 to a non-@code{nil} value, then Emacs does not subsequently load the
263 @file{default.el} file.
265 Another file for site-customization is @file{site-start.el}. Emacs
266 loads this @emph{before} the user's init file. You can inhibit the
267 loading of this file with the option @samp{--no-site-file}.
269 @defvar site-run-file
270 This variable specifies the site-customization file to load before the
271 user's init file. Its normal value is @code{"site-start"}. The only
272 way you can change it with real effect is to do so before dumping
276 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
277 examples of how to make various commonly desired customizations in your
280 @defopt inhibit-default-init
281 This variable prevents Emacs from loading the default initialization
282 library file for your session of Emacs. If its value is non-@code{nil},
283 then the default library is not loaded. The default value is
287 @defvar before-init-hook
288 This normal hook is run, once, just before loading all the init files
289 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
290 (The only way to change it with real effect is before dumping Emacs.)
293 @defvar after-init-hook
294 This normal hook is run, once, just after loading all the init files
295 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
296 before loading the terminal-specific library and processing the
297 command-line action arguments.
300 @defvar emacs-startup-hook
301 This normal hook is run, once, just after handling the command line
302 arguments, just before @code{term-setup-hook}.
305 @defvar user-init-file
306 This variable holds the absolute file name of the user's init file. If the
307 actual init file loaded is a compiled file, such as @file{.emacs.elc},
308 the value refers to the corresponding source file.
311 @defvar user-emacs-directory
312 This variable holds the name of the @file{.emacs.d} directory. It is
313 ordinarily @file{~/.emacs.d}, but differs on some platforms.
316 @node Terminal-Specific
317 @subsection Terminal-Specific Initialization
318 @cindex terminal-specific initialization
320 Each terminal type can have its own Lisp library that Emacs loads when
321 run on that type of terminal. The library's name is constructed by
322 concatenating the value of the variable @code{term-file-prefix} and the
323 terminal type (specified by the environment variable @code{TERM}).
324 Normally, @code{term-file-prefix} has the value
325 @code{"term/"}; changing this is not recommended. Emacs finds the file
326 in the normal manner, by searching the @code{load-path} directories, and
327 trying the @samp{.elc} and @samp{.el} suffixes.
330 The usual function of a terminal-specific library is to enable
331 special keys to send sequences that Emacs can recognize. It may also
332 need to set or add to @code{input-decode-map} if the Termcap or
333 Terminfo entry does not specify all the terminal's function keys.
334 @xref{Terminal Input}.
336 When the name of the terminal type contains a hyphen, and no library
337 is found whose name is identical to the terminal's name, Emacs strips
338 from the terminal's name the last hyphen and everything that follows
339 it, and tries again. This process is repeated until Emacs finds a
340 matching library or until there are no more hyphens in the name (the
341 latter means the terminal doesn't have any library specific to it).
342 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
343 libraries, Emacs will try the same library @file{term/aaa.el} for
344 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
345 library can evaluate @code{(getenv "TERM")} to find the full name of
346 the terminal type.@refill
348 Your init file can prevent the loading of the
349 terminal-specific library by setting the variable
350 @code{term-file-prefix} to @code{nil}. This feature is useful when
351 experimenting with your own peculiar customizations.
353 You can also arrange to override some of the actions of the
354 terminal-specific library by setting the variable
355 @code{term-setup-hook}. This is a normal hook which Emacs runs using
356 @code{run-hooks} at the end of Emacs initialization, after loading both
357 your init file and any terminal-specific libraries. You can
358 use this variable to define initializations for terminals that do not
359 have their own libraries. @xref{Hooks}.
361 @defvar term-file-prefix
362 @cindex @code{TERM} environment variable
363 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
364 a terminal-specific initialization file as follows:
367 (load (concat term-file-prefix (getenv "TERM")))
371 You may set the @code{term-file-prefix} variable to @code{nil} in your
372 init file if you do not wish to load the
373 terminal-initialization file. To do this, put the following in
374 your init file: @code{(setq term-file-prefix nil)}.
376 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
377 uses @samp{internal} as the terminal type.
380 @defvar term-setup-hook
381 This variable is a normal hook that Emacs runs after loading your
382 init file, the default initialization file (if any) and the
383 terminal-specific Lisp file.
385 You can use @code{term-setup-hook} to override the definitions made by a
386 terminal-specific file.
389 See @code{window-setup-hook} in @ref{Window Systems}, for a related
392 @node Command-Line Arguments
393 @subsection Command-Line Arguments
394 @cindex command-line arguments
396 You can use command-line arguments to request various actions when you
397 start Emacs. Since you do not need to start Emacs more than once per
398 day, and will often leave your Emacs session running longer than that,
399 command-line arguments are hardly ever used. As a practical matter, it
400 is best to avoid making the habit of using them, since this habit would
401 encourage you to kill and restart Emacs unnecessarily often. These
402 options exist for two reasons: to be compatible with other editors (for
403 invocation by other programs) and to enable shell scripts to run
404 specific Lisp programs.
406 This section describes how Emacs processes command-line arguments,
407 and how you can customize them.
410 (Note that some other editors require you to start afresh each time
411 you want to edit a file. With this kind of editor, you will probably
412 specify the file as a command-line argument. The recommended way to
413 use GNU Emacs is to start it only once, just after you log in, and do
414 all your editing in the same Emacs process. Each time you want to edit
415 a different file, you visit it with the existing Emacs, which eventually
416 comes to have many files in it ready for editing. Usually you do not
417 kill the Emacs until you are about to log out.)
421 This function parses the command line that Emacs was called with,
422 processes it, loads the user's init file and displays the
426 @defvar command-line-processed
427 The value of this variable is @code{t} once the command line has been
430 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
431 this variable to @code{nil} first in order to cause the new dumped Emacs
432 to process its new command-line arguments.
435 @defvar command-switch-alist
436 @cindex switches on command line
437 @cindex options on command line
438 @cindex command-line options
439 The value of this variable is an alist of user-defined command-line
440 options and associated handler functions. This variable exists so you
441 can add elements to it.
443 A @dfn{command-line option} is an argument on the command line, which
450 The elements of the @code{command-switch-alist} look like this:
453 (@var{option} . @var{handler-function})
456 The @sc{car}, @var{option}, is a string, the name of a command-line
457 option (not including the initial hyphen). The @var{handler-function}
458 is called to handle @var{option}, and receives the option name as its
461 In some cases, the option is followed in the command line by an
462 argument. In these cases, the @var{handler-function} can find all the
463 remaining command-line arguments in the variable
464 @code{command-line-args-left}. (The entire list of command-line
465 arguments is in @code{command-line-args}.)
467 The command-line arguments are parsed by the @code{command-line-1}
468 function in the @file{startup.el} file. See also @ref{Emacs
469 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
473 @defvar command-line-args
474 The value of this variable is the list of command-line arguments passed
478 @defvar command-line-functions
479 This variable's value is a list of functions for handling an
480 unrecognized command-line argument. Each time the next argument to be
481 processed has no special meaning, the functions in this list are called,
482 in order of appearance, until one of them returns a non-@code{nil}
485 These functions are called with no arguments. They can access the
486 command-line argument under consideration through the variable
487 @code{argi}, which is bound temporarily at this point. The remaining
488 arguments (not including the current one) are in the variable
489 @code{command-line-args-left}.
491 When a function recognizes and processes the argument in @code{argi}, it
492 should return a non-@code{nil} value to say it has dealt with that
493 argument. If it has also dealt with some of the following arguments, it
494 can indicate that by deleting them from @code{command-line-args-left}.
496 If all of these functions return @code{nil}, then the argument is used
497 as a file name to visit.
501 @section Getting Out of Emacs
502 @cindex exiting Emacs
504 There are two ways to get out of Emacs: you can kill the Emacs job,
505 which exits permanently, or you can suspend it, which permits you to
506 reenter the Emacs process later. As a practical matter, you seldom kill
507 Emacs---only when you are about to log out. Suspending is much more
511 * Killing Emacs:: Exiting Emacs irreversibly.
512 * Suspending Emacs:: Exiting Emacs reversibly.
516 @comment node-name, next, previous, up
517 @subsection Killing Emacs
518 @cindex killing Emacs
520 Killing Emacs means ending the execution of the Emacs process. The
521 parent process normally resumes control. The low-level primitive for
522 killing Emacs is @code{kill-emacs}.
524 @defun kill-emacs &optional exit-data
525 This function exits the Emacs process and kills it.
527 If @var{exit-data} is an integer, then it is used as the exit status
528 of the Emacs process. (This is useful primarily in batch operation; see
531 If @var{exit-data} is a string, its contents are stuffed into the
532 terminal input buffer so that the shell (or whatever program next reads
533 input) can read them.
536 All the information in the Emacs process, aside from files that have
537 been saved, is lost when the Emacs process is killed. Because killing
538 Emacs inadvertently can lose a lot of work, Emacs queries for
539 confirmation before actually terminating if you have buffers that need
540 saving or subprocesses that are running. This is done in the function
541 @code{save-buffers-kill-emacs}, the higher level function from which
542 @code{kill-emacs} is usually called.
544 @defvar kill-emacs-query-functions
545 After asking the standard questions, @code{save-buffers-kill-emacs}
546 calls the functions in the list @code{kill-emacs-query-functions}, in
547 order of appearance, with no arguments. These functions can ask for
548 additional confirmation from the user. If any of them returns
549 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
550 does not run the remaining functions in this hook. Calling
551 @code{kill-emacs} directly does not run this hook.
554 @defvar kill-emacs-hook
555 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
556 finished with all file saving and confirmation, it calls
557 @code{kill-emacs} which runs the functions in this hook.
558 @code{kill-emacs} does not run this hook in batch mode.
560 @code{kill-emacs} may be invoked directly (that is not via
561 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
562 similar situations where interaction with the user is not possible.
563 Thus, if your hook needs to interact with the user, put it on
564 @code{kill-emacs-query-functions}; if it needs to run regardless of
565 how Emacs is killed, put it on @code{kill-emacs-hook}.
568 @node Suspending Emacs
569 @subsection Suspending Emacs
570 @cindex suspending Emacs
572 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
573 control to its superior process, which is usually the shell. This
574 allows you to resume editing later in the same Emacs process, with the
575 same buffers, the same kill ring, the same undo history, and so on. To
576 resume Emacs, use the appropriate command in the parent shell---most
579 Some operating systems do not support suspension of jobs; on these
580 systems, ``suspension'' actually creates a new shell temporarily as a
581 subprocess of Emacs. Then you would exit the shell to return to Emacs.
583 Suspension is not useful with window systems, because the Emacs job
584 may not have a parent that can resume it again, and in any case you can
585 give input to some other job such as a shell merely by moving to a
586 different window. Therefore, suspending is not allowed when Emacs is using
587 a window system (X, MS Windows).
589 @defun suspend-emacs &optional string
590 This function stops Emacs and returns control to the superior process.
591 If and when the superior process resumes Emacs, @code{suspend-emacs}
592 returns @code{nil} to its caller in Lisp.
594 If @var{string} is non-@code{nil}, its characters are sent to be read
595 as terminal input by Emacs's superior shell. The characters in
596 @var{string} are not echoed by the superior shell; only the results
599 Before suspending, @code{suspend-emacs} runs the normal hook
602 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
603 @code{suspend-resume-hook}. @xref{Hooks}.
605 The next redisplay after resumption will redraw the entire screen,
606 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
607 (@pxref{Refresh Screen}).
609 In the following example, note that @samp{pwd} is not echoed after
610 Emacs is suspended. But it is read and executed by the shell.
619 (add-hook 'suspend-hook
623 (error "Suspend canceled")))))
624 @result{} (lambda nil
625 (or (y-or-n-p "Really suspend? ")
626 (error "Suspend canceled")))
629 (add-hook 'suspend-resume-hook
630 (function (lambda () (message "Resumed!"))))
631 @result{} (lambda nil (message "Resumed!"))
634 (suspend-emacs "pwd")
638 ---------- Buffer: Minibuffer ----------
639 Really suspend? @kbd{y}
640 ---------- Buffer: Minibuffer ----------
644 ---------- Parent Shell ----------
645 lewis@@slug[23] % /user/lewis/manual
650 ---------- Echo Area ----------
657 This variable is a normal hook that Emacs runs before suspending.
660 @defvar suspend-resume-hook
661 This variable is a normal hook that Emacs runs on resuming
665 @node System Environment
666 @section Operating System Environment
667 @cindex operating system environment
669 Emacs provides access to variables in the operating system environment
670 through various functions. These variables include the name of the
671 system, the user's @acronym{UID}, and so on.
673 @defvar system-configuration
674 This variable holds the standard GNU configuration name for the
675 hardware/software configuration of your system, as a string. The
676 convenient way to test parts of this string is with
680 @cindex system type and name
682 The value of this variable is a symbol indicating the type of operating
683 system Emacs is operating on. Here is a table of the possible values:
696 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
699 A GNU/Linux system---that is, a variant GNU system, using the Linux
700 kernel. (These systems are the ones people often call ``Linux,'' but
701 actually Linux is just the kernel, not the whole system.)
704 Hewlett-Packard HPUX operating system.
707 Silicon Graphics Irix system.
710 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
711 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
718 Microsoft windows NT. The same executable supports Windows 9X, but the
719 value of @code{system-type} is @code{windows-nt} in either case.
723 We do not wish to add new symbols to make finer distinctions unless it
724 is absolutely necessary! In fact, we hope to eliminate some of these
725 alternatives in the future. We recommend using
726 @code{system-configuration} to distinguish between different operating
731 This function returns the name of the machine you are running on.
734 @result{} "www.gnu.org"
738 The symbol @code{system-name} is a variable as well as a function. In
739 fact, the function returns whatever value the variable
740 @code{system-name} currently holds. Thus, you can set the variable
741 @code{system-name} in case Emacs is confused about the name of your
742 system. The variable is also useful for constructing frame titles
743 (@pxref{Frame Titles}).
745 @defvar mail-host-address
746 If this variable is non-@code{nil}, it is used instead of
747 @code{system-name} for purposes of generating email addresses. For
748 example, it is used when constructing the default value of
749 @code{user-mail-address}. @xref{User Identification}. (Since this is
750 done when Emacs starts up, the value actually used is the one saved when
751 Emacs was dumped. @xref{Building Emacs}.)
754 @deffn Command getenv var
755 @cindex environment variable access
756 This function returns the value of the environment variable @var{var},
757 as a string. @var{var} should be a string. If @var{var} is undefined
758 in the environment, @code{getenv} returns @code{nil}. If returns
759 @samp{""} if @var{var} is set but null. Within Emacs, the environment
760 variable values are kept in the Lisp variable @code{process-environment}.
769 lewis@@slug[10] % printenv
770 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
782 @deffn Command setenv variable &optional value
783 This command sets the value of the environment variable named
784 @var{variable} to @var{value}. @var{variable} should be a string.
785 Internally, Emacs Lisp can handle any string. However, normally
786 @var{variable} should be a valid shell identifier, that is, a sequence
787 of letters, digits and underscores, starting with a letter or
788 underscore. Otherwise, errors may occur if subprocesses of Emacs try
789 to access the value of @var{variable}. If @var{value} is omitted or
790 @code{nil}, @code{setenv} removes @var{variable} from the environment.
791 Otherwise, @var{value} should be a string.
793 @code{setenv} works by modifying @code{process-environment}; binding
794 that variable with @code{let} is also reasonable practice.
796 @code{setenv} returns the new value of @var{variable}, or @code{nil}
797 if it removed @var{variable} from the environment.
800 @defvar process-environment
801 This variable is a list of strings, each describing one environment
802 variable. The functions @code{getenv} and @code{setenv} work by means
808 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
809 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
819 If @code{process-environment} contains ``duplicate'' elements that
820 specify the same environment variable, the first of these elements
821 specifies the variable, and the other ``duplicates'' are ignored.
824 @defvar path-separator
825 This variable holds a string which says which character separates
826 directories in a search path (as found in an environment variable). Its
827 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
831 @defun parse-colon-path path
832 This function takes a search path string such as would be the value of
833 the @code{PATH} environment variable, and splits it at the separators,
834 returning a list of directory names. @code{nil} in this list stands for
835 ``use the current directory.'' Although the function's name says
836 ``colon,'' it actually uses the value of @code{path-separator}.
839 (parse-colon-path ":/foo:/bar")
840 @result{} (nil "/foo/" "/bar/")
844 @defvar invocation-name
845 This variable holds the program name under which Emacs was invoked. The
846 value is a string, and does not include a directory name.
849 @defvar invocation-directory
850 This variable holds the directory from which the Emacs executable was
851 invoked, or perhaps @code{nil} if that directory cannot be determined.
854 @defvar installation-directory
855 If non-@code{nil}, this is a directory within which to look for the
856 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
857 when Emacs can't find those directories in their standard installed
858 locations, but can find them in a directory related somehow to the one
859 containing the Emacs executable.
862 @defun load-average &optional use-float
863 This function returns the current 1-minute, 5-minute, and 15-minute load
866 By default, the values are integers that are 100 times the system load
867 averages, which indicate the average number of processes trying to run.
868 If @var{use-float} is non-@code{nil}, then they are returned
869 as floating point numbers and without multiplying by 100.
871 If it is impossible to obtain the load average, this function signals
872 an error. On some platforms, access to load averages requires
873 installing Emacs as setuid or setgid so that it can read kernel
874 information, and that usually isn't advisable.
876 If the 1-minute load average is available, but the 5- or 15-minute
877 averages are not, this function returns a shortened list containing
878 the available averages.
883 @result{} (169 48 36)
887 @result{} (1.69 0.48 0.36)
891 lewis@@rocky[5] % uptime
892 11:55am up 1 day, 19:37, 3 users,
893 load average: 1.69, 0.48, 0.36
899 This function returns the process @acronym{ID} of the Emacs process,
903 @defvar tty-erase-char
904 This variable holds the erase character that was selected
905 in the system's terminal driver, before Emacs was started.
906 The value is @code{nil} if Emacs is running under a window system.
909 @node User Identification
910 @section User Identification
911 @cindex user identification
913 @defvar init-file-user
914 This variable says which user's init files should be used by
915 Emacs---or @code{nil} if none. @code{""} stands for the user who
916 originally logged in. The value reflects command-line options such as
917 @samp{-q} or @samp{-u @var{user}}.
919 Lisp packages that load files of customizations, or any other sort of
920 user profile, should obey this variable in deciding where to find it.
921 They should load the profile of the user name found in this variable.
922 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
923 option was used, then Lisp packages should not load any customization
924 files or user profile.
927 @defvar user-mail-address
928 This holds the nominal email address of the user who is using Emacs.
929 Emacs normally sets this variable to a default value after reading your
930 init files, but not if you have already set it. So you can set the
931 variable to some other value in your init file if you do not
932 want to use the default value.
935 @defun user-login-name &optional uid
936 If you don't specify @var{uid}, this function returns the name under
937 which the user is logged in. If the environment variable @code{LOGNAME}
938 is set, that value is used. Otherwise, if the environment variable
939 @code{USER} is set, that value is used. Otherwise, the value is based
940 on the effective @acronym{UID}, not the real @acronym{UID}.
942 If you specify @var{uid}, the value is the user name that corresponds
943 to @var{uid} (which should be an integer), or @code{nil} if there is
954 @defun user-real-login-name
955 This function returns the user name corresponding to Emacs's real
956 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
957 environment variables @code{LOGNAME} and @code{USER}.
960 @defun user-full-name &optional uid
961 This function returns the full name of the logged-in user---or the value
962 of the environment variable @code{NAME}, if that is set.
964 @c "Bil" is the correct spelling.
968 @result{} "Bil Lewis"
972 If the Emacs job's user-id does not correspond to any known user (and
973 provided @code{NAME} is not set), the value is @code{"unknown"}.
975 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
976 or a string (a login name). Then @code{user-full-name} returns the full
977 name corresponding to that user-id or login name. If you specify a
978 user-id or login name that isn't defined, it returns @code{nil}.
981 @vindex user-full-name
982 @vindex user-real-login-name
983 @vindex user-login-name
984 The symbols @code{user-login-name}, @code{user-real-login-name} and
985 @code{user-full-name} are variables as well as functions. The functions
986 return the same values that the variables hold. These variables allow
987 you to ``fake out'' Emacs by telling the functions what to return. The
988 variables are also useful for constructing frame titles (@pxref{Frame
992 This function returns the real @acronym{UID} of the user.
993 The value may be a floating point number.
1004 This function returns the effective @acronym{UID} of the user.
1005 The value may be a floating point number.
1009 @section Time of Day
1011 This section explains how to determine the current time and the time
1014 @defun current-time-string &optional time-value
1015 This function returns the current time and date as a human-readable
1016 string. The format of the string is unvarying; the number of characters
1017 used for each part is always the same, so you can reliably use
1018 @code{substring} to extract pieces of it. It is wise to count the
1019 characters from the beginning of the string rather than from the end, as
1020 additional information may some day be added at the end.
1023 The argument @var{time-value}, if given, specifies a time to format
1024 instead of the current time. The argument should be a list whose first
1025 two elements are integers. Thus, you can use times obtained from
1026 @code{current-time} (see below) and from @code{file-attributes}
1027 (@pxref{Definition of file-attributes}). @var{time-value} can also be
1028 a cons of two integers, but this is considered obsolete.
1032 (current-time-string)
1033 @result{} "Wed Oct 14 22:21:05 1987"
1040 This function returns the system's time value as a list of three
1041 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
1042 @var{high} and @var{low} combine to give the number of seconds since
1043 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1045 @var{high} * 2**16 + @var{low}.
1051 The third element, @var{microsec}, gives the microseconds since the
1052 start of the current second (or 0 for systems that return time with
1053 the resolution of only one second).
1055 The first two elements can be compared with file time values such as you
1056 get with the function @code{file-attributes}.
1057 @xref{Definition of file-attributes}.
1061 @defun current-time-zone &optional time-value
1062 This function returns a list describing the time zone that the user is
1065 The value has the form @code{(@var{offset} @var{name})}. Here
1066 @var{offset} is an integer giving the number of seconds ahead of UTC
1067 (east of Greenwich). A negative value means west of Greenwich. The
1068 second element, @var{name}, is a string giving the name of the time
1069 zone. Both elements change when daylight saving time begins or ends;
1070 if the user has specified a time zone that does not use a seasonal time
1071 adjustment, then the value is constant through time.
1073 If the operating system doesn't supply all the information necessary to
1074 compute the value, the unknown elements of the list are @code{nil}.
1076 The argument @var{time-value}, if given, specifies a time to analyze
1077 instead of the current time. The argument should have the same form
1078 as for @code{current-time-string} (see above). Thus, you can use
1079 times obtained from @code{current-time} (see above) and from
1080 @code{file-attributes}. @xref{Definition of file-attributes}.
1083 @defun set-time-zone-rule tz
1084 This function specifies the local time zone according to @var{tz}. If
1085 @var{tz} is @code{nil}, that means to use an implementation-defined
1086 default time zone. If @var{tz} is @code{t}, that means to use
1087 Universal Time. Otherwise, @var{tz} should be a string specifying a
1091 @defun float-time &optional time-value
1092 This function returns the current time as a floating-point number of
1093 seconds since the epoch. The argument @var{time-value}, if given,
1094 specifies a time to convert instead of the current time. The argument
1095 should have the same form as for @code{current-time-string} (see
1096 above). Thus, it accepts the output of @code{current-time} and
1097 @code{file-attributes}.
1099 @emph{Warning}: Since the result is floating point, it may not be
1100 exact. Do not use this function if precise time stamps are required.
1103 @node Time Conversion
1104 @section Time Conversion
1106 These functions convert time values (lists of two or three integers)
1107 to calendrical information and vice versa. You can get time values
1108 from the functions @code{current-time} (@pxref{Time of Day}) and
1109 @code{file-attributes} (@pxref{Definition of file-attributes}).
1111 Many operating systems are limited to time values that contain 32 bits
1112 of information; these systems typically handle only the times from
1113 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1114 operating systems have larger time values, and can represent times far
1115 in the past or future.
1117 Time conversion functions always use the Gregorian calendar, even
1118 for dates before the Gregorian calendar was introduced. Year numbers
1119 count the number of years since the year 1 B.C., and do not skip zero
1120 as traditional Gregorian years do; for example, the year number
1121 @minus{}37 represents the Gregorian year 38 B.C@.
1123 @defun decode-time &optional time
1124 This function converts a time value into calendrical information. If
1125 you don't specify @var{time}, it decodes the current time. The return
1126 value is a list of nine elements, as follows:
1129 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1132 Here is what the elements mean:
1136 The number of seconds past the minute, as an integer between 0 and 59.
1137 On some operating systems, this is 60 for leap seconds.
1139 The number of minutes past the hour, as an integer between 0 and 59.
1141 The hour of the day, as an integer between 0 and 23.
1143 The day of the month, as an integer between 1 and 31.
1145 The month of the year, as an integer between 1 and 12.
1147 The year, an integer typically greater than 1900.
1149 The day of week, as an integer between 0 and 6, where 0 stands for
1152 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1154 An integer indicating the time zone, as the number of seconds east of
1158 @strong{Common Lisp Note:} Common Lisp has different meanings for
1159 @var{dow} and @var{zone}.
1162 @defun encode-time seconds minutes hour day month year &optional zone
1163 This function is the inverse of @code{decode-time}. It converts seven
1164 items of calendrical data into a time value. For the meanings of the
1165 arguments, see the table above under @code{decode-time}.
1167 Year numbers less than 100 are not treated specially. If you want them
1168 to stand for years above 1900, or years above 2000, you must alter them
1169 yourself before you call @code{encode-time}.
1171 The optional argument @var{zone} defaults to the current time zone and
1172 its daylight saving time rules. If specified, it can be either a list
1173 (as you would get from @code{current-time-zone}), a string as in the
1174 @code{TZ} environment variable, @code{t} for Universal Time, or an
1175 integer (as you would get from @code{decode-time}). The specified
1176 zone is used without any further alteration for daylight saving time.
1178 If you pass more than seven arguments to @code{encode-time}, the first
1179 six are used as @var{seconds} through @var{year}, the last argument is
1180 used as @var{zone}, and the arguments in between are ignored. This
1181 feature makes it possible to use the elements of a list returned by
1182 @code{decode-time} as the arguments to @code{encode-time}, like this:
1185 (apply 'encode-time (decode-time @dots{}))
1188 You can perform simple date arithmetic by using out-of-range values for
1189 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1190 arguments; for example, day 0 means the day preceding the given month.
1192 The operating system puts limits on the range of possible time values;
1193 if you try to encode a time that is out of range, an error results.
1194 For instance, years before 1970 do not work on some systems;
1195 on others, years as early as 1901 do work.
1199 @section Parsing and Formatting Times
1201 These functions convert time values (lists of two or three integers)
1202 to text in a string, and vice versa.
1204 @defun date-to-time string
1205 This function parses the time-string @var{string} and returns the
1206 corresponding time value.
1209 @defun format-time-string format-string &optional time universal
1210 This function converts @var{time} (or the current time, if @var{time} is
1211 omitted) to a string according to @var{format-string}. The argument
1212 @var{format-string} may contain @samp{%}-sequences which say to
1213 substitute parts of the time. Here is a table of what the
1214 @samp{%}-sequences mean:
1218 This stands for the abbreviated name of the day of week.
1220 This stands for the full name of the day of week.
1222 This stands for the abbreviated name of the month.
1224 This stands for the full name of the month.
1226 This is a synonym for @samp{%x %X}.
1228 This has a locale-specific meaning. In the default locale (named C), it
1229 is equivalent to @samp{%A, %B %e, %Y}.
1231 This stands for the day of month, zero-padded.
1233 This is a synonym for @samp{%m/%d/%y}.
1235 This stands for the day of month, blank-padded.
1237 This is a synonym for @samp{%b}.
1239 This stands for the hour (00-23).
1241 This stands for the hour (01-12).
1243 This stands for the day of the year (001-366).
1245 This stands for the hour (0-23), blank padded.
1247 This stands for the hour (1-12), blank padded.
1249 This stands for the month (01-12).
1251 This stands for the minute (00-59).
1253 This stands for a newline.
1255 This stands for @samp{AM} or @samp{PM}, as appropriate.
1257 This is a synonym for @samp{%I:%M:%S %p}.
1259 This is a synonym for @samp{%H:%M}.
1261 This stands for the seconds (00-59).
1263 This stands for a tab character.
1265 This is a synonym for @samp{%H:%M:%S}.
1267 This stands for the week of the year (01-52), assuming that weeks
1270 This stands for the numeric day of week (0-6). Sunday is day 0.
1272 This stands for the week of the year (01-52), assuming that weeks
1275 This has a locale-specific meaning. In the default locale (named
1276 @samp{C}), it is equivalent to @samp{%D}.
1278 This has a locale-specific meaning. In the default locale (named
1279 @samp{C}), it is equivalent to @samp{%T}.
1281 This stands for the year without century (00-99).
1283 This stands for the year with century.
1285 This stands for the time zone abbreviation (e.g., @samp{EST}).
1287 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1290 You can also specify the field width and type of padding for any of
1291 these @samp{%}-sequences. This works as in @code{printf}: you write
1292 the field width as digits in the middle of a @samp{%}-sequences. If you
1293 start the field width with @samp{0}, it means to pad with zeros. If you
1294 start the field width with @samp{_}, it means to pad with spaces.
1296 For example, @samp{%S} specifies the number of seconds since the minute;
1297 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1298 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1299 because that is how @samp{%S} normally pads to two positions.
1301 The characters @samp{E} and @samp{O} act as modifiers when used between
1302 @samp{%} and one of the letters in the table above. @samp{E} specifies
1303 using the current locale's ``alternative'' version of the date and time.
1304 In a Japanese locale, for example, @code{%Ex} might yield a date format
1305 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1306 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1309 @samp{O} means to use the current locale's ``alternative''
1310 representation of numbers, instead of the ordinary decimal digits. This
1311 is allowed with most letters, all the ones that output numbers.
1313 If @var{universal} is non-@code{nil}, that means to describe the time as
1314 Universal Time; @code{nil} means describe it using what Emacs believes
1315 is the local time zone (see @code{current-time-zone}).
1317 This function uses the C library function @code{strftime}
1318 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1319 Manual}) to do most of the work. In order to communicate with that
1320 function, it first encodes its argument using the coding system
1321 specified by @code{locale-coding-system} (@pxref{Locales}); after
1322 @code{strftime} returns the resulting string,
1323 @code{format-time-string} decodes the string using that same coding
1327 @defun seconds-to-time seconds
1328 This function converts @var{seconds}, a floating point number of
1329 seconds since the epoch, to a time value and returns that. To perform
1330 the inverse conversion, use @code{float-time}.
1333 @defun format-seconds format-string seconds
1334 This function converts its argument @var{seconds} into a string of
1335 years, days, hours, etc., according to @var{format-string}. The
1336 argument @var{format-string} may contain @samp{%}-sequences which
1337 control the conversion. Here is a table of what the
1338 @samp{%}-sequences mean:
1343 The number of full 365-day years.
1346 The number of full days.
1349 The number of full hours.
1352 The number of full minutes.
1355 The number of seconds.
1357 Non-printing control flag. When it is used, other specifiers must be
1358 given in the order of decreasing size, i.e.@: years before days, hours
1359 before minutes, etc. Nothing will be produced in the result string to
1360 the left of @samp{%z} until the first non-zero conversion is
1361 encountered. For example, the default format used by
1362 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1363 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1364 will always be produced, but years, days, hours, and minutes will only
1365 be shown if they are non-zero.
1367 Produces a literal @samp{%}.
1370 Upper-case format sequences produce the units in addition to the
1371 numbers, lower-case formats produce only the numbers.
1373 You can also specify the field width by following the @samp{%} with a
1374 number; shorter numbers will be padded with blanks. An optional
1375 period before the width requests zero-padding instead. For example,
1376 @code{"%.3Y"} might produce @code{"004 years"}.
1378 @emph{Warning:} This function works only with values of @var{seconds}
1379 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1380 most-positive-fixnum}).
1383 @node Processor Run Time
1384 @section Processor Run time
1385 @cindex processor run time
1386 @cindex Emacs process run time
1388 Emacs provides several functions and primitives that return time,
1389 both elapsed and processor time, used by the Emacs process.
1391 @defun emacs-uptime &optional format
1392 This function returns a string representing the Emacs
1393 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1394 running. The string is formatted according to the optional argument
1395 @var{format}. For the available format descriptors, see @ref{Time
1396 Parsing, format-seconds}. If @var{format} is nil or omitted, it
1397 defaults to @code{"%Y, %D, %H, %M, %z%S"}.
1400 @defun get-internal-run-time
1401 This function returns the processor run time used by Emacs as a list
1402 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1403 integers @var{high} and @var{low} combine to give the number of
1406 @var{high} * 2**16 + @var{low}.
1412 The third element, @var{microsec}, gives the microseconds (or 0 for
1413 systems that return time with the resolution of only one second).
1415 Note that the time returned by this function excludes the time Emacs
1416 was not using the processor, and if the Emacs process has several
1417 threads, the returned value is the sum of the processor times used up
1418 by all Emacs threads.
1420 If the system doesn't provide a way to determine the processor run
1421 time, @code{get-internal-run-time} returns the same time as
1422 @code{current-time}.
1425 @defun emacs-init-time
1426 This function returns the duration of the Emacs initialization
1427 (@pxref{Startup Summary}) in seconds, as a string.
1430 @node Time Calculations
1431 @section Time Calculations
1433 These functions perform calendrical computations using time values
1434 (the kind of list that @code{current-time} returns).
1436 @defun time-less-p t1 t2
1437 This returns @code{t} if time value @var{t1} is less than time value
1441 @defun time-subtract t1 t2
1442 This returns the time difference @var{t1} @minus{} @var{t2} between
1443 two time values, in the same format as a time value.
1446 @defun time-add t1 t2
1447 This returns the sum of two time values, one of which ought to
1448 represent a time difference rather than a point in time.
1449 Here is how to add a number of seconds to a time value:
1452 (time-add @var{time} (seconds-to-time @var{seconds}))
1456 @defun time-to-days time
1457 This function returns the number of days between the beginning of year
1461 @defun time-to-day-in-year time
1462 This returns the day number within the year corresponding to @var{time}.
1465 @defun date-leap-year-p year
1466 This function returns @code{t} if @var{year} is a leap year.
1470 @section Timers for Delayed Execution
1473 You can set up a @dfn{timer} to call a function at a specified
1474 future time or after a certain length of idleness.
1476 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1477 can run them only when Emacs could accept output from a subprocess:
1478 namely, while waiting or inside certain primitive functions such as
1479 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1480 timer's execution may be delayed if Emacs is busy. However, the time of
1481 execution is very precise if Emacs is idle.
1483 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1484 function, because quitting out of many timer functions can leave
1485 things in an inconsistent state. This is normally unproblematical
1486 because most timer functions don't do a lot of work. Indeed, for a
1487 timer to call a function that takes substantial time to run is likely
1488 to be annoying. If a timer function needs to allow quitting, it
1489 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1490 a timer function calls @code{accept-process-output} to receive output
1491 from an external process, that call should be wrapped inside
1492 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1495 It is usually a bad idea for timer functions to alter buffer
1496 contents. When they do, they usually should call @code{undo-boundary}
1497 both before and after changing the buffer, to separate the timer's
1498 changes from user commands' changes and prevent a single undo entry
1499 from growing to be quite large.
1501 Timer functions should also avoid calling functions that cause Emacs
1502 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1503 unpredictable effects, since other timers (or even the same timer) can
1504 run while waiting. If a timer function needs to perform an action
1505 after a certain time has elapsed, it can do this by scheduling a new
1508 If a timer function calls functions that can change the match data,
1509 it should save and restore the match data. @xref{Saving Match Data}.
1511 @deffn Command run-at-time time repeat function &rest args
1512 This sets up a timer that calls the function @var{function} with
1513 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1514 (integer or floating point), the timer is scheduled to run again every
1515 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1516 the timer runs only once.
1518 @var{time} may specify an absolute or a relative time.
1520 Absolute times may be specified using a string with a limited variety
1521 of formats, and are taken to be times @emph{today}, even if already in
1522 the past. The recognized forms are @samp{@var{xxxx}},
1523 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1524 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1525 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1526 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1527 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1528 to separate the hour and minute parts.
1530 To specify a relative time as a string, use numbers followed by units.
1535 denotes 1 minute from now.
1537 denotes 65 seconds from now.
1538 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1539 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1542 For relative time values, Emacs considers a month to be exactly thirty
1543 days, and a year to be exactly 365.25 days.
1545 Not all convenient formats are strings. If @var{time} is a number
1546 (integer or floating point), that specifies a relative time measured in
1547 seconds. The result of @code{encode-time} can also be used to specify
1548 an absolute value for @var{time}.
1550 In most cases, @var{repeat} has no effect on when @emph{first} call
1551 takes place---@var{time} alone specifies that. There is one exception:
1552 if @var{time} is @code{t}, then the timer runs whenever the time is a
1553 multiple of @var{repeat} seconds after the epoch. This is useful for
1554 functions like @code{display-time}.
1556 The function @code{run-at-time} returns a timer value that identifies
1557 the particular scheduled future action. You can use this value to call
1558 @code{cancel-timer} (see below).
1561 A repeating timer nominally ought to run every @var{repeat} seconds,
1562 but remember that any invocation of a timer can be late. Lateness of
1563 one repetition has no effect on the scheduled time of the next
1564 repetition. For instance, if Emacs is busy computing for long enough
1565 to cover three scheduled repetitions of the timer, and then starts to
1566 wait, it will immediately call the timer function three times in
1567 immediate succession (presuming no other timers trigger before or
1568 between them). If you want a timer to run again no less than @var{n}
1569 seconds after the last invocation, don't use the @var{repeat} argument.
1570 Instead, the timer function should explicitly reschedule the timer.
1572 @defvar timer-max-repeats
1573 This variable's value specifies the maximum number of times to repeat
1574 calling a timer function in a row, when many previously scheduled
1575 calls were unavoidably delayed.
1578 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1579 Execute @var{body}, but give up after @var{seconds} seconds. If
1580 @var{body} finishes before the time is up, @code{with-timeout} returns
1581 the value of the last form in @var{body}. If, however, the execution of
1582 @var{body} is cut short by the timeout, then @code{with-timeout}
1583 executes all the @var{timeout-forms} and returns the value of the last
1586 This macro works by setting a timer to run after @var{seconds} seconds. If
1587 @var{body} finishes before that time, it cancels the timer. If the
1588 timer actually runs, it terminates execution of @var{body}, then
1589 executes @var{timeout-forms}.
1591 Since timers can run within a Lisp program only when the program calls a
1592 primitive that can wait, @code{with-timeout} cannot stop executing
1593 @var{body} while it is in the midst of a computation---only when it
1594 calls one of those primitives. So use @code{with-timeout} only with a
1595 @var{body} that waits for input, not one that does a long computation.
1598 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1599 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1602 @defun cancel-timer timer
1603 This cancels the requested action for @var{timer}, which should be a
1604 timer---usually, one previously returned by @code{run-at-time} or
1605 @code{run-with-idle-timer}. This cancels the effect of that call to
1606 one of these functions; the arrival of the specified time will not
1607 cause anything special to happen.
1611 @section Idle Timers
1613 Here is how to set up a timer that runs when Emacs is idle for a
1614 certain length of time. Aside from how to set them up, idle timers
1615 work just like ordinary timers.
1617 @deffn Command run-with-idle-timer secs repeat function &rest args
1618 Set up a timer which runs when Emacs has been idle for @var{secs}
1619 seconds. The value of @var{secs} may be an integer or a floating point
1620 number; a value of the type returned by @code{current-idle-time}
1623 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1624 Emacs remains idle for a long enough time. More often @var{repeat} is
1625 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1626 remains idle for @var{secs} seconds.
1628 The function @code{run-with-idle-timer} returns a timer value which you
1629 can use in calling @code{cancel-timer} (@pxref{Timers}).
1633 Emacs becomes ``idle'' when it starts waiting for user input, and it
1634 remains idle until the user provides some input. If a timer is set for
1635 five seconds of idleness, it runs approximately five seconds after Emacs
1636 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1637 will not run again as long as Emacs remains idle, because the duration
1638 of idleness will continue to increase and will not go down to five
1641 Emacs can do various things while idle: garbage collect, autosave or
1642 handle data from a subprocess. But these interludes during idleness do
1643 not interfere with idle timers, because they do not reset the clock of
1644 idleness to zero. An idle timer set for 600 seconds will run when ten
1645 minutes have elapsed since the last user command was finished, even if
1646 subprocess output has been accepted thousands of times within those ten
1647 minutes, and even if there have been garbage collections and autosaves.
1649 When the user supplies input, Emacs becomes non-idle while executing the
1650 input. Then it becomes idle again, and all the idle timers that are
1651 set up to repeat will subsequently run another time, one by one.
1654 @defun current-idle-time
1655 If Emacs is idle, this function returns the length of time Emacs has
1656 been idle, as a list of three integers: @code{(@var{high} @var{low}
1657 @var{microsec})}. The integers @var{high} and @var{low} combine to
1658 give the number of seconds of idleness, which is
1660 @var{high} * 2**16 + @var{low}.
1666 The third element, @var{microsec}, gives the microseconds since the
1667 start of the current second (or 0 for systems that return time with
1668 the resolution of only one second).
1670 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1671 This is a convenient way to test whether Emacs is idle.
1673 The main use of this function is when an idle timer function wants to
1674 ``take a break'' for a while. It can set up another idle timer to
1675 call the same function again, after a few seconds more idleness.
1679 (defvar resume-timer nil
1680 "Timer that `timer-function' used to reschedule itself, or nil.")
1682 (defun timer-function ()
1683 ;; @r{If the user types a command while @code{resume-timer}}
1684 ;; @r{is active, the next time this function is called from}
1685 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1687 (cancel-timer resume-timer))
1688 ...@var{do the work for a while}...
1689 (when @var{taking-a-break}
1691 (run-with-idle-timer
1692 ;; Compute an idle time @var{break-length}
1693 ;; more than the current value.
1694 (time-add (current-idle-time)
1695 (seconds-to-time @var{break-length}))
1701 Some idle timer functions in user Lisp packages have a loop that
1702 does a certain amount of processing each time around, and exits when
1703 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1704 natural but has two problems:
1708 It blocks out all process output (since Emacs accepts process output
1709 only while waiting).
1712 It blocks out any idle timers that ought to run during that time.
1716 To avoid these problems, don't use that technique. Instead, write
1717 such idle timers to reschedule themselves after a brief pause, using
1718 the method in the @code{timer-function} example above.
1720 @node Terminal Input
1721 @section Terminal Input
1722 @cindex terminal input
1724 This section describes functions and variables for recording or
1725 manipulating terminal input. See @ref{Display}, for related
1729 * Input Modes:: Options for how input is processed.
1730 * Recording Input:: Saving histories of recent or all input events.
1734 @subsection Input Modes
1736 @cindex terminal input modes
1738 @defun set-input-mode interrupt flow meta &optional quit-char
1739 This function sets the mode for reading keyboard input. If
1740 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1741 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1742 system-dependent. Some systems always use @sc{cbreak} mode regardless
1743 of what is specified.
1745 When Emacs communicates directly with X, it ignores this argument and
1746 uses interrupts if that is the way it knows how to communicate.
1748 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1749 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1750 has no effect except in @sc{cbreak} mode.
1753 The argument @var{meta} controls support for input character codes
1754 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1755 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1756 Emacs disregards the 8th bit; this is necessary when the terminal uses
1757 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1758 Emacs uses all 8 bits of input unchanged. This is good for terminals
1759 that use 8-bit character sets.
1762 If @var{quit-char} is non-@code{nil}, it specifies the character to
1763 use for quitting. Normally this character is @kbd{C-g}.
1767 The @code{current-input-mode} function returns the input mode settings
1768 Emacs is currently using.
1771 @defun current-input-mode
1772 This function returns the current mode for reading keyboard input. It
1773 returns a list, corresponding to the arguments of @code{set-input-mode},
1774 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1778 is non-@code{nil} when Emacs is using interrupt-driven input. If
1779 @code{nil}, Emacs is using @sc{cbreak} mode.
1781 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1782 flow control for output to the terminal. This value is meaningful only
1783 when @var{interrupt} is @code{nil}.
1785 is @code{t} if Emacs treats the eighth bit of input characters as
1786 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1787 input character; any other value means Emacs uses all eight bits as the
1788 basic character code.
1790 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1794 @node Recording Input
1795 @subsection Recording Input
1796 @cindex recording input
1799 This function returns a vector containing the last 300 input events from
1800 the keyboard or mouse. All input events are included, whether or not
1801 they were used as parts of key sequences. Thus, you always get the last
1802 100 input events, not counting events generated by keyboard macros.
1803 (These are excluded because they are less interesting for debugging; it
1804 should be enough to see the events that invoked the macros.)
1806 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1807 causes this function to return an empty vector immediately afterward.
1810 @deffn Command open-dribble-file filename
1811 @cindex dribble file
1812 This function opens a @dfn{dribble file} named @var{filename}. When a
1813 dribble file is open, each input event from the keyboard or mouse (but
1814 not those from keyboard macros) is written in that file. A
1815 non-character event is expressed using its printed representation
1816 surrounded by @samp{<@dots{}>}.
1818 You close the dribble file by calling this function with an argument
1821 This function is normally used to record the input necessary to
1822 trigger an Emacs bug, for the sake of a bug report.
1826 (open-dribble-file "~/dribble")
1832 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1834 @node Terminal Output
1835 @section Terminal Output
1836 @cindex terminal output
1838 The terminal output functions send output to a text terminal, or keep
1839 track of output sent to the terminal. The variable @code{baud-rate}
1840 tells you what Emacs thinks is the output speed of the terminal.
1843 This variable's value is the output speed of the terminal, as far as
1844 Emacs knows. Setting this variable does not change the speed of actual
1845 data transmission, but the value is used for calculations such as
1848 It also affects decisions about whether to scroll part of the
1849 screen or repaint on text terminals. @xref{Forcing Redisplay},
1850 for the corresponding functionality on graphical terminals.
1852 The value is measured in baud.
1855 If you are running across a network, and different parts of the
1856 network work at different baud rates, the value returned by Emacs may be
1857 different from the value used by your local terminal. Some network
1858 protocols communicate the local terminal speed to the remote machine, so
1859 that Emacs and other programs can get the proper value, but others do
1860 not. If Emacs has the wrong value, it makes decisions that are less
1861 than optimal. To fix the problem, set @code{baud-rate}.
1864 This obsolete function returns the value of the variable
1868 @defun send-string-to-terminal string
1869 This function sends @var{string} to the terminal without alteration.
1870 Control characters in @var{string} have terminal-dependent effects.
1871 This function operates only on text terminals.
1873 One use of this function is to define function keys on terminals that
1874 have downloadable function key definitions. For example, this is how (on
1875 certain terminals) to define function key 4 to move forward four
1876 characters (by transmitting the characters @kbd{C-u C-f} to the
1881 (send-string-to-terminal "\eF4\^U\^F")
1887 @deffn Command open-termscript filename
1888 @cindex termscript file
1889 This function is used to open a @dfn{termscript file} that will record
1890 all the characters sent by Emacs to the terminal. It returns
1891 @code{nil}. Termscript files are useful for investigating problems
1892 where Emacs garbles the screen, problems that are due to incorrect
1893 Termcap entries or to undesirable settings of terminal options more
1894 often than to actual Emacs bugs. Once you are certain which characters
1895 were actually output, you can determine reliably whether they correspond
1896 to the Termcap specifications in use.
1898 You close the termscript file by calling this function with an
1899 argument of @code{nil}.
1901 See also @code{open-dribble-file} in @ref{Recording Input}.
1905 (open-termscript "../junk/termscript")
1912 @section Sound Output
1915 To play sound using Emacs, use the function @code{play-sound}. Only
1916 certain systems are supported; if you call @code{play-sound} on a system
1917 which cannot really do the job, it gives an error. Emacs version 20 and
1918 earlier did not support sound at all.
1920 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1921 or Sun Audio format (@samp{.au}).
1923 @defun play-sound sound
1924 This function plays a specified sound. The argument, @var{sound}, has
1925 the form @code{(sound @var{properties}...)}, where the @var{properties}
1926 consist of alternating keywords (particular symbols recognized
1927 specially) and values corresponding to them.
1929 Here is a table of the keywords that are currently meaningful in
1930 @var{sound}, and their meanings:
1933 @item :file @var{file}
1934 This specifies the file containing the sound to play.
1935 If the file name is not absolute, it is expanded against
1936 the directory @code{data-directory}.
1938 @item :data @var{data}
1939 This specifies the sound to play without need to refer to a file. The
1940 value, @var{data}, should be a string containing the same bytes as a
1941 sound file. We recommend using a unibyte string.
1943 @item :volume @var{volume}
1944 This specifies how loud to play the sound. It should be a number in the
1945 range of 0 to 1. The default is to use whatever volume has been
1948 @item :device @var{device}
1949 This specifies the system device on which to play the sound, as a
1950 string. The default device is system-dependent.
1953 Before actually playing the sound, @code{play-sound}
1954 calls the functions in the list @code{play-sound-functions}.
1955 Each function is called with one argument, @var{sound}.
1958 @defun play-sound-file file &optional volume device
1959 This function is an alternative interface to playing a sound @var{file}
1960 specifying an optional @var{volume} and @var{device}.
1963 @defvar play-sound-functions
1964 A list of functions to be called before playing a sound. Each function
1965 is called with one argument, a property list that describes the sound.
1969 @section Operating on X11 Keysyms
1972 To define system-specific X11 keysyms, set the variable
1973 @code{system-key-alist}.
1975 @defvar system-key-alist
1976 This variable's value should be an alist with one element for each
1977 system-specific keysym. Each element has the form @code{(@var{code}
1978 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1979 including the ``vendor specific'' bit,
1986 and @var{symbol} is the name for the function key.
1988 For example @code{(168 . mute-acute)} defines a system-specific key (used
1989 by HP X servers) whose numeric code is
1998 It is not crucial to exclude from the alist the keysyms of other X
1999 servers; those do no harm, as long as they don't conflict with the ones
2000 used by the X server actually in use.
2002 The variable is always local to the current terminal, and cannot be
2003 buffer-local. @xref{Multiple Displays}.
2006 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2008 @defvar x-alt-keysym
2009 @defvarx x-meta-keysym
2010 @defvarx x-hyper-keysym
2011 @defvarx x-super-keysym
2012 The name of the keysym that should stand for the Alt modifier
2013 (respectively, for Meta, Hyper, and Super). For example, here is
2014 how to swap the Meta and Alt modifiers within Emacs:
2016 (setq x-alt-keysym 'meta)
2017 (setq x-meta-keysym 'alt)
2025 The command-line option @samp{-batch} causes Emacs to run
2026 noninteractively. In this mode, Emacs does not read commands from the
2027 terminal, it does not alter the terminal modes, and it does not expect
2028 to be outputting to an erasable screen. The idea is that you specify
2029 Lisp programs to run; when they are finished, Emacs should exit. The
2030 way to specify the programs to run is with @samp{-l @var{file}}, which
2031 loads the library named @var{file}, or @samp{-f @var{function}}, which
2032 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2034 Any Lisp program output that would normally go to the echo area,
2035 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2036 as the stream, goes instead to Emacs's standard error descriptor when
2037 in batch mode. Similarly, input that would normally come from the
2038 minibuffer is read from the standard input descriptor.
2039 Thus, Emacs behaves much like a noninteractive
2040 application program. (The echo area output that Emacs itself normally
2041 generates, such as command echoing, is suppressed entirely.)
2043 @defvar noninteractive
2044 This variable is non-@code{nil} when Emacs is running in batch mode.
2047 @node Session Management
2048 @section Session Management
2049 @cindex session manager
2051 Emacs supports the X Session Management Protocol for suspension and
2052 restart of applications. In the X Window System, a program called the
2053 @dfn{session manager} has the responsibility to keep track of the
2054 applications that are running. During shutdown, the session manager
2055 asks applications to save their state, and delays the actual shutdown
2056 until they respond. An application can also cancel the shutdown.
2058 When the session manager restarts a suspended session, it directs
2059 these applications to individually reload their saved state. It does
2060 this by specifying a special command-line argument that says what
2061 saved session to restore. For Emacs, this argument is @samp{--smid
2064 @defvar emacs-save-session-functions
2065 Emacs supports saving state by using a hook called
2066 @code{emacs-save-session-functions}. Each function in this hook is
2067 called when the session manager tells Emacs that the window system is
2068 shutting down. The functions are called with no arguments and with the
2069 current buffer set to a temporary buffer. Each function can use
2070 @code{insert} to add Lisp code to this buffer. At the end, Emacs
2071 saves the buffer in a file that a subsequent Emacs invocation will
2072 load in order to restart the saved session.
2074 If a function in @code{emacs-save-session-functions} returns
2075 non-@code{nil}, Emacs tells the session manager to cancel the
2079 Here is an example that just inserts some text into @samp{*scratch*} when
2080 Emacs is restarted by the session manager.
2084 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2088 (defun save-yourself-test ()
2089 (insert "(save-excursion
2090 (switch-to-buffer \"*scratch*\")
2091 (insert \"I am restored\"))")
2097 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7