2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/os
7 @node System Interface, Antinews, Calendar, 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 a string, or
25 to calendrical data (or vice versa).
26 * Time Calculations:: Adding, subtracting, comparing times, etc.
27 * Timers:: Setting a timer to call a function at a certain time.
28 * Terminal Input:: Recording terminal input for debugging.
29 * Terminal Output:: Recording terminal output for debugging.
30 * Sound Output:: Playing sounds on the computer's speaker.
31 * X11 Keysyms:: Operating on key symbols for X Windows
32 * Flow Control:: How to turn output flow control on or off.
33 * Batch Mode:: Running Emacs without terminal interaction.
34 * Session Management:: Saving and restoring state with X Session Management.
38 @section Starting Up Emacs
40 This section describes what Emacs does when it is started, and how you
41 can customize these actions.
44 * Startup Summary:: Sequence of actions Emacs performs at startup.
45 * Init File:: Details on reading the init file (@file{.emacs}).
46 * Terminal-Specific:: How the terminal-specific Lisp file is read.
47 * Command-Line Arguments:: How command-line arguments are processed,
48 and how you can customize them.
52 @subsection Summary: Sequence of Actions at Startup
53 @cindex initialization
54 @cindex startup of Emacs
55 @cindex @file{startup.el}
57 The order of operations performed (in @file{startup.el}) by Emacs when
58 it is started up is as follows:
62 It adds subdirectories to @code{load-path}, by running the file named
63 @file{subdirs.el} in each directory in the list. Normally this file
64 adds the directory's subdirectories to the list, and these will be
65 scanned in their turn. The files @file{subdirs.el} are normally
66 generated automatically by Emacs installation.
69 It sets the language environment and the terminal coding system,
70 if requested by environment variables such as @code{LANG}.
73 It loads the initialization library for the window system, if you are
74 using a window system. This library's name is
75 @file{term/@var{windowsystem}-win.el}.
78 It processes the initial options. (Some of them are handled
79 even earlier than this.)
82 It initializes the window frame and faces, if appropriate.
85 It runs the normal hook @code{before-init-hook}.
88 It loads the library @file{site-start}, unless the option
89 @samp{-no-site-file} was specified. The library's file name is usually
91 @cindex @file{site-start.el}
94 It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
95 @samp{-no-init-file}, or @samp{-batch} was specified on the command line.
96 The @samp{-u} option can specify another user whose home directory
97 should be used instead of @file{~}.
100 It loads the library @file{default}, unless @code{inhibit-default-init}
101 is non-@code{nil}. (This is not done in @samp{-batch} mode or if
102 @samp{-q} was specified on the command line.) The library's file name
103 is usually @file{default.el}.
104 @cindex @file{default.el}
107 It runs the normal hook @code{after-init-hook}.
110 It sets the major mode according to @code{initial-major-mode}, provided
111 the buffer @samp{*scratch*} is still current and still in Fundamental
115 It loads the terminal-specific Lisp file, if any, except when in batch
116 mode or using a window system.
119 It displays the initial echo area message, unless you have suppressed
120 that with @code{inhibit-startup-echo-area-message}.
123 It processes the action arguments from the command line.
126 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
129 It calls @code{frame-notice-user-settings}, which modifies the
130 parameters of the selected frame according to whatever the init files
134 It runs @code{window-setup-hook}. @xref{Window Systems}.
137 It displays copyleft, nonwarranty, and basic use information, provided
138 there were no remaining command-line arguments (a few steps above),
139 the value of @code{inhibit-startup-message} is @code{nil}, and the
140 buffer is still empty.
143 @defopt inhibit-startup-message
144 This variable inhibits the initial startup messages (the nonwarranty,
145 etc.). If it is non-@code{nil}, then the messages are not printed.
147 This variable exists so you can set it in your personal init file, once
148 you are familiar with the contents of the startup message. Do not set
149 this variable in the init file of a new user, or in a way that affects
150 more than one user, because that would prevent new users from receiving
151 the information they are supposed to see.
154 @defopt inhibit-startup-echo-area-message
155 This variable controls the display of the startup echo area message.
156 You can suppress the startup echo area message by adding text with this
157 form to your init file:
160 (setq inhibit-startup-echo-area-message
161 "@var{your-login-name}")
164 Emacs explicitly checks for an expression as shown above in your init
165 file; your login name must appear in the expression as a Lisp string
166 constant. Other methods of setting
167 @code{inhibit-startup-echo-area-message} to the same value do not
168 inhibit the startup message.
170 This way, you can easily inhibit the message for yourself if you wish,
171 but thoughtless copying of your init file will not inhibit the message
176 @subsection The Init File, @file{.emacs}
178 @cindex @file{.emacs}
180 When you start Emacs, it normally attempts to load your @dfn{init
181 file}, a file in your home directory. Its normal name is @file{.emacs},
182 but you can alternatively call it @file{.emacs.el}, which enables you to
183 byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
184 will be @file{.emacs.elc}.
186 The command-line switches @samp{-q} and @samp{-u} control whether and
187 where to find the init file; @samp{-q} says not to load an init file,
188 and @samp{-u @var{user}} says to load @var{user}'s init file instead of
189 yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
190 neither option is specified, Emacs uses the @code{LOGNAME} environment
191 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
192 systems) variable, to find your home directory and thus your init file;
193 this way, even if you have su'd, Emacs still loads your own init file.
194 If those environment variables are absent, though, Emacs uses your
195 user-id to find your home directory.
197 @cindex default init file
198 A site may have a @dfn{default init file}, which is the library named
199 @file{default.el}. Emacs finds the @file{default.el} file through the
200 standard search path for libraries (@pxref{How Programs Do Loading}).
201 The Emacs distribution does not come with this file; sites may provide
202 one for local customizations. If the default init file exists, it is
203 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
204 specified. But your own personal init file, if any, is loaded first; if
205 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
206 Emacs does not subsequently load the @file{default.el} file.
208 Another file for site-customization is @file{site-start.el}. Emacs
209 loads this @emph{before} the user's init file. You can inhibit the
210 loading of this file with the option @samp{-no-site-file}.
212 @defvar site-run-file
213 This variable specifies the site-customization file to load before the
214 user's init file. Its normal value is @code{"site-start"}. The only
215 way you can change it with real effect is to do so before dumping
219 @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
220 examples of how to make various commonly desired customizations in your
223 @defopt inhibit-default-init
224 This variable prevents Emacs from loading the default initialization
225 library file for your session of Emacs. If its value is non-@code{nil},
226 then the default library is not loaded. The default value is
230 @defvar before-init-hook
231 This normal hook is run, once, just before loading all the init files
232 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
233 (The only way to change it with real effect is before dumping Emacs.)
236 @defvar after-init-hook
237 This normal hook is run, once, just after loading all the init files
238 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
239 before loading the terminal-specific library and processing the
240 command-line arguments.
243 @defvar emacs-startup-hook
244 @tindex emacs-startup-hook
245 This normal hook is run, once, just after handling the command line
246 arguments, just before @code{term-setup-hook}.
249 @defvar user-init-file
250 @tindex user-init-file
251 This variable holds the file name of the user's init file. If the
252 actual init file loaded is a compiled file, such as @file{.emacs.elc},
253 the value refers to the corresponding source file.
256 @node Terminal-Specific
257 @subsection Terminal-Specific Initialization
258 @cindex terminal-specific initialization
260 Each terminal type can have its own Lisp library that Emacs loads when
261 run on that type of terminal. The library's name is constructed by
262 concatenating the value of the variable @code{term-file-prefix} and the
263 terminal type (specified by the environment variable @code{TERM}).
264 Normally, @code{term-file-prefix} has the value
265 @code{"term/"}; changing this is not recommended. Emacs finds the file
266 in the normal manner, by searching the @code{load-path} directories, and
267 trying the @samp{.elc} and @samp{.el} suffixes.
269 The usual function of a terminal-specific library is to enable special
270 keys to send sequences that Emacs can recognize. It may also need to
271 set or add to @code{function-key-map} if the Termcap entry does not
272 specify all the terminal's function keys. @xref{Terminal Input}.
275 When the name of the terminal type contains a hyphen, only the part of
276 the name before the first hyphen is significant in choosing the library
277 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
278 the @file{term/aaa} library. If necessary, the library can evaluate
279 @code{(getenv "TERM")} to find the full name of the terminal
282 Your init file can prevent the loading of the
283 terminal-specific library by setting the variable
284 @code{term-file-prefix} to @code{nil}. This feature is useful when
285 experimenting with your own peculiar customizations.
287 You can also arrange to override some of the actions of the
288 terminal-specific library by setting the variable
289 @code{term-setup-hook}. This is a normal hook which Emacs runs using
290 @code{run-hooks} at the end of Emacs initialization, after loading both
291 your init file and any terminal-specific libraries. You can
292 use this variable to define initializations for terminals that do not
293 have their own libraries. @xref{Hooks}.
295 @defvar term-file-prefix
296 @cindex @code{TERM} environment variable
297 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
298 a terminal-specific initialization file as follows:
301 (load (concat term-file-prefix (getenv "TERM")))
305 You may set the @code{term-file-prefix} variable to @code{nil} in your
306 init file if you do not wish to load the
307 terminal-initialization file. To do this, put the following in
308 your init file: @code{(setq term-file-prefix nil)}.
310 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
311 uses @samp{internal} as the terminal type.
314 @defvar term-setup-hook
315 This variable is a normal hook that Emacs runs after loading your
316 init file, the default initialization file (if any) and the
317 terminal-specific Lisp file.
319 You can use @code{term-setup-hook} to override the definitions made by a
320 terminal-specific file.
323 See @code{window-setup-hook} in @ref{Window Systems}, for a related
326 @node Command-Line Arguments
327 @subsection Command-Line Arguments
328 @cindex command-line arguments
330 You can use command-line arguments to request various actions when you
331 start Emacs. Since you do not need to start Emacs more than once per
332 day, and will often leave your Emacs session running longer than that,
333 command-line arguments are hardly ever used. As a practical matter, it
334 is best to avoid making the habit of using them, since this habit would
335 encourage you to kill and restart Emacs unnecessarily often. These
336 options exist for two reasons: to be compatible with other editors (for
337 invocation by other programs) and to enable shell scripts to run
338 specific Lisp programs.
340 This section describes how Emacs processes command-line arguments,
341 and how you can customize them.
344 (Note that some other editors require you to start afresh each time
345 you want to edit a file. With this kind of editor, you will probably
346 specify the file as a command-line argument. The recommended way to
347 use GNU Emacs is to start it only once, just after you log in, and do
348 all your editing in the same Emacs process. Each time you want to edit
349 a different file, you visit it with the existing Emacs, which eventually
350 comes to have many files in it ready for editing. Usually you do not
351 kill the Emacs until you are about to log out.)
355 This function parses the command line that Emacs was called with,
356 processes it, loads the user's init file and displays the
360 @defvar command-line-processed
361 The value of this variable is @code{t} once the command line has been
364 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
365 this variable to @code{nil} first in order to cause the new dumped Emacs
366 to process its new command-line arguments.
369 @defvar command-switch-alist
370 @cindex switches on command line
371 @cindex options on command line
372 @cindex command-line options
373 The value of this variable is an alist of user-defined command-line
374 options and associated handler functions. This variable exists so you
375 can add elements to it.
377 A @dfn{command-line option} is an argument on the command line, which
384 The elements of the @code{command-switch-alist} look like this:
387 (@var{option} . @var{handler-function})
390 The @sc{car}, @var{option}, is a string, the name of a command-line
391 option (not including the initial hyphen). The @var{handler-function}
392 is called to handle @var{option}, and receives the option name as its
395 In some cases, the option is followed in the command line by an
396 argument. In these cases, the @var{handler-function} can find all the
397 remaining command-line arguments in the variable
398 @code{command-line-args-left}. (The entire list of command-line
399 arguments is in @code{command-line-args}.)
401 The command-line arguments are parsed by the @code{command-line-1}
402 function in the @file{startup.el} file. See also @ref{Command
403 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
407 @defvar command-line-args
408 The value of this variable is the list of command-line arguments passed
412 @defvar command-line-functions
413 This variable's value is a list of functions for handling an
414 unrecognized command-line argument. Each time the next argument to be
415 processed has no special meaning, the functions in this list are called,
416 in order of appearance, until one of them returns a non-@code{nil}
419 These functions are called with no arguments. They can access the
420 command-line argument under consideration through the variable
421 @code{argi}, which is bound temporarily at this point. The remaining
422 arguments (not including the current one) are in the variable
423 @code{command-line-args-left}.
425 When a function recognizes and processes the argument in @code{argi}, it
426 should return a non-@code{nil} value to say it has dealt with that
427 argument. If it has also dealt with some of the following arguments, it
428 can indicate that by deleting them from @code{command-line-args-left}.
430 If all of these functions return @code{nil}, then the argument is used
431 as a file name to visit.
435 @section Getting Out of Emacs
436 @cindex exiting Emacs
438 There are two ways to get out of Emacs: you can kill the Emacs job,
439 which exits permanently, or you can suspend it, which permits you to
440 reenter the Emacs process later. As a practical matter, you seldom kill
441 Emacs---only when you are about to log out. Suspending is much more
445 * Killing Emacs:: Exiting Emacs irreversibly.
446 * Suspending Emacs:: Exiting Emacs reversibly.
450 @comment node-name, next, previous, up
451 @subsection Killing Emacs
452 @cindex killing Emacs
454 Killing Emacs means ending the execution of the Emacs process. The
455 parent process normally resumes control. The low-level primitive for
456 killing Emacs is @code{kill-emacs}.
458 @defun kill-emacs &optional exit-data
459 This function exits the Emacs process and kills it.
461 If @var{exit-data} is an integer, then it is used as the exit status
462 of the Emacs process. (This is useful primarily in batch operation; see
465 If @var{exit-data} is a string, its contents are stuffed into the
466 terminal input buffer so that the shell (or whatever program next reads
467 input) can read them.
470 All the information in the Emacs process, aside from files that have
471 been saved, is lost when the Emacs process is killed. Because killing
472 Emacs inadvertently can lose a lot of work, Emacs queries for
473 confirmation before actually terminating if you have buffers that need
474 saving or subprocesses that are running. This is done in the function
475 @code{save-buffers-kill-emacs}.
477 @defvar kill-emacs-query-functions
478 After asking the standard questions, @code{save-buffers-kill-emacs}
479 calls the functions in the list @code{kill-emacs-query-functions}, in
480 order of appearance, with no arguments. These functions can ask for
481 additional confirmation from the user. If any of them returns
482 @code{nil}, Emacs is not killed.
485 @defvar kill-emacs-hook
486 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
487 finished with all file saving and confirmation, it runs the functions in
488 this hook. This hook is not run in batch mode.
491 @node Suspending Emacs
492 @subsection Suspending Emacs
493 @cindex suspending Emacs
495 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
496 control to its superior process, which is usually the shell. This
497 allows you to resume editing later in the same Emacs process, with the
498 same buffers, the same kill ring, the same undo history, and so on. To
499 resume Emacs, use the appropriate command in the parent shell---most
502 Some operating systems do not support suspension of jobs; on these
503 systems, ``suspension'' actually creates a new shell temporarily as a
504 subprocess of Emacs. Then you would exit the shell to return to Emacs.
506 Suspension is not useful with window systems, because the Emacs job
507 may not have a parent that can resume it again, and in any case you can
508 give input to some other job such as a shell merely by moving to a
509 different window. Therefore, suspending is not allowed when Emacs is using
510 a window system (X or MS Windows).
512 @defun suspend-emacs string
513 This function stops Emacs and returns control to the superior process.
514 If and when the superior process resumes Emacs, @code{suspend-emacs}
515 returns @code{nil} to its caller in Lisp.
517 If @var{string} is non-@code{nil}, its characters are sent to be read
518 as terminal input by Emacs's superior shell. The characters in
519 @var{string} are not echoed by the superior shell; only the results
522 Before suspending, @code{suspend-emacs} runs the normal hook
525 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
526 @code{suspend-resume-hook}. @xref{Hooks}.
528 The next redisplay after resumption will redraw the entire screen,
529 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
530 (@pxref{Refresh Screen}).
532 In the following example, note that @samp{pwd} is not echoed after
533 Emacs is suspended. But it is read and executed by the shell.
542 (add-hook 'suspend-hook
546 (error "Suspend cancelled")))))
547 @result{} (lambda nil
548 (or (y-or-n-p "Really suspend? ")
549 (error "Suspend cancelled")))
552 (add-hook 'suspend-resume-hook
553 (function (lambda () (message "Resumed!"))))
554 @result{} (lambda nil (message "Resumed!"))
557 (suspend-emacs "pwd")
561 ---------- Buffer: Minibuffer ----------
562 Really suspend? @kbd{y}
563 ---------- Buffer: Minibuffer ----------
567 ---------- Parent Shell ----------
568 lewis@@slug[23] % /user/lewis/manual
573 ---------- Echo Area ----------
580 This variable is a normal hook that Emacs runs before suspending.
583 @defvar suspend-resume-hook
584 This variable is a normal hook that Emacs runs on resuming
588 @node System Environment
589 @section Operating System Environment
590 @cindex operating system environment
592 Emacs provides access to variables in the operating system environment
593 through various functions. These variables include the name of the
594 system, the user's @sc{uid}, and so on.
596 @defvar system-configuration
597 This variable holds the GNU configuration name for the hardware/software
598 configuration of your system, as a string. The convenient way to test
599 parts of this string is with @code{string-match}.
603 The value of this variable is a symbol indicating the type of operating
604 system Emacs is operating on. Here is a table of the possible values:
620 Data General DGUX operating system.
623 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
626 A GNU/Linux system---that is, a variant GNU system, using the Linux
627 kernel. (These systems are the ones people often call ``Linux,'' but
628 actually Linux is just the kernel, not the whole system.)
631 Hewlett-Packard HPUX operating system.
634 Silicon Graphics Irix system.
637 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
638 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
642 NeXT Mach-based system.
645 Masscomp RTU, UCB universe.
657 Microsoft windows NT. The same executable supports Windows 9X, but the
658 value of @code{system-type} is @code{windows-nt} in either case.
664 We do not wish to add new symbols to make finer distinctions unless it
665 is absolutely necessary! In fact, we hope to eliminate some of these
666 alternatives in the future. We recommend using
667 @code{system-configuration} to distinguish between different operating
672 This function returns the name of the machine you are running on.
675 @result{} "www.gnu.org"
679 The symbol @code{system-name} is a variable as well as a function. In
680 fact, the function returns whatever value the variable
681 @code{system-name} currently holds. Thus, you can set the variable
682 @code{system-name} in case Emacs is confused about the name of your
683 system. The variable is also useful for constructing frame titles
684 (@pxref{Frame Titles}).
686 @defvar mail-host-address
687 If this variable is non-@code{nil}, it is used instead of
688 @code{system-name} for purposes of generating email addresses. For
689 example, it is used when constructing the default value of
690 @code{user-mail-address}. @xref{User Identification}. (Since this is
691 done when Emacs starts up, the value actually used is the one saved when
692 Emacs was dumped. @xref{Building Emacs}.)
695 @deffn Command getenv var
696 @cindex environment variable access
697 This function returns the value of the environment variable @var{var},
698 as a string. Within Emacs, the environment variable values are kept in
699 the Lisp variable @code{process-environment}.
708 lewis@@slug[10] % printenv
709 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
721 @deffn Command setenv variable value
722 This command sets the value of the environment variable named
723 @var{variable} to @var{value}. Both arguments should be strings. This
724 function works by modifying @code{process-environment}; binding that
725 variable with @code{let} is also reasonable practice.
728 @defvar process-environment
729 This variable is a list of strings, each describing one environment
730 variable. The functions @code{getenv} and @code{setenv} work by means
736 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
737 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
747 If @code{process-environment} contains ``duplicate'' elements that
748 specify the same environment variable, the first of these elements
749 specifies the variable, and the other ``duplicates'' are ignored.
752 @defvar path-separator
753 This variable holds a string which says which character separates
754 directories in a search path (as found in an environment variable). Its
755 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
759 @defun parse-colon-path path
760 @tindex parse-colon-path
761 This function takes a search path string such as would be the value of
762 the @code{PATH} environment variable, and splits it at the separators,
763 returning a list of directory names. @code{nil} in this list stands for
764 ``use the current directory.'' Although the function's name says
765 ``colon,'' it actually uses the value of @code{path-separator}.
768 (parse-colon-path ":/foo:/bar")
769 @result{} (nil "/foo/" "/bar/")
773 @defvar invocation-name
774 This variable holds the program name under which Emacs was invoked. The
775 value is a string, and does not include a directory name.
778 @defvar invocation-directory
779 This variable holds the directory from which the Emacs executable was
780 invoked, or perhaps @code{nil} if that directory cannot be determined.
783 @defvar installation-directory
784 If non-@code{nil}, this is a directory within which to look for the
785 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
786 when Emacs can't find those directories in their standard installed
787 locations, but can find them in a directory related somehow to the one
788 containing the Emacs executable.
791 @defun load-average &optional use-float
792 This function returns the current 1-minute, 5-minute, and 15-minute load
795 By default, the values are integers that are 100 times the system load
796 averages, which indicate the average number of processes trying to run.
797 If @var{use-float} is non-@code{nil}, then they are returned
798 as floating point numbers and without multiplying by 100.
803 @result{} (169 48 36)
807 @result{} (1.69 0.48 0.36)
811 lewis@@rocky[5] % uptime
812 11:55am up 1 day, 19:37, 3 users,
813 load average: 1.69, 0.48, 0.36
819 This function returns the process @sc{id} of the Emacs process.
822 @defvar tty-erase-char
823 This variable holds the erase character that was selected
824 in the system's terminal driver, before Emacs was started.
827 @defun setprv privilege-name &optional setp getprv
828 This function sets or resets a VMS privilege. (It does not exist on
829 other systems.) The first argument is the privilege name, as a string.
830 The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
831 whether the privilege is to be turned on or off. Its default is
832 @code{nil}. The function returns @code{t} if successful, @code{nil}
835 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
836 does not change the privilege, but returns @code{t} or @code{nil}
837 indicating whether the privilege is currently enabled.
840 @node User Identification
841 @section User Identification
843 @defvar init-file-user
844 This variable says which user's init files should be used by Emacs---or
845 @code{nil} if none. The value reflects command-line options such as
846 @samp{-q} or @samp{-u @var{user}}.
848 Lisp packages that load files of customizations, or any other sort of
849 user profile, should obey this variable in deciding where to find it.
850 They should load the profile of the user name found in this variable.
851 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
852 option was used, then Lisp packages should not load any customization
853 files or user profile.
856 @defvar user-mail-address
857 This holds the nominal email address of the user who is using Emacs.
858 Emacs normally sets this variable to a default value after reading your
859 init files, but not if you have already set it. So you can set the
860 variable to some other value in your init file if you do not
861 want to use the default value.
864 @defun user-login-name &optional uid
865 If you don't specify @var{uid}, this function returns the name under
866 which the user is logged in. If the environment variable @code{LOGNAME}
867 is set, that value is used. Otherwise, if the environment variable
868 @code{USER} is set, that value is used. Otherwise, the value is based
869 on the effective @sc{uid}, not the real @sc{uid}.
871 If you specify @var{uid}, the value is the user name that corresponds
872 to @var{uid} (which should be an integer).
882 @defun user-real-login-name
883 This function returns the user name corresponding to Emacs's real
884 @sc{uid}. This ignores the effective @sc{uid} and ignores the
885 environment variables @code{LOGNAME} and @code{USER}.
888 @defun user-full-name &optional uid
889 This function returns the full name of the logged-in user---or the value
890 of the environment variable @code{NAME}, if that is set.
892 @c "Bil" is the correct spelling.
896 @result{} "Bil Lewis"
900 If the Emacs job's user-id does not correspond to any known user (and
901 provided @code{NAME} is not set), the value is @code{"unknown"}.
903 If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
904 or a string (a login name). Then @code{user-full-name} returns the full
905 name corresponding to that user-id or login name. If you specify a
906 user-id or login name that isn't defined, it returns @code{nil}.
909 @vindex user-full-name
910 @vindex user-real-login-name
911 @vindex user-login-name
912 The symbols @code{user-login-name}, @code{user-real-login-name} and
913 @code{user-full-name} are variables as well as functions. The functions
914 return the same values that the variables hold. These variables allow
915 you to ``fake out'' Emacs by telling the functions what to return. The
916 variables are also useful for constructing frame titles (@pxref{Frame
920 This function returns the real @sc{uid} of the user.
931 This function returns the effective @sc{uid} of the user.
937 This section explains how to determine the current time and the time
940 @defun current-time-string &optional time-value
941 This function returns the current time and date as a human-readable
942 string. The format of the string is unvarying; the number of characters
943 used for each part is always the same, so you can reliably use
944 @code{substring} to extract pieces of it. It is wise to count the
945 characters from the beginning of the string rather than from the end, as
946 additional information may some day be added at the end.
949 The argument @var{time-value}, if given, specifies a time to format
950 instead of the current time. The argument should be a list whose first
951 two elements are integers. Thus, you can use times obtained from
952 @code{current-time} (see below) and from @code{file-attributes}
953 (@pxref{File Attributes}).
957 (current-time-string)
958 @result{} "Wed Oct 14 22:21:05 1987"
965 This function returns the system's time value as a list of three
966 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
967 @var{high} and @var{low} combine to give the number of seconds since
968 0:00 January 1, 1970 (local time), which is
970 @var{high} * 2**16 + @var{low}.
976 The third element, @var{microsec}, gives the microseconds since the
977 start of the current second (or 0 for systems that return time with
978 the resolution of only one second).
980 The first two elements can be compared with file time values such as you
981 get with the function @code{file-attributes}. @xref{File Attributes}.
985 @defun current-time-zone &optional time-value
986 This function returns a list describing the time zone that the user is
989 The value has the form @code{(@var{offset} @var{name})}. Here
990 @var{offset} is an integer giving the number of seconds ahead of UTC
991 (east of Greenwich). A negative value means west of Greenwich. The
992 second element, @var{name}, is a string giving the name of the time
993 zone. Both elements change when daylight savings time begins or ends;
994 if the user has specified a time zone that does not use a seasonal time
995 adjustment, then the value is constant through time.
997 If the operating system doesn't supply all the information necessary to
998 compute the value, both elements of the list are @code{nil}.
1000 The argument @var{time-value}, if given, specifies a time to analyze
1001 instead of the current time. The argument should be a cons cell
1002 containing two integers, or a list whose first two elements are
1003 integers. Thus, you can use times obtained from @code{current-time}
1004 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
1007 @defun float-time &optional time-value
1008 This function returns the current time as a floating-point number of
1009 seconds since the epoch. The argument @var{time-value}, if given,
1010 specifies a time to convert instead of the current time. The argument
1011 should have the same form as for @code{current-time-string} (see
1012 above), and it also accepts the output of @code{current-time} and
1013 @code{file-attributes}.
1015 @emph{Warning}: Since the result is floating point, it may not be
1016 exact. Do not use this function if precise time stamps are required.
1019 @node Time Conversion
1020 @section Time Conversion
1022 These functions convert time values (lists of two or three integers)
1023 to strings or to calendrical information. There is also a function to
1024 convert calendrical information to a time value. You can get time
1025 values from the functions @code{current-time} (@pxref{Time of Day}) and
1026 @code{file-attributes} (@pxref{File Attributes}).
1028 Many operating systems are limited to time values that contain 32 bits
1029 of information; these systems typically handle only the times from
1030 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1031 operating systems have larger time values, and can represent times far
1032 in the past or future.
1034 Time conversion functions always use the Gregorian calendar, even for
1035 dates before the Gregorian calendar was introduced. Year numbers count
1036 the number of years since the year 1 B.C., and do not skip zero as
1037 traditional Gregorian years do; for example, the year number @minus{}37
1038 represents the Gregorian year 38 B.C@.
1040 @defun date-to-time string
1041 This function parses the time-string @var{string} and returns the
1042 corresponding time value.
1045 @defun format-time-string format-string &optional time universal
1046 This function converts @var{time} (or the current time, if @var{time} is
1047 omitted) to a string according to @var{format-string}. The argument
1048 @var{format-string} may contain @samp{%}-sequences which say to
1049 substitute parts of the time. Here is a table of what the
1050 @samp{%}-sequences mean:
1054 This stands for the abbreviated name of the day of week.
1056 This stands for the full name of the day of week.
1058 This stands for the abbreviated name of the month.
1060 This stands for the full name of the month.
1062 This is a synonym for @samp{%x %X}.
1064 This has a locale-specific meaning. In the default locale (named C), it
1065 is equivalent to @samp{%A, %B %e, %Y}.
1067 This stands for the day of month, zero-padded.
1069 This is a synonym for @samp{%m/%d/%y}.
1071 This stands for the day of month, blank-padded.
1073 This is a synonym for @samp{%b}.
1075 This stands for the hour (00-23).
1077 This stands for the hour (01-12).
1079 This stands for the day of the year (001-366).
1081 This stands for the hour (0-23), blank padded.
1083 This stands for the hour (1-12), blank padded.
1085 This stands for the month (01-12).
1087 This stands for the minute (00-59).
1089 This stands for a newline.
1091 This stands for @samp{AM} or @samp{PM}, as appropriate.
1093 This is a synonym for @samp{%I:%M:%S %p}.
1095 This is a synonym for @samp{%H:%M}.
1097 This stands for the seconds (00-59).
1099 This stands for a tab character.
1101 This is a synonym for @samp{%H:%M:%S}.
1103 This stands for the week of the year (01-52), assuming that weeks
1106 This stands for the numeric day of week (0-6). Sunday is day 0.
1108 This stands for the week of the year (01-52), assuming that weeks
1111 This has a locale-specific meaning. In the default locale (named
1112 @samp{C}), it is equivalent to @samp{%D}.
1114 This has a locale-specific meaning. In the default locale (named
1115 @samp{C}), it is equivalent to @samp{%T}.
1117 This stands for the year without century (00-99).
1119 This stands for the year with century.
1121 This stands for the time zone abbreviation.
1124 You can also specify the field width and type of padding for any of
1125 these @samp{%}-sequences. This works as in @code{printf}: you write
1126 the field width as digits in the middle of a @samp{%}-sequences. If you
1127 start the field width with @samp{0}, it means to pad with zeros. If you
1128 start the field width with @samp{_}, it means to pad with spaces.
1130 For example, @samp{%S} specifies the number of seconds since the minute;
1131 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1132 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1133 because that is how @samp{%S} normally pads to two positions.
1135 The characters @samp{E} and @samp{O} act as modifiers when used between
1136 @samp{%} and one of the letters in the table above. @samp{E} specifies
1137 using the current locale's ``alternative'' version of the date and time.
1138 In a Japanese locale, for example, @code{%Ex} might yield a date format
1139 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1140 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1143 @samp{O} means to use the current locale's ``alternative''
1144 representation of numbers, instead of the ordinary decimal digits. This
1145 is allowed with most letters, all the ones that output numbers.
1147 If @var{universal} is non-@code{nil}, that means to describe the time as
1148 Universal Time; @code{nil} means describe it using what Emacs believes
1149 is the local time zone (see @code{current-time-zone}).
1151 This function uses the C library function @code{strftime} to do most of
1152 the work. In order to communicate with that function, it first encodes
1153 its argument using the coding system specified by
1154 @code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
1155 returns the resulting string, @code{format-time-string} decodes the
1156 string using that same coding system.
1159 @defun seconds-to-time seconds
1160 This function converts @var{seconds}, a floating point number of
1161 seconds since the epoch, to a time value and returns that. To perform
1162 the inverse conversion, use @code{float-time}.
1165 @defun decode-time time
1166 This function converts a time value into calendrical information. The
1167 return value is a list of nine elements, as follows:
1170 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1173 Here is what the elements mean:
1177 The number of seconds past the minute, as an integer between 0 and 59.
1179 The number of minutes past the hour, as an integer between 0 and 59.
1181 The hour of the day, as an integer between 0 and 23.
1183 The day of the month, as an integer between 1 and 31.
1185 The month of the year, as an integer between 1 and 12.
1187 The year, an integer typically greater than 1900.
1189 The day of week, as an integer between 0 and 6, where 0 stands for
1192 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1194 An integer indicating the time zone, as the number of seconds east of
1198 @strong{Common Lisp Note:} Common Lisp has different meanings for
1199 @var{dow} and @var{zone}.
1202 @defun encode-time seconds minutes hour day month year &optional zone
1203 This function is the inverse of @code{decode-time}. It converts seven
1204 items of calendrical data into a time value. For the meanings of the
1205 arguments, see the table above under @code{decode-time}.
1207 Year numbers less than 100 are not treated specially. If you want them
1208 to stand for years above 1900, or years above 2000, you must alter them
1209 yourself before you call @code{encode-time}.
1211 The optional argument @var{zone} defaults to the current time zone and
1212 its daylight savings time rules. If specified, it can be either a list
1213 (as you would get from @code{current-time-zone}), a string as in the
1214 @code{TZ} environment variable, or an integer (as you would get from
1215 @code{decode-time}). The specified zone is used without any further
1216 alteration for daylight savings time.
1218 If you pass more than seven arguments to @code{encode-time}, the first
1219 six are used as @var{seconds} through @var{year}, the last argument is
1220 used as @var{zone}, and the arguments in between are ignored. This
1221 feature makes it possible to use the elements of a list returned by
1222 @code{decode-time} as the arguments to @code{encode-time}, like this:
1225 (apply 'encode-time (decode-time @dots{}))
1228 You can perform simple date arithmetic by using out-of-range values for
1229 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1230 arguments; for example, day 0 means the day preceding the given month.
1232 The operating system puts limits on the range of possible time values;
1233 if you try to encode a time that is out of range, an error results.
1236 @node Time Calculations
1237 @section Time Calculations
1239 These functions perform calendrical computations using time values
1240 (the kind of list that @code{current-time} returns).
1242 @defun time-less-p t1 t2
1243 This returns @code{t} if time value @var{t1} is less than time value
1247 @defun time-subtract t1 t2
1248 This returns the time difference @var{t1} @minus{} @var{t2} between
1249 two time values, in the same format as a time value.
1252 @defun time-add t1 t2
1253 This returns the sum of two time values, one of which ought to
1254 represent a time difference rather than a point in time.
1255 Here is how to add a number of seconds to a time value:
1258 (time-add @var{time} (seconds-to-time @var{seconds}))
1262 @defun time-to-days time
1263 This function returns the number of days between the beginning of year
1267 @defun time-to-day-in-year time
1268 This returns the day number within the year corresponding to @var{time}.
1271 @defun date-leap-year-p year
1272 This function returns @code{t} if @var{year} is a leap year.
1276 @section Timers for Delayed Execution
1279 You can set up a @dfn{timer} to call a function at a specified future time or
1280 after a certain length of idleness.
1282 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1283 can run them only when Emacs could accept output from a subprocess:
1284 namely, while waiting or inside certain primitive functions such as
1285 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1286 timer's execution may be delayed if Emacs is busy. However, the time of
1287 execution is very precise if Emacs is idle.
1289 @defun run-at-time time repeat function &rest args
1290 This function arranges to call @var{function} with arguments @var{args}
1291 at time @var{time}. The argument @var{function} is a function to call
1292 later, and @var{args} are the arguments to give it when it is called.
1293 The time @var{time} is specified as a string.
1295 Absolute times may be specified in a wide variety of formats; this
1296 function tries to accept all the commonly used date formats. Valid
1297 formats include these two,
1300 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
1302 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
1306 where in both examples all fields are numbers; the format that
1307 @code{current-time-string} returns is also allowed, and many others
1310 To specify a relative time, use numbers followed by units.
1315 denotes 1 minute from now.
1317 denotes 65 seconds from now.
1318 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1319 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1322 For relative time values, Emacs considers a month to be exactly thirty
1323 days, and a year to be exactly 365.25 days.
1325 If @var{time} is a number (integer or floating point), that specifies a
1326 relative time measured in seconds.
1328 The argument @var{repeat} specifies how often to repeat the call. If
1329 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
1330 called just once, at @var{time}. If @var{repeat} is a number, it
1331 specifies a repetition period measured in seconds.
1333 In most cases, @var{repeat} has no effect on when @emph{first} call
1334 takes place---@var{time} alone specifies that. There is one exception:
1335 if @var{time} is @code{t}, then the timer runs whenever the time is a
1336 multiple of @var{repeat} seconds after the epoch. This is useful for
1337 functions like @code{display-time}.
1339 The function @code{run-at-time} returns a timer value that identifies
1340 the particular scheduled future action. You can use this value to call
1341 @code{cancel-timer} (see below).
1344 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1345 Execute @var{body}, but give up after @var{seconds} seconds. If
1346 @var{body} finishes before the time is up, @code{with-timeout} returns
1347 the value of the last form in @var{body}. If, however, the execution of
1348 @var{body} is cut short by the timeout, then @code{with-timeout}
1349 executes all the @var{timeout-forms} and returns the value of the last
1352 This macro works by setting a timer to run after @var{seconds} seconds. If
1353 @var{body} finishes before that time, it cancels the timer. If the
1354 timer actually runs, it terminates execution of @var{body}, then
1355 executes @var{timeout-forms}.
1357 Since timers can run within a Lisp program only when the program calls a
1358 primitive that can wait, @code{with-timeout} cannot stop executing
1359 @var{body} while it is in the midst of a computation---only when it
1360 calls one of those primitives. So use @code{with-timeout} only with a
1361 @var{body} that waits for input, not one that does a long computation.
1364 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1365 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1368 @defun run-with-idle-timer secs repeat function &rest args
1369 Set up a timer which runs when Emacs has been idle for @var{secs}
1370 seconds. The value of @var{secs} may be an integer or a floating point
1373 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1374 Emacs remains idle for a long enough time. More often @var{repeat} is
1375 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1376 remains idle for @var{secs} seconds.
1378 The function @code{run-with-idle-timer} returns a timer value which you
1379 can use in calling @code{cancel-timer} (see below).
1383 Emacs becomes ``idle'' when it starts waiting for user input, and it
1384 remains idle until the user provides some input. If a timer is set for
1385 five seconds of idleness, it runs approximately five seconds after Emacs
1386 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1387 will not run again as long as Emacs remains idle, because the duration
1388 of idleness will continue to increase and will not go down to five
1391 Emacs can do various things while idle: garbage collect, autosave or
1392 handle data from a subprocess. But these interludes during idleness do
1393 not interfere with idle timers, because they do not reset the clock of
1394 idleness to zero. An idle timer set for 600 seconds will run when ten
1395 minutes have elapsed since the last user command was finished, even if
1396 subprocess output has been accepted thousands of times within those ten
1397 minutes, and even if there have been garbage collections and autosaves.
1399 When the user supplies input, Emacs becomes non-idle while executing the
1400 input. Then it becomes idle again, and all the idle timers that are
1401 set up to repeat will subsequently run another time, one by one.
1403 @defun cancel-timer timer
1404 Cancel the requested action for @var{timer}, which should be a value
1405 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
1406 This cancels the effect of that call to @code{run-at-time}; the arrival
1407 of the specified time will not cause anything special to happen.
1410 @node Terminal Input
1411 @section Terminal Input
1412 @cindex terminal input
1414 This section describes functions and variables for recording or
1415 manipulating terminal input. See @ref{Display}, for related
1419 * Input Modes:: Options for how input is processed.
1420 * Translating Input:: Low level conversion of some characters or events
1422 * Recording Input:: Saving histories of recent or all input events.
1426 @subsection Input Modes
1428 @cindex terminal input modes
1430 @defun set-input-mode interrupt flow meta quit-char
1431 This function sets the mode for reading keyboard input. If
1432 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1433 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1434 system-dependent. Some systems always use @sc{cbreak} mode regardless
1435 of what is specified.
1437 When Emacs communicates directly with X, it ignores this argument and
1438 uses interrupts if that is the way it knows how to communicate.
1440 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1441 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1442 has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
1445 The argument @var{meta} controls support for input character codes
1446 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1447 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1448 Emacs disregards the 8th bit; this is necessary when the terminal uses
1449 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1450 Emacs uses all 8 bits of input unchanged. This is good for terminals
1451 that use 8-bit character sets.
1454 If @var{quit-char} is non-@code{nil}, it specifies the character to
1455 use for quitting. Normally this character is @kbd{C-g}.
1459 The @code{current-input-mode} function returns the input mode settings
1460 Emacs is currently using.
1463 @defun current-input-mode
1464 This function returns the current mode for reading keyboard input. It
1465 returns a list, corresponding to the arguments of @code{set-input-mode},
1466 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1470 is non-@code{nil} when Emacs is using interrupt-driven input. If
1471 @code{nil}, Emacs is using @sc{cbreak} mode.
1473 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1474 flow control for output to the terminal. This value is meaningful only
1475 when @var{interrupt} is @code{nil}.
1477 is @code{t} if Emacs treats the eighth bit of input characters as
1478 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1479 input character; any other value means Emacs uses all eight bits as the
1480 basic character code.
1482 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1486 @node Translating Input
1487 @subsection Translating Input Events
1488 @cindex translating input events
1490 This section describes features for translating input events into
1491 other input events before they become part of key sequences. These
1492 features apply to each event in the order they are described here: each
1493 event is first modified according to @code{extra-keyboard-modifiers},
1494 then translated through @code{keyboard-translate-table} (if applicable),
1495 and finally decoded with the specified keyboard coding system. If it is
1496 being read as part of a key sequence, it is then added to the sequence
1497 being read; then subsequences containing it are checked first with
1498 @code{function-key-map} and then with @code{key-translation-map}.
1501 @defvar extra-keyboard-modifiers
1502 This variable lets Lisp programs ``press'' the modifier keys on the
1503 keyboard. The value is a bit mask:
1507 The @key{SHIFT} key.
1516 Each time the user types a keyboard key, it is altered as if the
1517 modifier keys specified in the bit mask were held down.
1519 When using a window system, the program can ``press'' any of the
1520 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
1521 keys can be virtually pressed.
1524 @defvar keyboard-translate-table
1525 This variable is the translate table for keyboard characters. It lets
1526 you reshuffle the keys on the keyboard without changing any command
1527 bindings. Its value is normally a char-table, or else @code{nil}.
1529 If @code{keyboard-translate-table} is a char-table
1530 (@pxref{Char-Tables}), then each character read from the keyboard is
1531 looked up in this char-table. If the value found there is
1532 non-@code{nil}, then it is used instead of the actual input character.
1534 In the example below, we set @code{keyboard-translate-table} to a
1535 char-table. Then we fill it in to swap the characters @kbd{C-s} and
1536 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
1537 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
1538 versa. (@xref{Flow Control}, for more information on this subject.)
1540 @cindex flow control example
1543 (defun evade-flow-control ()
1544 "Replace C-s with C-\ and C-q with C-^."
1548 (setq keyboard-translate-table
1549 (make-char-table 'keyboard-translate-table nil))
1552 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1553 (aset keyboard-translate-table ?\034 ?\^s)
1554 (aset keyboard-translate-table ?\^s ?\034)
1557 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1558 (aset keyboard-translate-table ?\036 ?\^q)
1559 (aset keyboard-translate-table ?\^q ?\036))
1563 Note that this translation is the first thing that happens to a
1564 character after it is read from the terminal. Record-keeping features
1565 such as @code{recent-keys} and dribble files record the characters after
1569 @defun keyboard-translate from to
1570 This function modifies @code{keyboard-translate-table} to translate
1571 character code @var{from} into character code @var{to}. It creates
1572 the keyboard translate table if necessary.
1575 The remaining translation features translate subsequences of key
1576 sequences being read. They are implemented in @code{read-key-sequence}
1577 and have no effect on input read with @code{read-event}.
1579 @defvar function-key-map
1580 This variable holds a keymap that describes the character sequences sent
1581 by function keys on an ordinary character terminal. This keymap has the
1582 same structure as other keymaps, but is used differently: it specifies
1583 translations to make while reading key sequences, rather than bindings
1586 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1587 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1588 key sequence, it is replaced with the events in @var{v}.
1590 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1591 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
1592 that sequence of events into the single event @code{pf1}. We accomplish
1593 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1594 @code{function-key-map}, when using a VT100.
1596 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1597 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1598 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1601 Entries in @code{function-key-map} are ignored if they conflict with
1602 bindings made in the minor mode, local, or global keymaps. The intent
1603 is that the character sequences that function keys send should not have
1604 command bindings in their own right---but if they do, the ordinary
1605 bindings take priority.
1607 The value of @code{function-key-map} is usually set up automatically
1608 according to the terminal's Terminfo or Termcap entry, but sometimes
1609 those need help from terminal-specific Lisp files. Emacs comes with
1610 terminal-specific files for many common terminals; their main purpose is
1611 to make entries in @code{function-key-map} beyond those that can be
1612 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1615 @defvar key-translation-map
1616 This variable is another keymap used just like @code{function-key-map}
1617 to translate input events into other events. It differs from
1618 @code{function-key-map} in two ways:
1622 @code{key-translation-map} goes to work after @code{function-key-map} is
1623 finished; it receives the results of translation by
1624 @code{function-key-map}.
1627 @code{key-translation-map} overrides actual key bindings. For example,
1628 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
1629 translation takes effect even though @kbd{C-x f} also has a key binding
1633 The intent of @code{key-translation-map} is for users to map one
1634 character set to another, including ordinary characters normally bound
1635 to @code{self-insert-command}.
1638 @cindex key translation function
1639 You can use @code{function-key-map} or @code{key-translation-map} for
1640 more than simple aliases, by using a function, instead of a key
1641 sequence, as the ``translation'' of a key. Then this function is called
1642 to compute the translation of that key.
1644 The key translation function receives one argument, which is the prompt
1645 that was specified in @code{read-key-sequence}---or @code{nil} if the
1646 key sequence is being read by the editor command loop. In most cases
1647 you can ignore the prompt value.
1649 If the function reads input itself, it can have the effect of altering
1650 the event that follows. For example, here's how to define @kbd{C-c h}
1651 to turn the character that follows into a Hyper character:
1655 (defun hyperify (prompt)
1656 (let ((e (read-event)))
1657 (vector (if (numberp e)
1658 (logior (lsh 1 24) e)
1659 (if (memq 'hyper (event-modifiers e))
1661 (add-event-modifier "H-" e))))))
1663 (defun add-event-modifier (string e)
1664 (let ((symbol (if (symbolp e) e (car e))))
1665 (setq symbol (intern (concat string
1666 (symbol-name symbol))))
1671 (cons symbol (cdr e)))))
1673 (define-key function-key-map "\C-ch" 'hyperify)
1677 Finally, if you have enabled keyboard character set decoding using
1678 @code{set-keyboard-coding-system}, decoding is done after the
1679 translations listed above. @xref{Specifying Coding Systems}. In future
1680 Emacs versions, character set decoding may be done before the other
1683 @node Recording Input
1684 @subsection Recording Input
1687 This function returns a vector containing the last 100 input events from
1688 the keyboard or mouse. All input events are included, whether or not
1689 they were used as parts of key sequences. Thus, you always get the last
1690 100 input events, not counting events generated by keyboard macros.
1691 (These are excluded because they are less interesting for debugging; it
1692 should be enough to see the events that invoked the macros.)
1694 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1695 causes this function to return an empty vector immediately afterward.
1698 @deffn Command open-dribble-file filename
1699 @cindex dribble file
1700 This function opens a @dfn{dribble file} named @var{filename}. When a
1701 dribble file is open, each input event from the keyboard or mouse (but
1702 not those from keyboard macros) is written in that file. A
1703 non-character event is expressed using its printed representation
1704 surrounded by @samp{<@dots{}>}.
1706 You close the dribble file by calling this function with an argument
1709 This function is normally used to record the input necessary to
1710 trigger an Emacs bug, for the sake of a bug report.
1714 (open-dribble-file "~/dribble")
1720 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1722 @node Terminal Output
1723 @section Terminal Output
1724 @cindex terminal output
1726 The terminal output functions send output to the terminal, or keep
1727 track of output sent to the terminal. The variable @code{baud-rate}
1728 tells you what Emacs thinks is the output speed of the terminal.
1731 This variable's value is the output speed of the terminal, as far as
1732 Emacs knows. Setting this variable does not change the speed of actual
1733 data transmission, but the value is used for calculations such as
1734 padding. It also affects decisions about whether to scroll part of the
1735 screen or repaint---even when using a window system. (We designed it
1736 this way despite the fact that a window system has no true ``output
1737 speed'', to give you a way to tune these decisions.)
1739 The value is measured in baud.
1742 If you are running across a network, and different parts of the
1743 network work at different baud rates, the value returned by Emacs may be
1744 different from the value used by your local terminal. Some network
1745 protocols communicate the local terminal speed to the remote machine, so
1746 that Emacs and other programs can get the proper value, but others do
1747 not. If Emacs has the wrong value, it makes decisions that are less
1748 than optimal. To fix the problem, set @code{baud-rate}.
1751 This obsolete function returns the value of the variable
1755 @defun send-string-to-terminal string
1756 This function sends @var{string} to the terminal without alteration.
1757 Control characters in @var{string} have terminal-dependent effects.
1759 One use of this function is to define function keys on terminals that
1760 have downloadable function key definitions. For example, this is how (on
1761 certain terminals) to define function key 4 to move forward four
1762 characters (by transmitting the characters @kbd{C-u C-f} to the
1767 (send-string-to-terminal "\eF4\^U\^F")
1773 @deffn Command open-termscript filename
1774 @cindex termscript file
1775 This function is used to open a @dfn{termscript file} that will record
1776 all the characters sent by Emacs to the terminal. It returns
1777 @code{nil}. Termscript files are useful for investigating problems
1778 where Emacs garbles the screen, problems that are due to incorrect
1779 Termcap entries or to undesirable settings of terminal options more
1780 often than to actual Emacs bugs. Once you are certain which characters
1781 were actually output, you can determine reliably whether they correspond
1782 to the Termcap specifications in use.
1784 See also @code{open-dribble-file} in @ref{Terminal Input}.
1788 (open-termscript "../junk/termscript")
1795 @section Sound Output
1798 To play sound using Emacs, use the function @code{play-sound}. Only
1799 certain systems are supported; if you call @code{play-sound} on a system
1800 which cannot really do the job, it gives an error. Emacs version 20 and
1801 earlier did not support sound at all.
1803 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1804 or Sun Audio format (@samp{.au}).
1807 @defun play-sound sound
1808 This function plays a specified sound. The argument, @var{sound}, has
1809 the form @code{(sound @var{properties}...)}, where the @var{properties}
1810 consist of alternating keywords (particular symbols recognized
1811 specially) and values corresponding to them.
1813 Here is a table of the keywords that are currently meaningful in
1814 @var{sound}, and their meanings:
1817 @item :file @var{file}
1818 This specifies the file containing the sound to play.
1819 If the file name is not absolute, it is expanded against
1820 the directory @code{data-directory}.
1822 @item :data @var{data}
1823 This specifies the sound to play without need to refer to a file. The
1824 value, @var{data}, should be a string containing the same bytes as a
1825 sound file. We recommend using a unibyte string.
1827 @item :volume @var{volume}
1828 This specifies how loud to play the sound. It should be a number in the
1829 range of 0 to 1. The default is to use whatever volume has been
1832 @item :device @var{device}
1833 This specifies the system device on which to play the sound, as a
1834 string. The default device is system-dependent.
1837 Before actually playing the sound, @code{play-sound}
1838 calls the functions in the list @code{play-sound-functions}.
1839 Each function is called with one argument, @var{sound}.
1842 @defun play-sound-file file &optional volume device
1843 @tindex play-sound-file
1844 This function is an alternative interface to playing a sound @var{file}
1845 specifying an optional @var{volume} and @var{device}.
1848 @tindex play-sound-functions
1849 @defvar play-sound-functions
1850 A list of functions to be called before playing a sound. Each function
1851 is called with one argument, a property list that describes the sound.
1855 @section Operating on X11 Keysyms
1857 To define system-specific X11 keysyms, set the variable
1858 @code{system-key-alist}.
1860 @defvar system-key-alist
1861 This variable's value should be an alist with one element for each
1862 system-specific keysym. Each element has the form @code{(@var{code}
1863 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1864 including the ``vendor specific'' bit,
1871 and @var{symbol} is the name for the function key.
1873 For example @code{(168 . mute-acute)} defines a system-specific key (used
1874 by HP X servers) whose numeric code is
1883 It is not crucial to exclude from the alist the keysyms of other X
1884 servers; those do no harm, as long as they don't conflict with the ones
1885 used by the X server actually in use.
1887 The variable is always local to the current terminal, and cannot be
1888 buffer-local. @xref{Multiple Displays}.
1891 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
1893 @defvar x-alt-keysym
1894 @defvarx x-meta-keysym
1895 @defvarx x-hyper-keysym
1896 @defvarx x-super-keysym
1897 The name of the keysym that should stand for the Alt modifier
1898 (respectively, for Meta, Hyper, and Super). For example, here is
1899 how to swap the Meta and Alt modifiers within Emacs:
1901 (setq x-alt-keysym 'meta)
1902 (setq x-meta-keysym 'alt)
1907 @section Flow Control
1908 @cindex flow control characters
1910 This section attempts to answer the question ``Why does Emacs use
1911 flow-control characters in its command character set?'' For a second
1912 view on this issue, read the comments on flow control in the
1913 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1914 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1918 At one time, most terminals did not need flow control, and none used
1919 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1920 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
1921 was natural and uncontroversial. With so many commands needing key
1922 assignments, of course we assigned meanings to nearly all @sc{ascii}
1925 Later, some terminals were introduced which required these characters
1926 for flow control. They were not very good terminals for full-screen
1927 editing, so Emacs maintainers ignored them. In later years, flow
1928 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
1929 but by this time it was usually an option. And the majority of Emacs
1930 users, who can turn flow control off, did not want to switch to less
1931 mnemonic key bindings for the sake of flow control.
1933 So which usage is ``right''---Emacs's or that of some terminal and
1934 concentrator manufacturers? This question has no simple answer.
1936 One reason why we are reluctant to cater to the problems caused by
1937 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1938 techniques (albeit less common in practice) for flow control that
1939 preserve transparency of the character stream. Note also that their use
1940 for flow control is not an official standard. Interestingly, on the
1941 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
1942 @kbd{C-q} were sent by the computer to turn the punch on and off!
1944 As window systems and PC terminal emulators replace character-only
1945 terminals, the flow control problem is gradually disappearing. For the
1946 mean time, Emacs provides a convenient way of enabling flow control if
1947 you want it: call the function @code{enable-flow-control}.
1949 @deffn Command enable-flow-control
1950 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1951 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1952 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1955 You can use the function @code{enable-flow-control-on} in your
1956 init file to enable flow control automatically on certain
1959 @defun enable-flow-control-on &rest termtypes
1960 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1961 if the terminal type is one of @var{termtypes}. For example:
1964 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1968 Here is how @code{enable-flow-control} does its job:
1973 It sets @sc{cbreak} mode for terminal input, and tells the operating
1974 system to handle flow control, with @code{(set-input-mode nil t)}.
1977 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1978 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1979 lowest level, Emacs never knows that the characters typed were anything
1980 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1981 and @kbd{C-^} even when they are input for other commands.
1982 @xref{Translating Input}.
1985 If the terminal is the source of the flow control characters, then once
1986 you enable kernel flow control handling, you probably can make do with
1987 less padding than normal for that terminal. You can reduce the amount
1988 of padding by customizing the Termcap entry. You can also reduce it by
1989 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1990 speed when calculating the padding needed. @xref{Terminal Output}.
1995 @cindex noninteractive use
1997 The command-line option @samp{-batch} causes Emacs to run
1998 noninteractively. In this mode, Emacs does not read commands from the
1999 terminal, it does not alter the terminal modes, and it does not expect
2000 to be outputting to an erasable screen. The idea is that you specify
2001 Lisp programs to run; when they are finished, Emacs should exit. The
2002 way to specify the programs to run is with @samp{-l @var{file}}, which
2003 loads the library named @var{file}, and @samp{-f @var{function}}, which
2004 calls @var{function} with no arguments.
2006 Any Lisp program output that would normally go to the echo area,
2007 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2008 as the stream, goes instead to Emacs's standard error descriptor when
2009 in batch mode. Similarly, input that would normally come from the
2010 minibuffer is read from the standard input descriptor.
2011 Thus, Emacs behaves much like a noninteractive
2012 application program. (The echo area output that Emacs itself normally
2013 generates, such as command echoing, is suppressed entirely.)
2015 @defvar noninteractive
2016 This variable is non-@code{nil} when Emacs is running in batch mode.
2019 @node Session Management
2020 @section Session Management
2021 @cindex session manager
2023 Emacs supports the X Session Management Protocol for suspension and
2024 restart of applications. In the X Window System, a program called the
2025 @dfn{session manager} has the responsibility to keep track of the
2026 applications that are running. During shutdown, the session manager
2027 asks applications to save their state, and delays the actual shutdown
2028 until they respond. An application can also cancel the shutdown.
2030 When the session manager restarts a suspended session, it directs
2031 these applications to individually reload their saved state. It does
2032 this by specifying a special command-line argument that says what
2033 saved session to restore. For Emacs, this argument is @samp{--smid
2036 @defvar emacs-save-session-functions
2037 @tindex emacs-save-session-functions
2038 Emacs supports saving state by using a hook called
2039 @code{emacs-save-session-functions}. Each function in this hook is
2040 called when the session manager tells Emacs that the window system is
2041 shutting down. The functions are called with the current buffer set
2042 to a temporary buffer. Each functions can use @code{insert} to add
2043 Lisp code to this buffer. At the end, Emacs saves the buffer in a
2044 file that Emacs will load in order to restart the saved session.
2046 If a function in @code{emacs-save-session-functions} returns
2047 non-@code{nil}, Emacs tells the session manager to cancel the
2051 Here is an example that just inserts some text into *scratch* when
2052 Emacs is restarted by the session manager.
2056 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2060 (defun save-yourself-test ()
2061 (insert "(save-excursion
2062 (switch-to-buffer \"*scratch*\")
2063 (insert \"I am restored\"))")