@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,@c 2004, 2005 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/os@node System Interface, Antinews, Display, Top@chapter Operating System Interface This chapter is about starting and getting out of Emacs, access tovalues in the operating system environment, and terminal input, output,and flow control. @xref{Building Emacs}, for related information. See also@ref{Display}, for additional operating system status informationpertaining to the terminal and the screen.@menu* Starting Up:: Customizing Emacs startup processing.* Getting Out:: How exiting works (permanent or temporary).* System Environment:: Distinguish the name and kind of system.* User Identification:: Finding the name and user id of the user.* Time of Day:: Getting the current time.* Time Conversion:: Converting a time from numeric form to calendrical data, and vice versa).* Time Parsing:: Converting a time from numeric form to text and vice versa.* Processor Run Time:: Getting the run time used by Emacs.* Time Calculations:: Adding, subtracting, comparing times, etc.* Timers:: Setting a timer to call a function at a certain time.* Terminal Input:: Recording terminal input for debugging.* Terminal Output:: Recording terminal output for debugging.* Sound Output:: Playing sounds on the computer's speaker.* X11 Keysyms:: Operating on key symbols for X Windows* Batch Mode:: Running Emacs without terminal interaction.* Session Management:: Saving and restoring state with X Session Management.@end menu@node Starting Up@section Starting Up Emacs This section describes what Emacs does when it is started, and how youcan customize these actions.@menu* Startup Summary:: Sequence of actions Emacs performs at startup.* Init File:: Details on reading the init file (@file{.emacs}).* Terminal-Specific:: How the terminal-specific Lisp file is read.* Command-Line Arguments:: How command-line arguments are processed, and how you can customize them.@end menu@node Startup Summary@subsection Summary: Sequence of Actions at Startup@cindex initialization@cindex startup of Emacs@cindex @file{startup.el} The order of operations performed (in @file{startup.el}) by Emacs whenit is started up is as follows:@enumerate@itemIt adds subdirectories to @code{load-path}, by running the file named@file{subdirs.el} in each directory in the list. Normally this fileadds the directory's subdirectories to the list, and these will bescanned in their turn. The files @file{subdirs.el} are normallygenerated automatically by Emacs installation.@itemIt sets the language environment and the terminal coding system,if requested by environment variables such as @code{LANG}.@itemIt loads the initialization library for the window system, if you areusing a window system. This library's name is@file{term/@var{windowsystem}-win.el}.@itemIt processes the initial options. (Some of them are handledeven earlier than this.)@itemIt initializes the window frame and faces, if appropriate.@itemIt runs the normal hook @code{before-init-hook}.@itemIt loads the library @file{site-start} (if any), unless the option@samp{-Q} (or @samp{--no-site-file}) was specified. The library's filename is usually @file{site-start.el}.@cindex @file{site-start.el}@itemIt loads your init file (usually @file{~/.emacs}), unless the option@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} wasspecified on the command line. The @samp{-u} option can specifyanother user whose home directory should be used instead of @file{~}.@itemIt loads the library @file{default} (if any), unless@code{inhibit-default-init} is non-@code{nil}. (This is not done in@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on thecommand line.) The library's file name is usually @file{default.el}.@cindex @file{default.el}@itemIt runs the normal hook @code{after-init-hook}.@itemIt sets the major mode according to @code{initial-major-mode}, providedthe buffer @samp{*scratch*} is still current and still in Fundamentalmode.@itemIt loads the terminal-specific Lisp file, if any, except when in batchmode or using a window system.@itemIt displays the initial echo area message, unless you have suppressedthat with @code{inhibit-startup-echo-area-message}.@itemIt processes the action arguments from the command line.@itemIt runs @code{emacs-startup-hook} and then @code{term-setup-hook}.@itemIt calls @code{frame-notice-user-settings}, which modifies theparameters of the selected frame according to whatever the init filesspecify.@itemIt runs @code{window-setup-hook}. @xref{Window Systems}.@itemIt displays copyleft, nonwarranty, and basic use information, providedthe value of @code{inhibit-startup-message} is @code{nil}, you didn'tspecify @samp{--no-splash} or @samp{-Q}.@end enumerate@defopt inhibit-startup-messageThis variable inhibits the initial startup messages (the nonwarranty,etc.). If it is non-@code{nil}, then the messages are not printed.This variable exists so you can set it in your personal init file, onceyou are familiar with the contents of the startup message. Do not setthis variable in the init file of a new user, or in a way that affectsmore than one user, because that would prevent new users from receivingthe information they are supposed to see.@end defopt@defopt inhibit-startup-echo-area-messageThis variable controls the display of the startup echo area message.You can suppress the startup echo area message by adding text with thisform to your init file:@example(setq inhibit-startup-echo-area-message "@var{your-login-name}")@end exampleEmacs explicitly checks for an expression as shown above in your initfile; your login name must appear in the expression as a Lisp stringconstant. Other methods of setting@code{inhibit-startup-echo-area-message} to the same value do notinhibit the startup message.This way, you can easily inhibit the message for yourself if you wish,but thoughtless copying of your init file will not inhibit the messagefor someone else.@end defopt@node Init File@subsection The Init File, @file{.emacs}@cindex init file@cindex @file{.emacs} When you start Emacs, it normally attempts to load your @dfn{initfile}, a file in your home directory. Its normal name is@file{.emacs}, but you can also call it @file{.emacs.el}.Alternatively, you can use a file named @file{init.el} in asubdirectory @file{.emacs.d}. Whichever place you use, you can alsocompile the file (@pxref{Byte Compilation}); then the actual fileloaded will be @file{.emacs.elc} or @file{init.elc}. The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}control whether and where to find the init file; @samp{-q} (and thestronger @samp{-Q}) says not to load an init file, while @samp{-u@var{user}} says to load @var{user}'s init file instead of yours.@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neitheroption is specified, Emacs uses the @code{LOGNAME} environmentvariable, or the @code{USER} (most systems) or @code{USERNAME} (MSsystems) variable, to find your home directory and thus your initfile; this way, even if you have su'd, Emacs still loads your own initfile. If those environment variables are absent, though, Emacs usesyour user-id to find your home directory.@cindex default init file A site may have a @dfn{default init file}, which is the librarynamed @file{default.el}. Emacs finds the @file{default.el} filethrough the standard search path for libraries (@pxref{How Programs DoLoading}). The Emacs distribution does not come with this file; sitesmay provide one for local customizations. If the default init fileexists, it is loaded whenever you start Emacs, except in batch mode orif @samp{-q} (or @samp{-Q}) is specified. But your own personal initfile, if any, is loaded first; if it sets @code{inhibit-default-init}to a non-@code{nil} value, then Emacs does not subsequently load the@file{default.el} file. Another file for site-customization is @file{site-start.el}. Emacsloads this @emph{before} the user's init file. You can inhibit theloading of this file with the option @samp{--no-site-file}.@defvar site-run-fileThis variable specifies the site-customization file to load before theuser's init file. Its normal value is @code{"site-start"}. The onlyway you can change it with real effect is to do so before dumpingEmacs.@end defvar @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, forexamples of how to make various commonly desired customizations in your@file{.emacs} file.@defopt inhibit-default-initThis variable prevents Emacs from loading the default initializationlibrary file for your session of Emacs. If its value is non-@code{nil},then the default library is not loaded. The default value is@code{nil}.@end defopt@defvar before-init-hookThis normal hook is run, once, just before loading all the init files(the user's init file, @file{default.el}, and/or @file{site-start.el}).(The only way to change it with real effect is before dumping Emacs.)@end defvar@defvar after-init-hookThis normal hook is run, once, just after loading all the init files(the user's init file, @file{default.el}, and/or @file{site-start.el}),before loading the terminal-specific library and processing thecommand-line action arguments.@end defvar@defvar emacs-startup-hook@tindex emacs-startup-hookThis normal hook is run, once, just after handling the command linearguments, just before @code{term-setup-hook}.@end defvar@defvar user-init-file@tindex user-init-fileThis variable holds the absolute file name of the user's init file. If theactual init file loaded is a compiled file, such as @file{.emacs.elc},the value refers to the corresponding source file.@end defvar@node Terminal-Specific@subsection Terminal-Specific Initialization@cindex terminal-specific initialization Each terminal type can have its own Lisp library that Emacs loads whenrun on that type of terminal. The library's name is constructed byconcatenating the value of the variable @code{term-file-prefix} and theterminal type (specified by the environment variable @code{TERM}).Normally, @code{term-file-prefix} has the value@code{"term/"}; changing this is not recommended. Emacs finds the filein the normal manner, by searching the @code{load-path} directories, andtrying the @samp{.elc} and @samp{.el} suffixes. The usual function of a terminal-specific library is to enable specialkeys to send sequences that Emacs can recognize. It may also need toset or add to @code{function-key-map} if the Termcap entry does notspecify all the terminal's function keys. @xref{Terminal Input}.@cindex Termcap When the name of the terminal type contains a hyphen, only the part ofthe name before the first hyphen is significant in choosing the libraryname. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both usethe @file{term/aaa} library. If necessary, the library can evaluate@code{(getenv "TERM")} to find the full name of the terminaltype.@refill Your init file can prevent the loading of theterminal-specific library by setting the variable@code{term-file-prefix} to @code{nil}. This feature is useful whenexperimenting with your own peculiar customizations. You can also arrange to override some of the actions of theterminal-specific library by setting the variable@code{term-setup-hook}. This is a normal hook which Emacs runs using@code{run-hooks} at the end of Emacs initialization, after loading bothyour init file and any terminal-specific libraries. You canuse this variable to define initializations for terminals that do nothave their own libraries. @xref{Hooks}.@defvar term-file-prefix@cindex @code{TERM} environment variableIf the @code{term-file-prefix} variable is non-@code{nil}, Emacs loadsa terminal-specific initialization file as follows:@example(load (concat term-file-prefix (getenv "TERM")))@end example@noindentYou may set the @code{term-file-prefix} variable to @code{nil} in yourinit file if you do not wish to load theterminal-initialization file. To do this, put the following inyour init file: @code{(setq term-file-prefix nil)}.On MS-DOS, if the environment variable @code{TERM} is not set, Emacsuses @samp{internal} as the terminal type.@end defvar@defvar term-setup-hookThis variable is a normal hook that Emacs runs after loading yourinit file, the default initialization file (if any) and theterminal-specific Lisp file.You can use @code{term-setup-hook} to override the definitions made by aterminal-specific file.@end defvar See @code{window-setup-hook} in @ref{Window Systems}, for a relatedfeature.@node Command-Line Arguments@subsection Command-Line Arguments@cindex command-line arguments You can use command-line arguments to request various actions when youstart Emacs. Since you do not need to start Emacs more than once perday, and will often leave your Emacs session running longer than that,command-line arguments are hardly ever used. As a practical matter, itis best to avoid making the habit of using them, since this habit wouldencourage you to kill and restart Emacs unnecessarily often. Theseoptions exist for two reasons: to be compatible with other editors (forinvocation by other programs) and to enable shell scripts to runspecific Lisp programs. This section describes how Emacs processes command-line arguments,and how you can customize them.@ignore (Note that some other editors require you to start afresh each timeyou want to edit a file. With this kind of editor, you will probablyspecify the file as a command-line argument. The recommended way touse GNU Emacs is to start it only once, just after you log in, and doall your editing in the same Emacs process. Each time you want to edita different file, you visit it with the existing Emacs, which eventuallycomes to have many files in it ready for editing. Usually you do notkill the Emacs until you are about to log out.)@end ignore@defun command-lineThis function parses the command line that Emacs was called with,processes it, loads the user's init file and displays thestartup messages.@end defun@defvar command-line-processedThe value of this variable is @code{t} once the command line has beenprocessed.If you redump Emacs by calling @code{dump-emacs}, you may wish to setthis variable to @code{nil} first in order to cause the new dumped Emacsto process its new command-line arguments.@end defvar@defvar command-switch-alist@cindex switches on command line@cindex options on command line@cindex command-line optionsThe value of this variable is an alist of user-defined command-lineoptions and associated handler functions. This variable exists so youcan add elements to it.A @dfn{command-line option} is an argument on the command line, whichhas the form:@example-@var{option}@end exampleThe elements of the @code{command-switch-alist} look like this:@example(@var{option} . @var{handler-function})@end exampleThe @sc{car}, @var{option}, is a string, the name of a command-lineoption (not including the initial hyphen). The @var{handler-function}is called to handle @var{option}, and receives the option name as itssole argument.In some cases, the option is followed in the command line by anargument. In these cases, the @var{handler-function} can find all theremaining command-line arguments in the variable@code{command-line-args-left}. (The entire list of command-linearguments is in @code{command-line-args}.)The command-line arguments are parsed by the @code{command-line-1}function in the @file{startup.el} file. See also @ref{CommandArguments, , Command Line Arguments, emacs, The GNU Emacs Manual}.@end defvar@defvar command-line-argsThe value of this variable is the list of command-line arguments passedto Emacs.@end defvar@defvar command-line-functionsThis variable's value is a list of functions for handling anunrecognized command-line argument. Each time the next argument to beprocessed has no special meaning, the functions in this list are called,in order of appearance, until one of them returns a non-@code{nil}value.These functions are called with no arguments. They can access thecommand-line argument under consideration through the variable@code{argi}, which is bound temporarily at this point. The remainingarguments (not including the current one) are in the variable@code{command-line-args-left}.When a function recognizes and processes the argument in @code{argi}, itshould return a non-@code{nil} value to say it has dealt with thatargument. If it has also dealt with some of the following arguments, itcan indicate that by deleting them from @code{command-line-args-left}.If all of these functions return @code{nil}, then the argument is usedas a file name to visit.@end defvar@node Getting Out@section Getting Out of Emacs@cindex exiting Emacs There are two ways to get out of Emacs: you can kill the Emacs job,which exits permanently, or you can suspend it, which permits you toreenter the Emacs process later. As a practical matter, you seldom killEmacs---only when you are about to log out. Suspending is much morecommon.@menu* Killing Emacs:: Exiting Emacs irreversibly.* Suspending Emacs:: Exiting Emacs reversibly.@end menu@node Killing Emacs@comment node-name, next, previous, up@subsection Killing Emacs@cindex killing Emacs Killing Emacs means ending the execution of the Emacs process. Theparent process normally resumes control. The low-level primitive forkilling Emacs is @code{kill-emacs}.@defun kill-emacs &optional exit-dataThis function exits the Emacs process and kills it.If @var{exit-data} is an integer, then it is used as the exit statusof the Emacs process. (This is useful primarily in batch operation; see@ref{Batch Mode}.)If @var{exit-data} is a string, its contents are stuffed into theterminal input buffer so that the shell (or whatever program next readsinput) can read them.@end defun All the information in the Emacs process, aside from files that havebeen saved, is lost when the Emacs process is killed. Because killingEmacs inadvertently can lose a lot of work, Emacs queries forconfirmation before actually terminating if you have buffers that needsaving or subprocesses that are running. This is done in the function@code{save-buffers-kill-emacs}, the higher level function from which@code{kill-emacs} is usually called.@defvar kill-emacs-query-functionsAfter asking the standard questions, @code{save-buffers-kill-emacs}calls the functions in the list @code{kill-emacs-query-functions}, inorder of appearance, with no arguments. These functions can ask foradditional confirmation from the user. If any of them returns@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, anddoes not run the remaining functions in this hook. Calling@code{kill-emacs} directly does not run this hook.@end defvar@defvar kill-emacs-hookThis variable is a normal hook; once @code{save-buffers-kill-emacs} isfinished with all file saving and confirmation, it calls@code{kill-emacs} which runs the functions in this hook.@code{kill-emacs} does not run this hook in batch mode.@code{kill-emacs} may be invoked directly (that is not via@code{save-buffers-kill-emacs}) if the terminal is disconnected, or insimilar situations where interaction with the user is not possible.Thus, if your hook needs to interact with the user, put it on@code{kill-emacs-query-functions}; if it needs to run regardless ofhow Emacs is killed, put it on @code{kill-emacs-hook}.@end defvar@node Suspending Emacs@subsection Suspending Emacs@cindex suspending Emacs @dfn{Suspending Emacs} means stopping Emacs temporarily and returningcontrol to its superior process, which is usually the shell. Thisallows you to resume editing later in the same Emacs process, with thesame buffers, the same kill ring, the same undo history, and so on. Toresume Emacs, use the appropriate command in the parent shell---mostlikely @code{fg}. Some operating systems do not support suspension of jobs; on thesesystems, ``suspension'' actually creates a new shell temporarily as asubprocess of Emacs. Then you would exit the shell to return to Emacs. Suspension is not useful with window systems, because the Emacs jobmay not have a parent that can resume it again, and in any case you cangive input to some other job such as a shell merely by moving to adifferent window. Therefore, suspending is not allowed when Emacs is usinga window system (X or MS Windows).@defun suspend-emacs &optional stringThis function stops Emacs and returns control to the superior process.If and when the superior process resumes Emacs, @code{suspend-emacs}returns @code{nil} to its caller in Lisp.If @var{string} is non-@code{nil}, its characters are sent to be readas terminal input by Emacs's superior shell. The characters in@var{string} are not echoed by the superior shell; only the resultsappear.Before suspending, @code{suspend-emacs} runs the normal hook@code{suspend-hook}.After the user resumes Emacs, @code{suspend-emacs} runs the normal hook@code{suspend-resume-hook}. @xref{Hooks}.The next redisplay after resumption will redraw the entire screen,unless the variable @code{no-redraw-on-reenter} is non-@code{nil}(@pxref{Refresh Screen}).In the following example, note that @samp{pwd} is not echoed afterEmacs is suspended. But it is read and executed by the shell.@smallexample@group(suspend-emacs) @result{} nil@end group@group(add-hook 'suspend-hook (function (lambda () (or (y-or-n-p "Really suspend? ") (error "Suspend canceled"))))) @result{} (lambda nil (or (y-or-n-p "Really suspend? ") (error "Suspend canceled")))@end group@group(add-hook 'suspend-resume-hook (function (lambda () (message "Resumed!")))) @result{} (lambda nil (message "Resumed!"))@end group@group(suspend-emacs "pwd") @result{} nil@end group@group---------- Buffer: Minibuffer ----------Really suspend? @kbd{y}---------- Buffer: Minibuffer ----------@end group@group---------- Parent Shell ----------lewis@@slug[23] % /user/lewis/manuallewis@@slug[24] % fg@end group@group---------- Echo Area ----------Resumed!@end group@end smallexample@end defun@defvar suspend-hookThis variable is a normal hook that Emacs runs before suspending.@end defvar@defvar suspend-resume-hookThis variable is a normal hook that Emacs runs on resumingafter a suspension.@end defvar@node System Environment@section Operating System Environment@cindex operating system environment Emacs provides access to variables in the operating system environmentthrough various functions. These variables include the name of thesystem, the user's @acronym{UID}, and so on.@defvar system-configurationThis variable holds the standard GNU configuration name for thehardware/software configuration of your system, as a string. Theconvenient way to test parts of this string is with@code{string-match}.@end defvar@defvar system-typeThe value of this variable is a symbol indicating the type of operatingsystem Emacs is operating on. Here is a table of the possible values:@table @code@item alpha-vmsVMS on the Alpha.@item aix-v3AIX.@item berkeley-unixBerkeley BSD.@item cygwinCygwin.@item dguxData General DGUX operating system.@item gnuthe GNU system (using the GNU kernel, which consists of the HURD and Mach).@item gnu/linuxA GNU/Linux system---that is, a variant GNU system, using the Linuxkernel. (These systems are the ones people often call ``Linux,'' butactually Linux is just the kernel, not the whole system.)@item hpuxHewlett-Packard HPUX operating system.@item irixSilicon Graphics Irix system.@item ms-dosMicrosoft MS-DOS ``operating system.'' Emacs compiled with DJGPP forMS-DOS binds @code{system-type} to @code{ms-dos} even when you run it onMS-Windows.@item next-machNeXT Mach-based system.@item rtuMasscomp RTU, UCB universe.@item unisoft-unixUniSoft UniPlus.@item usg-unix-vAT&T System V.@item vax-vmsVAX VMS.@item windows-ntMicrosoft windows NT. The same executable supports Windows 9X, but thevalue of @code{system-type} is @code{windows-nt} in either case.@item xenixSCO Xenix 386.@end tableWe do not wish to add new symbols to make finer distinctions unless itis absolutely necessary! In fact, we hope to eliminate some of thesealternatives in the future. We recommend using@code{system-configuration} to distinguish between different operatingsystems.@end defvar@defun system-nameThis function returns the name of the machine you are running on.@example(system-name) @result{} "www.gnu.org"@end example@end defun The symbol @code{system-name} is a variable as well as a function. Infact, the function returns whatever value the variable@code{system-name} currently holds. Thus, you can set the variable@code{system-name} in case Emacs is confused about the name of yoursystem. The variable is also useful for constructing frame titles(@pxref{Frame Titles}).@defvar mail-host-addressIf this variable is non-@code{nil}, it is used instead of@code{system-name} for purposes of generating email addresses. Forexample, it is used when constructing the default value of@code{user-mail-address}. @xref{User Identification}. (Since this isdone when Emacs starts up, the value actually used is the one saved whenEmacs was dumped. @xref{Building Emacs}.)@end defvar@deffn Command getenv var@cindex environment variable accessThis function returns the value of the environment variable @var{var},as a string. @var{var} should be a string. If @var{var} is undefinedin the environment, @code{getenv} returns @code{nil}. If returns@samp{""} if @var{var} is set but null. Within Emacs, the environmentvariable values are kept in the Lisp variable @code{process-environment}.@example@group(getenv "USER") @result{} "lewis"@end group@grouplewis@@slug[10] % printenvPATH=.:/user/lewis/bin:/usr/bin:/usr/local/binUSER=lewis@end group@groupTERM=ibmapa16SHELL=/bin/cshHOME=/user/lewis@end group@end example@end deffn@c Emacs 19 feature@deffn Command setenv variable &optional valueThis command sets the value of the environment variable named@var{variable} to @var{value}. @var{variable} should be a string.Internally, Emacs Lisp can handle any string. However, normally@var{variable} should be a valid shell identifier, that is, a sequenceof letters, digits and underscores, starting with a letter orunderscore. Otherwise, errors may occur if subprocesses of Emacs tryto access the value of @var{variable}. If @var{value} is omitted or@code{nil}, @code{setenv} removes @var{variable} from the environment.Otherwise, @var{value} should be a string.@code{setenv} works by modifying @code{process-environment}; bindingthat variable with @code{let} is also reasonable practice.@code{setenv} returns the new value of @var{variable}, or @code{nil}if it removed @var{variable} from the environment.@end deffn@defvar process-environmentThis variable is a list of strings, each describing one environmentvariable. The functions @code{getenv} and @code{setenv} work by meansof this variable.@smallexample@groupprocess-environment@result{} ("l=/usr/stanford/lib/gnuemacs/lisp" "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" "USER=lewis"@end group@group "TERM=ibmapa16" "SHELL=/bin/csh" "HOME=/user/lewis")@end group@end smallexampleIf @code{process-environment} contains ``duplicate'' elements thatspecify the same environment variable, the first of these elementsspecifies the variable, and the other ``duplicates'' are ignored.@end defvar@defvar path-separatorThis variable holds a string which says which character separatesdirectories in a search path (as found in an environment variable). Itsvalue is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOSand MS-Windows.@end defvar@defun parse-colon-path path@tindex parse-colon-pathThis function takes a search path string such as would be the value ofthe @code{PATH} environment variable, and splits it at the separators,returning a list of directory names. @code{nil} in this list stands for``use the current directory.'' Although the function's name says``colon,'' it actually uses the value of @code{path-separator}.@example(parse-colon-path ":/foo:/bar") @result{} (nil "/foo/" "/bar/")@end example@end defun@defvar invocation-nameThis variable holds the program name under which Emacs was invoked. Thevalue is a string, and does not include a directory name.@end defvar@defvar invocation-directoryThis variable holds the directory from which the Emacs executable wasinvoked, or perhaps @code{nil} if that directory cannot be determined.@end defvar@defvar installation-directoryIf non-@code{nil}, this is a directory within which to look for the@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}when Emacs can't find those directories in their standard installedlocations, but can find them in a directory related somehow to the onecontaining the Emacs executable.@end defvar@defun load-average &optional use-floatThis function returns the current 1-minute, 5-minute, and 15-minute loadaverages, in a list.By default, the values are integers that are 100 times the system loadaverages, which indicate the average number of processes trying to run.If @var{use-float} is non-@code{nil}, then they are returnedas floating point numbers and without multiplying by 100.If it is impossible to obtain the load average, this function signalsan error. On some platforms, access to load averages requiresinstalling Emacs as setuid or setgid so that it can read kernelinformation, and that usually isn't advisable.If the 1-minute load average is available, but the 5- or 15-minuteaverages are not, this function returns a shortened list containingthe available averages.@example@group(load-average) @result{} (169 48 36)@end group@group(load-average t) @result{} (1.69 0.48 0.36)@end group@grouplewis@@rocky[5] % uptime 11:55am up 1 day, 19:37, 3 users, load average: 1.69, 0.48, 0.36@end group@end example@end defun@defun emacs-pidThis function returns the process @acronym{ID} of the Emacs process,as an integer.@end defun@defvar tty-erase-charThis variable holds the erase character that was selectedin the system's terminal driver, before Emacs was started.The value is @code{nil} if Emacs is running under a window system.@end defvar@defun setprv privilege-name &optional setp getprvThis function sets or resets a VMS privilege. (It does not exist onother systems.) The first argument is the privilege name, as a string.The second argument, @var{setp}, is @code{t} or @code{nil}, indicatingwhether the privilege is to be turned on or off. Its default is@code{nil}. The function returns @code{t} if successful, @code{nil}otherwise.If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}does not change the privilege, but returns @code{t} or @code{nil}indicating whether the privilege is currently enabled.@end defun@node User Identification@section User Identification@defvar init-file-userThis variable says which user's init files should be used byEmacs---or @code{nil} if none. @code{""} stands for the user whooriginally logged in. The value reflects command-line options such as@samp{-q} or @samp{-u @var{user}}.Lisp packages that load files of customizations, or any other sort ofuser profile, should obey this variable in deciding where to find it.They should load the profile of the user name found in this variable.If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}option was used, then Lisp packages should not load any customizationfiles or user profile.@end defvar@defvar user-mail-addressThis holds the nominal email address of the user who is using Emacs.Emacs normally sets this variable to a default value after reading yourinit files, but not if you have already set it. So you can set thevariable to some other value in your init file if you do notwant to use the default value.@end defvar@defun user-login-name &optional uidIf you don't specify @var{uid}, this function returns the name underwhich the user is logged in. If the environment variable @code{LOGNAME}is set, that value is used. Otherwise, if the environment variable@code{USER} is set, that value is used. Otherwise, the value is basedon the effective @acronym{UID}, not the real @acronym{UID}.If you specify @var{uid}, the value is the user name that correspondsto @var{uid} (which should be an integer), or @code{nil} if there isno such user.@example@group(user-login-name) @result{} "lewis"@end group@end example@end defun@defun user-real-login-nameThis function returns the user name corresponding to Emacs's real@acronym{UID}. This ignores the effective @acronym{UID} and ignores theenvironment variables @code{LOGNAME} and @code{USER}.@end defun@defun user-full-name &optional uidThis function returns the full name of the logged-in user---or the valueof the environment variable @code{NAME}, if that is set.@c "Bil" is the correct spelling.@example@group(user-full-name) @result{} "Bil Lewis"@end group@end exampleIf the Emacs job's user-id does not correspond to any known user (andprovided @code{NAME} is not set), the value is @code{"unknown"}.If @var{uid} is non-@code{nil}, then it should be a number (a user-id)or a string (a login name). Then @code{user-full-name} returns the fullname corresponding to that user-id or login name. If you specify auser-id or login name that isn't defined, it returns @code{nil}.@end defun@vindex user-full-name@vindex user-real-login-name@vindex user-login-name The symbols @code{user-login-name}, @code{user-real-login-name} and@code{user-full-name} are variables as well as functions. The functionsreturn the same values that the variables hold. These variables allowyou to ``fake out'' Emacs by telling the functions what to return. Thevariables are also useful for constructing frame titles (@pxref{FrameTitles}).@defun user-real-uidThis function returns the real @acronym{UID} of the user.The value may be a floating point number.@example@group(user-real-uid) @result{} 19@end group@end example@end defun@defun user-uidThis function returns the effective @acronym{UID} of the user.The value may be a floating point number.@end defun@node Time of Day@section Time of Day This section explains how to determine the current time and the timezone.@defun current-time-string &optional time-valueThis function returns the current time and date as a human-readablestring. The format of the string is unvarying; the number of charactersused for each part is always the same, so you can reliably use@code{substring} to extract pieces of it. It is wise to count thecharacters from the beginning of the string rather than from the end, asadditional information may some day be added at the end.@c Emacs 19 featureThe argument @var{time-value}, if given, specifies a time to formatinstead of the current time. The argument should be a list whose firsttwo elements are integers. Thus, you can use times obtained from@code{current-time} (see below) and from @code{file-attributes}(@pxref{Definition of file-attributes}). @var{time-value} can also bea cons of two integers, but this is considered obsolete.@example@group(current-time-string) @result{} "Wed Oct 14 22:21:05 1987"@end group@end example@end defun@c Emacs 19 feature@defun current-timeThis function returns the system's time value as a list of threeintegers: @code{(@var{high} @var{low} @var{microsec})}. The integers@var{high} and @var{low} combine to give the number of seconds since0:00 January 1, 1970 UTC (Coordinated Universal Time), which is@ifnottex@var{high} * 2**16 + @var{low}.@end ifnottex@tex$high*2^{16}+low$.@end texThe third element, @var{microsec}, gives the microseconds since thestart of the current second (or 0 for systems that return time withthe resolution of only one second).The first two elements can be compared with file time values such as youget with the function @code{file-attributes}.@xref{Definition of file-attributes}.@end defun@c Emacs 19 feature@defun current-time-zone &optional time-valueThis function returns a list describing the time zone that the user isin.The value has the form @code{(@var{offset} @var{name})}. Here@var{offset} is an integer giving the number of seconds ahead of UTC(east of Greenwich). A negative value means west of Greenwich. Thesecond element, @var{name}, is a string giving the name of the timezone. Both elements change when daylight savings time begins or ends;if the user has specified a time zone that does not use a seasonal timeadjustment, then the value is constant through time.If the operating system doesn't supply all the information necessary tocompute the value, the unknown elements of the list are @code{nil}.The argument @var{time-value}, if given, specifies a time to analyzeinstead of the current time. The argument should have the same formas for @code{current-time-string} (see above). Thus, you can usetimes obtained from @code{current-time} (see above) and from@code{file-attributes}. @xref{Definition of file-attributes}.@end defun@defun set-time-zone-rule tzThis function specifies the local time zone according to @var{tz}. If@var{tz} is @code{nil}, that means to use an implementation-defineddefault time zone. If @var{tz} is @code{t}, that means to useUniversal Time. Otherwise, @var{tz} should be a string specifying atime zone rule.@end defun@defun float-time &optional time-valueThis function returns the current time as a floating-point number ofseconds since the epoch. The argument @var{time-value}, if given,specifies a time to convert instead of the current time. The argumentshould have the same form as for @code{current-time-string} (seeabove). Thus, it accepts the output of @code{current-time} and@code{file-attributes}.@emph{Warning}: Since the result is floating point, it may not beexact. Do not use this function if precise time stamps are required.@end defun@node Time Conversion@section Time Conversion These functions convert time values (lists of two or three integers)to calendrical information and vice versa. You can get time valuesfrom the functions @code{current-time} (@pxref{Time of Day}) and@code{file-attributes} (@pxref{Definition of file-attributes}). Many operating systems are limited to time values that contain 32 bitsof information; these systems typically handle only the times from1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, someoperating systems have larger time values, and can represent times farin the past or future. Time conversion functions always use the Gregorian calendar, evenfor dates before the Gregorian calendar was introduced. Year numberscount the number of years since the year 1 B.C., and do not skip zeroas traditional Gregorian years do; for example, the year number@minus{}37 represents the Gregorian year 38 B.C@.@defun decode-time &optional timeThis function converts a time value into calendrical information. Ifyou don't specify @var{time}, it decodes the current time. The returnvalue is a list of nine elements, as follows:@example(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})@end exampleHere is what the elements mean:@table @var@item secondsThe number of seconds past the minute, as an integer between 0 and 59.On some operating systems, this is 60 for leap seconds.@item minutesThe number of minutes past the hour, as an integer between 0 and 59.@item hourThe hour of the day, as an integer between 0 and 23.@item dayThe day of the month, as an integer between 1 and 31.@item monthThe month of the year, as an integer between 1 and 12.@item yearThe year, an integer typically greater than 1900.@item dowThe day of week, as an integer between 0 and 6, where 0 stands forSunday.@item dst@code{t} if daylight savings time is effect, otherwise @code{nil}.@item zoneAn integer indicating the time zone, as the number of seconds east ofGreenwich.@end table@strong{Common Lisp Note:} Common Lisp has different meanings for@var{dow} and @var{zone}.@end defun@defun encode-time seconds minutes hour day month year &optional zoneThis function is the inverse of @code{decode-time}. It converts sevenitems of calendrical data into a time value. For the meanings of thearguments, see the table above under @code{decode-time}.Year numbers less than 100 are not treated specially. If you want themto stand for years above 1900, or years above 2000, you must alter themyourself before you call @code{encode-time}.The optional argument @var{zone} defaults to the current time zone andits daylight savings time rules. If specified, it can be either a list(as you would get from @code{current-time-zone}), a string as in the@code{TZ} environment variable, @code{t} for Universal Time, or aninteger (as you would get from @code{decode-time}). The specifiedzone is used without any further alteration for daylight savings time.If you pass more than seven arguments to @code{encode-time}, the firstsix are used as @var{seconds} through @var{year}, the last argument isused as @var{zone}, and the arguments in between are ignored. Thisfeature makes it possible to use the elements of a list returned by@code{decode-time} as the arguments to @code{encode-time}, like this:@example(apply 'encode-time (decode-time @dots{}))@end exampleYou can perform simple date arithmetic by using out-of-range values forthe @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}arguments; for example, day 0 means the day preceding the given month.The operating system puts limits on the range of possible time values;if you try to encode a time that is out of range, an error results.For instance, years before 1970 do not work on some systems;on others, years as early as 1901 do work.@end defun@node Time Parsing@section Parsing and Formatting Times These functions convert time values (lists of two or three integers)to text in a string, and vice versa.@defun date-to-time stringThis function parses the time-string @var{string} and returns thecorresponding time value.@end defun@defun format-time-string format-string &optional time universalThis function converts @var{time} (or the current time, if @var{time} isomitted) to a string according to @var{format-string}. The argument@var{format-string} may contain @samp{%}-sequences which say tosubstitute parts of the time. Here is a table of what the@samp{%}-sequences mean:@table @samp@item %aThis stands for the abbreviated name of the day of week.@item %AThis stands for the full name of the day of week.@item %bThis stands for the abbreviated name of the month.@item %BThis stands for the full name of the month.@item %cThis is a synonym for @samp{%x %X}.@item %CThis has a locale-specific meaning. In the default locale (named C), itis equivalent to @samp{%A, %B %e, %Y}.@item %dThis stands for the day of month, zero-padded.@item %DThis is a synonym for @samp{%m/%d/%y}.@item %eThis stands for the day of month, blank-padded.@item %hThis is a synonym for @samp{%b}.@item %HThis stands for the hour (00-23).@item %IThis stands for the hour (01-12).@item %jThis stands for the day of the year (001-366).@item %kThis stands for the hour (0-23), blank padded.@item %lThis stands for the hour (1-12), blank padded.@item %mThis stands for the month (01-12).@item %MThis stands for the minute (00-59).@item %nThis stands for a newline.@item %pThis stands for @samp{AM} or @samp{PM}, as appropriate.@item %rThis is a synonym for @samp{%I:%M:%S %p}.@item %RThis is a synonym for @samp{%H:%M}.@item %SThis stands for the seconds (00-59).@item %tThis stands for a tab character.@item %TThis is a synonym for @samp{%H:%M:%S}.@item %UThis stands for the week of the year (01-52), assuming that weeksstart on Sunday.@item %wThis stands for the numeric day of week (0-6). Sunday is day 0.@item %WThis stands for the week of the year (01-52), assuming that weeksstart on Monday.@item %xThis has a locale-specific meaning. In the default locale (named@samp{C}), it is equivalent to @samp{%D}.@item %XThis has a locale-specific meaning. In the default locale (named@samp{C}), it is equivalent to @samp{%T}.@item %yThis stands for the year without century (00-99).@item %YThis stands for the year with century.@item %ZThis stands for the time zone abbreviation.@end tableYou can also specify the field width and type of padding for any ofthese @samp{%}-sequences. This works as in @code{printf}: you writethe field width as digits in the middle of a @samp{%}-sequences. If youstart the field width with @samp{0}, it means to pad with zeros. If youstart the field width with @samp{_}, it means to pad with spaces.For example, @samp{%S} specifies the number of seconds since the minute;@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} topad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,because that is how @samp{%S} normally pads to two positions.The characters @samp{E} and @samp{O} act as modifiers when used between@samp{%} and one of the letters in the table above. @samp{E} specifiesusing the current locale's ``alternative'' version of the date and time.In a Japanese locale, for example, @code{%Ex} might yield a date formatbased on the Japanese Emperors' reigns. @samp{E} is allowed in@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and@samp{%EY}.@samp{O} means to use the current locale's ``alternative''representation of numbers, instead of the ordinary decimal digits. Thisis allowed with most letters, all the ones that output numbers.If @var{universal} is non-@code{nil}, that means to describe the time asUniversal Time; @code{nil} means describe it using what Emacs believesis the local time zone (see @code{current-time-zone}).This function uses the C library function @code{strftime} to do most ofthe work. In order to communicate with that function, it first encodesits argument using the coding system specified by@code{locale-coding-system} (@pxref{Locales}); after @code{strftime}returns the resulting string, @code{format-time-string} decodes thestring using that same coding system.@end defun@defun seconds-to-time secondsThis function converts @var{seconds}, a floating point number ofseconds since the epoch, to a time value and returns that. To performthe inverse conversion, use @code{float-time}.@end defun@node Processor Run Time@section Processor Run time@defun get-internal-run-timeThis function returns the processor run time used by Emacs as a listof three integers: @code{(@var{high} @var{low} @var{microsec})}. Theintegers @var{high} and @var{low} combine to give the number ofseconds, which is@ifnottex@var{high} * 2**16 + @var{low}.@end ifnottex@tex$high*2^{16}+low$.@end texThe third element, @var{microsec}, gives the microseconds (or 0 forsystems that return time with the resolution of only one second).If the system doesn't provide a way to determine the processor runtime, get-internal-run-time returns the same time as current-time.@end defun@node Time Calculations@section Time Calculations These functions perform calendrical computations using time values(the kind of list that @code{current-time} returns).@defun time-less-p t1 t2This returns @code{t} if time value @var{t1} is less than time value@var{t2}.@end defun@defun time-subtract t1 t2This returns the time difference @var{t1} @minus{} @var{t2} betweentwo time values, in the same format as a time value.@end defun@defun time-add t1 t2This returns the sum of two time values, one of which ought torepresent a time difference rather than a point in time.Here is how to add a number of seconds to a time value:@example(time-add @var{time} (seconds-to-time @var{seconds}))@end example@end defun@defun time-to-days timeThis function returns the number of days between the beginning of year1 and @var{time}.@end defun@defun time-to-day-in-year timeThis returns the day number within the year corresponding to @var{time}.@end defun@defun date-leap-year-p yearThis function returns @code{t} if @var{year} is a leap year.@end defun@node Timers@section Timers for Delayed Execution@cindex timer You can set up a @dfn{timer} to call a function at a specifiedfuture time or after a certain length of idleness. Emacs cannot run timers at any arbitrary point in a Lisp program; itcan run them only when Emacs could accept output from a subprocess:namely, while waiting or inside certain primitive functions such as@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, atimer's execution may be delayed if Emacs is busy. However, the time ofexecution is very precise if Emacs is idle. Emacs binds @code{inhibit-quit} to @code{t} before calling the timerfunction, because quitting out of many timer functions can leavethings in an inconsistent state. This is normally unproblematicalbecause most timer functions don't do a lot of work. Indeed, for atimer to call a function that takes substantial time to run is likelyto be annoying. It is usually a bad idea for timer functions to alter buffercontents. When they do, they usually should call @code{undo-boundary}both before and after changing the buffer, to separate the timer'schanges from user commands' changes and prevent a single undo entryfrom growing to be quite large. If a timer function calls functions that can change the match data,it should save and restore the match data. @xref{Saving Match Data}.@deffn Command run-at-time time repeat function &rest argsThis sets up a timer that calls the function @var{function} witharguments @var{args} at time @var{time}. If @var{repeat} is a number(integer or floating point), the timer also runs every @var{repeat}seconds after that. If @var{repeat} is @code{nil}, the timer runsonly once.@var{time} may specify an absolute or a relative time.Absolute times may be specified in a wide variety of formats; thisfunction tries to accept all the commonly used date formats. The mostconvenient formats are strings. Valid such formats include these two,@example@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}@end example@noindentwhere in both examples all fields are numbers; the format that@code{current-time-string} returns is also allowed, and many othersas well.To specify a relative time as a string, use numbers followed by units.For example:@table @samp@item 1 mindenotes 1 minute from now.@item 1 min 5 secdenotes 65 seconds from now.@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 yeardenotes exactly 103 months, 123 days, and 10862 seconds from now.@end tableFor relative time values, Emacs considers a month to be exactly thirtydays, and a year to be exactly 365.25 days.Not all convenient formats are strings. If @var{time} is a number(integer or floating point), that specifies a relative time measuredin seconds.In most cases, @var{repeat} has no effect on when @emph{first} calltakes place---@var{time} alone specifies that. There is one exception:if @var{time} is @code{t}, then the timer runs whenever the time is amultiple of @var{repeat} seconds after the epoch. This is useful forfunctions like @code{display-time}.The function @code{run-at-time} returns a timer value that identifiesthe particular scheduled future action. You can use this value to call@code{cancel-timer} (see below).@end deffn@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}Execute @var{body}, but give up after @var{seconds} seconds. If@var{body} finishes before the time is up, @code{with-timeout} returnsthe value of the last form in @var{body}. If, however, the execution of@var{body} is cut short by the timeout, then @code{with-timeout}executes all the @var{timeout-forms} and returns the value of the lastof them.This macro works by setting a timer to run after @var{seconds} seconds. If@var{body} finishes before that time, it cancels the timer. If thetimer actually runs, it terminates execution of @var{body}, thenexecutes @var{timeout-forms}.Since timers can run within a Lisp program only when the program calls aprimitive that can wait, @code{with-timeout} cannot stop executing@var{body} while it is in the midst of a computation---only when itcalls one of those primitives. So use @code{with-timeout} only with a@var{body} that waits for input, not one that does a long computation.@end defmac The function @code{y-or-n-p-with-timeout} provides a simple way to usea timer to avoid waiting too long for an answer. @xref{Yes-or-NoQueries}.@deffn Command run-with-idle-timer secs repeat function &rest argsSet up a timer which runs when Emacs has been idle for @var{secs}seconds. The value of @var{secs} may be an integer or a floating pointnumber.If @var{repeat} is @code{nil}, the timer runs just once, the first timeEmacs remains idle for a long enough time. More often @var{repeat} isnon-@code{nil}, which means to run the timer @emph{each time} Emacsremains idle for @var{secs} seconds.The function @code{run-with-idle-timer} returns a timer value which youcan use in calling @code{cancel-timer} (see below).@end deffn@cindex idleness Emacs becomes ``idle'' when it starts waiting for user input, and itremains idle until the user provides some input. If a timer is set forfive seconds of idleness, it runs approximately five seconds after Emacsfirst becomes idle. Even if @var{repeat} is non-@code{nil}, this timerwill not run again as long as Emacs remains idle, because the durationof idleness will continue to increase and will not go down to fiveseconds again. Emacs can do various things while idle: garbage collect, autosave orhandle data from a subprocess. But these interludes during idleness donot interfere with idle timers, because they do not reset the clock ofidleness to zero. An idle timer set for 600 seconds will run when tenminutes have elapsed since the last user command was finished, even ifsubprocess output has been accepted thousands of times within those tenminutes, and even if there have been garbage collections and autosaves. When the user supplies input, Emacs becomes non-idle while executing theinput. Then it becomes idle again, and all the idle timers that areset up to repeat will subsequently run another time, one by one.@defun cancel-timer timerCancel the requested action for @var{timer}, which should be a valuepreviously returned by @code{run-at-time} or @code{run-with-idle-timer}.This cancels the effect of that call to one of these functions; thearrival of the specified time will not cause anything special to happen.@end defun@node Terminal Input@section Terminal Input@cindex terminal input This section describes functions and variables for recording ormanipulating terminal input. See @ref{Display}, for relatedfunctions.@menu* Input Modes:: Options for how input is processed.* Translating Input:: Low level conversion of some characters or events into others.* Recording Input:: Saving histories of recent or all input events.@end menu@node Input Modes@subsection Input Modes@cindex input modes@cindex terminal input modes@defun set-input-mode interrupt flow meta &optional quit-charThis function sets the mode for reading keyboard input. If@var{interrupt} is non-null, then Emacs uses input interrupts. If it is@code{nil}, then it uses @sc{cbreak} mode. The default setting issystem-dependent. Some systems always use @sc{cbreak} mode regardlessof what is specified.When Emacs communicates directly with X, it ignores this argument anduses interrupts if that is the way it knows how to communicate.If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. Thishas no effect except in @sc{cbreak} mode.@c Emacs 19 featureThe argument @var{meta} controls support for input character codesabove 127. If @var{meta} is @code{t}, Emacs converts characters withthe 8th bit set into Meta characters. If @var{meta} is @code{nil},Emacs disregards the 8th bit; this is necessary when the terminal usesit as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},Emacs uses all 8 bits of input unchanged. This is good for terminalsthat use 8-bit character sets.@c Emacs 19 featureIf @var{quit-char} is non-@code{nil}, it specifies the character touse for quitting. Normally this character is @kbd{C-g}.@xref{Quitting}.@end defunThe @code{current-input-mode} function returns the input mode settingsEmacs is currently using.@c Emacs 19 feature@defun current-input-modeThis function returns the current mode for reading keyboard input. Itreturns a list, corresponding to the arguments of @code{set-input-mode},of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} inwhich:@table @var@item interruptis non-@code{nil} when Emacs is using interrupt-driven input. If@code{nil}, Emacs is using @sc{cbreak} mode.@item flowis non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})flow control for output to the terminal. This value is meaningful onlywhen @var{interrupt} is @code{nil}.@item metais @code{t} if Emacs treats the eighth bit of input characters asthe meta bit; @code{nil} means Emacs clears the eighth bit of everyinput character; any other value means Emacs uses all eight bits as thebasic character code.@item quitis the character Emacs currently uses for quitting, usually @kbd{C-g}.@end table@end defun@node Translating Input@subsection Translating Input Events@cindex translating input events This section describes features for translating input events intoother input events before they become part of key sequences. Thesefeatures apply to each event in the order they are described here: eachevent is first modified according to @code{extra-keyboard-modifiers},then translated through @code{keyboard-translate-table} (if applicable),and finally decoded with the specified keyboard coding system. If it isbeing read as part of a key sequence, it is then added to the sequencebeing read; then subsequences containing it are checked first with@code{function-key-map} and then with @code{key-translation-map}.@c Emacs 19 feature@defvar extra-keyboard-modifiersThis variable lets Lisp programs ``press'' the modifier keys on thekeyboard. The value is a character. Only the modifiers of thecharacter matter. Each time the user types a keyboard key, it isaltered as if those modifier keys were held down. For instance, ifyou bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then allkeyboard input characters typed during the scope of the binding willhave the control and meta modifiers applied to them. The character@code{?\C-@@}, equivalent to the integer 0, does not count as a controlcharacter for this purpose, but as a character with no modifiers.Thus, setting @code{extra-keyboard-modifiers} to zero cancels anymodification.When using a window system, the program can ``press'' any of themodifier keys in this way. Otherwise, only the @key{CTL} and @key{META}keys can be virtually pressed.Note that this variable applies only to events that really come fromthe keyboard, and has no effect on mouse events or any other events.@end defvar@defvar keyboard-translate-tableThis variable is the translate table for keyboard characters. It letsyou reshuffle the keys on the keyboard without changing any commandbindings. Its value is normally a char-table, or else @code{nil}.(It can also be a string or vector, but this is considered obsolete.)If @code{keyboard-translate-table} is a char-table(@pxref{Char-Tables}), then each character read from the keyboard islooked up in this char-table. If the value found there isnon-@code{nil}, then it is used instead of the actual input character.Note that this translation is the first thing that happens to acharacter after it is read from the terminal. Record-keeping featuressuch as @code{recent-keys} and dribble files record the characters aftertranslation.Note also that this translation is done before the characters aresupplied to input methods (@pxref{Input Methods}). Use@code{translation-table-for-input} (@pxref{Translation of Characters}),if you want to translate characters after input methods operate.@end defvar@defun keyboard-translate from toThis function modifies @code{keyboard-translate-table} to translatecharacter code @var{from} into character code @var{to}. It createsthe keyboard translate table if necessary.@end defun Here's an example of using the @code{keyboard-translate-table} tomake @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and pasteoperations:@example(keyboard-translate ?\C-x 'control-x)(keyboard-translate ?\C-c 'control-c)(keyboard-translate ?\C-v 'control-v)(global-set-key [control-x] 'kill-region)(global-set-key [control-c] 'kill-ring-save)(global-set-key [control-v] 'yank)@end example@noindentOn a graphical terminal that supports extended @acronym{ASCII} input,you can still get the standard Emacs meanings of one of thosecharacters by typing it with the shift key. That makes it a differentcharacter as far as keyboard translation is concerned, but it has thesame usual meaning. The remaining translation features translate subsequences of keysequences being read. They are implemented in @code{read-key-sequence}and have no effect on input read with @code{read-event}.@defvar function-key-mapThis variable holds a keymap that describes the character sequences sentby function keys on an ordinary character terminal. This keymap has thesame structure as other keymaps, but is used differently: it specifiestranslations to make while reading key sequences, rather than bindingsfor key sequences.If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in akey sequence, it is replaced with the events in @var{v}.For example, VT100 terminals send @kbd{@key{ESC} O P} when thekeypad @key{PF1} key is pressed. Therefore, we want Emacs to translatethat sequence of events into the single event @code{pf1}. We accomplishthis by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in@code{function-key-map}, when using a VT100.Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c@key{ESC} O P}; later the function @code{read-key-sequence} translatesthis back into @kbd{C-c @key{PF1}}, which it returns as the vector@code{[?\C-c pf1]}.Entries in @code{function-key-map} are ignored if they conflict withbindings made in the minor mode, local, or global keymaps. The intentis that the character sequences that function keys send should not havecommand bindings in their own right---but if they do, the ordinarybindings take priority.The value of @code{function-key-map} is usually set up automaticallyaccording to the terminal's Terminfo or Termcap entry, but sometimesthose need help from terminal-specific Lisp files. Emacs comes withterminal-specific files for many common terminals; their main purpose isto make entries in @code{function-key-map} beyond those that can bededuced from Termcap and Terminfo. @xref{Terminal-Specific}.@end defvar@defvar key-translation-mapThis variable is another keymap used just like @code{function-key-map}to translate input events into other events. It differs from@code{function-key-map} in two ways:@itemize @bullet@item@code{key-translation-map} goes to work after @code{function-key-map} isfinished; it receives the results of translation by@code{function-key-map}.@itemNon-prefix bindings in @code{key-translation-map} override actual keybindings. For example, if @kbd{C-x f} has a non-prefix binding in@code{key-translation-map}, that translation takes effect even though@kbd{C-x f} also has a key binding in the global map.@end itemizeNote however that actual key bindings can have an effect on@code{key-translation-map}, even though they are overridden by it.Indeed, actual key bindings override @code{function-key-map} and thusmay alter the key sequence that @code{key-translation-map} receives.Clearly, it is better to avoid this type of situation.The intent of @code{key-translation-map} is for users to map onecharacter set to another, including ordinary characters normally boundto @code{self-insert-command}.@end defvar@cindex key translation functionYou can use @code{function-key-map} or @code{key-translation-map} formore than simple aliases, by using a function, instead of a keysequence, as the ``translation'' of a key. Then this function is calledto compute the translation of that key.The key translation function receives one argument, which is the promptthat was specified in @code{read-key-sequence}---or @code{nil} if thekey sequence is being read by the editor command loop. In most casesyou can ignore the prompt value.If the function reads input itself, it can have the effect of alteringthe event that follows. For example, here's how to define @kbd{C-c h}to turn the character that follows into a Hyper character:@example@group(defun hyperify (prompt) (let ((e (read-event))) (vector (if (numberp e) (logior (lsh 1 24) e) (if (memq 'hyper (event-modifiers e)) e (add-event-modifier "H-" e))))))(defun add-event-modifier (string e) (let ((symbol (if (symbolp e) e (car e)))) (setq symbol (intern (concat string (symbol-name symbol))))@end group@group (if (symbolp e) symbol (cons symbol (cdr e)))))(define-key function-key-map "\C-ch" 'hyperify)@end group@end exampleFinally, if you have enabled keyboard character set decoding using@code{set-keyboard-coding-system}, decoding is done after thetranslations listed above. @xref{Terminal I/O Encoding}. In futureEmacs versions, character set decoding may be done before the othertranslations.@node Recording Input@subsection Recording Input@defun recent-keysThis function returns a vector containing the last 100 input events fromthe keyboard or mouse. All input events are included, whether or notthey were used as parts of key sequences. Thus, you always get the last100 input events, not counting events generated by keyboard macros.(These are excluded because they are less interesting for debugging; itshould be enough to see the events that invoked the macros.)A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})causes this function to return an empty vector immediately afterward.@end defun@deffn Command open-dribble-file filename@cindex dribble fileThis function opens a @dfn{dribble file} named @var{filename}. When adribble file is open, each input event from the keyboard or mouse (butnot those from keyboard macros) is written in that file. Anon-character event is expressed using its printed representationsurrounded by @samp{<@dots{}>}.You close the dribble file by calling this function with an argumentof @code{nil}.This function is normally used to record the input necessary totrigger an Emacs bug, for the sake of a bug report.@example@group(open-dribble-file "~/dribble") @result{} nil@end group@end example@end deffn See also the @code{open-termscript} function (@pxref{Terminal Output}).@node Terminal Output@section Terminal Output@cindex terminal output The terminal output functions send output to a text terminal, or keeptrack of output sent to the terminal. The variable @code{baud-rate}tells you what Emacs thinks is the output speed of the terminal.@defvar baud-rateThis variable's value is the output speed of the terminal, as far asEmacs knows. Setting this variable does not change the speed of actualdata transmission, but the value is used for calculations such aspadding. It also affects decisions about whether to scroll part of thescreen or repaint---even when using a window system. (We designed itthis way despite the fact that a window system has no true ``outputspeed'', to give you a way to tune these decisions.)The value is measured in baud.@end defvar If you are running across a network, and different parts of thenetwork work at different baud rates, the value returned by Emacs may bedifferent from the value used by your local terminal. Some networkprotocols communicate the local terminal speed to the remote machine, sothat Emacs and other programs can get the proper value, but others donot. If Emacs has the wrong value, it makes decisions that are lessthan optimal. To fix the problem, set @code{baud-rate}.@defun baud-rateThis obsolete function returns the value of the variable@code{baud-rate}.@end defun@defun send-string-to-terminal stringThis function sends @var{string} to the terminal without alteration.Control characters in @var{string} have terminal-dependent effects.This function operates only on text terminals.One use of this function is to define function keys on terminals thathave downloadable function key definitions. For example, this is how (oncertain terminals) to define function key 4 to move forward fourcharacters (by transmitting the characters @kbd{C-u C-f} to thecomputer):@example@group(send-string-to-terminal "\eF4\^U\^F") @result{} nil@end group@end example@end defun@deffn Command open-termscript filename@cindex termscript fileThis function is used to open a @dfn{termscript file} that will recordall the characters sent by Emacs to the terminal. It returns@code{nil}. Termscript files are useful for investigating problemswhere Emacs garbles the screen, problems that are due to incorrectTermcap entries or to undesirable settings of terminal options moreoften than to actual Emacs bugs. Once you are certain which characterswere actually output, you can determine reliably whether they correspondto the Termcap specifications in use.You close the termscript file by calling this function with anargument of @code{nil}.See also @code{open-dribble-file} in @ref{Recording Input}.@example@group(open-termscript "../junk/termscript") @result{} nil@end group@end example@end deffn@node Sound Output@section Sound Output@cindex sound To play sound using Emacs, use the function @code{play-sound}. Onlycertain systems are supported; if you call @code{play-sound} on a systemwhich cannot really do the job, it gives an error. Emacs version 20 andearlier did not support sound at all. The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})or Sun Audio format (@samp{.au}).@tindex play-sound@defun play-sound soundThis function plays a specified sound. The argument, @var{sound}, hasthe form @code{(sound @var{properties}...)}, where the @var{properties}consist of alternating keywords (particular symbols recognizedspecially) and values corresponding to them.Here is a table of the keywords that are currently meaningful in@var{sound}, and their meanings:@table @code@item :file @var{file}This specifies the file containing the sound to play.If the file name is not absolute, it is expanded againstthe directory @code{data-directory}.@item :data @var{data}This specifies the sound to play without need to refer to a file. Thevalue, @var{data}, should be a string containing the same bytes as asound file. We recommend using a unibyte string.@item :volume @var{volume}This specifies how loud to play the sound. It should be a number in therange of 0 to 1. The default is to use whatever volume has beenspecified before.@item :device @var{device}This specifies the system device on which to play the sound, as astring. The default device is system-dependent.@end tableBefore actually playing the sound, @code{play-sound}calls the functions in the list @code{play-sound-functions}.Each function is called with one argument, @var{sound}.@end defun@defun play-sound-file file &optional volume device@tindex play-sound-fileThis function is an alternative interface to playing a sound @var{file}specifying an optional @var{volume} and @var{device}.@end defun@tindex play-sound-functions@defvar play-sound-functionsA list of functions to be called before playing a sound. Each functionis called with one argument, a property list that describes the sound.@end defvar@node X11 Keysyms@section Operating on X11 KeysymsTo define system-specific X11 keysyms, set the variable@code{system-key-alist}.@defvar system-key-alistThis variable's value should be an alist with one element for eachsystem-specific keysym. Each element has the form @code{(@var{code}. @var{symbol})}, where @var{code} is the numeric keysym code (notincluding the ``vendor specific'' bit,@ifnottex-2**28),@end ifnottex@tex$-2^{28}$),@end texand @var{symbol} is the name for the function key.For example @code{(168 . mute-acute)} defines a system-specific key (usedby HP X servers) whose numeric code is@ifnottex-2**28@end ifnottex@tex$-2^{28}$@end tex+ 168.It is not crucial to exclude from the alist the keysyms of other Xservers; those do no harm, as long as they don't conflict with the onesused by the X server actually in use.The variable is always local to the current terminal, and cannot bebuffer-local. @xref{Multiple Displays}.@end defvarYou can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:@defvar x-alt-keysym@defvarx x-meta-keysym@defvarx x-hyper-keysym@defvarx x-super-keysymThe name of the keysym that should stand for the Alt modifier(respectively, for Meta, Hyper, and Super). For example, here ishow to swap the Meta and Alt modifiers within Emacs:@lisp(setq x-alt-keysym 'meta)(setq x-meta-keysym 'alt)@end lisp@end defvar@node Batch Mode@section Batch Mode@cindex batch mode@cindex noninteractive use The command-line option @samp{-batch} causes Emacs to runnoninteractively. In this mode, Emacs does not read commands from theterminal, it does not alter the terminal modes, and it does not expectto be outputting to an erasable screen. The idea is that you specifyLisp programs to run; when they are finished, Emacs should exit. Theway to specify the programs to run is with @samp{-l @var{file}}, whichloads the library named @var{file}, or @samp{-f @var{function}}, whichcalls @var{function} with no arguments, or @samp{--eval @var{form}}. Any Lisp program output that would normally go to the echo area,either using @code{message}, or using @code{prin1}, etc., with @code{t}as the stream, goes instead to Emacs's standard error descriptor whenin batch mode. Similarly, input that would normally come from theminibuffer is read from the standard input descriptor.Thus, Emacs behaves much like a noninteractiveapplication program. (The echo area output that Emacs itself normallygenerates, such as command echoing, is suppressed entirely.)@defvar noninteractiveThis variable is non-@code{nil} when Emacs is running in batch mode.@end defvar@node Session Management@section Session Management@cindex session managerEmacs supports the X Session Management Protocol for suspension andrestart of applications. In the X Window System, a program called the@dfn{session manager} has the responsibility to keep track of theapplications that are running. During shutdown, the session managerasks applications to save their state, and delays the actual shutdownuntil they respond. An application can also cancel the shutdown.When the session manager restarts a suspended session, it directsthese applications to individually reload their saved state. It doesthis by specifying a special command-line argument that says whatsaved session to restore. For Emacs, this argument is @samp{--smid@var{session}}.@defvar emacs-save-session-functions@tindex emacs-save-session-functionsEmacs supports saving state by using a hook called@code{emacs-save-session-functions}. Each function in this hook iscalled when the session manager tells Emacs that the window system isshutting down. The functions are called with no arguments and with thecurrent buffer set to a temporary buffer. Each function can use@code{insert} to add Lisp code to this buffer. At the end, Emacssaves the buffer in a file that a subsequent Emacs invocation willload in order to restart the saved session.If a function in @code{emacs-save-session-functions} returnsnon-@code{nil}, Emacs tells the session manager to cancel theshutdown.@end defvarHere is an example that just inserts some text into @samp{*scratch*} whenEmacs is restarted by the session manager.@example@group(add-hook 'emacs-save-session-functions 'save-yourself-test)@end group@group(defun save-yourself-test () (insert "(save-excursion (switch-to-buffer \"*scratch*\") (insert \"I am restored\"))") nil)@end group@end example@ignore arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7@end ignore