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}).
1094 This function uses the C library function @code{strftime} to do most of
1095 the work. In order to communicate with that function, it first encodes
1096 its argument using the coding system specified by
1097 @code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
1098 returns the resulting string, @code{format-time-string} decodes the
1099 string using that same coding system.
1102 @defun decode-time time
1103 This function converts a time value into calendrical information. The
1104 return value is a list of nine elements, as follows:
1107 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1110 Here is what the elements mean:
1114 The number of seconds past the minute, as an integer between 0 and 59.
1116 The number of minutes past the hour, as an integer between 0 and 59.
1118 The hour of the day, as an integer between 0 and 23.
1120 The day of the month, as an integer between 1 and 31.
1122 The month of the year, as an integer between 1 and 12.
1124 The year, an integer typically greater than 1900.
1126 The day of week, as an integer between 0 and 6, where 0 stands for
1129 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1131 An integer indicating the time zone, as the number of seconds east of
1135 @strong{Common Lisp Note:} Common Lisp has different meanings for
1136 @var{dow} and @var{zone}.
1139 @defun encode-time seconds minutes hour day month year &optional @dots{}zone
1140 This function is the inverse of @code{decode-time}. It converts seven
1141 items of calendrical data into a time value. For the meanings of the
1142 arguments, see the table above under @code{decode-time}.
1144 Year numbers less than 100 are not treated specially. If you want them
1145 to stand for years above 1900, you must alter them yourself before you
1146 call @code{encode-time}.
1148 The optional argument @var{zone} defaults to the current time zone and
1149 its daylight savings time rules. If specified, it can be either a list
1150 (as you would get from @code{current-time-zone}), a string as in the
1151 @code{TZ} environment variable, or an integer (as you would get from
1152 @code{decode-time}). The specified zone is used without any further
1153 alteration for daylight savings time.
1155 If you pass more than seven arguments to @code{encode-time}, the first
1156 six are used as @var{seconds} through @var{year}, the last argument is
1157 used as @var{zone}, and the arguments in between are ignored. This
1158 feature makes it possible to use the elements of a list returned by
1159 @code{decode-time} as the arguments to @code{encode-time}, like this:
1162 (apply 'encode-time (decode-time @dots{}))
1165 You can perform simple date arithmetic by using out-of-range values for
1166 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1167 arguments; for example, day 0 means the day preceding the given month.
1169 The operating system puts limits on the range of possible time values;
1170 if you try to encode a time that is out of range, an error results.
1174 @section Timers for Delayed Execution
1177 You can set up a @dfn{timer} to call a function at a specified future time or
1178 after a certain length of idleness.
1180 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1181 can run them only when Emacs could accept output from a subprocess:
1182 namely, while waiting or inside certain primitive functions such as
1183 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1184 timer's execution may be delayed if Emacs is busy. However, the time of
1185 execution is very precise if Emacs is idle.
1187 @defun run-at-time time repeat function &rest args
1188 This function arranges to call @var{function} with arguments @var{args}
1189 at time @var{time}. The argument @var{function} is a function to call
1190 later, and @var{args} are the arguments to give it when it is called.
1191 The time @var{time} is specified as a string.
1193 Absolute times may be specified in a wide variety of formats; this
1194 function tries to accept all the commonly used date formats. Valid
1195 formats include these two,
1198 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
1200 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
1204 where in both examples all fields are numbers; the format that
1205 @code{current-time-string} returns is also allowed, and many others
1208 To specify a relative time, use numbers followed by units.
1213 denotes 1 minute from now.
1215 denotes 65 seconds from now.
1216 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1217 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1220 For relative time values, Emacs considers a month to be exactly thirty
1221 days, and a year to be exactly 365.25 days.
1223 If @var{time} is a number (integer or floating point), that specifies a
1224 relative time measured in seconds.
1226 The argument @var{repeat} specifies how often to repeat the call. If
1227 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
1228 called just once, at @var{time}. If @var{repeat} is a number, it
1229 specifies a repetition period measured in seconds.
1231 In most cases, @var{repeat} has no effect on when @emph{first} call
1232 takes place---@var{time} alone specifies that. There is one exception:
1233 if @var{time} is @code{t}, then the timer runs whenever the time is a
1234 multiple of @var{repeat} seconds after the epoch. This is useful for
1235 functions like @code{display-time}.
1237 The function @code{run-at-time} returns a timer value that identifies
1238 the particular scheduled future action. You can use this value to call
1239 @code{cancel-timer} (see below).
1242 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1243 Execute @var{body}, but give up after @var{seconds} seconds. If
1244 @var{body} finishes before the time is up, @code{with-timeout} returns
1245 the value of the last form in @var{body}. If, however, the execution of
1246 @var{body} is cut short by the timeout, then @code{with-timeout}
1247 executes all the @var{timeout-forms} and returns the value of the last
1250 This macro works by setting a timer to run after @var{seconds} seconds. If
1251 @var{body} finishes before that time, it cancels the timer. If the
1252 timer actually runs, it terminates execution of @var{body}, then
1253 executes @var{timeout-forms}.
1255 Since timers can run within a Lisp program only when the program calls a
1256 primitive that can wait, @code{with-timeout} cannot stop executing
1257 @var{body} while it is in the midst of a computation---only when it
1258 calls one of those primitives. So use @code{with-timeout} only with a
1259 @var{body} that waits for input, not one that does a long computation.
1262 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1263 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1266 @defun run-with-idle-timer secs repeat function &rest args
1267 Set up a timer which runs when Emacs has been idle for @var{secs}
1268 seconds. The value of @var{secs} may be an integer or a floating point
1271 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1272 Emacs remains idle for a long enough time. More often @var{repeat} is
1273 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1274 remains idle for @var{secs} seconds.
1276 The function @code{run-with-idle-timer} returns a timer value which you
1277 can use in calling @code{cancel-timer} (see below).
1281 Emacs becomes ``idle'' when it starts waiting for user input, and it
1282 remains idle until the user provides some input. If a timer is set for
1283 five seconds of idleness, it runs approximately five seconds after Emacs
1284 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1285 will not run again as long as Emacs remains idle, because the duration
1286 of idleness will continue to increase and will not go down to five
1289 Emacs can do various things while idle: garbage collect, autosave or
1290 handle data from a subprocess. But these interludes during idleness do
1291 not interfere with idle timers, because they do not reset the clock of
1292 idleness to zero. An idle timer set for 600 seconds will run when ten
1293 minutes have elapsed since the last user command was finished, even if
1294 subprocess output has been accepted thousands of times within those ten
1295 minutes, and even if there have been garbage collections and autosaves.
1297 When the user supplies input, Emacs becomes non-idle while executing the
1298 input. Then it becomes idle again, and all the idle timers that are
1299 set up to repeat will subsequently run another time, one by one.
1301 @defun cancel-timer timer
1302 Cancel the requested action for @var{timer}, which should be a value
1303 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
1304 This cancels the effect of that call to @code{run-at-time}; the arrival
1305 of the specified time will not cause anything special to happen.
1308 @node Terminal Input
1309 @section Terminal Input
1310 @cindex terminal input
1312 This section describes functions and variables for recording or
1313 manipulating terminal input. See @ref{Display}, for related
1317 * Input Modes:: Options for how input is processed.
1318 * Translating Input:: Low level conversion of some characters or events
1320 * Recording Input:: Saving histories of recent or all input events.
1324 @subsection Input Modes
1326 @cindex terminal input modes
1328 @defun set-input-mode interrupt flow meta quit-char
1329 This function sets the mode for reading keyboard input. If
1330 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1331 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1332 system-dependent. Some systems always use @sc{cbreak} mode regardless
1333 of what is specified.
1335 When Emacs communicates directly with X, it ignores this argument and
1336 uses interrupts if that is the way it knows how to communicate.
1338 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1339 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1340 has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
1343 The argument @var{meta} controls support for input character codes
1344 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1345 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1346 Emacs disregards the 8th bit; this is necessary when the terminal uses
1347 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1348 Emacs uses all 8 bits of input unchanged. This is good for terminals
1349 that use 8-bit character sets.
1352 If @var{quit-char} is non-@code{nil}, it specifies the character to
1353 use for quitting. Normally this character is @kbd{C-g}.
1357 The @code{current-input-mode} function returns the input mode settings
1358 Emacs is currently using.
1361 @defun current-input-mode
1362 This function returns the current mode for reading keyboard input. It
1363 returns a list, corresponding to the arguments of @code{set-input-mode},
1364 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1368 is non-@code{nil} when Emacs is using interrupt-driven input. If
1369 @code{nil}, Emacs is using @sc{cbreak} mode.
1371 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1372 flow control for output to the terminal. This value is meaningful only
1373 when @var{interrupt} is @code{nil}.
1375 is @code{t} if Emacs treats the eighth bit of input characters as
1376 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1377 input character; any other value means Emacs uses all eight bits as the
1378 basic character code.
1380 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1384 @node Translating Input
1385 @subsection Translating Input Events
1386 @cindex translating input events
1388 This section describes features for translating input events into
1389 other input events before they become part of key sequences. These
1390 features apply to each event in the order they are described here: each
1391 event is first modified according to @code{extra-keyboard-modifiers},
1392 then translated through @code{keyboard-translate-table} (if applicable),
1393 and finally decoded with the specified keyboard coding system. If it is
1394 being read as part of a key sequence, it is then added to the sequence
1395 being read; then subsequences containing it are checked first with
1396 @code{function-key-map} and then with @code{key-translation-map}.
1399 @defvar extra-keyboard-modifiers
1400 This variable lets Lisp programs ``press'' the modifier keys on the
1401 keyboard. The value is a bit mask:
1405 The @key{SHIFT} key.
1414 Each time the user types a keyboard key, it is altered as if the
1415 modifier keys specified in the bit mask were held down.
1417 When using a window system, the program can ``press'' any of the
1418 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
1419 keys can be virtually pressed.
1422 @defvar keyboard-translate-table
1423 This variable is the translate table for keyboard characters. It lets
1424 you reshuffle the keys on the keyboard without changing any command
1425 bindings. Its value is normally a char-table, or else @code{nil}.
1427 If @code{keyboard-translate-table} is a char-table
1428 (@pxref{Char-Tables}), then each character read from the keyboard is
1429 looked up in this char-table. If the value found there is
1430 non-@code{nil}, then it is used instead of the actual input character.
1432 In the example below, we set @code{keyboard-translate-table} to a
1433 char-table. Then we fill it in to swap the characters @kbd{C-s} and
1434 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
1435 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
1436 versa. (@xref{Flow Control}, for more information on this subject.)
1438 @cindex flow control example
1441 (defun evade-flow-control ()
1442 "Replace C-s with C-\ and C-q with C-^."
1446 (setq keyboard-translate-table
1447 (make-char-table 'keyboard-translate-table nil))
1450 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1451 (aset keyboard-translate-table ?\034 ?\^s)
1452 (aset keyboard-translate-table ?\^s ?\034)
1455 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1456 (aset keyboard-translate-table ?\036 ?\^q)
1457 (aset keyboard-translate-table ?\^q ?\036))
1461 Note that this translation is the first thing that happens to a
1462 character after it is read from the terminal. Record-keeping features
1463 such as @code{recent-keys} and dribble files record the characters after
1467 @defun keyboard-translate from to
1468 This function modifies @code{keyboard-translate-table} to translate
1469 character code @var{from} into character code @var{to}. It creates
1470 the keyboard translate table if necessary.
1473 The remaining translation features translate subsequences of key
1474 sequences being read. They are implemented in @code{read-key-sequence}
1475 and have no effect on input read with @code{read-event}.
1477 @defvar function-key-map
1478 This variable holds a keymap that describes the character sequences sent
1479 by function keys on an ordinary character terminal. This keymap has the
1480 same structure as other keymaps, but is used differently: it specifies
1481 translations to make while reading key sequences, rather than bindings
1484 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1485 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1486 key sequence, it is replaced with the events in @var{v}.
1488 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1489 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
1490 that sequence of events into the single event @code{pf1}. We accomplish
1491 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1492 @code{function-key-map}, when using a VT100.
1494 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1495 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1496 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1499 Entries in @code{function-key-map} are ignored if they conflict with
1500 bindings made in the minor mode, local, or global keymaps. The intent
1501 is that the character sequences that function keys send should not have
1502 command bindings in their own right---but if they do, the ordinary
1503 bindings take priority.
1505 The value of @code{function-key-map} is usually set up automatically
1506 according to the terminal's Terminfo or Termcap entry, but sometimes
1507 those need help from terminal-specific Lisp files. Emacs comes with
1508 terminal-specific files for many common terminals; their main purpose is
1509 to make entries in @code{function-key-map} beyond those that can be
1510 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1513 @defvar key-translation-map
1514 This variable is another keymap used just like @code{function-key-map}
1515 to translate input events into other events. It differs from
1516 @code{function-key-map} in two ways:
1520 @code{key-translation-map} goes to work after @code{function-key-map} is
1521 finished; it receives the results of translation by
1522 @code{function-key-map}.
1525 @code{key-translation-map} overrides actual key bindings. For example,
1526 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
1527 translation takes effect even though @kbd{C-x f} also has a key binding
1531 The intent of @code{key-translation-map} is for users to map one
1532 character set to another, including ordinary characters normally bound
1533 to @code{self-insert-command}.
1536 @cindex key translation function
1537 You can use @code{function-key-map} or @code{key-translation-map} for
1538 more than simple aliases, by using a function, instead of a key
1539 sequence, as the ``translation'' of a key. Then this function is called
1540 to compute the translation of that key.
1542 The key translation function receives one argument, which is the prompt
1543 that was specified in @code{read-key-sequence}---or @code{nil} if the
1544 key sequence is being read by the editor command loop. In most cases
1545 you can ignore the prompt value.
1547 If the function reads input itself, it can have the effect of altering
1548 the event that follows. For example, here's how to define @kbd{C-c h}
1549 to turn the character that follows into a Hyper character:
1553 (defun hyperify (prompt)
1554 (let ((e (read-event)))
1555 (vector (if (numberp e)
1556 (logior (lsh 1 24) e)
1557 (if (memq 'hyper (event-modifiers e))
1559 (add-event-modifier "H-" e))))))
1561 (defun add-event-modifier (string e)
1562 (let ((symbol (if (symbolp e) e (car e))))
1563 (setq symbol (intern (concat string
1564 (symbol-name symbol))))
1569 (cons symbol (cdr e)))))
1571 (define-key function-key-map "\C-ch" 'hyperify)
1575 Finally, if you have enabled keyboard character set decoding using
1576 @code{set-keyboard-coding-system}, decoding is done after the
1577 translations listed above. @xref{Specifying Coding Systems}. In future
1578 Emacs versions, character set decoding may be done before the other
1581 @node Recording Input
1582 @subsection Recording Input
1585 This function returns a vector containing the last 100 input events from
1586 the keyboard or mouse. All input events are included, whether or not
1587 they were used as parts of key sequences. Thus, you always get the last
1588 100 input events, not counting events generated by keyboard macros.
1589 (These are excluded because they are less interesting for debugging; it
1590 should be enough to see the events that invoked the macros.)
1593 @deffn Command open-dribble-file filename
1594 @cindex dribble file
1595 This function opens a @dfn{dribble file} named @var{filename}. When a
1596 dribble file is open, each input event from the keyboard or mouse (but
1597 not those from keyboard macros) is written in that file. A
1598 non-character event is expressed using its printed representation
1599 surrounded by @samp{<@dots{}>}.
1601 You close the dribble file by calling this function with an argument
1604 This function is normally used to record the input necessary to
1605 trigger an Emacs bug, for the sake of a bug report.
1609 (open-dribble-file "~/dribble")
1615 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1617 @node Terminal Output
1618 @section Terminal Output
1619 @cindex terminal output
1621 The terminal output functions send output to the terminal, or keep
1622 track of output sent to the terminal. The variable @code{baud-rate}
1623 tells you what Emacs thinks is the output speed of the terminal.
1626 This variable's value is the output speed of the terminal, as far as
1627 Emacs knows. Setting this variable does not change the speed of actual
1628 data transmission, but the value is used for calculations such as
1629 padding. It also affects decisions about whether to scroll part of the
1630 screen or repaint---even when using a window system. (We designed it
1631 this way despite the fact that a window system has no true ``output
1632 speed'', to give you a way to tune these decisions.)
1634 The value is measured in baud.
1637 If you are running across a network, and different parts of the
1638 network work at different baud rates, the value returned by Emacs may be
1639 different from the value used by your local terminal. Some network
1640 protocols communicate the local terminal speed to the remote machine, so
1641 that Emacs and other programs can get the proper value, but others do
1642 not. If Emacs has the wrong value, it makes decisions that are less
1643 than optimal. To fix the problem, set @code{baud-rate}.
1646 This obsolete function returns the value of the variable
1650 @defun send-string-to-terminal string
1651 This function sends @var{string} to the terminal without alteration.
1652 Control characters in @var{string} have terminal-dependent effects.
1654 One use of this function is to define function keys on terminals that
1655 have downloadable function key definitions. For example, this is how (on
1656 certain terminals) to define function key 4 to move forward four
1657 characters (by transmitting the characters @kbd{C-u C-f} to the
1662 (send-string-to-terminal "\eF4\^U\^F")
1668 @deffn Command open-termscript filename
1669 @cindex termscript file
1670 This function is used to open a @dfn{termscript file} that will record
1671 all the characters sent by Emacs to the terminal. It returns
1672 @code{nil}. Termscript files are useful for investigating problems
1673 where Emacs garbles the screen, problems that are due to incorrect
1674 Termcap entries or to undesirable settings of terminal options more
1675 often than to actual Emacs bugs. Once you are certain which characters
1676 were actually output, you can determine reliably whether they correspond
1677 to the Termcap specifications in use.
1679 See also @code{open-dribble-file} in @ref{Terminal Input}.
1683 (open-termscript "../junk/termscript")
1690 @section Sound Output
1693 To play sound using Emacs, use the function @code{play-sound}. Only
1694 certain systems are supported; if you call @code{play-sound} on a system
1695 which cannot really do the job, it gives an error. Emacs version 20 and
1696 earlier did not support sound at all.
1698 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1699 or Sun Audio format (@samp{.au}).
1702 @defun play-sound sound
1703 This function plays a specified sound. The argument, @var{sound}, has
1704 the form @code{(sound @var{properties}...)}, where the @var{properties}
1705 consist of alternating keywords (particular symbols recognized
1706 specially) and values corresponding to them.
1708 Here is a table of the keywords that are currently meaningful in
1709 @var{sound}, and their meanings:
1712 @item :file @var{file}
1713 This specifies the file containing the sound to play.
1714 If the file name is not absolute, it is expanded against
1715 the directory @code{data-directory}.
1717 @item :volume @var{volume}
1718 This specifies how loud to play the sound. It should be a number in the
1719 range of 0 to 1. The default is to use whatever volume has been
1723 Before actually playing the sound, @code{play-sound}
1724 calls the functions in the list @code{play-sound-functions}.
1725 Each function is called with one argument, @var{sound}.
1728 @tindex play-sound-functions
1729 @defvar play-sound-functions
1730 A list of functions to be called before playing a sound. Each function
1731 is called with one argument, a property list that describes the sound.
1734 @node Special Keysyms
1735 @section System-Specific X11 Keysyms
1737 To define system-specific X11 keysyms, set the variable
1738 @code{system-key-alist}.
1740 @defvar system-key-alist
1741 This variable's value should be an alist with one element for each
1742 system-specific keysym. Each element has the form @code{(@var{code}
1743 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1744 including the ``vendor specific'' bit,
1751 and @var{symbol} is the name for the function key.
1753 For example @code{(168 . mute-acute)} defines a system-specific key (used
1754 by HP X servers) whose numeric code is
1763 It is not crucial to exclude from the alist the keysyms of other X
1764 servers; those do no harm, as long as they don't conflict with the ones
1765 used by the X server actually in use.
1767 The variable is always local to the current terminal, and cannot be
1768 buffer-local. @xref{Multiple Displays}.
1772 @section Flow Control
1773 @cindex flow control characters
1775 This section attempts to answer the question ``Why does Emacs use
1776 flow-control characters in its command character set?'' For a second
1777 view on this issue, read the comments on flow control in the
1778 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1779 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1783 At one time, most terminals did not need flow control, and none used
1784 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1785 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
1786 was natural and uncontroversial. With so many commands needing key
1787 assignments, of course we assigned meanings to nearly all @sc{ascii}
1790 Later, some terminals were introduced which required these characters
1791 for flow control. They were not very good terminals for full-screen
1792 editing, so Emacs maintainers ignored them. In later years, flow
1793 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
1794 but by this time it was usually an option. And the majority of Emacs
1795 users, who can turn flow control off, did not want to switch to less
1796 mnemonic key bindings for the sake of flow control.
1798 So which usage is ``right''---Emacs's or that of some terminal and
1799 concentrator manufacturers? This question has no simple answer.
1801 One reason why we are reluctant to cater to the problems caused by
1802 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1803 techniques (albeit less common in practice) for flow control that
1804 preserve transparency of the character stream. Note also that their use
1805 for flow control is not an official standard. Interestingly, on the
1806 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
1807 @kbd{C-q} were sent by the computer to turn the punch on and off!
1809 As window systems and PC terminal emulators replace character-only
1810 terminals, the flow control problem is gradually disappearing. For the
1811 mean time, Emacs provides a convenient way of enabling flow control if
1812 you want it: call the function @code{enable-flow-control}.
1814 @deffn Command enable-flow-control
1815 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1816 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1817 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1820 You can use the function @code{enable-flow-control-on} in your
1821 init file to enable flow control automatically on certain
1824 @defun enable-flow-control-on &rest termtypes
1825 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1826 if the terminal type is one of @var{termtypes}. For example:
1829 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1833 Here is how @code{enable-flow-control} does its job:
1838 It sets @sc{cbreak} mode for terminal input, and tells the operating
1839 system to handle flow control, with @code{(set-input-mode nil t)}.
1842 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1843 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1844 lowest level, Emacs never knows that the characters typed were anything
1845 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1846 and @kbd{C-^} even when they are input for other commands.
1847 @xref{Translating Input}.
1850 If the terminal is the source of the flow control characters, then once
1851 you enable kernel flow control handling, you probably can make do with
1852 less padding than normal for that terminal. You can reduce the amount
1853 of padding by customizing the Termcap entry. You can also reduce it by
1854 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1855 speed when calculating the padding needed. @xref{Terminal Output}.
1860 @cindex noninteractive use
1862 The command-line option @samp{-batch} causes Emacs to run
1863 noninteractively. In this mode, Emacs does not read commands from the
1864 terminal, it does not alter the terminal modes, and it does not expect
1865 to be outputting to an erasable screen. The idea is that you specify
1866 Lisp programs to run; when they are finished, Emacs should exit. The
1867 way to specify the programs to run is with @samp{-l @var{file}}, which
1868 loads the library named @var{file}, and @samp{-f @var{function}}, which
1869 calls @var{function} with no arguments.
1871 Any Lisp program output that would normally go to the echo area,
1872 either using @code{message}, or using @code{prin1}, etc., with @code{t}
1873 as the stream, goes instead to Emacs's standard error descriptor when
1874 in batch mode. Thus, Emacs behaves much like a noninteractive
1875 application program. (The echo area output that Emacs itself normally
1876 generates, such as command echoing, is suppressed entirely.)
1878 @defvar noninteractive
1879 This variable is non-@code{nil} when Emacs is running in batch mode.