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.
73 It sets the language environment and the terminal coding system,
74 if requested by environment variables such as @code{LANG}.
77 It loads the initialization library for the window system, if you are
78 using a window system. This library's name is
79 @file{term/@var{windowsystem}-win.el}.
82 It processes the initial options. (Some of them are handled
83 even earlier than this.)
86 It initializes the window frame and faces, if appropriate.
89 It runs the normal hook @code{before-init-hook}.
92 It loads the library @file{site-start} (if any), unless the option
93 @samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
94 name is usually @file{site-start.el}.
95 @cindex @file{site-start.el}
98 It loads your init file (usually @file{~/.emacs}), unless the option
99 @samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
100 specified on the command line. The @samp{-u} option can specify
101 another user whose home directory should be used instead of @file{~}.
104 It loads the library @file{default} (if any), unless
105 @code{inhibit-default-init} is non-@code{nil}. (This is not done in
106 @samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
107 command line.) The library's file name is usually @file{default.el}.
108 @cindex @file{default.el}
111 It runs the normal hook @code{after-init-hook}.
114 It sets the major mode according to @code{initial-major-mode}, provided
115 the buffer @samp{*scratch*} is still current and still in Fundamental
119 It loads the terminal-specific Lisp file, if any, except when in batch
120 mode or using a window system.
123 It displays the initial echo area message, unless you have suppressed
124 that with @code{inhibit-startup-echo-area-message}.
127 It processes the action arguments from the command line.
130 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
133 It calls @code{frame-notice-user-settings}, which modifies the
134 parameters of the selected frame according to whatever the init files
138 It runs @code{window-setup-hook}. @xref{Window Systems}.
141 It displays copyleft, nonwarranty, and basic use information, provided
142 the value of @code{inhibit-startup-message} is @code{nil}, you didn't
143 specify @samp{--no-splash} or @samp{-Q}.
146 @defopt inhibit-startup-message
147 This variable inhibits the initial startup messages (the nonwarranty,
148 etc.). If it is non-@code{nil}, then the messages are not printed.
150 This variable exists so you can set it in your personal init file, once
151 you are familiar with the contents of the startup message. Do not set
152 this variable in the init file of a new user, or in a way that affects
153 more than one user, because that would prevent new users from receiving
154 the information they are supposed to see.
157 @defopt inhibit-startup-echo-area-message
158 This variable controls the display of the startup echo area message.
159 You can suppress the startup echo area message by adding text with this
160 form to your init file:
163 (setq inhibit-startup-echo-area-message
164 "@var{your-login-name}")
167 Emacs explicitly checks for an expression as shown above in your init
168 file; your login name must appear in the expression as a Lisp string
169 constant. Other methods of setting
170 @code{inhibit-startup-echo-area-message} to the same value do not
171 inhibit the startup message.
173 This way, you can easily inhibit the message for yourself if you wish,
174 but thoughtless copying of your init file will not inhibit the message
179 @subsection The Init File, @file{.emacs}
181 @cindex @file{.emacs}
183 When you start Emacs, it normally attempts to load your @dfn{init
184 file}, a file in your home directory. Its normal name is
185 @file{.emacs}, but you can also call it @file{.emacs.el}.
186 Alternatively, you can use a file named @file{init.el} in a
187 subdirectory @file{.emacs.d}. Whichever place you use, you can also
188 compile the file (@pxref{Byte Compilation}); then the actual file
189 loaded will be @file{.emacs.elc} or @file{init.elc}.
191 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
192 control whether and where to find the init file; @samp{-q} (and the
193 stronger @samp{-Q}) says not to load an init file, while @samp{-u
194 @var{user}} says to load @var{user}'s init file instead of yours.
195 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
196 option is specified, Emacs uses the @code{LOGNAME} environment
197 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
198 systems) variable, to find your home directory and thus your init
199 file; this way, even if you have su'd, Emacs still loads your own init
200 file. If those environment variables are absent, though, Emacs uses
201 your user-id to find your home directory.
203 @cindex default init file
204 A site may have a @dfn{default init file}, which is the library
205 named @file{default.el}. Emacs finds the @file{default.el} file
206 through the standard search path for libraries (@pxref{How Programs Do
207 Loading}). The Emacs distribution does not come with this file; sites
208 may provide one for local customizations. If the default init file
209 exists, it is loaded whenever you start Emacs, except in batch mode or
210 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
211 file, if any, is loaded first; if it sets @code{inhibit-default-init}
212 to a non-@code{nil} value, then Emacs does not subsequently load the
213 @file{default.el} file.
215 Another file for site-customization is @file{site-start.el}. Emacs
216 loads this @emph{before} the user's init file. You can inhibit the
217 loading of this file with the option @samp{--no-site-file}.
219 @defvar site-run-file
220 This variable specifies the site-customization file to load before the
221 user's init file. Its normal value is @code{"site-start"}. The only
222 way you can change it with real effect is to do so before dumping
226 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
227 examples of how to make various commonly desired customizations in your
230 @defopt inhibit-default-init
231 This variable prevents Emacs from loading the default initialization
232 library file for your session of Emacs. If its value is non-@code{nil},
233 then the default library is not loaded. The default value is
237 @defvar before-init-hook
238 This normal hook is run, once, just before loading all the init files
239 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
240 (The only way to change it with real effect is before dumping Emacs.)
243 @defvar after-init-hook
244 This normal hook is run, once, just after loading all the init files
245 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
246 before loading the terminal-specific library and processing the
247 command-line action arguments.
250 @defvar emacs-startup-hook
251 This normal hook is run, once, just after handling the command line
252 arguments, just before @code{term-setup-hook}.
255 @defvar user-init-file
256 This variable holds the absolute file name of the user's init file. If the
257 actual init file loaded is a compiled file, such as @file{.emacs.elc},
258 the value refers to the corresponding source file.
261 @defvar user-emacs-directory
262 This variable holds the name of the @file{.emacs.d} directory. It is
263 ordinarily @file{~/.emacs.d}, but differs on some platforms.
266 @node Terminal-Specific
267 @subsection Terminal-Specific Initialization
268 @cindex terminal-specific initialization
270 Each terminal type can have its own Lisp library that Emacs loads when
271 run on that type of terminal. The library's name is constructed by
272 concatenating the value of the variable @code{term-file-prefix} and the
273 terminal type (specified by the environment variable @code{TERM}).
274 Normally, @code{term-file-prefix} has the value
275 @code{"term/"}; changing this is not recommended. Emacs finds the file
276 in the normal manner, by searching the @code{load-path} directories, and
277 trying the @samp{.elc} and @samp{.el} suffixes.
280 The usual function of a terminal-specific library is to enable
281 special keys to send sequences that Emacs can recognize. It may also
282 need to set or add to @code{input-decode-map} if the Termcap or
283 Terminfo entry does not specify all the terminal's function keys.
284 @xref{Terminal Input}.
286 When the name of the terminal type contains a hyphen, and no library
287 is found whose name is identical to the terminal's name, Emacs strips
288 from the terminal's name the last hyphen and everything that follows
289 it, and tries again. This process is repeated until Emacs finds a
290 matching library or until there are no more hyphens in the name (the
291 latter means the terminal doesn't have any library specific to it).
292 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
293 libraries, Emacs will try the same library @file{term/aaa.el} for
294 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
295 library can evaluate @code{(getenv "TERM")} to find the full name of
296 the terminal type.@refill
298 Your init file can prevent the loading of the
299 terminal-specific library by setting the variable
300 @code{term-file-prefix} to @code{nil}. This feature is useful when
301 experimenting with your own peculiar customizations.
303 You can also arrange to override some of the actions of the
304 terminal-specific library by setting the variable
305 @code{term-setup-hook}. This is a normal hook which Emacs runs using
306 @code{run-hooks} at the end of Emacs initialization, after loading both
307 your init file and any terminal-specific libraries. You can
308 use this variable to define initializations for terminals that do not
309 have their own libraries. @xref{Hooks}.
311 @defvar term-file-prefix
312 @cindex @code{TERM} environment variable
313 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
314 a terminal-specific initialization file as follows:
317 (load (concat term-file-prefix (getenv "TERM")))
321 You may set the @code{term-file-prefix} variable to @code{nil} in your
322 init file if you do not wish to load the
323 terminal-initialization file. To do this, put the following in
324 your init file: @code{(setq term-file-prefix nil)}.
326 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
327 uses @samp{internal} as the terminal type.
330 @defvar term-setup-hook
331 This variable is a normal hook that Emacs runs after loading your
332 init file, the default initialization file (if any) and the
333 terminal-specific Lisp file.
335 You can use @code{term-setup-hook} to override the definitions made by a
336 terminal-specific file.
339 See @code{window-setup-hook} in @ref{Window Systems}, for a related
342 @node Command-Line Arguments
343 @subsection Command-Line Arguments
344 @cindex command-line arguments
346 You can use command-line arguments to request various actions when you
347 start Emacs. Since you do not need to start Emacs more than once per
348 day, and will often leave your Emacs session running longer than that,
349 command-line arguments are hardly ever used. As a practical matter, it
350 is best to avoid making the habit of using them, since this habit would
351 encourage you to kill and restart Emacs unnecessarily often. These
352 options exist for two reasons: to be compatible with other editors (for
353 invocation by other programs) and to enable shell scripts to run
354 specific Lisp programs.
356 This section describes how Emacs processes command-line arguments,
357 and how you can customize them.
360 (Note that some other editors require you to start afresh each time
361 you want to edit a file. With this kind of editor, you will probably
362 specify the file as a command-line argument. The recommended way to
363 use GNU Emacs is to start it only once, just after you log in, and do
364 all your editing in the same Emacs process. Each time you want to edit
365 a different file, you visit it with the existing Emacs, which eventually
366 comes to have many files in it ready for editing. Usually you do not
367 kill the Emacs until you are about to log out.)
371 This function parses the command line that Emacs was called with,
372 processes it, loads the user's init file and displays the
376 @defvar command-line-processed
377 The value of this variable is @code{t} once the command line has been
380 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
381 this variable to @code{nil} first in order to cause the new dumped Emacs
382 to process its new command-line arguments.
385 @defvar command-switch-alist
386 @cindex switches on command line
387 @cindex options on command line
388 @cindex command-line options
389 The value of this variable is an alist of user-defined command-line
390 options and associated handler functions. This variable exists so you
391 can add elements to it.
393 A @dfn{command-line option} is an argument on the command line, which
400 The elements of the @code{command-switch-alist} look like this:
403 (@var{option} . @var{handler-function})
406 The @sc{car}, @var{option}, is a string, the name of a command-line
407 option (not including the initial hyphen). The @var{handler-function}
408 is called to handle @var{option}, and receives the option name as its
411 In some cases, the option is followed in the command line by an
412 argument. In these cases, the @var{handler-function} can find all the
413 remaining command-line arguments in the variable
414 @code{command-line-args-left}. (The entire list of command-line
415 arguments is in @code{command-line-args}.)
417 The command-line arguments are parsed by the @code{command-line-1}
418 function in the @file{startup.el} file. See also @ref{Emacs
419 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
423 @defvar command-line-args
424 The value of this variable is the list of command-line arguments passed
428 @defvar command-line-functions
429 This variable's value is a list of functions for handling an
430 unrecognized command-line argument. Each time the next argument to be
431 processed has no special meaning, the functions in this list are called,
432 in order of appearance, until one of them returns a non-@code{nil}
435 These functions are called with no arguments. They can access the
436 command-line argument under consideration through the variable
437 @code{argi}, which is bound temporarily at this point. The remaining
438 arguments (not including the current one) are in the variable
439 @code{command-line-args-left}.
441 When a function recognizes and processes the argument in @code{argi}, it
442 should return a non-@code{nil} value to say it has dealt with that
443 argument. If it has also dealt with some of the following arguments, it
444 can indicate that by deleting them from @code{command-line-args-left}.
446 If all of these functions return @code{nil}, then the argument is used
447 as a file name to visit.
451 @section Getting Out of Emacs
452 @cindex exiting Emacs
454 There are two ways to get out of Emacs: you can kill the Emacs job,
455 which exits permanently, or you can suspend it, which permits you to
456 reenter the Emacs process later. As a practical matter, you seldom kill
457 Emacs---only when you are about to log out. Suspending is much more
461 * Killing Emacs:: Exiting Emacs irreversibly.
462 * Suspending Emacs:: Exiting Emacs reversibly.
466 @comment node-name, next, previous, up
467 @subsection Killing Emacs
468 @cindex killing Emacs
470 Killing Emacs means ending the execution of the Emacs process. The
471 parent process normally resumes control. The low-level primitive for
472 killing Emacs is @code{kill-emacs}.
474 @defun kill-emacs &optional exit-data
475 This function exits the Emacs process and kills it.
477 If @var{exit-data} is an integer, then it is used as the exit status
478 of the Emacs process. (This is useful primarily in batch operation; see
481 If @var{exit-data} is a string, its contents are stuffed into the
482 terminal input buffer so that the shell (or whatever program next reads
483 input) can read them.
486 All the information in the Emacs process, aside from files that have
487 been saved, is lost when the Emacs process is killed. Because killing
488 Emacs inadvertently can lose a lot of work, Emacs queries for
489 confirmation before actually terminating if you have buffers that need
490 saving or subprocesses that are running. This is done in the function
491 @code{save-buffers-kill-emacs}, the higher level function from which
492 @code{kill-emacs} is usually called.
494 @defvar kill-emacs-query-functions
495 After asking the standard questions, @code{save-buffers-kill-emacs}
496 calls the functions in the list @code{kill-emacs-query-functions}, in
497 order of appearance, with no arguments. These functions can ask for
498 additional confirmation from the user. If any of them returns
499 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
500 does not run the remaining functions in this hook. Calling
501 @code{kill-emacs} directly does not run this hook.
504 @defvar kill-emacs-hook
505 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
506 finished with all file saving and confirmation, it calls
507 @code{kill-emacs} which runs the functions in this hook.
508 @code{kill-emacs} does not run this hook in batch mode.
510 @code{kill-emacs} may be invoked directly (that is not via
511 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
512 similar situations where interaction with the user is not possible.
513 Thus, if your hook needs to interact with the user, put it on
514 @code{kill-emacs-query-functions}; if it needs to run regardless of
515 how Emacs is killed, put it on @code{kill-emacs-hook}.
518 @node Suspending Emacs
519 @subsection Suspending Emacs
520 @cindex suspending Emacs
522 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
523 control to its superior process, which is usually the shell. This
524 allows you to resume editing later in the same Emacs process, with the
525 same buffers, the same kill ring, the same undo history, and so on. To
526 resume Emacs, use the appropriate command in the parent shell---most
529 Some operating systems do not support suspension of jobs; on these
530 systems, ``suspension'' actually creates a new shell temporarily as a
531 subprocess of Emacs. Then you would exit the shell to return to Emacs.
533 Suspension is not useful with window systems, because the Emacs job
534 may not have a parent that can resume it again, and in any case you can
535 give input to some other job such as a shell merely by moving to a
536 different window. Therefore, suspending is not allowed when Emacs is using
537 a window system (X, MS Windows).
539 @defun suspend-emacs &optional string
540 This function stops Emacs and returns control to the superior process.
541 If and when the superior process resumes Emacs, @code{suspend-emacs}
542 returns @code{nil} to its caller in Lisp.
544 If @var{string} is non-@code{nil}, its characters are sent to be read
545 as terminal input by Emacs's superior shell. The characters in
546 @var{string} are not echoed by the superior shell; only the results
549 Before suspending, @code{suspend-emacs} runs the normal hook
552 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
553 @code{suspend-resume-hook}. @xref{Hooks}.
555 The next redisplay after resumption will redraw the entire screen,
556 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
557 (@pxref{Refresh Screen}).
559 In the following example, note that @samp{pwd} is not echoed after
560 Emacs is suspended. But it is read and executed by the shell.
569 (add-hook 'suspend-hook
573 (error "Suspend canceled")))))
574 @result{} (lambda nil
575 (or (y-or-n-p "Really suspend? ")
576 (error "Suspend canceled")))
579 (add-hook 'suspend-resume-hook
580 (function (lambda () (message "Resumed!"))))
581 @result{} (lambda nil (message "Resumed!"))
584 (suspend-emacs "pwd")
588 ---------- Buffer: Minibuffer ----------
589 Really suspend? @kbd{y}
590 ---------- Buffer: Minibuffer ----------
594 ---------- Parent Shell ----------
595 lewis@@slug[23] % /user/lewis/manual
600 ---------- Echo Area ----------
607 This variable is a normal hook that Emacs runs before suspending.
610 @defvar suspend-resume-hook
611 This variable is a normal hook that Emacs runs on resuming
615 @node System Environment
616 @section Operating System Environment
617 @cindex operating system environment
619 Emacs provides access to variables in the operating system environment
620 through various functions. These variables include the name of the
621 system, the user's @acronym{UID}, and so on.
623 @defvar system-configuration
624 This variable holds the standard GNU configuration name for the
625 hardware/software configuration of your system, as a string. The
626 convenient way to test parts of this string is with
630 @cindex system type and name
632 The value of this variable is a symbol indicating the type of operating
633 system Emacs is operating on. Here is a table of the possible values:
645 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
648 A GNU/Linux system---that is, a variant GNU system, using the Linux
649 kernel. (These systems are the ones people often call ``Linux,'' but
650 actually Linux is just the kernel, not the whole system.)
653 Hewlett-Packard HPUX operating system.
656 Silicon Graphics Irix system.
659 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
660 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
667 Microsoft windows NT. The same executable supports Windows 9X, but the
668 value of @code{system-type} is @code{windows-nt} in either case.
672 We do not wish to add new symbols to make finer distinctions unless it
673 is absolutely necessary! In fact, we hope to eliminate some of these
674 alternatives in the future. We recommend using
675 @code{system-configuration} to distinguish between different operating
680 This function returns the name of the machine you are running on.
683 @result{} "www.gnu.org"
687 The symbol @code{system-name} is a variable as well as a function. In
688 fact, the function returns whatever value the variable
689 @code{system-name} currently holds. Thus, you can set the variable
690 @code{system-name} in case Emacs is confused about the name of your
691 system. The variable is also useful for constructing frame titles
692 (@pxref{Frame Titles}).
694 @defvar mail-host-address
695 If this variable is non-@code{nil}, it is used instead of
696 @code{system-name} for purposes of generating email addresses. For
697 example, it is used when constructing the default value of
698 @code{user-mail-address}. @xref{User Identification}. (Since this is
699 done when Emacs starts up, the value actually used is the one saved when
700 Emacs was dumped. @xref{Building Emacs}.)
703 @deffn Command getenv var
704 @cindex environment variable access
705 This function returns the value of the environment variable @var{var},
706 as a string. @var{var} should be a string. If @var{var} is undefined
707 in the environment, @code{getenv} returns @code{nil}. If returns
708 @samp{""} if @var{var} is set but null. Within Emacs, the environment
709 variable values are kept in the Lisp variable @code{process-environment}.
718 lewis@@slug[10] % printenv
719 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
731 @deffn Command setenv variable &optional value
732 This command sets the value of the environment variable named
733 @var{variable} to @var{value}. @var{variable} should be a string.
734 Internally, Emacs Lisp can handle any string. However, normally
735 @var{variable} should be a valid shell identifier, that is, a sequence
736 of letters, digits and underscores, starting with a letter or
737 underscore. Otherwise, errors may occur if subprocesses of Emacs try
738 to access the value of @var{variable}. If @var{value} is omitted or
739 @code{nil}, @code{setenv} removes @var{variable} from the environment.
740 Otherwise, @var{value} should be a string.
742 @code{setenv} works by modifying @code{process-environment}; binding
743 that variable with @code{let} is also reasonable practice.
745 @code{setenv} returns the new value of @var{variable}, or @code{nil}
746 if it removed @var{variable} from the environment.
749 @defvar process-environment
750 This variable is a list of strings, each describing one environment
751 variable. The functions @code{getenv} and @code{setenv} work by means
757 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
758 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
768 If @code{process-environment} contains ``duplicate'' elements that
769 specify the same environment variable, the first of these elements
770 specifies the variable, and the other ``duplicates'' are ignored.
773 @defvar path-separator
774 This variable holds a string which says which character separates
775 directories in a search path (as found in an environment variable). Its
776 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
780 @defun parse-colon-path path
781 This function takes a search path string such as would be the value of
782 the @code{PATH} environment variable, and splits it at the separators,
783 returning a list of directory names. @code{nil} in this list stands for
784 ``use the current directory.'' Although the function's name says
785 ``colon,'' it actually uses the value of @code{path-separator}.
788 (parse-colon-path ":/foo:/bar")
789 @result{} (nil "/foo/" "/bar/")
793 @defvar invocation-name
794 This variable holds the program name under which Emacs was invoked. The
795 value is a string, and does not include a directory name.
798 @defvar invocation-directory
799 This variable holds the directory from which the Emacs executable was
800 invoked, or perhaps @code{nil} if that directory cannot be determined.
803 @defvar installation-directory
804 If non-@code{nil}, this is a directory within which to look for the
805 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
806 when Emacs can't find those directories in their standard installed
807 locations, but can find them in a directory related somehow to the one
808 containing the Emacs executable.
811 @defun load-average &optional use-float
812 This function returns the current 1-minute, 5-minute, and 15-minute load
815 By default, the values are integers that are 100 times the system load
816 averages, which indicate the average number of processes trying to run.
817 If @var{use-float} is non-@code{nil}, then they are returned
818 as floating point numbers and without multiplying by 100.
820 If it is impossible to obtain the load average, this function signals
821 an error. On some platforms, access to load averages requires
822 installing Emacs as setuid or setgid so that it can read kernel
823 information, and that usually isn't advisable.
825 If the 1-minute load average is available, but the 5- or 15-minute
826 averages are not, this function returns a shortened list containing
827 the available averages.
832 @result{} (169 48 36)
836 @result{} (1.69 0.48 0.36)
840 lewis@@rocky[5] % uptime
841 11:55am up 1 day, 19:37, 3 users,
842 load average: 1.69, 0.48, 0.36
848 This function returns the process @acronym{ID} of the Emacs process,
852 @defvar tty-erase-char
853 This variable holds the erase character that was selected
854 in the system's terminal driver, before Emacs was started.
855 The value is @code{nil} if Emacs is running under a window system.
858 @node User Identification
859 @section User Identification
860 @cindex user identification
862 @defvar init-file-user
863 This variable says which user's init files should be used by
864 Emacs---or @code{nil} if none. @code{""} stands for the user who
865 originally logged in. The value reflects command-line options such as
866 @samp{-q} or @samp{-u @var{user}}.
868 Lisp packages that load files of customizations, or any other sort of
869 user profile, should obey this variable in deciding where to find it.
870 They should load the profile of the user name found in this variable.
871 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
872 option was used, then Lisp packages should not load any customization
873 files or user profile.
876 @defvar user-mail-address
877 This holds the nominal email address of the user who is using Emacs.
878 Emacs normally sets this variable to a default value after reading your
879 init files, but not if you have already set it. So you can set the
880 variable to some other value in your init file if you do not
881 want to use the default value.
884 @defun user-login-name &optional uid
885 If you don't specify @var{uid}, this function returns the name under
886 which the user is logged in. If the environment variable @code{LOGNAME}
887 is set, that value is used. Otherwise, if the environment variable
888 @code{USER} is set, that value is used. Otherwise, the value is based
889 on the effective @acronym{UID}, not the real @acronym{UID}.
891 If you specify @var{uid}, the value is the user name that corresponds
892 to @var{uid} (which should be an integer), or @code{nil} if there is
903 @defun user-real-login-name
904 This function returns the user name corresponding to Emacs's real
905 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
906 environment variables @code{LOGNAME} and @code{USER}.
909 @defun user-full-name &optional uid
910 This function returns the full name of the logged-in user---or the value
911 of the environment variable @code{NAME}, if that is set.
913 @c "Bil" is the correct spelling.
917 @result{} "Bil Lewis"
921 If the Emacs job's user-id does not correspond to any known user (and
922 provided @code{NAME} is not set), the value is @code{"unknown"}.
924 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
925 or a string (a login name). Then @code{user-full-name} returns the full
926 name corresponding to that user-id or login name. If you specify a
927 user-id or login name that isn't defined, it returns @code{nil}.
930 @vindex user-full-name
931 @vindex user-real-login-name
932 @vindex user-login-name
933 The symbols @code{user-login-name}, @code{user-real-login-name} and
934 @code{user-full-name} are variables as well as functions. The functions
935 return the same values that the variables hold. These variables allow
936 you to ``fake out'' Emacs by telling the functions what to return. The
937 variables are also useful for constructing frame titles (@pxref{Frame
941 This function returns the real @acronym{UID} of the user.
942 The value may be a floating point number.
953 This function returns the effective @acronym{UID} of the user.
954 The value may be a floating point number.
960 This section explains how to determine the current time and the time
963 @defun current-time-string &optional time-value
964 This function returns the current time and date as a human-readable
965 string. The format of the string is unvarying; the number of characters
966 used for each part is always the same, so you can reliably use
967 @code{substring} to extract pieces of it. It is wise to count the
968 characters from the beginning of the string rather than from the end, as
969 additional information may some day be added at the end.
972 The argument @var{time-value}, if given, specifies a time to format
973 instead of the current time. The argument should be a list whose first
974 two elements are integers. Thus, you can use times obtained from
975 @code{current-time} (see below) and from @code{file-attributes}
976 (@pxref{Definition of file-attributes}). @var{time-value} can also be
977 a cons of two integers, but this is considered obsolete.
981 (current-time-string)
982 @result{} "Wed Oct 14 22:21:05 1987"
989 This function returns the system's time value as a list of three
990 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
991 @var{high} and @var{low} combine to give the number of seconds since
992 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
994 @var{high} * 2**16 + @var{low}.
1000 The third element, @var{microsec}, gives the microseconds since the
1001 start of the current second (or 0 for systems that return time with
1002 the resolution of only one second).
1004 The first two elements can be compared with file time values such as you
1005 get with the function @code{file-attributes}.
1006 @xref{Definition of file-attributes}.
1010 @defun current-time-zone &optional time-value
1011 This function returns a list describing the time zone that the user is
1014 The value has the form @code{(@var{offset} @var{name})}. Here
1015 @var{offset} is an integer giving the number of seconds ahead of UTC
1016 (east of Greenwich). A negative value means west of Greenwich. The
1017 second element, @var{name}, is a string giving the name of the time
1018 zone. Both elements change when daylight saving time begins or ends;
1019 if the user has specified a time zone that does not use a seasonal time
1020 adjustment, then the value is constant through time.
1022 If the operating system doesn't supply all the information necessary to
1023 compute the value, the unknown elements of the list are @code{nil}.
1025 The argument @var{time-value}, if given, specifies a time to analyze
1026 instead of the current time. The argument should have the same form
1027 as for @code{current-time-string} (see above). Thus, you can use
1028 times obtained from @code{current-time} (see above) and from
1029 @code{file-attributes}. @xref{Definition of file-attributes}.
1032 @defun set-time-zone-rule tz
1033 This function specifies the local time zone according to @var{tz}. If
1034 @var{tz} is @code{nil}, that means to use an implementation-defined
1035 default time zone. If @var{tz} is @code{t}, that means to use
1036 Universal Time. Otherwise, @var{tz} should be a string specifying a
1040 @defun float-time &optional time-value
1041 This function returns the current time as a floating-point number of
1042 seconds since the epoch. The argument @var{time-value}, if given,
1043 specifies a time to convert instead of the current time. The argument
1044 should have the same form as for @code{current-time-string} (see
1045 above). Thus, it accepts the output of @code{current-time} and
1046 @code{file-attributes}.
1048 @emph{Warning}: Since the result is floating point, it may not be
1049 exact. Do not use this function if precise time stamps are required.
1052 @node Time Conversion
1053 @section Time Conversion
1055 These functions convert time values (lists of two or three integers)
1056 to calendrical information and vice versa. You can get time values
1057 from the functions @code{current-time} (@pxref{Time of Day}) and
1058 @code{file-attributes} (@pxref{Definition of file-attributes}).
1060 Many operating systems are limited to time values that contain 32 bits
1061 of information; these systems typically handle only the times from
1062 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1063 operating systems have larger time values, and can represent times far
1064 in the past or future.
1066 Time conversion functions always use the Gregorian calendar, even
1067 for dates before the Gregorian calendar was introduced. Year numbers
1068 count the number of years since the year 1 B.C., and do not skip zero
1069 as traditional Gregorian years do; for example, the year number
1070 @minus{}37 represents the Gregorian year 38 B.C@.
1072 @defun decode-time &optional time
1073 This function converts a time value into calendrical information. If
1074 you don't specify @var{time}, it decodes the current time. The return
1075 value is a list of nine elements, as follows:
1078 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1081 Here is what the elements mean:
1085 The number of seconds past the minute, as an integer between 0 and 59.
1086 On some operating systems, this is 60 for leap seconds.
1088 The number of minutes past the hour, as an integer between 0 and 59.
1090 The hour of the day, as an integer between 0 and 23.
1092 The day of the month, as an integer between 1 and 31.
1094 The month of the year, as an integer between 1 and 12.
1096 The year, an integer typically greater than 1900.
1098 The day of week, as an integer between 0 and 6, where 0 stands for
1101 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1103 An integer indicating the time zone, as the number of seconds east of
1107 @strong{Common Lisp Note:} Common Lisp has different meanings for
1108 @var{dow} and @var{zone}.
1111 @defun encode-time seconds minutes hour day month year &optional zone
1112 This function is the inverse of @code{decode-time}. It converts seven
1113 items of calendrical data into a time value. For the meanings of the
1114 arguments, see the table above under @code{decode-time}.
1116 Year numbers less than 100 are not treated specially. If you want them
1117 to stand for years above 1900, or years above 2000, you must alter them
1118 yourself before you call @code{encode-time}.
1120 The optional argument @var{zone} defaults to the current time zone and
1121 its daylight saving time rules. If specified, it can be either a list
1122 (as you would get from @code{current-time-zone}), a string as in the
1123 @code{TZ} environment variable, @code{t} for Universal Time, or an
1124 integer (as you would get from @code{decode-time}). The specified
1125 zone is used without any further alteration for daylight saving time.
1127 If you pass more than seven arguments to @code{encode-time}, the first
1128 six are used as @var{seconds} through @var{year}, the last argument is
1129 used as @var{zone}, and the arguments in between are ignored. This
1130 feature makes it possible to use the elements of a list returned by
1131 @code{decode-time} as the arguments to @code{encode-time}, like this:
1134 (apply 'encode-time (decode-time @dots{}))
1137 You can perform simple date arithmetic by using out-of-range values for
1138 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1139 arguments; for example, day 0 means the day preceding the given month.
1141 The operating system puts limits on the range of possible time values;
1142 if you try to encode a time that is out of range, an error results.
1143 For instance, years before 1970 do not work on some systems;
1144 on others, years as early as 1901 do work.
1148 @section Parsing and Formatting Times
1150 These functions convert time values (lists of two or three integers)
1151 to text in a string, and vice versa.
1153 @defun date-to-time string
1154 This function parses the time-string @var{string} and returns the
1155 corresponding time value.
1158 @defun format-time-string format-string &optional time universal
1159 This function converts @var{time} (or the current time, if @var{time} is
1160 omitted) to a string according to @var{format-string}. The argument
1161 @var{format-string} may contain @samp{%}-sequences which say to
1162 substitute parts of the time. Here is a table of what the
1163 @samp{%}-sequences mean:
1167 This stands for the abbreviated name of the day of week.
1169 This stands for the full name of the day of week.
1171 This stands for the abbreviated name of the month.
1173 This stands for the full name of the month.
1175 This is a synonym for @samp{%x %X}.
1177 This has a locale-specific meaning. In the default locale (named C), it
1178 is equivalent to @samp{%A, %B %e, %Y}.
1180 This stands for the day of month, zero-padded.
1182 This is a synonym for @samp{%m/%d/%y}.
1184 This stands for the day of month, blank-padded.
1186 This is a synonym for @samp{%b}.
1188 This stands for the hour (00-23).
1190 This stands for the hour (01-12).
1192 This stands for the day of the year (001-366).
1194 This stands for the hour (0-23), blank padded.
1196 This stands for the hour (1-12), blank padded.
1198 This stands for the month (01-12).
1200 This stands for the minute (00-59).
1202 This stands for a newline.
1204 This stands for @samp{AM} or @samp{PM}, as appropriate.
1206 This is a synonym for @samp{%I:%M:%S %p}.
1208 This is a synonym for @samp{%H:%M}.
1210 This stands for the seconds (00-59).
1212 This stands for a tab character.
1214 This is a synonym for @samp{%H:%M:%S}.
1216 This stands for the week of the year (01-52), assuming that weeks
1219 This stands for the numeric day of week (0-6). Sunday is day 0.
1221 This stands for the week of the year (01-52), assuming that weeks
1224 This has a locale-specific meaning. In the default locale (named
1225 @samp{C}), it is equivalent to @samp{%D}.
1227 This has a locale-specific meaning. In the default locale (named
1228 @samp{C}), it is equivalent to @samp{%T}.
1230 This stands for the year without century (00-99).
1232 This stands for the year with century.
1234 This stands for the time zone abbreviation (e.g., @samp{EST}).
1236 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1239 You can also specify the field width and type of padding for any of
1240 these @samp{%}-sequences. This works as in @code{printf}: you write
1241 the field width as digits in the middle of a @samp{%}-sequences. If you
1242 start the field width with @samp{0}, it means to pad with zeros. If you
1243 start the field width with @samp{_}, it means to pad with spaces.
1245 For example, @samp{%S} specifies the number of seconds since the minute;
1246 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1247 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1248 because that is how @samp{%S} normally pads to two positions.
1250 The characters @samp{E} and @samp{O} act as modifiers when used between
1251 @samp{%} and one of the letters in the table above. @samp{E} specifies
1252 using the current locale's ``alternative'' version of the date and time.
1253 In a Japanese locale, for example, @code{%Ex} might yield a date format
1254 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1255 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1258 @samp{O} means to use the current locale's ``alternative''
1259 representation of numbers, instead of the ordinary decimal digits. This
1260 is allowed with most letters, all the ones that output numbers.
1262 If @var{universal} is non-@code{nil}, that means to describe the time as
1263 Universal Time; @code{nil} means describe it using what Emacs believes
1264 is the local time zone (see @code{current-time-zone}).
1266 This function uses the C library function @code{strftime}
1267 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1268 Manual}) to do most of the work. In order to communicate with that
1269 function, it first encodes its argument using the coding system
1270 specified by @code{locale-coding-system} (@pxref{Locales}); after
1271 @code{strftime} returns the resulting string,
1272 @code{format-time-string} decodes the string using that same coding
1276 @defun seconds-to-time seconds
1277 This function converts @var{seconds}, a floating point number of
1278 seconds since the epoch, to a time value and returns that. To perform
1279 the inverse conversion, use @code{float-time}.
1282 @node Processor Run Time
1283 @section Processor Run time
1284 @cindex processor run time
1286 @defun get-internal-run-time
1287 This function returns the processor run time used by Emacs as a list
1288 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1289 integers @var{high} and @var{low} combine to give the number of
1292 @var{high} * 2**16 + @var{low}.
1298 The third element, @var{microsec}, gives the microseconds (or 0 for
1299 systems that return time with the resolution of only one second).
1301 If the system doesn't provide a way to determine the processor run
1302 time, get-internal-run-time returns the same time as current-time.
1305 @node Time Calculations
1306 @section Time Calculations
1308 These functions perform calendrical computations using time values
1309 (the kind of list that @code{current-time} returns).
1311 @defun time-less-p t1 t2
1312 This returns @code{t} if time value @var{t1} is less than time value
1316 @defun time-subtract t1 t2
1317 This returns the time difference @var{t1} @minus{} @var{t2} between
1318 two time values, in the same format as a time value.
1321 @defun time-add t1 t2
1322 This returns the sum of two time values, one of which ought to
1323 represent a time difference rather than a point in time.
1324 Here is how to add a number of seconds to a time value:
1327 (time-add @var{time} (seconds-to-time @var{seconds}))
1331 @defun time-to-days time
1332 This function returns the number of days between the beginning of year
1336 @defun time-to-day-in-year time
1337 This returns the day number within the year corresponding to @var{time}.
1340 @defun date-leap-year-p year
1341 This function returns @code{t} if @var{year} is a leap year.
1345 @section Timers for Delayed Execution
1348 You can set up a @dfn{timer} to call a function at a specified
1349 future time or after a certain length of idleness.
1351 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1352 can run them only when Emacs could accept output from a subprocess:
1353 namely, while waiting or inside certain primitive functions such as
1354 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1355 timer's execution may be delayed if Emacs is busy. However, the time of
1356 execution is very precise if Emacs is idle.
1358 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1359 function, because quitting out of many timer functions can leave
1360 things in an inconsistent state. This is normally unproblematical
1361 because most timer functions don't do a lot of work. Indeed, for a
1362 timer to call a function that takes substantial time to run is likely
1363 to be annoying. If a timer function needs to allow quitting, it
1364 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1365 a timer function calls @code{accept-process-output} to receive output
1366 from an external process, that call should be wrapped inside
1367 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1370 It is usually a bad idea for timer functions to alter buffer
1371 contents. When they do, they usually should call @code{undo-boundary}
1372 both before and after changing the buffer, to separate the timer's
1373 changes from user commands' changes and prevent a single undo entry
1374 from growing to be quite large.
1376 Timer functions should also avoid calling functions that cause Emacs
1377 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1378 unpredictable effects, since other timers (or even the same timer) can
1379 run while waiting. If a timer function needs to perform an action
1380 after a certain time has elapsed, it can do this by scheduling a new
1383 If a timer function calls functions that can change the match data,
1384 it should save and restore the match data. @xref{Saving Match Data}.
1386 @deffn Command run-at-time time repeat function &rest args
1387 This sets up a timer that calls the function @var{function} with
1388 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1389 (integer or floating point), the timer is scheduled to run again every
1390 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1391 the timer runs only once.
1393 @var{time} may specify an absolute or a relative time.
1395 Absolute times may be specified using a string with a limited variety
1396 of formats, and are taken to be times @emph{today}, even if already in
1397 the past. The recognized forms are @samp{@var{xxxx}},
1398 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1399 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1400 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1401 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1402 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1403 to separate the hour and minute parts.
1405 To specify a relative time as a string, use numbers followed by units.
1410 denotes 1 minute from now.
1412 denotes 65 seconds from now.
1413 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1414 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1417 For relative time values, Emacs considers a month to be exactly thirty
1418 days, and a year to be exactly 365.25 days.
1420 Not all convenient formats are strings. If @var{time} is a number
1421 (integer or floating point), that specifies a relative time measured in
1422 seconds. The result of @code{encode-time} can also be used to specify
1423 an absolute value for @var{time}.
1425 In most cases, @var{repeat} has no effect on when @emph{first} call
1426 takes place---@var{time} alone specifies that. There is one exception:
1427 if @var{time} is @code{t}, then the timer runs whenever the time is a
1428 multiple of @var{repeat} seconds after the epoch. This is useful for
1429 functions like @code{display-time}.
1431 The function @code{run-at-time} returns a timer value that identifies
1432 the particular scheduled future action. You can use this value to call
1433 @code{cancel-timer} (see below).
1436 A repeating timer nominally ought to run every @var{repeat} seconds,
1437 but remember that any invocation of a timer can be late. Lateness of
1438 one repetition has no effect on the scheduled time of the next
1439 repetition. For instance, if Emacs is busy computing for long enough
1440 to cover three scheduled repetitions of the timer, and then starts to
1441 wait, it will immediately call the timer function three times in
1442 immediate succession (presuming no other timers trigger before or
1443 between them). If you want a timer to run again no less than @var{n}
1444 seconds after the last invocation, don't use the @var{repeat} argument.
1445 Instead, the timer function should explicitly reschedule the timer.
1447 @defvar timer-max-repeats
1448 This variable's value specifies the maximum number of times to repeat
1449 calling a timer function in a row, when many previously scheduled
1450 calls were unavoidably delayed.
1453 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1454 Execute @var{body}, but give up after @var{seconds} seconds. If
1455 @var{body} finishes before the time is up, @code{with-timeout} returns
1456 the value of the last form in @var{body}. If, however, the execution of
1457 @var{body} is cut short by the timeout, then @code{with-timeout}
1458 executes all the @var{timeout-forms} and returns the value of the last
1461 This macro works by setting a timer to run after @var{seconds} seconds. If
1462 @var{body} finishes before that time, it cancels the timer. If the
1463 timer actually runs, it terminates execution of @var{body}, then
1464 executes @var{timeout-forms}.
1466 Since timers can run within a Lisp program only when the program calls a
1467 primitive that can wait, @code{with-timeout} cannot stop executing
1468 @var{body} while it is in the midst of a computation---only when it
1469 calls one of those primitives. So use @code{with-timeout} only with a
1470 @var{body} that waits for input, not one that does a long computation.
1473 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1474 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1477 @defun cancel-timer timer
1478 This cancels the requested action for @var{timer}, which should be a
1479 timer---usually, one previously returned by @code{run-at-time} or
1480 @code{run-with-idle-timer}. This cancels the effect of that call to
1481 one of these functions; the arrival of the specified time will not
1482 cause anything special to happen.
1486 @section Idle Timers
1488 Here is how to set up a timer that runs when Emacs is idle for a
1489 certain length of time. Aside from how to set them up, idle timers
1490 work just like ordinary timers.
1492 @deffn Command run-with-idle-timer secs repeat function &rest args
1493 Set up a timer which runs when Emacs has been idle for @var{secs}
1494 seconds. The value of @var{secs} may be an integer or a floating point
1495 number; a value of the type returned by @code{current-idle-time}
1498 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1499 Emacs remains idle for a long enough time. More often @var{repeat} is
1500 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1501 remains idle for @var{secs} seconds.
1503 The function @code{run-with-idle-timer} returns a timer value which you
1504 can use in calling @code{cancel-timer} (@pxref{Timers}).
1508 Emacs becomes ``idle'' when it starts waiting for user input, and it
1509 remains idle until the user provides some input. If a timer is set for
1510 five seconds of idleness, it runs approximately five seconds after Emacs
1511 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1512 will not run again as long as Emacs remains idle, because the duration
1513 of idleness will continue to increase and will not go down to five
1516 Emacs can do various things while idle: garbage collect, autosave or
1517 handle data from a subprocess. But these interludes during idleness do
1518 not interfere with idle timers, because they do not reset the clock of
1519 idleness to zero. An idle timer set for 600 seconds will run when ten
1520 minutes have elapsed since the last user command was finished, even if
1521 subprocess output has been accepted thousands of times within those ten
1522 minutes, and even if there have been garbage collections and autosaves.
1524 When the user supplies input, Emacs becomes non-idle while executing the
1525 input. Then it becomes idle again, and all the idle timers that are
1526 set up to repeat will subsequently run another time, one by one.
1529 @defun current-idle-time
1530 If Emacs is idle, this function returns the length of time Emacs has
1531 been idle, as a list of three integers: @code{(@var{high} @var{low}
1532 @var{microsec})}. The integers @var{high} and @var{low} combine to
1533 give the number of seconds of idleness, which is
1535 @var{high} * 2**16 + @var{low}.
1541 The third element, @var{microsec}, gives the microseconds since the
1542 start of the current second (or 0 for systems that return time with
1543 the resolution of only one second).
1545 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1546 This is a convenient way to test whether Emacs is idle.
1548 The main use of this function is when an idle timer function wants to
1549 ``take a break'' for a while. It can set up another idle timer to
1550 call the same function again, after a few seconds more idleness.
1554 (defvar resume-timer nil
1555 "Timer that `timer-function' used to reschedule itself, or nil.")
1557 (defun timer-function ()
1558 ;; @r{If the user types a command while @code{resume-timer}}
1559 ;; @r{is active, the next time this function is called from}
1560 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1562 (cancel-timer resume-timer))
1563 ...@var{do the work for a while}...
1564 (when @var{taking-a-break}
1566 (run-with-idle-timer
1567 ;; Compute an idle time @var{break-length}
1568 ;; more than the current value.
1569 (time-add (current-idle-time)
1570 (seconds-to-time @var{break-length}))
1576 Some idle timer functions in user Lisp packages have a loop that
1577 does a certain amount of processing each time around, and exits when
1578 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1579 natural but has two problems:
1583 It blocks out all process output (since Emacs accepts process output
1584 only while waiting).
1587 It blocks out any idle timers that ought to run during that time.
1591 To avoid these problems, don't use that technique. Instead, write
1592 such idle timers to reschedule themselves after a brief pause, using
1593 the method in the @code{timer-function} example above.
1595 @node Terminal Input
1596 @section Terminal Input
1597 @cindex terminal input
1599 This section describes functions and variables for recording or
1600 manipulating terminal input. See @ref{Display}, for related
1604 * Input Modes:: Options for how input is processed.
1605 * Recording Input:: Saving histories of recent or all input events.
1609 @subsection Input Modes
1611 @cindex terminal input modes
1613 @defun set-input-mode interrupt flow meta &optional quit-char
1614 This function sets the mode for reading keyboard input. If
1615 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1616 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1617 system-dependent. Some systems always use @sc{cbreak} mode regardless
1618 of what is specified.
1620 When Emacs communicates directly with X, it ignores this argument and
1621 uses interrupts if that is the way it knows how to communicate.
1623 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1624 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1625 has no effect except in @sc{cbreak} mode.
1628 The argument @var{meta} controls support for input character codes
1629 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1630 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1631 Emacs disregards the 8th bit; this is necessary when the terminal uses
1632 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1633 Emacs uses all 8 bits of input unchanged. This is good for terminals
1634 that use 8-bit character sets.
1637 If @var{quit-char} is non-@code{nil}, it specifies the character to
1638 use for quitting. Normally this character is @kbd{C-g}.
1642 The @code{current-input-mode} function returns the input mode settings
1643 Emacs is currently using.
1646 @defun current-input-mode
1647 This function returns the current mode for reading keyboard input. It
1648 returns a list, corresponding to the arguments of @code{set-input-mode},
1649 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1653 is non-@code{nil} when Emacs is using interrupt-driven input. If
1654 @code{nil}, Emacs is using @sc{cbreak} mode.
1656 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1657 flow control for output to the terminal. This value is meaningful only
1658 when @var{interrupt} is @code{nil}.
1660 is @code{t} if Emacs treats the eighth bit of input characters as
1661 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1662 input character; any other value means Emacs uses all eight bits as the
1663 basic character code.
1665 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1669 @node Recording Input
1670 @subsection Recording Input
1671 @cindex recording input
1674 This function returns a vector containing the last 300 input events from
1675 the keyboard or mouse. All input events are included, whether or not
1676 they were used as parts of key sequences. Thus, you always get the last
1677 100 input events, not counting events generated by keyboard macros.
1678 (These are excluded because they are less interesting for debugging; it
1679 should be enough to see the events that invoked the macros.)
1681 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1682 causes this function to return an empty vector immediately afterward.
1685 @deffn Command open-dribble-file filename
1686 @cindex dribble file
1687 This function opens a @dfn{dribble file} named @var{filename}. When a
1688 dribble file is open, each input event from the keyboard or mouse (but
1689 not those from keyboard macros) is written in that file. A
1690 non-character event is expressed using its printed representation
1691 surrounded by @samp{<@dots{}>}.
1693 You close the dribble file by calling this function with an argument
1696 This function is normally used to record the input necessary to
1697 trigger an Emacs bug, for the sake of a bug report.
1701 (open-dribble-file "~/dribble")
1707 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1709 @node Terminal Output
1710 @section Terminal Output
1711 @cindex terminal output
1713 The terminal output functions send output to a text terminal, or keep
1714 track of output sent to the terminal. The variable @code{baud-rate}
1715 tells you what Emacs thinks is the output speed of the terminal.
1718 This variable's value is the output speed of the terminal, as far as
1719 Emacs knows. Setting this variable does not change the speed of actual
1720 data transmission, but the value is used for calculations such as
1723 It also affects decisions about whether to scroll part of the
1724 screen or repaint on text terminals. @xref{Forcing Redisplay},
1725 for the corresponding functionality on graphical terminals.
1727 The value is measured in baud.
1730 If you are running across a network, and different parts of the
1731 network work at different baud rates, the value returned by Emacs may be
1732 different from the value used by your local terminal. Some network
1733 protocols communicate the local terminal speed to the remote machine, so
1734 that Emacs and other programs can get the proper value, but others do
1735 not. If Emacs has the wrong value, it makes decisions that are less
1736 than optimal. To fix the problem, set @code{baud-rate}.
1739 This obsolete function returns the value of the variable
1743 @defun send-string-to-terminal string
1744 This function sends @var{string} to the terminal without alteration.
1745 Control characters in @var{string} have terminal-dependent effects.
1746 This function operates only on text terminals.
1748 One use of this function is to define function keys on terminals that
1749 have downloadable function key definitions. For example, this is how (on
1750 certain terminals) to define function key 4 to move forward four
1751 characters (by transmitting the characters @kbd{C-u C-f} to the
1756 (send-string-to-terminal "\eF4\^U\^F")
1762 @deffn Command open-termscript filename
1763 @cindex termscript file
1764 This function is used to open a @dfn{termscript file} that will record
1765 all the characters sent by Emacs to the terminal. It returns
1766 @code{nil}. Termscript files are useful for investigating problems
1767 where Emacs garbles the screen, problems that are due to incorrect
1768 Termcap entries or to undesirable settings of terminal options more
1769 often than to actual Emacs bugs. Once you are certain which characters
1770 were actually output, you can determine reliably whether they correspond
1771 to the Termcap specifications in use.
1773 You close the termscript file by calling this function with an
1774 argument of @code{nil}.
1776 See also @code{open-dribble-file} in @ref{Recording Input}.
1780 (open-termscript "../junk/termscript")
1787 @section Sound Output
1790 To play sound using Emacs, use the function @code{play-sound}. Only
1791 certain systems are supported; if you call @code{play-sound} on a system
1792 which cannot really do the job, it gives an error. Emacs version 20 and
1793 earlier did not support sound at all.
1795 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1796 or Sun Audio format (@samp{.au}).
1798 @defun play-sound sound
1799 This function plays a specified sound. The argument, @var{sound}, has
1800 the form @code{(sound @var{properties}...)}, where the @var{properties}
1801 consist of alternating keywords (particular symbols recognized
1802 specially) and values corresponding to them.
1804 Here is a table of the keywords that are currently meaningful in
1805 @var{sound}, and their meanings:
1808 @item :file @var{file}
1809 This specifies the file containing the sound to play.
1810 If the file name is not absolute, it is expanded against
1811 the directory @code{data-directory}.
1813 @item :data @var{data}
1814 This specifies the sound to play without need to refer to a file. The
1815 value, @var{data}, should be a string containing the same bytes as a
1816 sound file. We recommend using a unibyte string.
1818 @item :volume @var{volume}
1819 This specifies how loud to play the sound. It should be a number in the
1820 range of 0 to 1. The default is to use whatever volume has been
1823 @item :device @var{device}
1824 This specifies the system device on which to play the sound, as a
1825 string. The default device is system-dependent.
1828 Before actually playing the sound, @code{play-sound}
1829 calls the functions in the list @code{play-sound-functions}.
1830 Each function is called with one argument, @var{sound}.
1833 @defun play-sound-file file &optional volume device
1834 This function is an alternative interface to playing a sound @var{file}
1835 specifying an optional @var{volume} and @var{device}.
1838 @defvar play-sound-functions
1839 A list of functions to be called before playing a sound. Each function
1840 is called with one argument, a property list that describes the sound.
1844 @section Operating on X11 Keysyms
1847 To define system-specific X11 keysyms, set the variable
1848 @code{system-key-alist}.
1850 @defvar system-key-alist
1851 This variable's value should be an alist with one element for each
1852 system-specific keysym. Each element has the form @code{(@var{code}
1853 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1854 including the ``vendor specific'' bit,
1861 and @var{symbol} is the name for the function key.
1863 For example @code{(168 . mute-acute)} defines a system-specific key (used
1864 by HP X servers) whose numeric code is
1873 It is not crucial to exclude from the alist the keysyms of other X
1874 servers; those do no harm, as long as they don't conflict with the ones
1875 used by the X server actually in use.
1877 The variable is always local to the current terminal, and cannot be
1878 buffer-local. @xref{Multiple Displays}.
1881 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
1883 @defvar x-alt-keysym
1884 @defvarx x-meta-keysym
1885 @defvarx x-hyper-keysym
1886 @defvarx x-super-keysym
1887 The name of the keysym that should stand for the Alt modifier
1888 (respectively, for Meta, Hyper, and Super). For example, here is
1889 how to swap the Meta and Alt modifiers within Emacs:
1891 (setq x-alt-keysym 'meta)
1892 (setq x-meta-keysym 'alt)
1900 The command-line option @samp{-batch} causes Emacs to run
1901 noninteractively. In this mode, Emacs does not read commands from the
1902 terminal, it does not alter the terminal modes, and it does not expect
1903 to be outputting to an erasable screen. The idea is that you specify
1904 Lisp programs to run; when they are finished, Emacs should exit. The
1905 way to specify the programs to run is with @samp{-l @var{file}}, which
1906 loads the library named @var{file}, or @samp{-f @var{function}}, which
1907 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
1909 Any Lisp program output that would normally go to the echo area,
1910 either using @code{message}, or using @code{prin1}, etc., with @code{t}
1911 as the stream, goes instead to Emacs's standard error descriptor when
1912 in batch mode. Similarly, input that would normally come from the
1913 minibuffer is read from the standard input descriptor.
1914 Thus, Emacs behaves much like a noninteractive
1915 application program. (The echo area output that Emacs itself normally
1916 generates, such as command echoing, is suppressed entirely.)
1918 @defvar noninteractive
1919 This variable is non-@code{nil} when Emacs is running in batch mode.
1922 @node Session Management
1923 @section Session Management
1924 @cindex session manager
1926 Emacs supports the X Session Management Protocol for suspension and
1927 restart of applications. In the X Window System, a program called the
1928 @dfn{session manager} has the responsibility to keep track of the
1929 applications that are running. During shutdown, the session manager
1930 asks applications to save their state, and delays the actual shutdown
1931 until they respond. An application can also cancel the shutdown.
1933 When the session manager restarts a suspended session, it directs
1934 these applications to individually reload their saved state. It does
1935 this by specifying a special command-line argument that says what
1936 saved session to restore. For Emacs, this argument is @samp{--smid
1939 @defvar emacs-save-session-functions
1940 Emacs supports saving state by using a hook called
1941 @code{emacs-save-session-functions}. Each function in this hook is
1942 called when the session manager tells Emacs that the window system is
1943 shutting down. The functions are called with no arguments and with the
1944 current buffer set to a temporary buffer. Each function can use
1945 @code{insert} to add Lisp code to this buffer. At the end, Emacs
1946 saves the buffer in a file that a subsequent Emacs invocation will
1947 load in order to restart the saved session.
1949 If a function in @code{emacs-save-session-functions} returns
1950 non-@code{nil}, Emacs tells the session manager to cancel the
1954 Here is an example that just inserts some text into @samp{*scratch*} when
1955 Emacs is restarted by the session manager.
1959 (add-hook 'emacs-save-session-functions 'save-yourself-test)
1963 (defun save-yourself-test ()
1964 (insert "(save-excursion
1965 (switch-to-buffer \"*scratch*\")
1966 (insert \"I am restored\"))")
1972 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7