2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/os
6 @node System Interface, Antinews, Calendar, Top
7 @chapter Operating System Interface
9 This chapter is about starting and getting out of Emacs, access to
10 values in the operating system environment, and terminal input, output,
13 @xref{Building Emacs}, for related information. See also
14 @ref{Display}, for additional operating system status information
15 pertaining to the terminal and the screen.
18 * Starting Up:: Customizing Emacs startup processing.
19 * Getting Out:: How exiting works (permanent or temporary).
20 * System Environment:: Distinguish the name and kind of system.
21 * User Identification:: Finding the name and user id of the user.
22 * Time of Day:: Getting the current time.
23 * Time Conversion:: Converting a time from numeric form to a string, or
24 to calendrical data (or vice versa).
25 * Timers:: Setting a timer to call a function at a certain time.
26 * Terminal Input:: Recording terminal input for debugging.
27 * Terminal Output:: Recording terminal output for debugging.
28 * Sound Output:: Playing sounds on the computer's speaker.
29 * Special Keysyms:: Defining system-specific key symbols for X windows.
30 * Flow Control:: How to turn output flow control on or off.
31 * Batch Mode:: Running Emacs without terminal interaction.
35 @section Starting Up Emacs
37 This section describes what Emacs does when it is started, and how you
38 can customize these actions.
41 * Startup Summary:: Sequence of actions Emacs performs at startup.
42 * Init File:: Details on reading the init file (@file{.emacs}).
43 * Terminal-Specific:: How the terminal-specific Lisp file is read.
44 * Command-Line Arguments:: How command-line arguments are processed,
45 and how you can customize them.
49 @subsection Summary: Sequence of Actions at Startup
50 @cindex initialization
51 @cindex startup of Emacs
52 @cindex @file{startup.el}
54 The order of operations performed (in @file{startup.el}) by Emacs when
55 it is started up is as follows:
59 It adds subdirectories to @code{load-path}, by running the file
60 named @file{subdirs.el} in each directory that is listed.
63 It sets the language environment and the terminal coding system,
64 if requested by environment variables such as @code{LANG}.
67 It loads the initialization library for the window system, if you are
68 using a window system. This library's name is
69 @file{term/@var{windowsystem}-win.el}.
72 It processes the initial options. (Some of them are handled
73 even earlier than this.)
76 It initializes the window frame and faces, if appropriate.
79 It runs the normal hook @code{before-init-hook}.
82 It loads the library @file{site-start}, unless the option
83 @samp{-no-site-file} was specified. The library's file name is usually
85 @cindex @file{site-start.el}
88 It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
89 @samp{-no-init-file}, or @samp{-batch} was specified on the command line.
90 The @samp{-u} option can specify another user whose home directory
91 should be used instead of @file{~}.
94 It loads the library @file{default}, unless @code{inhibit-default-init}
95 is non-@code{nil}. (This is not done in @samp{-batch} mode or if
96 @samp{-q} was specified on the command line.) The library's file name
97 is usually @file{default.el}.
98 @cindex @file{default.el}
101 It runs the normal hook @code{after-init-hook}.
104 It sets the major mode according to @code{initial-major-mode}, provided
105 the buffer @samp{*scratch*} is still current and still in Fundamental
109 It loads the terminal-specific Lisp file, if any, except when in batch
110 mode or using a window system.
113 It displays the initial echo area message, unless you have suppressed
114 that with @code{inhibit-startup-echo-area-message}.
117 It processes the action arguments from the command line.
120 It runs @code{term-setup-hook}.
123 It calls @code{frame-notice-user-settings}, which modifies the
124 parameters of the selected frame according to whatever the init files
128 It runs @code{window-setup-hook}. @xref{Window Systems}.
131 It displays copyleft, nonwarranty, and basic use information, provided
132 there were no remaining command-line arguments (a few steps above),
133 the value of @code{inhibit-startup-message} is @code{nil}, and the
134 buffer is still empty.
137 @defopt inhibit-startup-message
138 This variable inhibits the initial startup messages (the nonwarranty,
139 etc.). If it is non-@code{nil}, then the messages are not printed.
141 This variable exists so you can set it in your personal init file, once
142 you are familiar with the contents of the startup message. Do not set
143 this variable in the init file of a new user, or in a way that affects
144 more than one user, because that would prevent new users from receiving
145 the information they are supposed to see.
148 @defopt inhibit-startup-echo-area-message
149 This variable controls the display of the startup echo area message.
150 You can suppress the startup echo area message by adding text with this
151 form to your init file:
154 (setq inhibit-startup-echo-area-message
155 "@var{your-login-name}")
158 Emacs explicitly checks for an expression as shown above in your init
159 file; your login name must appear in the expression as a Lisp string
160 constant. Other methods of setting
161 @code{inhibit-startup-echo-area-message} to the same value do not
162 inhibit the startup message.
164 This way, you can easily inhibit the message for yourself if you wish,
165 but thoughtless copying of your init file will not inhibit the message
170 @subsection The Init File, @file{.emacs}
172 @cindex @file{.emacs}
174 When you start Emacs, it normally attempts to load your @dfn{init
175 file}, a file in your home directory. Its normal name is @file{.emacs},
176 but you can alternatively call it @file{.emacs.el}, which enables you to
177 byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
178 will be @file{.emacs.elc}.
180 The command-line switches @samp{-q} and @samp{-u} control whether and
181 where to find the init file; @samp{-q} says not to load an init file,
182 and @samp{-u @var{user}} says to load @var{user}'s init file instead of
183 yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
184 neither option is specified, Emacs uses the @code{LOGNAME} environment
185 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
186 systems) variable, to find your home directory and thus your init file;
187 this way, even if you have su'd, Emacs still loads your own init file.
188 If those environment variables are absent, though, Emacs uses your
189 user-id to find your home directory.
191 @cindex default init file
192 A site may have a @dfn{default init file}, which is the library named
193 @file{default.el}. Emacs finds the @file{default.el} file through the
194 standard search path for libraries (@pxref{How Programs Do Loading}).
195 The Emacs distribution does not come with this file; sites may provide
196 one for local customizations. If the default init file exists, it is
197 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
198 specified. But your own personal init file, if any, is loaded first; if
199 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
200 Emacs does not subsequently load the @file{default.el} file.
202 Another file for site-customization is @file{site-start.el}. Emacs
203 loads this @emph{before} the user's init file. You can inhibit the
204 loading of this file with the option @samp{-no-site-file}.
206 @defvar site-run-file
207 This variable specifies the site-customization file to load before the
208 user's init file. Its normal value is @code{"site-start"}. The only
209 way you can change it with real effect is to do so before dumping
213 @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
214 examples of how to make various commonly desired customizations in your
217 @defopt inhibit-default-init
218 This variable prevents Emacs from loading the default initialization
219 library file for your session of Emacs. If its value is non-@code{nil},
220 then the default library is not loaded. The default value is
224 @defvar before-init-hook
225 This normal hook is run, once, just before loading all the init files
226 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
227 (The only way to change it with real effect is before dumping Emacs.)
230 @defvar after-init-hook
231 This normal hook is run, once, just after loading all the init files
232 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
233 before the terminal-specific initialization.
236 @node Terminal-Specific
237 @subsection Terminal-Specific Initialization
238 @cindex terminal-specific initialization
240 Each terminal type can have its own Lisp library that Emacs loads when
241 run on that type of terminal. The library's name is constructed by
242 concatenating the value of the variable @code{term-file-prefix} and the
243 terminal type (specified by the environment variable @code{TERM}).
244 Normally, @code{term-file-prefix} has the value
245 @code{"term/"}; changing this is not recommended. Emacs finds the file
246 in the normal manner, by searching the @code{load-path} directories, and
247 trying the @samp{.elc} and @samp{.el} suffixes.
249 The usual function of a terminal-specific library is to enable special
250 keys to send sequences that Emacs can recognize. It may also need to
251 set or add to @code{function-key-map} if the Termcap entry does not
252 specify all the terminal's function keys. @xref{Terminal Input}.
255 When the name of the terminal type contains a hyphen, only the part of
256 the name before the first hyphen is significant in choosing the library
257 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
258 the @file{term/aaa} library. If necessary, the library can evaluate
259 @code{(getenv "TERM")} to find the full name of the terminal
262 Your init file can prevent the loading of the
263 terminal-specific library by setting the variable
264 @code{term-file-prefix} to @code{nil}. This feature is useful when
265 experimenting with your own peculiar customizations.
267 You can also arrange to override some of the actions of the
268 terminal-specific library by setting the variable
269 @code{term-setup-hook}. This is a normal hook which Emacs runs using
270 @code{run-hooks} at the end of Emacs initialization, after loading both
271 your init file and any terminal-specific libraries. You can
272 use this variable to define initializations for terminals that do not
273 have their own libraries. @xref{Hooks}.
275 @defvar term-file-prefix
276 @cindex @code{TERM} environment variable
277 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
278 a terminal-specific initialization file as follows:
281 (load (concat term-file-prefix (getenv "TERM")))
285 You may set the @code{term-file-prefix} variable to @code{nil} in your
286 init file if you do not wish to load the
287 terminal-initialization file. To do this, put the following in
288 your init file: @code{(setq term-file-prefix nil)}.
290 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
291 uses @samp{internal} as the terminal type.
294 @defvar term-setup-hook
295 This variable is a normal hook that Emacs runs after loading your
296 init file, the default initialization file (if any) and the
297 terminal-specific Lisp file.
299 You can use @code{term-setup-hook} to override the definitions made by a
300 terminal-specific file.
303 See @code{window-setup-hook} in @ref{Window Systems}, for a related
306 @node Command-Line Arguments
307 @subsection Command-Line Arguments
308 @cindex command-line arguments
310 You can use command-line arguments to request various actions when you
311 start Emacs. Since you do not need to start Emacs more than once per
312 day, and will often leave your Emacs session running longer than that,
313 command-line arguments are hardly ever used. As a practical matter, it
314 is best to avoid making the habit of using them, since this habit would
315 encourage you to kill and restart Emacs unnecessarily often. These
316 options exist for two reasons: to be compatible with other editors (for
317 invocation by other programs) and to enable shell scripts to run
318 specific Lisp programs.
320 This section describes how Emacs processes command-line arguments,
321 and how you can customize them.
324 (Note that some other editors require you to start afresh each time
325 you want to edit a file. With this kind of editor, you will probably
326 specify the file as a command-line argument. The recommended way to
327 use GNU Emacs is to start it only once, just after you log in, and do
328 all your editing in the same Emacs process. Each time you want to edit
329 a different file, you visit it with the existing Emacs, which eventually
330 comes to have many files in it ready for editing. Usually you do not
331 kill the Emacs until you are about to log out.)
335 This function parses the command line that Emacs was called with,
336 processes it, loads the user's init file and displays the
340 @defvar command-line-processed
341 The value of this variable is @code{t} once the command line has been
344 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
345 this variable to @code{nil} first in order to cause the new dumped Emacs
346 to process its new command-line arguments.
349 @defvar command-switch-alist
350 @cindex switches on command line
351 @cindex options on command line
352 @cindex command-line options
353 The value of this variable is an alist of user-defined command-line
354 options and associated handler functions. This variable exists so you
355 can add elements to it.
357 A @dfn{command-line option} is an argument on the command line, which
364 The elements of the @code{command-switch-alist} look like this:
367 (@var{option} . @var{handler-function})
370 The @sc{car}, @var{option}, is a string, the name of a command-line
371 option (not including the initial hyphen). The @var{handler-function}
372 is called to handle @var{option}, and receives the option name as its
375 In some cases, the option is followed in the command line by an
376 argument. In these cases, the @var{handler-function} can find all the
377 remaining command-line arguments in the variable
378 @code{command-line-args-left}. (The entire list of command-line
379 arguments is in @code{command-line-args}.)
381 The command-line arguments are parsed by the @code{command-line-1}
382 function in the @file{startup.el} file. See also @ref{Command
383 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
387 @defvar command-line-args
388 The value of this variable is the list of command-line arguments passed
392 @defvar command-line-functions
393 This variable's value is a list of functions for handling an
394 unrecognized command-line argument. Each time the next argument to be
395 processed has no special meaning, the functions in this list are called,
396 in order of appearance, until one of them returns a non-@code{nil}
399 These functions are called with no arguments. They can access the
400 command-line argument under consideration through the variable
401 @code{argi}, which is bound temporarily at this point. The remaining
402 arguments (not including the current one) are in the variable
403 @code{command-line-args-left}.
405 When a function recognizes and processes the argument in @code{argi}, it
406 should return a non-@code{nil} value to say it has dealt with that
407 argument. If it has also dealt with some of the following arguments, it
408 can indicate that by deleting them from @code{command-line-args-left}.
410 If all of these functions return @code{nil}, then the argument is used
411 as a file name to visit.
415 @section Getting Out of Emacs
416 @cindex exiting Emacs
418 There are two ways to get out of Emacs: you can kill the Emacs job,
419 which exits permanently, or you can suspend it, which permits you to
420 reenter the Emacs process later. As a practical matter, you seldom kill
421 Emacs---only when you are about to log out. Suspending is much more
425 * Killing Emacs:: Exiting Emacs irreversibly.
426 * Suspending Emacs:: Exiting Emacs reversibly.
430 @comment node-name, next, previous, up
431 @subsection Killing Emacs
432 @cindex killing Emacs
434 Killing Emacs means ending the execution of the Emacs process. The
435 parent process normally resumes control. The low-level primitive for
436 killing Emacs is @code{kill-emacs}.
438 @defun kill-emacs &optional exit-data
439 This function exits the Emacs process and kills it.
441 If @var{exit-data} is an integer, then it is used as the exit status
442 of the Emacs process. (This is useful primarily in batch operation; see
445 If @var{exit-data} is a string, its contents are stuffed into the
446 terminal input buffer so that the shell (or whatever program next reads
447 input) can read them.
450 All the information in the Emacs process, aside from files that have
451 been saved, is lost when the Emacs process is killed. Because killing
452 Emacs inadvertently can lose a lot of work, Emacs queries for
453 confirmation before actually terminating if you have buffers that need
454 saving or subprocesses that are running. This is done in the function
455 @code{save-buffers-kill-emacs}.
457 @defvar kill-emacs-query-functions
458 After asking the standard questions, @code{save-buffers-kill-emacs}
459 calls the functions in the list @code{kill-emacs-query-functions}, in
460 order of appearance, with no arguments. These functions can ask for
461 additional confirmation from the user. If any of them returns
462 @code{nil}, Emacs is not killed.
465 @defvar kill-emacs-hook
466 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
467 finished with all file saving and confirmation, it runs the functions in
471 @node Suspending Emacs
472 @subsection Suspending Emacs
473 @cindex suspending Emacs
475 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
476 control to its superior process, which is usually the shell. This
477 allows you to resume editing later in the same Emacs process, with the
478 same buffers, the same kill ring, the same undo history, and so on. To
479 resume Emacs, use the appropriate command in the parent shell---most
482 Some operating systems do not support suspension of jobs; on these
483 systems, ``suspension'' actually creates a new shell temporarily as a
484 subprocess of Emacs. Then you would exit the shell to return to Emacs.
486 Suspension is not useful with window systems, because the Emacs job
487 may not have a parent that can resume it again, and in any case you can
488 give input to some other job such as a shell merely by moving to a
489 different window. Therefore, suspending is not allowed when Emacs is using
490 a window system (X Windows or MS Windows).
492 @defun suspend-emacs string
493 This function stops Emacs and returns control to the superior process.
494 If and when the superior process resumes Emacs, @code{suspend-emacs}
495 returns @code{nil} to its caller in Lisp.
497 If @var{string} is non-@code{nil}, its characters are sent to be read
498 as terminal input by Emacs's superior shell. The characters in
499 @var{string} are not echoed by the superior shell; only the results
502 Before suspending, @code{suspend-emacs} runs the normal hook
505 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
506 @code{suspend-resume-hook}. @xref{Hooks}.
508 The next redisplay after resumption will redraw the entire screen,
509 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
510 (@pxref{Refresh Screen}).
512 In the following example, note that @samp{pwd} is not echoed after
513 Emacs is suspended. But it is read and executed by the shell.
522 (add-hook 'suspend-hook
526 (error "Suspend cancelled")))))
527 @result{} (lambda nil
528 (or (y-or-n-p "Really suspend? ")
529 (error "Suspend cancelled")))
532 (add-hook 'suspend-resume-hook
533 (function (lambda () (message "Resumed!"))))
534 @result{} (lambda nil (message "Resumed!"))
537 (suspend-emacs "pwd")
541 ---------- Buffer: Minibuffer ----------
542 Really suspend? @kbd{y}
543 ---------- Buffer: Minibuffer ----------
547 ---------- Parent Shell ----------
548 lewis@@slug[23] % /user/lewis/manual
553 ---------- Echo Area ----------
560 This variable is a normal hook that Emacs runs before suspending.
563 @defvar suspend-resume-hook
564 This variable is a normal hook that Emacs runs on resuming
568 @node System Environment
569 @section Operating System Environment
570 @cindex operating system environment
572 Emacs provides access to variables in the operating system environment
573 through various functions. These variables include the name of the
574 system, the user's @sc{uid}, and so on.
576 @defvar system-configuration
577 This variable holds the GNU configuration name for the hardware/software
578 configuration of your system, as a string. The convenient way to test
579 parts of this string is with @code{string-match}.
583 The value of this variable is a symbol indicating the type of operating
584 system Emacs is operating on. Here is a table of the possible values:
597 Data General DGUX operating system.
600 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
603 A GNU/Linux system---that is, a variant GNU system, using the Linux
604 kernel. (These systems are the ones people often call ``Linux,'' but
605 actually Linux is just the kernel, not the whole system.)
608 Hewlett-Packard HPUX operating system.
611 Silicon Graphics Irix system.
614 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
615 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
619 NeXT Mach-based system.
622 Masscomp RTU, UCB universe.
634 Microsoft windows NT. The same executable supports Windows 9X, but the
635 value of @code{system-type} is @code{windows-nt} in either case.
641 We do not wish to add new symbols to make finer distinctions unless it
642 is absolutely necessary! In fact, we hope to eliminate some of these
643 alternatives in the future. We recommend using
644 @code{system-configuration} to distinguish between different operating
649 This function returns the name of the machine you are running on.
652 @result{} "www.gnu.org"
656 The symbol @code{system-name} is a variable as well as a function. In
657 fact, the function returns whatever value the variable
658 @code{system-name} currently holds. Thus, you can set the variable
659 @code{system-name} in case Emacs is confused about the name of your
660 system. The variable is also useful for constructing frame titles
661 (@pxref{Frame Titles}).
663 @defvar mail-host-address
664 If this variable is non-@code{nil}, it is used instead of
665 @code{system-name} for purposes of generating email addresses. For
666 example, it is used when constructing the default value of
667 @code{user-mail-address}. @xref{User Identification}. (Since this is
668 done when Emacs starts up, the value actually used is the one saved when
669 Emacs was dumped. @xref{Building Emacs}.)
673 @cindex environment variable access
674 This function returns the value of the environment variable @var{var},
675 as a string. Within Emacs, the environment variable values are kept in
676 the Lisp variable @code{process-environment}.
685 lewis@@slug[10] % printenv
686 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
698 @deffn Command setenv variable value
699 This command sets the value of the environment variable named
700 @var{variable} to @var{value}. Both arguments should be strings. This
701 function works by modifying @code{process-environment}; binding that
702 variable with @code{let} is also reasonable practice.
705 @defvar process-environment
706 This variable is a list of strings, each describing one environment
707 variable. The functions @code{getenv} and @code{setenv} work by means
713 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
714 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
725 @defvar path-separator
726 This variable holds a string which says which character separates
727 directories in a search path (as found in an environment variable). Its
728 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
732 @defvar invocation-name
733 This variable holds the program name under which Emacs was invoked. The
734 value is a string, and does not include a directory name.
737 @defvar invocation-directory
738 This variable holds the directory from which the Emacs executable was
739 invoked, or perhaps @code{nil} if that directory cannot be determined.
742 @defvar installation-directory
743 If non-@code{nil}, this is a directory within which to look for the
744 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
745 when Emacs can't find those directories in their standard installed
746 locations, but can find them in a directory related somehow to the one
747 containing the Emacs executable.
750 @defun load-average &optional use-float
751 This function returns the current 1-minute, 5-minute, and 15-minute load
754 By default, the values are integers that are 100 times the system load
755 averages, which indicate the average number of processes trying to run.
756 If @var{use-float} is non-@code{nil}, then they are returned
757 as floating point numbers and without multiplying by 100.
762 @result{} (169 48 36)
766 @result{} (1.69 0.48 0.36)
770 lewis@@rocky[5] % uptime
771 11:55am up 1 day, 19:37, 3 users,
772 load average: 1.69, 0.48, 0.36
778 This function returns the process @sc{id} of the Emacs process.
781 @defvar tty-erase-char
782 @tindex tty-erase-char
783 This variable holds the erase character that was selected
784 in the system's terminal driver, before Emacs was started.
787 @defun setprv privilege-name &optional setp getprv
788 This function sets or resets a VMS privilege. (It does not exist on
789 other systems.) The first argument is the privilege name, as a string.
790 The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
791 whether the privilege is to be turned on or off. Its default is
792 @code{nil}. The function returns @code{t} if successful, @code{nil}
795 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
796 does not change the privilege, but returns @code{t} or @code{nil}
797 indicating whether the privilege is currently enabled.
800 @node User Identification
801 @section User Identification
803 @defvar init-file-user
804 This variable says which user's init files should be used by Emacs---or
805 @code{nil} if none. The value reflects command-line options such as
806 @samp{-q} or @samp{-u @var{user}}.
808 Lisp packages that load files of customizations, or any other sort of
809 user profile, should obey this variable in deciding where to find it.
810 They should load the profile of the user name found in this variable.
811 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
812 option was used, then Lisp packages should not load any customization
813 files or user profile.
816 @defvar user-mail-address
817 This holds the nominal email address of the user who is using Emacs.
818 Emacs normally sets this variable to a default value after reading your
819 init files, but not if you have already set it. So you can set the
820 variable to some other value in your init file if you do not
821 want to use the default value.
824 @defun user-login-name &optional uid
825 If you don't specify @var{uid}, this function returns the name under
826 which the user is logged in. If the environment variable @code{LOGNAME}
827 is set, that value is used. Otherwise, if the environment variable
828 @code{USER} is set, that value is used. Otherwise, the value is based
829 on the effective @sc{uid}, not the real @sc{uid}.
831 If you specify @var{uid}, the value is the user name that corresponds
832 to @var{uid} (which should be an integer).
842 @defun user-real-login-name
843 This function returns the user name corresponding to Emacs's real
844 @sc{uid}. This ignores the effective @sc{uid} and ignores the
845 environment variables @code{LOGNAME} and @code{USER}.
848 @defun user-full-name &optional uid
849 This function returns the full name of the logged-in user---or the value
850 of the environment variable @code{NAME}, if that is set.
852 @c "Bil" is the correct spelling.
856 @result{} "Bil Lewis"
860 If the Emacs job's user-id does not correspond to any known user (and
861 provided @code{NAME} is not set), the value is @code{"unknown"}.
863 If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
864 or a string (a login name). Then @code{user-full-name} returns the full
865 name corresponding to that user-id or login name. If you specify a
866 user-id or login name that isn't defined, it returns @code{nil}.
869 @vindex user-full-name
870 @vindex user-real-login-name
871 @vindex user-login-name
872 The symbols @code{user-login-name}, @code{user-real-login-name} and
873 @code{user-full-name} are variables as well as functions. The functions
874 return the same values that the variables hold. These variables allow
875 you to ``fake out'' Emacs by telling the functions what to return. The
876 variables are also useful for constructing frame titles (@pxref{Frame
880 This function returns the real @sc{uid} of the user.
891 This function returns the effective @sc{uid} of the user.
897 This section explains how to determine the current time and the time
900 @defun current-time-string &optional time-value
901 This function returns the current time and date as a human-readable
902 string. The format of the string is unvarying; the number of characters
903 used for each part is always the same, so you can reliably use
904 @code{substring} to extract pieces of it. It is wise to count the
905 characters from the beginning of the string rather than from the end, as
906 additional information may some day be added at the end.
909 The argument @var{time-value}, if given, specifies a time to format
910 instead of the current time. The argument should be a list whose first
911 two elements are integers. Thus, you can use times obtained from
912 @code{current-time} (see below) and from @code{file-attributes}
913 (@pxref{File Attributes}).
917 (current-time-string)
918 @result{} "Wed Oct 14 22:21:05 1987"
925 This function returns the system's time value as a list of three
926 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
927 @var{high} and @var{low} combine to give the number of seconds since
928 0:00 January 1, 1970 (local time), which is
930 @var{high} * 2**16 + @var{low}.
936 The third element, @var{microsec}, gives the microseconds since the
937 start of the current second (or 0 for systems that return time with
938 the resolution of only one second).
940 The first two elements can be compared with file time values such as you
941 get with the function @code{file-attributes}. @xref{File Attributes}.
945 @defun current-time-zone &optional time-value
946 This function returns a list describing the time zone that the user is
949 The value has the form @code{(@var{offset} @var{name})}. Here
950 @var{offset} is an integer giving the number of seconds ahead of UTC
951 (east of Greenwich). A negative value means west of Greenwich. The
952 second element, @var{name}, is a string giving the name of the time
953 zone. Both elements change when daylight savings time begins or ends;
954 if the user has specified a time zone that does not use a seasonal time
955 adjustment, then the value is constant through time.
957 If the operating system doesn't supply all the information necessary to
958 compute the value, both elements of the list are @code{nil}.
960 The argument @var{time-value}, if given, specifies a time to analyze
961 instead of the current time. The argument should be a cons cell
962 containing two integers, or a list whose first two elements are
963 integers. Thus, you can use times obtained from @code{current-time}
964 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
967 @node Time Conversion
968 @section Time Conversion
970 These functions convert time values (lists of two or three integers)
971 to strings or to calendrical information. There is also a function to
972 convert calendrical information to a time value. You can get time
973 values from the functions @code{current-time} (@pxref{Time of Day}) and
974 @code{file-attributes} (@pxref{File Attributes}).
976 Many operating systems are limited to time values that contain 32 bits
977 of information; these systems typically handle only the times from
978 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
979 operating systems have larger time values, and can represent times far
980 in the past or future.
982 Time conversion functions always use the Gregorian calendar, even for
983 dates before the Gregorian calendar was introduced. Year numbers count
984 the number of years since the year 1 B.C., and do not skip zero as
985 traditional Gregorian years do; for example, the year number @minus{}37
986 represents the Gregorian year 38 B.C@.
988 @defun format-time-string format-string &optional time universal
989 This function converts @var{time} (or the current time, if @var{time} is
990 omitted) to a string according to @var{format-string}. The argument
991 @var{format-string} may contain @samp{%}-sequences which say to
992 substitute parts of the time. Here is a table of what the
993 @samp{%}-sequences mean:
997 This stands for the abbreviated name of the day of week.
999 This stands for the full name of the day of week.
1001 This stands for the abbreviated name of the month.
1003 This stands for the full name of the month.
1005 This is a synonym for @samp{%x %X}.
1007 This has a locale-specific meaning. In the default locale (named C), it
1008 is equivalent to @samp{%A, %B %e, %Y}.
1010 This stands for the day of month, zero-padded.
1012 This is a synonym for @samp{%m/%d/%y}.
1014 This stands for the day of month, blank-padded.
1016 This is a synonym for @samp{%b}.
1018 This stands for the hour (00-23).
1020 This stands for the hour (01-12).
1022 This stands for the day of the year (001-366).
1024 This stands for the hour (0-23), blank padded.
1026 This stands for the hour (1-12), blank padded.
1028 This stands for the month (01-12).
1030 This stands for the minute (00-59).
1032 This stands for a newline.
1034 This stands for @samp{AM} or @samp{PM}, as appropriate.
1036 This is a synonym for @samp{%I:%M:%S %p}.
1038 This is a synonym for @samp{%H:%M}.
1040 This stands for the seconds (00-59).
1042 This stands for a tab character.
1044 This is a synonym for @samp{%H:%M:%S}.
1046 This stands for the week of the year (01-52), assuming that weeks
1049 This stands for the numeric day of week (0-6). Sunday is day 0.
1051 This stands for the week of the year (01-52), assuming that weeks
1054 This has a locale-specific meaning. In the default locale (named
1055 @samp{C}), it is equivalent to @samp{%D}.
1057 This has a locale-specific meaning. In the default locale (named
1058 @samp{C}), it is equivalent to @samp{%T}.
1060 This stands for the year without century (00-99).
1062 This stands for the year with century.
1064 This stands for the time zone abbreviation.
1067 You can also specify the field width and type of padding for any of
1068 these @samp{%}-sequences. This works as in @code{printf}: you write
1069 the field width as digits in the middle of a @samp{%}-sequences. If you
1070 start the field width with @samp{0}, it means to pad with zeros. If you
1071 start the field width with @samp{_}, it means to pad with spaces.
1073 For example, @samp{%S} specifies the number of seconds since the minute;
1074 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1075 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1076 because that is how @samp{%S} normally pads to two positions.
1078 The characters @samp{E} and @samp{O} act as modifiers when used between
1079 @samp{%} and one of the letters in the table above. @samp{E} specifies
1080 using the current locale's ``alternative'' version of the date and time.
1081 In a Japanese locale, for example, @code{%Ex} might yield a date format
1082 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1083 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1086 @samp{O} means to use the current locale's ``alternative''
1087 representation of numbers, instead of the ordinary decimal digits. This
1088 is allowed with most letters, all the ones that output numbers.
1090 If @var{universal} is non-@code{nil}, that means to describe the time as
1091 Universal Time; @code{nil} means describe it using what Emacs believes
1092 is the local time zone (see @code{current-time-zone}).
1095 @defun decode-time time
1096 This function converts a time value into calendrical information. The
1097 return value is a list of nine elements, as follows:
1100 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1103 Here is what the elements mean:
1107 The number of seconds past the minute, as an integer between 0 and 59.
1109 The number of minutes past the hour, as an integer between 0 and 59.
1111 The hour of the day, as an integer between 0 and 23.
1113 The day of the month, as an integer between 1 and 31.
1115 The month of the year, as an integer between 1 and 12.
1117 The year, an integer typically greater than 1900.
1119 The day of week, as an integer between 0 and 6, where 0 stands for
1122 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1124 An integer indicating the time zone, as the number of seconds east of
1128 @strong{Common Lisp Note:} Common Lisp has different meanings for
1129 @var{dow} and @var{zone}.
1132 @defun encode-time seconds minutes hour day month year &optional @dots{}zone
1133 This function is the inverse of @code{decode-time}. It converts seven
1134 items of calendrical data into a time value. For the meanings of the
1135 arguments, see the table above under @code{decode-time}.
1137 Year numbers less than 100 are not treated specially. If you want them
1138 to stand for years above 1900, you must alter them yourself before you
1139 call @code{encode-time}.
1141 The optional argument @var{zone} defaults to the current time zone and
1142 its daylight savings time rules. If specified, it can be either a list
1143 (as you would get from @code{current-time-zone}), a string as in the
1144 @code{TZ} environment variable, or an integer (as you would get from
1145 @code{decode-time}). The specified zone is used without any further
1146 alteration for daylight savings time.
1148 If you pass more than seven arguments to @code{encode-time}, the first
1149 six are used as @var{seconds} through @var{year}, the last argument is
1150 used as @var{zone}, and the arguments in between are ignored. This
1151 feature makes it possible to use the elements of a list returned by
1152 @code{decode-time} as the arguments to @code{encode-time}, like this:
1155 (apply 'encode-time (decode-time @dots{}))
1158 You can perform simple date arithmetic by using out-of-range values for
1159 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1160 arguments; for example, day 0 means the day preceding the given month.
1162 The operating system puts limits on the range of possible time values;
1163 if you try to encode a time that is out of range, an error results.
1167 @section Timers for Delayed Execution
1170 You can set up a @dfn{timer} to call a function at a specified future time or
1171 after a certain length of idleness.
1173 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1174 can run them only when Emacs could accept output from a subprocess:
1175 namely, while waiting or inside certain primitive functions such as
1176 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1177 timer's execution may be delayed if Emacs is busy. However, the time of
1178 execution is very precise if Emacs is idle.
1180 @defun run-at-time time repeat function &rest args
1181 This function arranges to call @var{function} with arguments @var{args}
1182 at time @var{time}. The argument @var{function} is a function to call
1183 later, and @var{args} are the arguments to give it when it is called.
1184 The time @var{time} is specified as a string.
1186 Absolute times may be specified in a wide variety of formats; this
1187 function tries to accept all the commonly used date formats. Valid
1188 formats include these two,
1191 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
1193 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
1197 where in both examples all fields are numbers; the format that
1198 @code{current-time-string} returns is also allowed, and many others
1201 To specify a relative time, use numbers followed by units.
1206 denotes 1 minute from now.
1208 denotes 65 seconds from now.
1209 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1210 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1213 For relative time values, Emacs considers a month to be exactly thirty
1214 days, and a year to be exactly 365.25 days.
1216 If @var{time} is a number (integer or floating point), that specifies a
1217 relative time measured in seconds.
1219 The argument @var{repeat} specifies how often to repeat the call. If
1220 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
1221 called just once, at @var{time}. If @var{repeat} is a number, it
1222 specifies a repetition period measured in seconds.
1224 In most cases, @var{repeat} has no effect on when @emph{first} call
1225 takes place---@var{time} alone specifies that. There is one exception:
1226 if @var{time} is @code{t}, then the timer runs whenever the time is a
1227 multiple of @var{repeat} seconds after the epoch. This is useful for
1228 functions like @code{display-time}.
1230 The function @code{run-at-time} returns a timer value that identifies
1231 the particular scheduled future action. You can use this value to call
1232 @code{cancel-timer} (see below).
1235 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1236 Execute @var{body}, but give up after @var{seconds} seconds. If
1237 @var{body} finishes before the time is up, @code{with-timeout} returns
1238 the value of the last form in @var{body}. If, however, the execution of
1239 @var{body} is cut short by the timeout, then @code{with-timeout}
1240 executes all the @var{timeout-forms} and returns the value of the last
1243 This macro works by setting a timer to run after @var{seconds} seconds. If
1244 @var{body} finishes before that time, it cancels the timer. If the
1245 timer actually runs, it terminates execution of @var{body}, then
1246 executes @var{timeout-forms}.
1248 Since timers can run within a Lisp program only when the program calls a
1249 primitive that can wait, @code{with-timeout} cannot stop executing
1250 @var{body} while it is in the midst of a computation---only when it
1251 calls one of those primitives. So use @code{with-timeout} only with a
1252 @var{body} that waits for input, not one that does a long computation.
1255 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1256 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1259 @defun run-with-idle-timer secs repeat function &rest args
1260 Set up a timer which runs when Emacs has been idle for @var{secs}
1261 seconds. The value of @var{secs} may be an integer or a floating point
1264 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1265 Emacs remains idle for a long enough time. More often @var{repeat} is
1266 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1267 remains idle for @var{secs} seconds.
1269 The function @code{run-with-idle-timer} returns a timer value which you
1270 can use in calling @code{cancel-timer} (see below).
1274 Emacs becomes ``idle'' when it starts waiting for user input, and it
1275 remains idle until the user provides some input. If a timer is set for
1276 five seconds of idleness, it runs approximately five seconds after Emacs
1277 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1278 will not run again as long as Emacs remains idle, because the duration
1279 of idleness will continue to increase and will not go down to five
1282 Emacs can do various things while idle: garbage collect, autosave or
1283 handle data from a subprocess. But these interludes during idleness do
1284 not interfere with idle timers, because they do not reset the clock of
1285 idleness to zero. An idle timer set for 600 seconds will run when ten
1286 minutes have elapsed since the last user command was finished, even if
1287 subprocess output has been accepted thousands of times within those ten
1288 minutes, and even if there have been garbage collections and autosaves.
1290 When the user supplies input, Emacs becomes non-idle while executing the
1291 input. Then it becomes idle again, and all the idle timers that are
1292 set up to repeat will subsequently run another time, one by one.
1294 @defun cancel-timer timer
1295 Cancel the requested action for @var{timer}, which should be a value
1296 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
1297 This cancels the effect of that call to @code{run-at-time}; the arrival
1298 of the specified time will not cause anything special to happen.
1301 @node Terminal Input
1302 @section Terminal Input
1303 @cindex terminal input
1305 This section describes functions and variables for recording or
1306 manipulating terminal input. See @ref{Display}, for related
1310 * Input Modes:: Options for how input is processed.
1311 * Translating Input:: Low level conversion of some characters or events
1313 * Recording Input:: Saving histories of recent or all input events.
1317 @subsection Input Modes
1319 @cindex terminal input modes
1321 @defun set-input-mode interrupt flow meta quit-char
1322 This function sets the mode for reading keyboard input. If
1323 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1324 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1325 system-dependent. Some systems always use @sc{cbreak} mode regardless
1326 of what is specified.
1328 When Emacs communicates directly with X, it ignores this argument and
1329 uses interrupts if that is the way it knows how to communicate.
1331 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1332 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1333 has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
1336 The argument @var{meta} controls support for input character codes
1337 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1338 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1339 Emacs disregards the 8th bit; this is necessary when the terminal uses
1340 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1341 Emacs uses all 8 bits of input unchanged. This is good for terminals
1342 that use 8-bit character sets.
1345 If @var{quit-char} is non-@code{nil}, it specifies the character to
1346 use for quitting. Normally this character is @kbd{C-g}.
1350 The @code{current-input-mode} function returns the input mode settings
1351 Emacs is currently using.
1354 @defun current-input-mode
1355 This function returns the current mode for reading keyboard input. It
1356 returns a list, corresponding to the arguments of @code{set-input-mode},
1357 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1361 is non-@code{nil} when Emacs is using interrupt-driven input. If
1362 @code{nil}, Emacs is using @sc{cbreak} mode.
1364 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1365 flow control for output to the terminal. This value is meaningful only
1366 when @var{interrupt} is @code{nil}.
1368 is @code{t} if Emacs treats the eighth bit of input characters as
1369 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1370 input character; any other value means Emacs uses all eight bits as the
1371 basic character code.
1373 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1377 @node Translating Input
1378 @subsection Translating Input Events
1379 @cindex translating input events
1381 This section describes features for translating input events into
1382 other input events before they become part of key sequences. These
1383 features apply to each event in the order they are described here: each
1384 event is first modified according to @code{extra-keyboard-modifiers},
1385 then translated through @code{keyboard-translate-table} (if applicable),
1386 and finally decoded with the specified keyboard coding system. If it is
1387 being read as part of a key sequence, it is then added to the sequence
1388 being read; then subsequences containing it are checked first with
1389 @code{function-key-map} and then with @code{key-translation-map}.
1392 @defvar extra-keyboard-modifiers
1393 This variable lets Lisp programs ``press'' the modifier keys on the
1394 keyboard. The value is a bit mask:
1398 The @key{SHIFT} key.
1407 Each time the user types a keyboard key, it is altered as if the
1408 modifier keys specified in the bit mask were held down.
1410 When using a window system, the program can ``press'' any of the
1411 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
1412 keys can be virtually pressed.
1415 @defvar keyboard-translate-table
1416 This variable is the translate table for keyboard characters. It lets
1417 you reshuffle the keys on the keyboard without changing any command
1418 bindings. Its value is normally a char-table, or else @code{nil}.
1420 If @code{keyboard-translate-table} is a char-table
1421 (@pxref{Char-Tables}), then each character read from the keyboard is
1422 looked up in this char-table. If the value found there is
1423 non-@code{nil}, then it is used instead of the actual input character.
1425 In the example below, we set @code{keyboard-translate-table} to a
1426 char-table. Then we fill it in to swap the characters @kbd{C-s} and
1427 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
1428 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
1429 versa. (@xref{Flow Control}, for more information on this subject.)
1431 @cindex flow control example
1434 (defun evade-flow-control ()
1435 "Replace C-s with C-\ and C-q with C-^."
1439 (setq keyboard-translate-table
1440 (make-char-table 'keyboard-translate-table nil))
1443 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1444 (aset keyboard-translate-table ?\034 ?\^s)
1445 (aset keyboard-translate-table ?\^s ?\034)
1448 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1449 (aset keyboard-translate-table ?\036 ?\^q)
1450 (aset keyboard-translate-table ?\^q ?\036))
1454 Note that this translation is the first thing that happens to a
1455 character after it is read from the terminal. Record-keeping features
1456 such as @code{recent-keys} and dribble files record the characters after
1460 @defun keyboard-translate from to
1461 This function modifies @code{keyboard-translate-table} to translate
1462 character code @var{from} into character code @var{to}. It creates
1463 the keyboard translate table if necessary.
1466 The remaining translation features translate subsequences of key
1467 sequences being read. They are implemented in @code{read-key-sequence}
1468 and have no effect on input read with @code{read-event}.
1470 @defvar function-key-map
1471 This variable holds a keymap that describes the character sequences sent
1472 by function keys on an ordinary character terminal. This keymap has the
1473 same structure as other keymaps, but is used differently: it specifies
1474 translations to make while reading key sequences, rather than bindings
1477 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1478 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1479 key sequence, it is replaced with the events in @var{v}.
1481 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1482 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
1483 that sequence of events into the single event @code{pf1}. We accomplish
1484 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1485 @code{function-key-map}, when using a VT100.
1487 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1488 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1489 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1492 Entries in @code{function-key-map} are ignored if they conflict with
1493 bindings made in the minor mode, local, or global keymaps. The intent
1494 is that the character sequences that function keys send should not have
1495 command bindings in their own right---but if they do, the ordinary
1496 bindings take priority.
1498 The value of @code{function-key-map} is usually set up automatically
1499 according to the terminal's Terminfo or Termcap entry, but sometimes
1500 those need help from terminal-specific Lisp files. Emacs comes with
1501 terminal-specific files for many common terminals; their main purpose is
1502 to make entries in @code{function-key-map} beyond those that can be
1503 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1506 @defvar key-translation-map
1507 This variable is another keymap used just like @code{function-key-map}
1508 to translate input events into other events. It differs from
1509 @code{function-key-map} in two ways:
1513 @code{key-translation-map} goes to work after @code{function-key-map} is
1514 finished; it receives the results of translation by
1515 @code{function-key-map}.
1518 @code{key-translation-map} overrides actual key bindings. For example,
1519 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
1520 translation takes effect even though @kbd{C-x f} also has a key binding
1524 The intent of @code{key-translation-map} is for users to map one
1525 character set to another, including ordinary characters normally bound
1526 to @code{self-insert-command}.
1529 @cindex key translation function
1530 You can use @code{function-key-map} or @code{key-translation-map} for
1531 more than simple aliases, by using a function, instead of a key
1532 sequence, as the ``translation'' of a key. Then this function is called
1533 to compute the translation of that key.
1535 The key translation function receives one argument, which is the prompt
1536 that was specified in @code{read-key-sequence}---or @code{nil} if the
1537 key sequence is being read by the editor command loop. In most cases
1538 you can ignore the prompt value.
1540 If the function reads input itself, it can have the effect of altering
1541 the event that follows. For example, here's how to define @kbd{C-c h}
1542 to turn the character that follows into a Hyper character:
1546 (defun hyperify (prompt)
1547 (let ((e (read-event)))
1548 (vector (if (numberp e)
1549 (logior (lsh 1 24) e)
1550 (if (memq 'hyper (event-modifiers e))
1552 (add-event-modifier "H-" e))))))
1554 (defun add-event-modifier (string e)
1555 (let ((symbol (if (symbolp e) e (car e))))
1556 (setq symbol (intern (concat string
1557 (symbol-name symbol))))
1562 (cons symbol (cdr e)))))
1564 (define-key function-key-map "\C-ch" 'hyperify)
1568 Finally, if you have enabled keyboard character set decoding using
1569 @code{set-keyboard-coding-system}, decoding is done after the
1570 translations listed above. @xref{Specifying Coding Systems}. In future
1571 Emacs versions, character set decoding may be done before the other
1574 @node Recording Input
1575 @subsection Recording Input
1578 This function returns a vector containing the last 100 input events from
1579 the keyboard or mouse. All input events are included, whether or not
1580 they were used as parts of key sequences. Thus, you always get the last
1581 100 input events, not counting events generated by keyboard macros.
1582 (These are excluded because they are less interesting for debugging; it
1583 should be enough to see the events that invoked the macros.)
1586 @deffn Command open-dribble-file filename
1587 @cindex dribble file
1588 This function opens a @dfn{dribble file} named @var{filename}. When a
1589 dribble file is open, each input event from the keyboard or mouse (but
1590 not those from keyboard macros) is written in that file. A
1591 non-character event is expressed using its printed representation
1592 surrounded by @samp{<@dots{}>}.
1594 You close the dribble file by calling this function with an argument
1597 This function is normally used to record the input necessary to
1598 trigger an Emacs bug, for the sake of a bug report.
1602 (open-dribble-file "~/dribble")
1608 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1610 @node Terminal Output
1611 @section Terminal Output
1612 @cindex terminal output
1614 The terminal output functions send output to the terminal, or keep
1615 track of output sent to the terminal. The variable @code{baud-rate}
1616 tells you what Emacs thinks is the output speed of the terminal.
1619 This variable's value is the output speed of the terminal, as far as
1620 Emacs knows. Setting this variable does not change the speed of actual
1621 data transmission, but the value is used for calculations such as
1622 padding. It also affects decisions about whether to scroll part of the
1623 screen or repaint---even when using a window system. (We designed it
1624 this way despite the fact that a window system has no true ``output
1625 speed'', to give you a way to tune these decisions.)
1627 The value is measured in baud.
1630 If you are running across a network, and different parts of the
1631 network work at different baud rates, the value returned by Emacs may be
1632 different from the value used by your local terminal. Some network
1633 protocols communicate the local terminal speed to the remote machine, so
1634 that Emacs and other programs can get the proper value, but others do
1635 not. If Emacs has the wrong value, it makes decisions that are less
1636 than optimal. To fix the problem, set @code{baud-rate}.
1639 This obsolete function returns the value of the variable
1643 @defun send-string-to-terminal string
1644 This function sends @var{string} to the terminal without alteration.
1645 Control characters in @var{string} have terminal-dependent effects.
1647 One use of this function is to define function keys on terminals that
1648 have downloadable function key definitions. For example, this is how (on
1649 certain terminals) to define function key 4 to move forward four
1650 characters (by transmitting the characters @kbd{C-u C-f} to the
1655 (send-string-to-terminal "\eF4\^U\^F")
1661 @deffn Command open-termscript filename
1662 @cindex termscript file
1663 This function is used to open a @dfn{termscript file} that will record
1664 all the characters sent by Emacs to the terminal. It returns
1665 @code{nil}. Termscript files are useful for investigating problems
1666 where Emacs garbles the screen, problems that are due to incorrect
1667 Termcap entries or to undesirable settings of terminal options more
1668 often than to actual Emacs bugs. Once you are certain which characters
1669 were actually output, you can determine reliably whether they correspond
1670 to the Termcap specifications in use.
1672 See also @code{open-dribble-file} in @ref{Terminal Input}.
1676 (open-termscript "../junk/termscript")
1683 @section Sound Output
1686 To play sound using Emacs, use the function @code{play-sound}. Only
1687 certain systems are supported; if you call @code{play-sound} on a system
1688 which cannot really do the job, it gives an error. Emacs version 20 and
1689 earlier did not support sound at all.
1691 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1692 or Sun Audio format (@samp{.au}).
1695 @defun play-sound sound
1696 This function plays a specified sound. The argument, @var{sound}, has
1697 the form @code{(sound @var{properties}...)}, where the @var{properties}
1698 consist of alternating keywords (particular symbols recognized
1699 specially) and values corresponding to them.
1701 Here is a table of the keywords that are currently meaningful in
1702 @var{sound}, and their meanings:
1705 @item :file @var{file}
1706 This specifies the file containing the sound to play.
1707 If the file name is not absolute, it is expanded against
1708 the directory @code{data-directory}.
1710 @item :volume @var{volume}
1711 This specifies how loud to play the sound. It should be a number in the
1712 range of 0 to 1. The default is to use whatever volume has been
1716 Before actually playing the sound, @code{play-sound}
1717 calls the functions in the list @code{play-sound-functions}.
1718 Each function is called with one argument, @var{sound}.
1721 @tindex play-sound-functions
1722 @defvar play-sound-functions
1723 A list of functions to be called before playing a sound. Each function
1724 is called with one argument, a property list that describes the sound.
1727 @node Special Keysyms
1728 @section System-Specific X11 Keysyms
1730 To define system-specific X11 keysyms, set the variable
1731 @code{system-key-alist}.
1733 @defvar system-key-alist
1734 This variable's value should be an alist with one element for each
1735 system-specific keysym. Each element has the form @code{(@var{code}
1736 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1737 including the ``vendor specific'' bit,
1744 and @var{symbol} is the name for the function key.
1746 For example @code{(168 . mute-acute)} defines a system-specific key (used
1747 by HP X servers) whose numeric code is
1756 It is not crucial to exclude from the alist the keysyms of other X
1757 servers; those do no harm, as long as they don't conflict with the ones
1758 used by the X server actually in use.
1760 The variable is always local to the current terminal, and cannot be
1761 buffer-local. @xref{Multiple Displays}.
1765 @section Flow Control
1766 @cindex flow control characters
1768 This section attempts to answer the question ``Why does Emacs use
1769 flow-control characters in its command character set?'' For a second
1770 view on this issue, read the comments on flow control in the
1771 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1772 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1776 At one time, most terminals did not need flow control, and none used
1777 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1778 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
1779 was natural and uncontroversial. With so many commands needing key
1780 assignments, of course we assigned meanings to nearly all @sc{ascii}
1783 Later, some terminals were introduced which required these characters
1784 for flow control. They were not very good terminals for full-screen
1785 editing, so Emacs maintainers ignored them. In later years, flow
1786 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
1787 but by this time it was usually an option. And the majority of Emacs
1788 users, who can turn flow control off, did not want to switch to less
1789 mnemonic key bindings for the sake of flow control.
1791 So which usage is ``right''---Emacs's or that of some terminal and
1792 concentrator manufacturers? This question has no simple answer.
1794 One reason why we are reluctant to cater to the problems caused by
1795 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1796 techniques (albeit less common in practice) for flow control that
1797 preserve transparency of the character stream. Note also that their use
1798 for flow control is not an official standard. Interestingly, on the
1799 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
1800 @kbd{C-q} were sent by the computer to turn the punch on and off!
1802 As window systems and PC terminal emulators replace character-only
1803 terminals, the flow control problem is gradually disappearing. For the
1804 mean time, Emacs provides a convenient way of enabling flow control if
1805 you want it: call the function @code{enable-flow-control}.
1807 @deffn Command enable-flow-control
1808 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1809 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1810 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1813 You can use the function @code{enable-flow-control-on} in your
1814 init file to enable flow control automatically on certain
1817 @defun enable-flow-control-on &rest termtypes
1818 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1819 if the terminal type is one of @var{termtypes}. For example:
1822 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1826 Here is how @code{enable-flow-control} does its job:
1831 It sets @sc{cbreak} mode for terminal input, and tells the operating
1832 system to handle flow control, with @code{(set-input-mode nil t)}.
1835 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1836 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1837 lowest level, Emacs never knows that the characters typed were anything
1838 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1839 and @kbd{C-^} even when they are input for other commands.
1840 @xref{Translating Input}.
1843 If the terminal is the source of the flow control characters, then once
1844 you enable kernel flow control handling, you probably can make do with
1845 less padding than normal for that terminal. You can reduce the amount
1846 of padding by customizing the Termcap entry. You can also reduce it by
1847 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1848 speed when calculating the padding needed. @xref{Terminal Output}.
1853 @cindex noninteractive use
1855 The command-line option @samp{-batch} causes Emacs to run
1856 noninteractively. In this mode, Emacs does not read commands from the
1857 terminal, it does not alter the terminal modes, and it does not expect
1858 to be outputting to an erasable screen. The idea is that you specify
1859 Lisp programs to run; when they are finished, Emacs should exit. The
1860 way to specify the programs to run is with @samp{-l @var{file}}, which
1861 loads the library named @var{file}, and @samp{-f @var{function}}, which
1862 calls @var{function} with no arguments.
1864 Any Lisp program output that would normally go to the echo area,
1865 either using @code{message}, or using @code{prin1}, etc., with @code{t}
1866 as the stream, goes instead to Emacs's standard error descriptor when
1867 in batch mode. Thus, Emacs behaves much like a noninteractive
1868 application program. (The echo area output that Emacs itself normally
1869 generates, such as command echoing, is suppressed entirely.)
1871 @defvar noninteractive
1872 This variable is non-@code{nil} when Emacs is running in batch mode.