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, Tips, 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 start-up 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 * Reading a Password:: Reading a password from the terminal.
23 * Time of Day:: Getting the current time.
24 * Time Conversion:: Converting a time from numeric form to a string, or
25 to calendrical data (or vice versa).
26 * Timers:: Setting a timer to call a function at a certain time.
27 * Terminal Input:: Recording terminal input for debugging.
28 * Terminal Output:: Recording terminal output for debugging.
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 * Start-up Summary:: Sequence of actions Emacs performs at start-up.
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.
48 @node Start-up Summary
49 @subsection Summary: Sequence of Actions at Start Up
50 @cindex initialization
51 @cindex start up 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 the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
89 specified on the command line. The @samp{-u} option can specify another
90 user name whose home directory should be used instead of @file{~}.
93 It loads the library @file{default}, unless @code{inhibit-default-init}
94 is non-@code{nil}. (This is not done in @samp{-batch} mode or if
95 @samp{-q} was specified on the command line.) The library's file name
96 is usually @file{default.el}.
97 @cindex @file{default.el}
100 It runs the normal hook @code{after-init-hook}.
103 It sets the major mode according to @code{initial-major-mode}, provided
104 the buffer @samp{*scratch*} is still current and still in Fundamental
108 It loads the terminal-specific Lisp file, if any, except when in batch
109 mode or using a window system.
112 It displays the initial echo area message, unless you have suppressed
113 that with @code{inhibit-startup-echo-area-message}.
116 It processes the action arguments from the command line.
119 It runs @code{term-setup-hook}.
122 It calls @code{frame-notice-user-settings}, which modifies the
123 parameters of the selected frame according to whatever the init files
127 It runs @code{window-setup-hook}. @xref{Window Systems}.
130 It displays copyleft, nonwarranty, and basic use information, provided
131 there were no remaining command line arguments (a few steps above),
132 the value of @code{inhibit-startup-message} is @code{nil}, and the
133 buffer is still empty.
136 @defopt inhibit-startup-message
137 This variable inhibits the initial startup messages (the nonwarranty,
138 etc.). If it is non-@code{nil}, then the messages are not printed.
140 This variable exists so you can set it in your personal init file, once
141 you are familiar with the contents of the startup message. Do not set
142 this variable in the init file of a new user, or in a way that affects
143 more than one user, because that would prevent new users from receiving
144 the information they are supposed to see.
147 @defopt inhibit-startup-echo-area-message
148 This variable controls the display of the startup echo area message.
149 You can suppress the startup echo area message by adding text with this
150 form to your @file{.emacs} file:
153 (setq inhibit-startup-echo-area-message
154 "@var{your-login-name}")
157 Emacs explicitly checks for an expression as shown above in your
158 @file{.emacs} file; your login name must appear in the expression as a
159 Lisp string constant. Other methods of setting
160 @code{inhibit-startup-echo-area-message} to the same value do not
161 inhibit the startup message.
163 This way, you can easily inhibit the message for yourself if you wish,
164 but thoughtless copying of your @file{.emacs} file will not inhibit the
165 message for someone else.
169 @subsection The Init File: @file{.emacs}
171 @cindex @file{.emacs}
173 When you start Emacs, it normally attempts to load the file
174 @file{.emacs} from your home directory. This file, if it exists, must
175 contain Lisp code. It is called your @dfn{init file}. The command line
176 switches @samp{-q} and @samp{-u} affect the use of the init file;
177 @samp{-q} says not to load an init file, and @samp{-u} says to load a
178 specified user's init file instead of yours. @xref{Entering Emacs,,,
179 emacs, The GNU Emacs Manual}.
181 @cindex default init file
182 A site may have a @dfn{default init file}, which is the library named
183 @file{default.el}. Emacs finds the @file{default.el} file through the
184 standard search path for libraries (@pxref{How Programs Do Loading}).
185 The Emacs distribution does not come with this file; sites may provide
186 one for local customizations. If the default init file exists, it is
187 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
188 specified. But your own personal init file, if any, is loaded first; if
189 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
190 Emacs does not subsequently load the @file{default.el} file.
192 Another file for site-customization is @file{site-start.el}. Emacs
193 loads this @emph{before} the user's init file. You can inhibit the
194 loading of this file with the option @samp{-no-site-file}.
196 @defvar site-run-file
197 This variable specifies the site-customization file to load before the
198 user's init file. Its normal value is @code{"site-start"}. The only
199 way you can change it with real effect is to do so before dumping
203 If there is a great deal of code in your @file{.emacs} file, you
204 should move it into another file named @file{@var{something}.el},
205 byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
206 file load the other file using @code{load} (@pxref{Loading}).
208 @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
209 examples of how to make various commonly desired customizations in your
212 @defopt inhibit-default-init
213 This variable prevents Emacs from loading the default initialization
214 library file for your session of Emacs. If its value is non-@code{nil},
215 then the default library is not loaded. The default value is
219 @defvar before-init-hook
220 This normal hook is run, once, just before loading all the init files
221 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
222 (The only way to change it with real effect is before dumping Emacs.)
225 @defvar after-init-hook
226 This normal hook is run, once, just after loading all the init files
227 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
228 before the terminal-specific initialization.
231 @node Terminal-Specific
232 @subsection Terminal-Specific Initialization
233 @cindex terminal-specific initialization
235 Each terminal type can have its own Lisp library that Emacs loads when
236 run on that type of terminal. The library's name is constructed by
237 concatenating the value of the variable @code{term-file-prefix} and the
238 terminal type. Normally, @code{term-file-prefix} has the value
239 @code{"term/"}; changing this is not recommended. Emacs finds the file
240 in the normal manner, by searching the @code{load-path} directories, and
241 trying the @samp{.elc} and @samp{.el} suffixes.
243 The usual function of a terminal-specific library is to enable special
244 keys to send sequences that Emacs can recognize. It may also need to
245 set or add to @code{function-key-map} if the Termcap entry does not
246 specify all the terminal's function keys. @xref{Terminal Input}.
249 When the name of the terminal type contains a hyphen, only the part of
250 the name before the first hyphen is significant in choosing the library
251 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
252 the @file{term/aaa} library. If necessary, the library can evaluate
253 @code{(getenv "TERM")} to find the full name of the terminal
256 Your @file{.emacs} file can prevent the loading of the
257 terminal-specific library by setting the variable
258 @code{term-file-prefix} to @code{nil}. This feature is useful when
259 experimenting with your own peculiar customizations.
261 You can also arrange to override some of the actions of the
262 terminal-specific library by setting the variable
263 @code{term-setup-hook}. This is a normal hook which Emacs runs using
264 @code{run-hooks} at the end of Emacs initialization, after loading both
265 your @file{.emacs} file and any terminal-specific libraries. You can
266 use this variable to define initializations for terminals that do not
267 have their own libraries. @xref{Hooks}.
269 @defvar term-file-prefix
270 @cindex @code{TERM} environment variable
271 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
272 a terminal-specific initialization file as follows:
275 (load (concat term-file-prefix (getenv "TERM")))
279 You may set the @code{term-file-prefix} variable to @code{nil} in your
280 @file{.emacs} file if you do not wish to load the
281 terminal-initialization file. To do this, put the following in
282 your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
285 @defvar term-setup-hook
286 This variable is a normal hook that Emacs runs after loading your
287 @file{.emacs} file, the default initialization file (if any) and the
288 terminal-specific Lisp file.
290 You can use @code{term-setup-hook} to override the definitions made by a
291 terminal-specific file.
294 See @code{window-setup-hook} in @ref{Window Systems}, for a related
297 @node Command Line Arguments
298 @subsection Command Line Arguments
299 @cindex command line arguments
301 You can use command line arguments to request various actions when you
302 start Emacs. Since you do not need to start Emacs more than once per
303 day, and will often leave your Emacs session running longer than that,
304 command line arguments are hardly ever used. As a practical matter, it
305 is best to avoid making the habit of using them, since this habit would
306 encourage you to kill and restart Emacs unnecessarily often. These
307 options exist for two reasons: to be compatible with other editors (for
308 invocation by other programs) and to enable shell scripts to run
309 specific Lisp programs.
311 This section describes how Emacs processes command line arguments,
312 and how you can customize them.
315 (Note that some other editors require you to start afresh each time
316 you want to edit a file. With this kind of editor, you will probably
317 specify the file as a command line argument. The recommended way to
318 use GNU Emacs is to start it only once, just after you log in, and do
319 all your editing in the same Emacs process. Each time you want to edit
320 a different file, you visit it with the existing Emacs, which eventually
321 comes to have many files in it ready for editing. Usually you do not
322 kill the Emacs until you are about to log out.)
326 This function parses the command line that Emacs was called with,
327 processes it, loads the user's @file{.emacs} file and displays the
331 @defvar command-line-processed
332 The value of this variable is @code{t} once the command line has been
335 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
336 this variable to @code{nil} first in order to cause the new dumped Emacs
337 to process its new command line arguments.
340 @defvar command-switch-alist
341 @cindex switches on command line
342 @cindex options on command line
343 @cindex command line options
344 The value of this variable is an alist of user-defined command-line
345 options and associated handler functions. This variable exists so you
346 can add elements to it.
348 A @dfn{command line option} is an argument on the command line of the
355 The elements of the @code{command-switch-alist} look like this:
358 (@var{option} . @var{handler-function})
361 The @var{handler-function} is called to handle @var{option} and receives
362 the option name as its sole argument.
364 In some cases, the option is followed in the command line by an
365 argument. In these cases, the @var{handler-function} can find all the
366 remaining command-line arguments in the variable
367 @code{command-line-args-left}. (The entire list of command-line
368 arguments is in @code{command-line-args}.)
370 The command line arguments are parsed by the @code{command-line-1}
371 function in the @file{startup.el} file. See also @ref{Command
372 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
376 @defvar command-line-args
377 The value of this variable is the list of command line arguments passed
381 @defvar command-line-functions
382 This variable's value is a list of functions for handling an
383 unrecognized command-line argument. Each time the next argument to be
384 processed has no special meaning, the functions in this list are called,
385 in order of appearance, until one of them returns a non-@code{nil}
388 These functions are called with no arguments. They can access the
389 command-line argument under consideration through the variable
390 @code{argi}, which is bound temporarily at this point. The remaining
391 arguments (not including the current one) are in the variable
392 @code{command-line-args-left}.
394 When a function recognizes and processes the argument in @code{argi}, it
395 should return a non-@code{nil} value to say it has dealt with that
396 argument. If it has also dealt with some of the following arguments, it
397 can indicate that by deleting them from @code{command-line-args-left}.
399 If all of these functions return @code{nil}, then the argument is used
400 as a file name to visit.
404 @section Getting Out of Emacs
405 @cindex exiting Emacs
407 There are two ways to get out of Emacs: you can kill the Emacs job,
408 which exits permanently, or you can suspend it, which permits you to
409 reenter the Emacs process later. As a practical matter, you seldom kill
410 Emacs---only when you are about to log out. Suspending is much more
414 * Killing Emacs:: Exiting Emacs irreversibly.
415 * Suspending Emacs:: Exiting Emacs reversibly.
419 @comment node-name, next, previous, up
420 @subsection Killing Emacs
421 @cindex killing Emacs
423 Killing Emacs means ending the execution of the Emacs process. The
424 parent process normally resumes control. The low-level primitive for
425 killing Emacs is @code{kill-emacs}.
427 @defun kill-emacs &optional exit-data
428 This function exits the Emacs process and kills it.
430 If @var{exit-data} is an integer, then it is used as the exit status
431 of the Emacs process. (This is useful primarily in batch operation; see
434 If @var{exit-data} is a string, its contents are stuffed into the
435 terminal input buffer so that the shell (or whatever program next reads
436 input) can read them.
439 All the information in the Emacs process, aside from files that have
440 been saved, is lost when the Emacs is killed. Because killing Emacs
441 inadvertently can lose a lot of work, Emacs queries for confirmation
442 before actually terminating if you have buffers that need saving or
443 subprocesses that are running. This is done in the function
444 @code{save-buffers-kill-emacs}.
446 @defvar kill-emacs-query-functions
447 After asking the standard questions, @code{save-buffers-kill-emacs}
448 calls the functions in the list @code{kill-emacs-query-functions}, in
449 order of appearance, with no arguments. These functions can ask for
450 additional confirmation from the user. If any of them returns
451 @code{nil}, Emacs is not killed.
454 @defvar kill-emacs-hook
455 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
456 finished with all file saving and confirmation, it runs the functions in
460 @node Suspending Emacs
461 @subsection Suspending Emacs
462 @cindex suspending Emacs
464 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
465 control to its superior process, which is usually the shell. This
466 allows you to resume editing later in the same Emacs process, with the
467 same buffers, the same kill ring, the same undo history, and so on. To
468 resume Emacs, use the appropriate command in the parent shell---most
471 Some operating systems do not support suspension of jobs; on these
472 systems, ``suspension'' actually creates a new shell temporarily as a
473 subprocess of Emacs. Then you would exit the shell to return to Emacs.
475 Suspension is not useful with window systems, because the Emacs job
476 may not have a parent that can resume it again, and in any case you can
477 give input to some other job such as a shell merely by moving to a
478 different window. Therefore, suspending is not allowed when Emacs is using
481 @defun suspend-emacs string
482 This function stops Emacs and returns control to the superior process.
483 If and when the superior process resumes Emacs, @code{suspend-emacs}
484 returns @code{nil} to its caller in Lisp.
486 If @var{string} is non-@code{nil}, its characters are sent to be read
487 as terminal input by Emacs's superior shell. The characters in
488 @var{string} are not echoed by the superior shell; only the results
491 Before suspending, @code{suspend-emacs} runs the normal hook
494 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
495 @code{suspend-resume-hook}. @xref{Hooks}.
497 The next redisplay after resumption will redraw the entire screen,
498 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
499 (@pxref{Refresh Screen}).
501 In the following example, note that @samp{pwd} is not echoed after
502 Emacs is suspended. But it is read and executed by the shell.
511 (add-hook 'suspend-hook
515 (error "Suspend cancelled")))))
516 @result{} (lambda nil
517 (or (y-or-n-p "Really suspend? ")
518 (error "Suspend cancelled")))
521 (add-hook 'suspend-resume-hook
522 (function (lambda () (message "Resumed!"))))
523 @result{} (lambda nil (message "Resumed!"))
526 (suspend-emacs "pwd")
530 ---------- Buffer: Minibuffer ----------
531 Really suspend? @kbd{y}
532 ---------- Buffer: Minibuffer ----------
536 ---------- Parent Shell ----------
537 lewis@@slug[23] % /user/lewis/manual
542 ---------- Echo Area ----------
549 This variable is a normal hook run before suspending.
552 @defvar suspend-resume-hook
553 This variable is a normal hook run after suspending.
556 @node System Environment
557 @section Operating System Environment
558 @cindex operating system environment
560 Emacs provides access to variables in the operating system environment
561 through various functions. These variables include the name of the
562 system, the user's @sc{uid}, and so on.
564 @defvar system-configuration
565 This variable holds the GNU configuration name for the hardware/software
566 configuration of your system, as a string. The convenient way to test
567 parts of this string is with @code{string-match}.
571 The value of this variable is a symbol indicating the type of operating
572 system Emacs is operating on. Here is a table of the possible values:
585 Data General DGUX operating system.
588 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
591 A GNU/Linux system---that is, a variant GNU system, using the Linux
592 kernel. (These systems are the ones people often call ``Linux,'' but
593 actually Linux is just the kernel, not the whole system.)
596 Hewlett-Packard HPUX operating system.
599 Silicon Graphics Irix system.
602 Microsoft MS-DOS ``operating system.''
605 NeXT Mach-based system.
608 Masscomp RTU, UCB universe.
620 Microsoft windows NT.
626 We do not wish to add new symbols to make finer distinctions unless it
627 is absolutely necessary! In fact, we hope to eliminate some of these
628 alternatives in the future. We recommend using
629 @code{system-configuration} to distinguish between different operating
634 This function returns the name of the machine you are running on.
637 @result{} "www.gnu.org"
641 The symbol @code{system-name} is a variable as well as a function. In
642 fact, the function returns whatever value the variable
643 @code{system-name} currently holds. Thus, you can set the variable
644 @code{system-name} in case Emacs is confused about the name of your
645 system. The variable is also useful for constructing frame titles
646 (@pxref{Frame Titles}).
648 @defvar mail-host-address
649 If this variable is non-@code{nil}, it is used instead of
650 @code{system-name} for purposes of generating email addresses. For
651 example, it is used when constructing the default value of
652 @code{user-mail-address}. @xref{User Identification}. (Since this is
653 done when Emacs starts up, the value actually used is the one saved when
654 Emacs was dumped. @xref{Building Emacs}.)
658 @cindex environment variable access
659 This function returns the value of the environment variable @var{var},
660 as a string. Within Emacs, the environment variable values are kept in
661 the Lisp variable @code{process-environment}.
670 lewis@@slug[10] % printenv
671 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
683 @deffn Command setenv variable value
684 This command sets the value of the environment variable named
685 @var{variable} to @var{value}. Both arguments should be strings. This
686 function works by modifying @code{process-environment}; binding that
687 variable with @code{let} is also reasonable practice.
690 @defvar process-environment
691 This variable is a list of strings, each describing one environment
692 variable. The functions @code{getenv} and @code{setenv} work by means
698 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
699 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
710 @defvar path-separator
711 This variable holds a string which says which character separates
712 directories in a search path (as found in an environment variable). Its
713 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
717 @defvar invocation-name
718 This variable holds the program name under which Emacs was invoked. The
719 value is a string, and does not include a directory name.
722 @defvar invocation-directory
723 This variable holds the directory from which the Emacs executable was
724 invoked, or perhaps @code{nil} if that directory cannot be determined.
727 @defvar installation-directory
728 If non-@code{nil}, this is a directory within which to look for the
729 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
730 when Emacs can't find those directories in their standard installed
731 locations, but can find them in a directory related somehow to the one
732 containing the Emacs executable.
735 @defun load-average &optional use-float
736 This function returns the current 1-minute, 5-minute, and 15-minute load
739 By default, the values are integers that are 100 times the system load
740 averages, which indicate the average number of processes trying to run.
741 If @var{use-float} is non-@code{nil}, then they are returned
742 as floating point numbers and without multiplying by 100.
747 @result{} (169 48 36)
751 @result{} (1.69 0.48 0.36)
755 lewis@@rocky[5] % uptime
756 11:55am up 1 day, 19:37, 3 users,
757 load average: 1.69, 0.48, 0.36
763 This function returns the process @sc{id} of the Emacs process.
766 @defvar tty-erase-char
767 @tindex tty-erase-char
768 This variable holds the erase character that was selected
769 in the system's terminal driver, before Emacs was started.
772 @defun setprv privilege-name &optional setp getprv
773 This function sets or resets a VMS privilege. (It does not exist on
774 Unix.) The first arg is the privilege name, as a string. The second
775 argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the
776 privilege is to be turned on or off. Its default is @code{nil}. The
777 function returns @code{t} if successful, @code{nil} otherwise.
779 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
780 does not change the privilege, but returns @code{t} or @code{nil}
781 indicating whether the privilege is currently enabled.
784 @node User Identification
785 @section User Identification
787 @defvar init-file-user
788 This variable says which user's init files should be used by Emacs---or
789 @code{nil} if none. The value reflects command line options such as
790 @samp{-q} or @samp{-u @var{user}}.
792 Lisp packages that load files of customizations, or any other sort of
793 user profile, should obey this variable in deciding where to find it.
794 They should load the profile of the user name found in this variable.
795 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
796 option was used, then Lisp packages should not load any customization
797 files or user profile.
800 @defvar user-mail-address
801 This holds the nominal email address of the user who is using Emacs.
802 Emacs normally sets this variable to a default value after reading your
803 init files, but not if you have already set it. So you can set the
804 variable to some other value in your @file{~/.emacs} file if you do not
805 want to use the default value.
808 @defun user-login-name &optional uid
809 If you don't specify @var{uid}, this function returns the name under
810 which the user is logged in. If the environment variable @code{LOGNAME}
811 is set, that value is used. Otherwise, if the environment variable
812 @code{USER} is set, that value is used. Otherwise, the value is based
813 on the effective @sc{uid}, not the real @sc{uid}.
815 If you specify @var{uid}, the value is the user name that corresponds
816 to @var{uid} (which should be an integer).
826 @defun user-real-login-name
827 This function returns the user name corresponding to Emacs's real
828 @sc{uid}. This ignores the effective @sc{uid} and ignores the
829 environment variables @code{LOGNAME} and @code{USER}.
832 @defun user-full-name &optional uid
833 This function returns the full name of the logged-in user---or the value
834 of the environment variables @code{NAME}, if that is set.
839 @result{} "Bil Lewis"
843 If @var{uid} is non-@code{nil}, then it should be an integer, a user-id,
844 or a string, a login name. Then @code{user-full-name} returns the full
845 name corresponding to that user-id or login name.
848 @vindex user-full-name
849 @vindex user-real-login-name
850 @vindex user-login-name
851 The symbols @code{user-login-name}, @code{user-real-login-name} and
852 @code{user-full-name} are variables as well as functions. The functions
853 return the same values that the variables hold. These variables allow
854 you to ``fake out'' Emacs by telling the functions what to return. The
855 variables are also useful for constructing frame titles (@pxref{Frame
859 This function returns the real @sc{uid} of the user.
870 This function returns the effective @sc{uid} of the user.
873 @node Reading a Password
874 @section Reading a Password
875 @cindex passwords, reading
877 To read a password to pass to another program, you can use the
878 function @code{read-passwd}.
881 @defun read-passwd prompt &optional confirm default
882 This function reads a password, prompting with @var{prompt}. It does
883 not echo the password as the user types it; instead, it echoes @samp{.}
884 for each character in the password.
886 The optional argument @var{confirm}, if non-@code{nil}, says to read the
887 password twice and insist it must be the same both times. If it isn't
888 the same, the user has to type it over and over until the last two
891 The optional argument @var{default} specifies the default password to
892 return if the user enters empty input. If @var{default} is @code{nil},
893 then @code{read-passwd} returns the null string in that case.
899 This section explains how to determine the current time and the time
902 @defun current-time-string &optional time-value
903 This function returns the current time and date as a human-readable
904 string. The format of the string is unvarying; the number of characters
905 used for each part is always the same, so you can reliably use
906 @code{substring} to extract pieces of it. It is wise to count the
907 characters from the beginning of the string rather than from the end, as
908 additional information may some day be added at the end.
911 The argument @var{time-value}, if given, specifies a time to format
912 instead of the current time. The argument should be a list whose first
913 two elements are integers. Thus, you can use times obtained from
914 @code{current-time} (see below) and from @code{file-attributes}
915 (@pxref{File Attributes}).
919 (current-time-string)
920 @result{} "Wed Oct 14 22:21:05 1987"
927 This function returns the system's time value as a list of three
928 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
929 @var{high} and @var{low} combine to give the number of seconds since
930 0:00 January 1, 1970, which is
932 @var{high} * 2**16 + @var{low}.
938 The third element, @var{microsec}, gives the microseconds since the
939 start of the current second (or 0 for systems that return time only on
940 the resolution of a second).
942 The first two elements can be compared with file time values such as you
943 get with the function @code{file-attributes}. @xref{File Attributes}.
947 @defun current-time-zone &optional time-value
948 This function returns a list describing the time zone that the user is
951 The value has the form @code{(@var{offset} @var{name})}. Here
952 @var{offset} is an integer giving the number of seconds ahead of UTC
953 (east of Greenwich). A negative value means west of Greenwich. The
954 second element, @var{name} is a string giving the name of the time
955 zone. Both elements change when daylight savings time begins or ends;
956 if the user has specified a time zone that does not use a seasonal time
957 adjustment, then the value is constant through time.
959 If the operating system doesn't supply all the information necessary to
960 compute the value, both elements of the list are @code{nil}.
962 The argument @var{time-value}, if given, specifies a time to analyze
963 instead of the current time. The argument should be a cons cell
964 containing two integers, or a list whose first two elements are
965 integers. Thus, you can use times obtained from @code{current-time}
966 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
969 @node Time Conversion
970 @section Time Conversion
972 These functions convert time values (lists of two or three integers)
973 to strings or to calendrical information. There is also a function to
974 convert calendrical information to a time value. You can get time
975 values from the functions @code{current-time} (@pxref{Time of Day}) and
976 @code{file-attributes} (@pxref{File Attributes}).
978 Many operating systems are limited to time values that contain 32 bits
979 of information; these systems typically handle only the times from
980 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
981 operating systems have larger time values, and can represent times far
982 in the past or future.
984 Time conversion functions always use the Gregorian calendar, even for
985 dates before the Gregorian calendar was introduced. Year numbers count
986 the number of years since the year 1 B.C., and do not skip zero as
987 traditional Gregorian years do; for example, the year number @minus{}37
988 represents the Gregorian year 38 B.C@.
990 @defun format-time-string format-string time
991 This function converts @var{time} to a string according to
992 @var{format-string}. The argument @var{format-string} may contain
993 @samp{%}-sequences which say to substitute parts of the time. Here is a
994 table of what the @samp{%}-sequences mean:
998 This stands for the abbreviated name of the day of week.
1000 This stands for the full name of the day of week.
1002 This stands for the abbreviated name of the month.
1004 This stands for the full name of the month.
1006 This is a synonym for @samp{%x %X}.
1008 This has a locale-specific meaning. In the default locale (named C), it
1009 is equivalent to @samp{%A, %B %e, %Y}.
1011 This stands for the day of month, zero-padded.
1013 This is a synonym for @samp{%m/%d/%y}.
1015 This stands for the day of month, blank-padded.
1017 This is a synonym for @samp{%b}.
1019 This stands for the hour (00-23).
1021 This stands for the hour (00-12).
1023 This stands for the day of the year (001-366).
1025 This stands for the hour (0-23), blank padded.
1027 This stands for the hour (1-12), blank padded.
1029 This stands for the month (01-12).
1031 This stands for the minute (00-59).
1033 This stands for a newline.
1035 This stands for @samp{AM} or @samp{PM}, as appropriate.
1037 This is a synonym for @samp{%I:%M:%S %p}.
1039 This is a synonym for @samp{%H:%M}.
1041 This stands for the seconds (00-60).
1043 This stands for a tab character.
1045 This is a synonym for @samp{%H:%M:%S}.
1047 This stands for the week of the year (01-52), assuming that weeks
1050 This stands for the numeric day of week (0-6). Sunday is day 0.
1052 This stands for the week of the year (01-52), assuming that weeks
1055 This has a locale-specific meaning. In the default locale (named
1056 @samp{C}), it is equivalent to @samp{%D}.
1058 This has a locale-specific meaning. In the default locale (named
1059 @samp{C}), it is equivalent to @samp{%T}.
1061 This stands for the year without century (00-99).
1063 This stands for the year with century.
1065 This stands for the time zone abbreviation.
1068 You can also specify the field width and type of padding for any of
1069 these @samp{%}-sequences. This works as in @code{printf}: you write
1070 the field width as digits in the middle of a @samp{%}-sequences. If you
1071 start the field width with @samp{0}, it means to pad with zeros. If you
1072 start the field width with @samp{_}, it means to pad with spaces.
1074 For example, @samp{%S} specifies the number of seconds since the minute;
1075 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1076 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1077 because that is how @samp{%S} normally pads to two positions.
1080 @defun decode-time time
1081 This function converts a time value into calendrical information. The
1082 return value is a list of nine elements, as follows:
1085 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1088 Here is what the elements mean:
1092 The number of seconds past the minute, as an integer between 0 and 59.
1094 The number of minutes past the hour, as an integer between 0 and 59.
1096 The hour of the day, as an integer between 0 and 23.
1098 The day of the month, as an integer between 1 and 31.
1100 The month of the year, as an integer between 1 and 12.
1102 The year, an integer typically greater than 1900.
1104 The day of week, as an integer between 0 and 6, where 0 stands for
1107 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1109 An integer indicating the time zone, as the number of seconds east of
1113 @strong{Common Lisp Note:} Common Lisp has different meanings for
1114 @var{dow} and @var{zone}.
1117 @defun encode-time seconds minutes hour day month year &optional @dots{}zone
1118 This function is the inverse of @code{decode-time}. It converts seven
1119 items of calendrical data into a time value. For the meanings of the
1120 arguments, see the table above under @code{decode-time}.
1122 Year numbers less than 100 are treated just like other year numbers. If
1123 you want them to stand for years above 1900, you must alter them yourself
1124 before you call @code{encode-time}.
1126 The optional argument @var{zone} defaults to the current time zone and
1127 its daylight savings time rules. If specified, it can be either a list
1128 (as you would get from @code{current-time-zone}), a string as in the
1129 @code{TZ} environment variable, or an integer (as you would get from
1130 @code{decode-time}). The specified zone is used without any further
1131 alteration for daylight savings time.
1133 If you pass more than seven arguments to @code{encode-time}, the first
1134 six are used as @var{seconds} through @var{year}, the last argument is
1135 used as @var{zone}, and the arguments in between are ignored. This
1136 feature makes it possible to use the elements of a list returned by
1137 @code{decode-time} as the arguments to @code{encode-time}, like this:
1140 (apply 'encode-time (decode-time @dots{}))
1143 You can perform simple date arithmetic by using out-of-range values for
1144 the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
1145 arguments; for example, day 0 means the day preceding the given month.
1147 The operating system puts limits on the range of possible time values;
1148 if you try to encode a time that is out of range, an error results.
1152 @section Timers for Delayed Execution
1155 You can set up a @dfn{timer} to call a function at a specified future time or
1156 after a certain length of idleness.
1158 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1159 can run them only when Emacs could accept output from a subprocess:
1160 namely, while waiting or inside certain primitive functions such as
1161 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1162 timer's execution may be delayed if Emacs is busy. However, the time of
1163 execution is very precise if Emacs is idle.
1165 @defun run-at-time time repeat function &rest args
1166 This function arranges to call @var{function} with arguments @var{args}
1167 at time @var{time}. The argument @var{function} is a function to call
1168 later, and @var{args} are the arguments to give it when it is called.
1169 The time @var{time} is specified as a string.
1171 Absolute times may be specified in a wide variety of formats; this
1172 function tries to accept all the commonly used date formats. Valid
1173 formats include these two,
1176 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
1178 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
1182 where in both examples all fields are numbers; the format that
1183 @code{current-time-string} returns is also allowed, and many others
1186 To specify a relative time, use numbers followed by units.
1191 denotes 1 minute from now.
1193 denotes 65 seconds from now.
1194 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1195 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1198 If @var{time} is a number (integer or floating point), that specifies a
1199 relative time measured in seconds.
1201 The argument @var{repeat} specifies how often to repeat the call. If
1202 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
1203 called just once, at @var{time}. If @var{repeat} is a number, it
1204 specifies a repetition period measured in seconds.
1206 In most cases, @var{repeat} has no effect on when @emph{first} call
1207 takes place---@var{time} alone specifies that. There is one exception:
1208 if @var{time} is @code{t}, then the timer runs whenever the time is a
1209 multiple of @var{repeat} seconds after the epoch. This is useful for
1210 functions like @code{display-time}.
1212 The function @code{run-at-time} returns a timer value that identifies
1213 the particular scheduled future action. You can use this value to call
1214 @code{cancel-timer} (see below).
1217 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1218 Execute @var{body}, but give up after @var{seconds} seconds. If
1219 @var{body} finishes before the time is up, @code{with-timeout} returns
1220 the value of the last form in @var{body}. If, however, the execution of
1221 @var{body} is cut short by the timeout, then @code{with-timeout}
1222 executes all the @var{timeout-forms} and returns the value of the last
1225 This macro works by setting a timer to run after @var{seconds} seconds. If
1226 @var{body} finishes before that time, it cancels the timer. If the
1227 timer actually runs, it terminates execution of @var{body}, then
1228 executes @var{timeout-forms}.
1230 Since timers can run within a Lisp program only when the program calls a
1231 primitive that can wait, @code{with-timeout} cannot stop executing
1232 @var{body} while it is in the midst of a computation---only when it
1233 calls one of those primitives. So use @code{with-timeout} only with a
1234 @var{body} that waits for input, not one that does a long computation.
1237 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1238 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1241 @defun run-with-idle-timer secs repeat function &rest args
1242 Set up a timer which runs when Emacs has been idle for @var{secs}
1243 seconds. The value of @var{secs} may be an integer or a floating point
1246 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1247 Emacs remains idle for a long enough time. More often @var{repeat} is
1248 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1249 remains idle for @var{secs} seconds.
1251 The function @code{run-with-idle-timer} returns a timer value which you
1252 can use in calling @code{cancel-timer} (see below).
1256 Emacs becomes ``idle'' when it starts waiting for user input, and it
1257 remains idle until the user provides some input. If a timer is set for
1258 five seconds of idleness, it runs approximately five seconds after Emacs
1259 first became idle. Even if its @var{repeat} is true, this timer will
1260 not run again as long as Emacs remains idle, because the duration of
1261 idleness will continue to increase and will not go down to five seconds
1264 Emacs can do various things while idle: garbage collect, autosave or
1265 handle data from a subprocess. But these interludes during idleness do
1266 not interfere with idle timers, because they do not reset the clock of
1267 idleness to zero. An idle timer set for 600 seconds will run when ten
1268 minutes have elapsed since the last user command was finished, even if
1269 subprocess output has been accepted thousands of times within those ten
1270 minutes, even if there have been garbage collections and autosaves.
1272 When the user supplies input, Emacs becomes non-idle while executing the
1273 input. Then it becomes idle again, and all the idle timers that are
1274 set up to repeat will subsequently run another time, one by one.
1276 @defun cancel-timer timer
1277 Cancel the requested action for @var{timer}, which should be a value
1278 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
1279 This cancels the effect of that call to @code{run-at-time}; the arrival
1280 of the specified time will not cause anything special to happen.
1283 @node Terminal Input
1284 @section Terminal Input
1285 @cindex terminal input
1287 This section describes functions and variables for recording or
1288 manipulating terminal input. See @ref{Display}, for related
1292 * Input Modes:: Options for how input is processed.
1293 * Translating Input:: Low level conversion of some characters or events
1295 * Recording Input:: Saving histories of recent or all input events.
1299 @subsection Input Modes
1301 @cindex terminal input modes
1303 @defun set-input-mode interrupt flow meta quit-char
1304 This function sets the mode for reading keyboard input. If
1305 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1306 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1307 system dependent. Some systems always use @sc{cbreak} mode regardless
1308 of what is specified.
1310 When Emacs communicates directly with X, it ignores this argument and
1311 uses interrupts if that is the way it knows how to communicate.
1313 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1314 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1315 has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
1318 The argument @var{meta} controls support for input character codes
1319 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1320 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1321 Emacs disregards the 8th bit; this is necessary when the terminal uses
1322 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1323 Emacs uses all 8 bits of input unchanged. This is good for terminals
1324 that use 8-bit character sets.
1327 If @var{quit-char} is non-@code{nil}, it specifies the character to
1328 use for quitting. Normally this character is @kbd{C-g}.
1332 The @code{current-input-mode} function returns the input mode settings
1333 Emacs is currently using.
1336 @defun current-input-mode
1337 This function returns current mode for reading keyboard input. It
1338 returns a list, corresponding to the arguments of @code{set-input-mode},
1339 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1343 is non-@code{nil} when Emacs is using interrupt-driven input. If
1344 @code{nil}, Emacs is using @sc{cbreak} mode.
1346 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1347 flow control for output to the terminal. This value is meaningful only
1348 when @var{interrupt} is @code{nil}.
1350 is @code{t} if Emacs treats the eighth bit of input characters as
1351 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1352 input character; any other value means Emacs uses all eight bits as the
1353 basic character code.
1355 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1359 @node Translating Input
1360 @subsection Translating Input Events
1361 @cindex translating input events
1363 This section describes features for translating input events into
1364 other input events before they become part of key sequences. These
1365 features apply to each event in the order they are described here: each
1366 event is first modified according to @code{extra-keyboard-modifiers},
1367 then translated through @code{keyboard-translate-table} (if applicable),
1368 and finally decoded with the specified keyboard coding system. If it is
1369 being read as part of a key sequence, it is then added to the sequence
1370 being read; then subsequences containing it are checked first with
1371 @code{function-key-map} and then with @code{key-translation-map}.
1374 @defvar extra-keyboard-modifiers
1375 This variable lets Lisp programs ``press'' the modifier keys on the
1376 keyboard. The value is a bit mask:
1380 The @key{SHIFT} key.
1389 Each time the user types a keyboard key, it is altered as if the
1390 modifier keys specified in the bit mask were held down.
1392 When using a window system, the program can ``press'' any of the
1393 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
1394 keys can be virtually pressed.
1397 @defvar keyboard-translate-table
1398 This variable is the translate table for keyboard characters. It lets
1399 you reshuffle the keys on the keyboard without changing any command
1400 bindings. Its value is normally a char-table, or else @code{nil}.
1402 If @code{keyboard-translate-table} is a char-table, then each character
1403 read from the keyboard is looked up in this character. If the value
1404 found there is non-@code{nil}, then it is used instead of the
1405 actual input character.
1407 In the example below, we set @code{keyboard-translate-table} to a
1408 char-table. Then we fill it in to swap the characters @kbd{C-s} and
1409 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
1410 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
1411 versa. (@xref{Flow Control} for more information on this subject.)
1413 @cindex flow control example
1416 (defun evade-flow-control ()
1417 "Replace C-s with C-\ and C-q with C-^."
1421 (setq keyboard-translate-table
1422 (make-char-table 'keyboard-translate-table nil))
1425 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1426 (aset keyboard-translate-table ?\034 ?\^s)
1427 (aset keyboard-translate-table ?\^s ?\034)
1430 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1431 (aset keyboard-translate-table ?\036 ?\^q)
1432 (aset keyboard-translate-table ?\^q ?\036))
1436 Note that this translation is the first thing that happens to a
1437 character after it is read from the terminal. Record-keeping features
1438 such as @code{recent-keys} and dribble files record the characters after
1442 @defun keyboard-translate from to
1443 This function modifies @code{keyboard-translate-table} to translate
1444 character code @var{from} into character code @var{to}. It creates
1445 the keyboard translate table if necessary.
1448 The remaining translation features translate subsequences of key
1449 sequences being read. They are implemented in @code{read-key-sequence}
1450 and have no effect on input read with @code{read-event}.
1452 @defvar function-key-map
1453 This variable holds a keymap that describes the character sequences sent
1454 by function keys on an ordinary character terminal. This keymap has the
1455 same structure as other keymaps, but is used differently: it specifies
1456 translations to make while reading key sequences, rather than bindings
1459 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1460 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1461 key sequence, it is replaced with the events in @var{v}.
1463 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1464 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
1465 that sequence of events into the single event @code{pf1}. We accomplish
1466 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1467 @code{function-key-map}, when using a VT100.
1469 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1470 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1471 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1474 Entries in @code{function-key-map} are ignored if they conflict with
1475 bindings made in the minor mode, local, or global keymaps. The intent
1476 is that the character sequences that function keys send should not have
1477 command bindings in their own right---but if they do, the ordinary
1478 bindings take priority.
1480 The value of @code{function-key-map} is usually set up automatically
1481 according to the terminal's Terminfo or Termcap entry, but sometimes
1482 those need help from terminal-specific Lisp files. Emacs comes with
1483 terminal-specific files for many common terminals; their main purpose is
1484 to make entries in @code{function-key-map} beyond those that can be
1485 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1488 @defvar key-translation-map
1489 This variable is another keymap used just like @code{function-key-map}
1490 to translate input events into other events. It differs from
1491 @code{function-key-map} in two ways:
1495 @code{key-translation-map} goes to work after @code{function-key-map} is
1496 finished; it receives the results of translation by
1497 @code{function-key-map}.
1500 @code{key-translation-map} overrides actual key bindings. For example,
1501 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
1502 translation takes effect even though @kbd{C-x f} also has a key binding
1506 The intent of @code{key-translation-map} is for users to map one
1507 character set to another, including ordinary characters normally bound
1508 to @code{self-insert-command}.
1511 @cindex key translation function
1512 You can use @code{function-key-map} or @code{key-translation-map} for
1513 more than simple aliases, by using a function, instead of a key
1514 sequence, as the ``translation'' of a key. Then this function is called
1515 to compute the translation of that key.
1517 The key translation function receives one argument, which is the prompt
1518 that was specified in @code{read-key-sequence}---or @code{nil} if the
1519 key sequence is being read by the editor command loop. In most cases
1520 you can ignore the prompt value.
1522 If the function reads input itself, it can have the effect of altering
1523 the event that follows. For example, here's how to define @kbd{C-c h}
1524 to turn the character that follows into a Hyper character:
1528 (defun hyperify (prompt)
1529 (let ((e (read-event)))
1530 (vector (if (numberp e)
1531 (logior (lsh 1 24) e)
1532 (if (memq 'hyper (event-modifiers e))
1534 (add-event-modifier "H-" e))))))
1536 (defun add-event-modifier (string e)
1537 (let ((symbol (if (symbolp e) e (car e))))
1538 (setq symbol (intern (concat string
1539 (symbol-name symbol))))
1544 (cons symbol (cdr e)))))
1546 (define-key function-key-map "\C-ch" 'hyperify)
1550 Finally, if you have enabled keyboard character set decoding using
1551 @code{set-keyboard-coding-system}, decoding is done after the
1552 translations listed above. @xref{Specifying Coding Systems}. In future
1553 Emacs versions, character set decoding may be done before the other
1556 @node Recording Input
1557 @subsection Recording Input
1560 This function returns a vector containing the last 100 input events from
1561 the keyboard or mouse. All input events are included, whether or not
1562 they were used as parts of key sequences. Thus, you always get the last
1563 100 input events, not counting events generated by keyboard macros.
1564 (These are excluded because they are less interesting for debugging; it
1565 should be enough to see the events that invoked the macros.)
1568 @deffn Command open-dribble-file filename
1569 @cindex dribble file
1570 This function opens a @dfn{dribble file} named @var{filename}. When a
1571 dribble file is open, each input event from the keyboard or mouse (but
1572 not those from keyboard macros) is written in that file. A
1573 non-character event is expressed using its printed representation
1574 surrounded by @samp{<@dots{}>}.
1576 You close the dribble file by calling this function with an argument
1579 This function is normally used to record the input necessary to
1580 trigger an Emacs bug, for the sake of a bug report.
1584 (open-dribble-file "~/dribble")
1590 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1592 @node Terminal Output
1593 @section Terminal Output
1594 @cindex terminal output
1596 The terminal output functions send output to the terminal or keep
1597 track of output sent to the terminal. The variable @code{baud-rate}
1598 tells you what Emacs thinks is the output speed of the terminal.
1601 This variable's value is the output speed of the terminal, as far as
1602 Emacs knows. Setting this variable does not change the speed of actual
1603 data transmission, but the value is used for calculations such as
1604 padding. It also affects decisions about whether to scroll part of the
1605 screen or repaint---even when using a window system. (We designed it
1606 this way despite the fact that a window system has no true ``output
1607 speed'', to give you a way to tune these decisions.)
1609 The value is measured in baud.
1612 If you are running across a network, and different parts of the
1613 network work at different baud rates, the value returned by Emacs may be
1614 different from the value used by your local terminal. Some network
1615 protocols communicate the local terminal speed to the remote machine, so
1616 that Emacs and other programs can get the proper value, but others do
1617 not. If Emacs has the wrong value, it makes decisions that are less
1618 than optimal. To fix the problem, set @code{baud-rate}.
1621 This obsolete function returns the value of the variable
1625 @defun send-string-to-terminal string
1626 This function sends @var{string} to the terminal without alteration.
1627 Control characters in @var{string} have terminal-dependent effects.
1629 One use of this function is to define function keys on terminals that
1630 have downloadable function key definitions. For example, this is how on
1631 certain terminals to define function key 4 to move forward four
1632 characters (by transmitting the characters @kbd{C-u C-f} to the
1637 (send-string-to-terminal "\eF4\^U\^F")
1643 @deffn Command open-termscript filename
1644 @cindex termscript file
1645 This function is used to open a @dfn{termscript file} that will record
1646 all the characters sent by Emacs to the terminal. It returns
1647 @code{nil}. Termscript files are useful for investigating problems
1648 where Emacs garbles the screen, problems that are due to incorrect
1649 Termcap entries or to undesirable settings of terminal options more
1650 often than to actual Emacs bugs. Once you are certain which characters
1651 were actually output, you can determine reliably whether they correspond
1652 to the Termcap specifications in use.
1654 See also @code{open-dribble-file} in @ref{Terminal Input}.
1658 (open-termscript "../junk/termscript")
1664 @node Special Keysyms
1665 @section System-Specific X11 Keysyms
1667 To define system-specific X11 keysyms, set the variable
1668 @code{system-key-alist}.
1670 @defvar system-key-alist
1671 This variable's value should be an alist with one element for each
1672 system-specific keysym. An element has this form: @code{(@var{code}
1673 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1674 including the ``vendor specific'' bit,
1681 and @var{symbol} is the name for the function key.
1683 For example @code{(168 . mute-acute)} defines a system-specific key used
1684 by HP X servers whose numeric code is
1693 It is not crucial to exclude from the alist the keysyms of other X
1694 servers; those do no harm, as long as they don't conflict with the ones
1695 used by the X server actually in use.
1697 The variable is always local to the current terminal, and cannot be
1698 buffer-local. @xref{Multiple Displays}.
1702 @section Flow Control
1703 @cindex flow control characters
1705 This section attempts to answer the question ``Why does Emacs use
1706 flow-control characters in its command character set?'' For a second
1707 view on this issue, read the comments on flow control in the
1708 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1709 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1713 At one time, most terminals did not need flow control, and none used
1714 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1715 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
1716 was natural and uncontroversial. With so many commands needing key
1717 assignments, of course we assigned meanings to nearly all @sc{ASCII}
1720 Later, some terminals were introduced which required these characters
1721 for flow control. They were not very good terminals for full-screen
1722 editing, so Emacs maintainers ignored them. In later years, flow
1723 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
1724 but by this time it was usually an option. And the majority of Emacs
1725 users, who can turn flow control off, did not want to switch to less
1726 mnemonic key bindings for the sake of flow control.
1728 So which usage is ``right''---Emacs's or that of some terminal and
1729 concentrator manufacturers? This question has no simple answer.
1731 One reason why we are reluctant to cater to the problems caused by
1732 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1733 techniques (albeit less common in practice) for flow control that
1734 preserve transparency of the character stream. Note also that their use
1735 for flow control is not an official standard. Interestingly, on the
1736 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
1737 @kbd{C-q} were sent by the computer to turn the punch on and off!
1739 As window systems and PC terminal emulators replace character-only
1740 terminals, the flow control problem is gradually disappearing. For the
1741 mean time, Emacs provides a convenient way of enabling flow control if
1742 you want it: call the function @code{enable-flow-control}.
1744 @deffn Command enable-flow-control
1745 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1746 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1747 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1750 You can use the function @code{enable-flow-control-on} in your
1751 @file{.emacs} file to enable flow control automatically on certain
1754 @defun enable-flow-control-on &rest termtypes
1755 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1756 if the terminal type is one of @var{termtypes}. For example:
1759 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1763 Here is how @code{enable-flow-control} does its job:
1768 It sets @sc{cbreak} mode for terminal input, and tells the operating
1769 system to handle flow control, with @code{(set-input-mode nil t)}.
1772 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1773 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1774 lowest level, Emacs never knows that the characters typed were anything
1775 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1776 and @kbd{C-^} even when they are input for other commands.
1777 @xref{Translating Input}.
1780 If the terminal is the source of the flow control characters, then once
1781 you enable kernel flow control handling, you probably can make do with
1782 less padding than normal for that terminal. You can reduce the amount
1783 of padding by customizing the Termcap entry. You can also reduce it by
1784 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1785 speed when calculating the padding needed. @xref{Terminal Output}.
1790 @cindex noninteractive use
1792 The command line option @samp{-batch} causes Emacs to run
1793 noninteractively. In this mode, Emacs does not read commands from the
1794 terminal, it does not alter the terminal modes, and it does not expect
1795 to be outputting to an erasable screen. The idea is that you specify
1796 Lisp programs to run; when they are finished, Emacs should exit. The
1797 way to specify the programs to run is with @samp{-l @var{file}}, which
1798 loads the library named @var{file}, and @samp{-f @var{function}}, which
1799 calls @var{function} with no arguments.
1801 Any Lisp program output that would normally go to the echo area,
1802 either using @code{message} or using @code{prin1}, etc., with @code{t}
1803 as the stream, goes instead to Emacs's standard error descriptor when
1804 in batch mode. Thus, Emacs behaves much like a noninteractive
1805 application program. (The echo area output that Emacs itself normally
1806 generates, such as command echoing, is suppressed entirely.)
1808 @defvar noninteractive
1809 This variable is non-@code{nil} when Emacs is running in batch mode.