*** empty log message ***
[emacs.git] / lispref / os.texi
blobbd05d39cf44631bbef9ddec96932d0e183b76af7
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/os
7 @node System Interface, Antinews, Calendar, Top
8 @chapter Operating System Interface
10   This chapter is about starting and getting out of Emacs, access to
11 values in the operating system environment, and terminal input, output,
12 and flow control.
14   @xref{Building Emacs}, for related information.  See also
15 @ref{Display}, for additional operating system status information
16 pertaining to the terminal and the screen.
18 @menu
19 * Starting Up::         Customizing Emacs startup processing.
20 * Getting Out::         How exiting works (permanent or temporary).
21 * System Environment::  Distinguish the name and kind of system.
22 * User Identification:: Finding the name and user id of the user.
23 * Time of Day::         Getting the current time.
24 * Time Conversion::     Converting a time from numeric form to a string, or
25                           to calendrical data (or vice versa).
26 * 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 * Sound Output::        Playing sounds on the computer's speaker.
30 * Special Keysyms::     Defining system-specific key symbols for X.
31 * Flow Control::        How to turn output flow control on or off.
32 * Batch Mode::          Running Emacs without terminal interaction.
33 @end menu
35 @node Starting Up
36 @section Starting Up Emacs
38   This section describes what Emacs does when it is started, and how you
39 can customize these actions.
41 @menu
42 * Startup Summary::         Sequence of actions Emacs performs at startup.
43 * Init File::               Details on reading the init file (@file{.emacs}).
44 * Terminal-Specific::       How the terminal-specific Lisp file is read.
45 * Command-Line Arguments::  How command-line arguments are processed,
46                               and how you can customize them.
47 @end menu
49 @node Startup Summary
50 @subsection Summary: Sequence of Actions at Startup
51 @cindex initialization
52 @cindex startup of Emacs
53 @cindex @file{startup.el}
55    The order of operations performed (in @file{startup.el}) by Emacs when
56 it is started up is as follows:
58 @enumerate
59 @item
60 It adds subdirectories to @code{load-path}, by running the file named
61 @file{subdirs.el} in each directory in the list.  Normally this file
62 adds the directory's subdirectories to the list, and these will be
63 scanned in their turn.  The files @file{subdirs.el} are normally
64 generated automatically by Emacs installation.
66 @item
67 It sets the language environment and the terminal coding system,
68 if requested by environment variables such as @code{LANG}.
70 @item
71 It loads the initialization library for the window system, if you are
72 using a window system.  This library's name is
73 @file{term/@var{windowsystem}-win.el}.
75 @item
76 It processes the initial options.  (Some of them are handled
77 even earlier than this.)
79 @item
80 It initializes the window frame and faces, if appropriate.
82 @item
83 It runs the normal hook @code{before-init-hook}.
85 @item
86 It loads the library @file{site-start}, unless the option
87 @samp{-no-site-file} was specified.  The library's file name is usually
88 @file{site-start.el}.
89 @cindex @file{site-start.el}
91 @item 
92 It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
93 @samp{-no-init-file}, or @samp{-batch} was specified on the command line.
94 The @samp{-u} option can specify another user whose home directory
95 should be used instead of @file{~}.
97 @item 
98 It loads the library @file{default}, unless @code{inhibit-default-init}
99 is non-@code{nil}.  (This is not done in @samp{-batch} mode or if
100 @samp{-q} was specified on the command line.)  The library's file name
101 is usually @file{default.el}.
102 @cindex @file{default.el}
104 @item
105 It runs the normal hook @code{after-init-hook}.
107 @item
108 It sets the major mode according to @code{initial-major-mode}, provided
109 the buffer @samp{*scratch*} is still current and still in Fundamental
110 mode.
112 @item 
113 It loads the terminal-specific Lisp file, if any, except when in batch
114 mode or using a window system.
116 @item
117 It displays the initial echo area message, unless you have suppressed
118 that with @code{inhibit-startup-echo-area-message}.
120 @item 
121 It processes the action arguments from the command line.
123 @item 
124 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
126 @item
127 It calls @code{frame-notice-user-settings}, which modifies the
128 parameters of the selected frame according to whatever the init files
129 specify.
131 @item 
132 It runs @code{window-setup-hook}.  @xref{Window Systems}.
134 @item 
135 It displays copyleft, nonwarranty, and basic use information, provided
136 there were no remaining command-line arguments (a few steps above),
137 the value of @code{inhibit-startup-message} is @code{nil}, and the
138 buffer is still empty.
139 @end enumerate
141 @defopt inhibit-startup-message
142 This variable inhibits the initial startup messages (the nonwarranty,
143 etc.).  If it is non-@code{nil}, then the messages are not printed.
145 This variable exists so you can set it in your personal init file, once
146 you are familiar with the contents of the startup message.  Do not set
147 this variable in the init file of a new user, or in a way that affects
148 more than one user, because that would prevent new users from receiving
149 the information they are supposed to see.
150 @end defopt
152 @defopt inhibit-startup-echo-area-message
153 This variable controls the display of the startup echo area message.
154 You can suppress the startup echo area message by adding text with this
155 form to your init file:
157 @example
158 (setq inhibit-startup-echo-area-message
159       "@var{your-login-name}")
160 @end example
162 Emacs explicitly checks for an expression as shown above in your init
163 file; your login name must appear in the expression as a Lisp string
164 constant.  Other methods of setting
165 @code{inhibit-startup-echo-area-message} to the same value do not
166 inhibit the startup message.
168 This way, you can easily inhibit the message for yourself if you wish,
169 but thoughtless copying of your init file will not inhibit the message
170 for someone else.
171 @end defopt
173 @node Init File
174 @subsection The Init File, @file{.emacs}
175 @cindex init file
176 @cindex @file{.emacs}
178   When you start Emacs, it normally attempts to load your @dfn{init
179 file}, a file in your home directory.  Its normal name is @file{.emacs},
180 but you can alternatively call it @file{.emacs.el}, which enables you to
181 byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
182 will be @file{.emacs.elc}.
184   The command-line switches @samp{-q} and @samp{-u} control whether and
185 where to find the init file; @samp{-q} says not to load an init file,
186 and @samp{-u @var{user}} says to load @var{user}'s init file instead of
187 yours.  @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}.  If
188 neither option is specified, Emacs uses the @code{LOGNAME} environment
189 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
190 systems) variable, to find your home directory and thus your init file;
191 this way, even if you have su'd, Emacs still loads your own init file.
192 If those environment variables are absent, though, Emacs uses your
193 user-id to find your home directory.
195 @cindex default init file
196   A site may have a @dfn{default init file}, which is the library named
197 @file{default.el}.  Emacs finds the @file{default.el} file through the
198 standard search path for libraries (@pxref{How Programs Do Loading}).
199 The Emacs distribution does not come with this file; sites may provide
200 one for local customizations.  If the default init file exists, it is
201 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
202 specified.  But your own personal init file, if any, is loaded first; if
203 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
204 Emacs does not subsequently load the @file{default.el} file.
206   Another file for site-customization is @file{site-start.el}.  Emacs
207 loads this @emph{before} the user's init file.  You can inhibit the
208 loading of this file with the option @samp{-no-site-file}.
210 @defvar site-run-file
211 This variable specifies the site-customization file to load before the
212 user's init file.  Its normal value is @code{"site-start"}.  The only
213 way you can change it with real effect is to do so before dumping
214 Emacs.
215 @end defvar
217   @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
218 examples of how to make various commonly desired customizations in your
219 @file{.emacs} file.
221 @defopt inhibit-default-init
222 This variable prevents Emacs from loading the default initialization
223 library file for your session of Emacs.  If its value is non-@code{nil},
224 then the default library is not loaded.  The default value is
225 @code{nil}.
226 @end defopt
228 @defvar before-init-hook
229 This normal hook is run, once, just before loading all the init files
230 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
231 (The only way to change it with real effect is before dumping Emacs.)
232 @end defvar
234 @defvar after-init-hook
235 This normal hook is run, once, just after loading all the init files
236 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
237 before loading the terminal-specific library and processing the
238 command-line arguments.
239 @end defvar
241 @defvar emacs-startup-hook
242 @tindex emacs-startup-hook
243 This normal hook is run, once, just after handling the command line
244 arguments, just before @code{term-setup-hook}.
245 @end defvar
247 @defvar user-init-file
248 @tindex user-init-file
249 This variable holds the file name of the user's init file.  If the
250 actual init file loaded is a compiled file, such as @file{.emacs.elc},
251 the value refers to the corresponding source file.
252 @end defvar
254 @node Terminal-Specific
255 @subsection Terminal-Specific Initialization
256 @cindex terminal-specific initialization
258   Each terminal type can have its own Lisp library that Emacs loads when
259 run on that type of terminal.  The library's name is constructed by
260 concatenating the value of the variable @code{term-file-prefix} and the
261 terminal type (specified by the environment variable @code{TERM}).
262 Normally, @code{term-file-prefix} has the value
263 @code{"term/"}; changing this is not recommended.  Emacs finds the file
264 in the normal manner, by searching the @code{load-path} directories, and
265 trying the @samp{.elc} and @samp{.el} suffixes.
267   The usual function of a terminal-specific library is to enable special
268 keys to send sequences that Emacs can recognize.  It may also need to
269 set or add to @code{function-key-map} if the Termcap entry does not
270 specify all the terminal's function keys.  @xref{Terminal Input}.
272 @cindex Termcap
273   When the name of the terminal type contains a hyphen, only the part of
274 the name before the first hyphen is significant in choosing the library
275 name.  Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
276 the @file{term/aaa} library.  If necessary, the library can evaluate
277 @code{(getenv "TERM")} to find the full name of the terminal
278 type.@refill
280   Your init file can prevent the loading of the
281 terminal-specific library by setting the variable
282 @code{term-file-prefix} to @code{nil}.  This feature is useful when
283 experimenting with your own peculiar customizations.
285   You can also arrange to override some of the actions of the
286 terminal-specific library by setting the variable
287 @code{term-setup-hook}.  This is a normal hook which Emacs runs using
288 @code{run-hooks} at the end of Emacs initialization, after loading both
289 your init file and any terminal-specific libraries.  You can
290 use this variable to define initializations for terminals that do not
291 have their own libraries.  @xref{Hooks}.
293 @defvar term-file-prefix
294 @cindex @code{TERM} environment variable
295 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
296 a terminal-specific initialization file as follows:
298 @example
299 (load (concat term-file-prefix (getenv "TERM")))
300 @end example
302 @noindent
303 You may set the @code{term-file-prefix} variable to @code{nil} in your
304 init file if you do not wish to load the
305 terminal-initialization file.  To do this, put the following in
306 your init file: @code{(setq term-file-prefix nil)}.
308 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
309 uses @samp{internal} as the terminal type.
310 @end defvar
312 @defvar term-setup-hook 
313 This variable is a normal hook that Emacs runs after loading your
314 init file, the default initialization file (if any) and the
315 terminal-specific Lisp file.
317 You can use @code{term-setup-hook} to override the definitions made by a
318 terminal-specific file.
319 @end defvar
321   See @code{window-setup-hook} in @ref{Window Systems}, for a related
322 feature.
324 @node Command-Line Arguments
325 @subsection Command-Line Arguments
326 @cindex command-line arguments
328   You can use command-line arguments to request various actions when you
329 start Emacs.  Since you do not need to start Emacs more than once per
330 day, and will often leave your Emacs session running longer than that,
331 command-line arguments are hardly ever used.  As a practical matter, it
332 is best to avoid making the habit of using them, since this habit would
333 encourage you to kill and restart Emacs unnecessarily often.  These
334 options exist for two reasons: to be compatible with other editors (for
335 invocation by other programs) and to enable shell scripts to run
336 specific Lisp programs.
338   This section describes how Emacs processes command-line arguments,
339 and how you can customize them.
341 @ignore
342   (Note that some other editors require you to start afresh each time
343 you want to edit a file.  With this kind of editor, you will probably
344 specify the file as a command-line argument.  The recommended way to
345 use GNU Emacs is to start it only once, just after you log in, and do
346 all your editing in the same Emacs process.  Each time you want to edit
347 a different file, you visit it with the existing Emacs, which eventually
348 comes to have many files in it ready for editing.  Usually you do not
349 kill the Emacs until you are about to log out.)
350 @end ignore
352 @defun command-line
353 This function parses the command line that Emacs was called with,
354 processes it, loads the user's init file and displays the
355 startup messages.
356 @end defun
358 @defvar command-line-processed
359 The value of this variable is @code{t} once the command line has been
360 processed.
362 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
363 this variable to @code{nil} first in order to cause the new dumped Emacs
364 to process its new command-line arguments.
365 @end defvar
367 @defvar command-switch-alist
368 @cindex switches on command line
369 @cindex options on command line
370 @cindex command-line options
371 The value of this variable is an alist of user-defined command-line
372 options and associated handler functions.  This variable exists so you
373 can add elements to it.
375 A @dfn{command-line option} is an argument on the command line, which
376 has the form:
378 @example
379 -@var{option}
380 @end example
382 The elements of the @code{command-switch-alist} look like this: 
384 @example
385 (@var{option} . @var{handler-function})
386 @end example
388 The @sc{car}, @var{option}, is a string, the name of a command-line
389 option (not including the initial hyphen).  The @var{handler-function}
390 is called to handle @var{option}, and receives the option name as its
391 sole argument.
393 In some cases, the option is followed in the command line by an
394 argument.  In these cases, the @var{handler-function} can find all the
395 remaining command-line arguments in the variable
396 @code{command-line-args-left}.  (The entire list of command-line
397 arguments is in @code{command-line-args}.)
399 The command-line arguments are parsed by the @code{command-line-1}
400 function in the @file{startup.el} file.  See also @ref{Command
401 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
402 Manual}.
403 @end defvar
405 @defvar command-line-args
406 The value of this variable is the list of command-line arguments passed
407 to Emacs.
408 @end defvar
410 @defvar command-line-functions
411 This variable's value is a list of functions for handling an
412 unrecognized command-line argument.  Each time the next argument to be
413 processed has no special meaning, the functions in this list are called,
414 in order of appearance, until one of them returns a non-@code{nil}
415 value.
417 These functions are called with no arguments.  They can access the
418 command-line argument under consideration through the variable
419 @code{argi}, which is bound temporarily at this point.  The remaining
420 arguments (not including the current one) are in the variable
421 @code{command-line-args-left}.
423 When a function recognizes and processes the argument in @code{argi}, it
424 should return a non-@code{nil} value to say it has dealt with that
425 argument.  If it has also dealt with some of the following arguments, it
426 can indicate that by deleting them from @code{command-line-args-left}.
428 If all of these functions return @code{nil}, then the argument is used
429 as a file name to visit.
430 @end defvar
432 @node Getting Out
433 @section Getting Out of Emacs
434 @cindex exiting Emacs
436   There are two ways to get out of Emacs: you can kill the Emacs job,
437 which exits permanently, or you can suspend it, which permits you to
438 reenter the Emacs process later.  As a practical matter, you seldom kill
439 Emacs---only when you are about to log out.  Suspending is much more
440 common.
442 @menu
443 * Killing Emacs::        Exiting Emacs irreversibly.
444 * Suspending Emacs::     Exiting Emacs reversibly.
445 @end menu
447 @node Killing Emacs
448 @comment  node-name,  next,  previous,  up
449 @subsection Killing Emacs
450 @cindex killing Emacs
452   Killing Emacs means ending the execution of the Emacs process.  The
453 parent process normally resumes control.  The low-level primitive for
454 killing Emacs is @code{kill-emacs}.
456 @defun kill-emacs &optional exit-data
457 This function exits the Emacs process and kills it.
459 If @var{exit-data} is an integer, then it is used as the exit status
460 of the Emacs process.  (This is useful primarily in batch operation; see
461 @ref{Batch Mode}.)
463 If @var{exit-data} is a string, its contents are stuffed into the
464 terminal input buffer so that the shell (or whatever program next reads
465 input) can read them.
466 @end defun
468   All the information in the Emacs process, aside from files that have
469 been saved, is lost when the Emacs process is killed.  Because killing
470 Emacs inadvertently can lose a lot of work, Emacs queries for
471 confirmation before actually terminating if you have buffers that need
472 saving or subprocesses that are running.  This is done in the function
473 @code{save-buffers-kill-emacs}.
475 @defvar kill-emacs-query-functions
476 After asking the standard questions, @code{save-buffers-kill-emacs}
477 calls the functions in the list @code{kill-emacs-query-functions}, in
478 order of appearance, with no arguments.  These functions can ask for
479 additional confirmation from the user.  If any of them returns
480 @code{nil}, Emacs is not killed.
481 @end defvar
483 @defvar kill-emacs-hook
484 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
485 finished with all file saving and confirmation, it runs the functions in
486 this hook.
487 @end defvar
489 @node Suspending Emacs
490 @subsection Suspending Emacs
491 @cindex suspending Emacs
493   @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
494 control to its superior process, which is usually the shell.  This
495 allows you to resume editing later in the same Emacs process, with the
496 same buffers, the same kill ring, the same undo history, and so on.  To
497 resume Emacs, use the appropriate command in the parent shell---most
498 likely @code{fg}.
500   Some operating systems do not support suspension of jobs; on these
501 systems, ``suspension'' actually creates a new shell temporarily as a
502 subprocess of Emacs.  Then you would exit the shell to return to Emacs.
504   Suspension is not useful with window systems, because the Emacs job
505 may not have a parent that can resume it again, and in any case you can
506 give input to some other job such as a shell merely by moving to a
507 different window.  Therefore, suspending is not allowed when Emacs is using
508 a window system (X or MS Windows).
510 @defun suspend-emacs string
511 This function stops Emacs and returns control to the superior process.
512 If and when the superior process resumes Emacs, @code{suspend-emacs}
513 returns @code{nil} to its caller in Lisp.
515 If @var{string} is non-@code{nil}, its characters are sent to be read
516 as terminal input by Emacs's superior shell.  The characters in
517 @var{string} are not echoed by the superior shell; only the results
518 appear.
520 Before suspending, @code{suspend-emacs} runs the normal hook
521 @code{suspend-hook}.
523 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
524 @code{suspend-resume-hook}.  @xref{Hooks}.
526 The next redisplay after resumption will redraw the entire screen,
527 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
528 (@pxref{Refresh Screen}).
530 In the following example, note that @samp{pwd} is not echoed after
531 Emacs is suspended.  But it is read and executed by the shell.
533 @smallexample
534 @group
535 (suspend-emacs)
536      @result{} nil
537 @end group
539 @group
540 (add-hook 'suspend-hook
541           (function (lambda ()
542                       (or (y-or-n-p
543                             "Really suspend? ")
544                           (error "Suspend cancelled")))))
545      @result{} (lambda nil
546           (or (y-or-n-p "Really suspend? ")
547               (error "Suspend cancelled")))
548 @end group
549 @group
550 (add-hook 'suspend-resume-hook
551           (function (lambda () (message "Resumed!"))))
552      @result{} (lambda nil (message "Resumed!"))
553 @end group
554 @group
555 (suspend-emacs "pwd")
556      @result{} nil
557 @end group
558 @group
559 ---------- Buffer: Minibuffer ----------
560 Really suspend? @kbd{y}
561 ---------- Buffer: Minibuffer ----------
562 @end group
564 @group
565 ---------- Parent Shell ----------
566 lewis@@slug[23] % /user/lewis/manual
567 lewis@@slug[24] % fg
568 @end group
570 @group
571 ---------- Echo Area ----------
572 Resumed!
573 @end group
574 @end smallexample
575 @end defun
577 @defvar suspend-hook
578 This variable is a normal hook that Emacs runs before suspending.
579 @end defvar
581 @defvar suspend-resume-hook
582 This variable is a normal hook that Emacs runs on resuming
583 after a suspension.
584 @end defvar
586 @node System Environment
587 @section Operating System Environment
588 @cindex operating system environment
590   Emacs provides access to variables in the operating system environment
591 through various functions.  These variables include the name of the
592 system, the user's @sc{uid}, and so on.
594 @defvar system-configuration
595 This variable holds the GNU configuration name for the hardware/software
596 configuration of your system, as a string.  The convenient way to test
597 parts of this string is with @code{string-match}.
598 @end defvar
600 @defvar system-type
601 The value of this variable is a symbol indicating the type of operating
602 system Emacs is operating on.  Here is a table of the possible values:
604 @table @code
605 @item alpha-vms
606 VMS on the Alpha.
608 @item aix-v3
609 AIX.
611 @item berkeley-unix
612 Berkeley BSD.
614 @item dgux
615 Data General DGUX operating system.
617 @item gnu
618 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
620 @item gnu/linux
621 A GNU/Linux system---that is, a variant GNU system, using the Linux
622 kernel.  (These systems are the ones people often call ``Linux,'' but
623 actually Linux is just the kernel, not the whole system.)
625 @item hpux
626 Hewlett-Packard HPUX operating system.
628 @item irix
629 Silicon Graphics Irix system.
631 @item ms-dos
632 Microsoft MS-DOS ``operating system.''  Emacs compiled with DJGPP for
633 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
634 MS-Windows.
636 @item next-mach
637 NeXT Mach-based system.
639 @item rtu
640 Masscomp RTU, UCB universe.
642 @item unisoft-unix
643 UniSoft UniPlus.
645 @item usg-unix-v
646 AT&T System V.
648 @item vax-vms
649 VAX VMS.
651 @item windows-nt
652 Microsoft windows NT.  The same executable supports Windows 9X, but the
653 value of @code{system-type} is @code{windows-nt} in either case.
655 @item xenix
656 SCO Xenix 386.
657 @end table
659 We do not wish to add new symbols to make finer distinctions unless it
660 is absolutely necessary!  In fact, we hope to eliminate some of these
661 alternatives in the future.  We recommend using
662 @code{system-configuration} to distinguish between different operating
663 systems.
664 @end defvar
666 @defun system-name
667 This function returns the name of the machine you are running on.
668 @example
669 (system-name)
670      @result{} "www.gnu.org"
671 @end example
672 @end defun
674   The symbol @code{system-name} is a variable as well as a function.  In
675 fact, the function returns whatever value the variable
676 @code{system-name} currently holds.  Thus, you can set the variable
677 @code{system-name} in case Emacs is confused about the name of your
678 system.  The variable is also useful for constructing frame titles
679 (@pxref{Frame Titles}).
681 @defvar mail-host-address
682 If this variable is non-@code{nil}, it is used instead of
683 @code{system-name} for purposes of generating email addresses.  For
684 example, it is used when constructing the default value of
685 @code{user-mail-address}.  @xref{User Identification}.  (Since this is
686 done when Emacs starts up, the value actually used is the one saved when
687 Emacs was dumped.  @xref{Building Emacs}.)
688 @end defvar
690 @deffn Command getenv var
691 @cindex environment variable access
692 This function returns the value of the environment variable @var{var},
693 as a string.  Within Emacs, the environment variable values are kept in
694 the Lisp variable @code{process-environment}.
696 @example
697 @group
698 (getenv "USER")
699      @result{} "lewis"
700 @end group
702 @group
703 lewis@@slug[10] % printenv
704 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
705 USER=lewis
706 @end group
707 @group
708 TERM=ibmapa16
709 SHELL=/bin/csh
710 HOME=/user/lewis
711 @end group
712 @end example
713 @end deffn
715 @c Emacs 19 feature
716 @deffn Command setenv variable value
717 This command sets the value of the environment variable named
718 @var{variable} to @var{value}.  Both arguments should be strings.  This
719 function works by modifying @code{process-environment}; binding that
720 variable with @code{let} is also reasonable practice.
721 @end deffn
723 @defvar process-environment
724 This variable is a list of strings, each describing one environment
725 variable.  The functions @code{getenv} and @code{setenv} work by means
726 of this variable.
728 @smallexample
729 @group
730 process-environment
731 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
732     "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
733     "USER=lewis" 
734 @end group
735 @group
736     "TERM=ibmapa16" 
737     "SHELL=/bin/csh"
738     "HOME=/user/lewis")
739 @end group
740 @end smallexample
741 @end defvar
743 @defvar path-separator
744 This variable holds a string which says which character separates
745 directories in a search path (as found in an environment variable).  Its
746 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
747 and MS-Windows.
748 @end defvar
750 @defun parse-colon-path path
751 @tindex parse-colon-path
752 This function takes a search path string such as would be the value of
753 the @code{PATH} environment variable, and splits it at the separators,
754 returning a list of directory names.  @code{nil} in this list stands for
755 ``use the current directory.''  Although the function's name says
756 ``colon,'' it actually uses the value of @code{path-separator}.
758 @example
759 (parse-colon-path ":/foo:/bar")
760      @result{} (nil "/foo/" "/bar/")
761 @end example
762 @end defun
764 @defvar invocation-name
765 This variable holds the program name under which Emacs was invoked.  The
766 value is a string, and does not include a directory name.
767 @end defvar
769 @defvar invocation-directory
770 This variable holds the directory from which the Emacs executable was
771 invoked, or perhaps @code{nil} if that directory cannot be determined.
772 @end defvar
774 @defvar installation-directory
775 If non-@code{nil}, this is a directory within which to look for the
776 @file{lib-src} and @file{etc} subdirectories.  This is non-@code{nil}
777 when Emacs can't find those directories in their standard installed
778 locations, but can find them in a directory related somehow to the one
779 containing the Emacs executable.
780 @end defvar
782 @defun load-average &optional use-float
783 This function returns the current 1-minute, 5-minute, and 15-minute load
784 averages, in a list.
786 By default, the values are integers that are 100 times the system load
787 averages, which indicate the average number of processes trying to run.
788 If @var{use-float} is non-@code{nil}, then they are returned
789 as floating point numbers and without multiplying by 100.
791 @example
792 @group
793 (load-average)
794      @result{} (169 48 36)
795 @end group
796 @group
797 (load-average t)
798      @result{} (1.69 0.48 0.36)
799 @end group
801 @group
802 lewis@@rocky[5] % uptime
803  11:55am  up 1 day, 19:37,  3 users,
804  load average: 1.69, 0.48, 0.36
805 @end group
806 @end example
807 @end defun
809 @defun emacs-pid
810 This function returns the process @sc{id} of the Emacs process.
811 @end defun
813 @defvar tty-erase-char
814 This variable holds the erase character that was selected
815 in the system's terminal driver, before Emacs was started.
816 @end defvar
818 @defun setprv privilege-name &optional setp getprv
819 This function sets or resets a VMS privilege.  (It does not exist on
820 other systems.)  The first argument is the privilege name, as a string.
821 The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
822 whether the privilege is to be turned on or off.  Its default is
823 @code{nil}.  The function returns @code{t} if successful, @code{nil}
824 otherwise.
826   If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
827 does not change the privilege, but returns @code{t} or @code{nil}
828 indicating whether the privilege is currently enabled.
829 @end defun
831 @node User Identification
832 @section User Identification
834 @defvar init-file-user
835 This variable says which user's init files should be used by Emacs---or
836 @code{nil} if none.  The value reflects command-line options such as
837 @samp{-q} or @samp{-u @var{user}}.
839 Lisp packages that load files of customizations, or any other sort of
840 user profile, should obey this variable in deciding where to find it.
841 They should load the profile of the user name found in this variable.
842 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
843 option was used, then Lisp packages should not load any customization
844 files or user profile.
845 @end defvar
847 @defvar user-mail-address
848 This holds the nominal email address of the user who is using Emacs.
849 Emacs normally sets this variable to a default value after reading your
850 init files, but not if you have already set it.  So you can set the
851 variable to some other value in your init file if you do not
852 want to use the default value.
853 @end defvar
855 @defun user-login-name &optional uid
856 If you don't specify @var{uid}, this function returns the name under
857 which the user is logged in.  If the environment variable @code{LOGNAME}
858 is set, that value is used.  Otherwise, if the environment variable
859 @code{USER} is set, that value is used.  Otherwise, the value is based
860 on the effective @sc{uid}, not the real @sc{uid}.
862 If you specify @var{uid}, the value is the user name that corresponds
863 to @var{uid} (which should be an integer).
865 @example
866 @group
867 (user-login-name)
868      @result{} "lewis"
869 @end group
870 @end example
871 @end defun
873 @defun user-real-login-name
874 This function returns the user name corresponding to Emacs's real
875 @sc{uid}.  This ignores the effective @sc{uid} and ignores the
876 environment variables @code{LOGNAME} and @code{USER}.
877 @end defun
879 @defun user-full-name &optional uid
880 This function returns the full name of the logged-in user---or the value
881 of the environment variable @code{NAME}, if that is set.
883 @c "Bil" is the correct spelling.
884 @example
885 @group
886 (user-full-name)
887      @result{} "Bil Lewis"
888 @end group
889 @end example
891 If the Emacs job's user-id does not correspond to any known user (and
892 provided @code{NAME} is not set), the value is @code{"unknown"}.
894 If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
895 or a string (a login name).  Then @code{user-full-name} returns the full
896 name corresponding to that user-id or login name.  If you specify a
897 user-id or login name that isn't defined, it returns @code{nil}.
898 @end defun
900 @vindex user-full-name
901 @vindex user-real-login-name
902 @vindex user-login-name
903   The symbols @code{user-login-name}, @code{user-real-login-name} and
904 @code{user-full-name} are variables as well as functions.  The functions
905 return the same values that the variables hold.  These variables allow
906 you to ``fake out'' Emacs by telling the functions what to return.  The
907 variables are also useful for constructing frame titles (@pxref{Frame
908 Titles}).
910 @defun user-real-uid
911 This function returns the real @sc{uid} of the user.
913 @example
914 @group
915 (user-real-uid)
916      @result{} 19
917 @end group
918 @end example
919 @end defun
921 @defun user-uid
922 This function returns the effective @sc{uid} of the user.  
923 @end defun
925 @node Time of Day
926 @section Time of Day
928   This section explains how to determine the current time and the time
929 zone.
931 @defun current-time-string &optional time-value
932 This function returns the current time and date as a human-readable
933 string.  The format of the string is unvarying; the number of characters
934 used for each part is always the same, so you can reliably use
935 @code{substring} to extract pieces of it.  It is wise to count the
936 characters from the beginning of the string rather than from the end, as
937 additional information may some day be added at the end.
939 @c Emacs 19 feature
940 The argument @var{time-value}, if given, specifies a time to format
941 instead of the current time.  The argument should be a list whose first
942 two elements are integers.  Thus, you can use times obtained from
943 @code{current-time} (see below) and from @code{file-attributes}
944 (@pxref{File Attributes}).
946 @example
947 @group
948 (current-time-string)
949      @result{} "Wed Oct 14 22:21:05 1987"
950 @end group
951 @end example
952 @end defun
954 @c Emacs 19 feature
955 @defun current-time
956 This function returns the system's time value as a list of three
957 integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
958 @var{high} and @var{low} combine to give the number of seconds since
959 0:00 January 1, 1970 (local time), which is
960 @ifnottex
961 @var{high} * 2**16 + @var{low}.
962 @end ifnottex
963 @tex
964 $high*2^{16}+low$.
965 @end tex
967 The third element, @var{microsec}, gives the microseconds since the
968 start of the current second (or 0 for systems that return time with
969 the resolution of only one second).
971 The first two elements can be compared with file time values such as you
972 get with the function @code{file-attributes}.  @xref{File Attributes}.
973 @end defun
975 @c Emacs 19 feature
976 @defun current-time-zone &optional time-value
977 This function returns a list describing the time zone that the user is
980 The value has the form @code{(@var{offset} @var{name})}.  Here
981 @var{offset} is an integer giving the number of seconds ahead of UTC
982 (east of Greenwich).  A negative value means west of Greenwich.  The
983 second element, @var{name}, is a string giving the name of the time
984 zone.  Both elements change when daylight savings time begins or ends;
985 if the user has specified a time zone that does not use a seasonal time
986 adjustment, then the value is constant through time.
988 If the operating system doesn't supply all the information necessary to
989 compute the value, both elements of the list are @code{nil}.
991 The argument @var{time-value}, if given, specifies a time to analyze
992 instead of the current time.  The argument should be a cons cell
993 containing two integers, or a list whose first two elements are
994 integers.  Thus, you can use times obtained from @code{current-time}
995 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
996 @end defun
998 @node Time Conversion
999 @section Time Conversion
1001   These functions convert time values (lists of two or three integers)
1002 to strings or to calendrical information.  There is also a function to
1003 convert calendrical information to a time value.  You can get time
1004 values from the functions @code{current-time} (@pxref{Time of Day}) and
1005 @code{file-attributes} (@pxref{File Attributes}).
1007 Many operating systems are limited to time values that contain 32 bits
1008 of information; these systems typically handle only the times from
1009 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
1010 operating systems have larger time values, and can represent times far
1011 in the past or future.
1013 Time conversion functions always use the Gregorian calendar, even for
1014 dates before the Gregorian calendar was introduced.  Year numbers count
1015 the number of years since the year 1 B.C., and do not skip zero as
1016 traditional Gregorian years do; for example, the year number @minus{}37
1017 represents the Gregorian year 38 B.C@.
1019 @defun format-time-string format-string &optional time universal
1020 This function converts @var{time} (or the current time, if @var{time} is
1021 omitted) to a string according to @var{format-string}.  The argument
1022 @var{format-string} may contain @samp{%}-sequences which say to
1023 substitute parts of the time.  Here is a table of what the
1024 @samp{%}-sequences mean:
1026 @table @samp
1027 @item %a
1028 This stands for the abbreviated name of the day of week.
1029 @item %A
1030 This stands for the full name of the day of week.
1031 @item %b
1032 This stands for the abbreviated name of the month.
1033 @item %B
1034 This stands for the full name of the month.
1035 @item %c
1036 This is a synonym for @samp{%x %X}.
1037 @item %C
1038 This has a locale-specific meaning.  In the default locale (named C), it
1039 is equivalent to @samp{%A, %B %e, %Y}.
1040 @item %d
1041 This stands for the day of month, zero-padded.
1042 @item %D
1043 This is a synonym for @samp{%m/%d/%y}.
1044 @item %e
1045 This stands for the day of month, blank-padded.
1046 @item %h
1047 This is a synonym for @samp{%b}.
1048 @item %H
1049 This stands for the hour (00-23).
1050 @item %I
1051 This stands for the hour (01-12).
1052 @item %j
1053 This stands for the day of the year (001-366).
1054 @item %k
1055 This stands for the hour (0-23), blank padded.
1056 @item %l
1057 This stands for the hour (1-12), blank padded.
1058 @item %m
1059 This stands for the month (01-12).
1060 @item %M
1061 This stands for the minute (00-59).
1062 @item %n
1063 This stands for a newline.
1064 @item %p
1065 This stands for @samp{AM} or @samp{PM}, as appropriate.
1066 @item %r
1067 This is a synonym for @samp{%I:%M:%S %p}.
1068 @item %R
1069 This is a synonym for @samp{%H:%M}.
1070 @item %S
1071 This stands for the seconds (00-59).
1072 @item %t
1073 This stands for a tab character.
1074 @item %T
1075 This is a synonym for @samp{%H:%M:%S}.
1076 @item %U
1077 This stands for the week of the year (01-52), assuming that weeks
1078 start on Sunday.
1079 @item %w
1080 This stands for the numeric day of week (0-6).  Sunday is day 0.
1081 @item %W
1082 This stands for the week of the year (01-52), assuming that weeks
1083 start on Monday.
1084 @item %x
1085 This has a locale-specific meaning.  In the default locale (named
1086 @samp{C}), it is equivalent to @samp{%D}.
1087 @item %X
1088 This has a locale-specific meaning.  In the default locale (named
1089 @samp{C}), it is equivalent to @samp{%T}.
1090 @item %y
1091 This stands for the year without century (00-99).
1092 @item %Y
1093 This stands for the year with century.
1094 @item %Z
1095 This stands for the time zone abbreviation.
1096 @end table
1098 You can also specify the field width and type of padding for any of
1099 these @samp{%}-sequences.  This works as in @code{printf}: you write
1100 the field width as digits in the middle of a @samp{%}-sequences.  If you
1101 start the field width with @samp{0}, it means to pad with zeros.  If you
1102 start the field width with @samp{_}, it means to pad with spaces.
1104 For example, @samp{%S} specifies the number of seconds since the minute;
1105 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1106 pad with spaces to 3 positions.  Plain @samp{%3S} pads with zeros,
1107 because that is how @samp{%S} normally pads to two positions.
1109 The characters @samp{E} and @samp{O} act as modifiers when used between
1110 @samp{%} and one of the letters in the table above.  @samp{E} specifies
1111 using the current locale's ``alternative'' version of the date and time.
1112 In a Japanese locale, for example, @code{%Ex} might yield a date format
1113 based on the Japanese Emperors' reigns.  @samp{E} is allowed in
1114 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1115 @samp{%EY}.
1117 @samp{O} means to use the current locale's ``alternative''
1118 representation of numbers, instead of the ordinary decimal digits.  This
1119 is allowed with most letters, all the ones that output numbers.
1121 If @var{universal} is non-@code{nil}, that means to describe the time as
1122 Universal Time; @code{nil} means describe it using what Emacs believes
1123 is the local time zone (see @code{current-time-zone}).
1125 This function uses the C library function @code{strftime} to do most of
1126 the work.  In order to communicate with that function, it first encodes
1127 its argument using the coding system specified by
1128 @code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
1129 returns the resulting string, @code{format-time-string} decodes the
1130 string using that same coding system.
1131 @end defun
1133 @defun decode-time time
1134 This function converts a time value into calendrical information.  The
1135 return value is a list of nine elements, as follows:
1137 @example
1138 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1139 @end example
1141 Here is what the elements mean:
1143 @table @var
1144 @item seconds
1145 The number of seconds past the minute, as an integer between 0 and 59.
1146 @item minutes
1147 The number of minutes past the hour, as an integer between 0 and 59.
1148 @item hour
1149 The hour of the day, as an integer between 0 and 23.
1150 @item day
1151 The day of the month, as an integer between 1 and 31.
1152 @item month
1153 The month of the year, as an integer between 1 and 12.
1154 @item year
1155 The year, an integer typically greater than 1900.
1156 @item dow
1157 The day of week, as an integer between 0 and 6, where 0 stands for
1158 Sunday.
1159 @item dst
1160 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1161 @item zone
1162 An integer indicating the time zone, as the number of seconds east of
1163 Greenwich.
1164 @end table
1166 @strong{Common Lisp Note:} Common Lisp has different meanings for
1167 @var{dow} and @var{zone}.
1168 @end defun
1170 @defun encode-time seconds minutes hour day month year &optional zone
1171 This function is the inverse of @code{decode-time}.  It converts seven
1172 items of calendrical data into a time value.  For the meanings of the
1173 arguments, see the table above under @code{decode-time}.
1175 Year numbers less than 100 are not treated specially.  If you want them
1176 to stand for years above 1900, or years above 2000, you must alter them
1177 yourself before you call @code{encode-time}.
1179 The optional argument @var{zone} defaults to the current time zone and
1180 its daylight savings time rules.  If specified, it can be either a list
1181 (as you would get from @code{current-time-zone}), a string as in the
1182 @code{TZ} environment variable, or an integer (as you would get from
1183 @code{decode-time}).  The specified zone is used without any further
1184 alteration for daylight savings time.
1186 If you pass more than seven arguments to @code{encode-time}, the first
1187 six are used as @var{seconds} through @var{year}, the last argument is
1188 used as @var{zone}, and the arguments in between are ignored.  This
1189 feature makes it possible to use the elements of a list returned by
1190 @code{decode-time} as the arguments to @code{encode-time}, like this:
1192 @example
1193 (apply 'encode-time (decode-time @dots{}))
1194 @end example
1196 You can perform simple date arithmetic by using out-of-range values for
1197 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1198 arguments; for example, day 0 means the day preceding the given month.
1200 The operating system puts limits on the range of possible time values;
1201 if you try to encode a time that is out of range, an error results.
1202 @end defun
1204 @node Timers
1205 @section Timers for Delayed Execution
1206 @cindex timer
1208   You can set up a @dfn{timer} to call a function at a specified future time or
1209 after a certain length of idleness.
1211   Emacs cannot run timers at any arbitrary point in a Lisp program; it
1212 can run them only when Emacs could accept output from a subprocess:
1213 namely, while waiting or inside certain primitive functions such as
1214 @code{sit-for} or @code{read-event} which @emph{can} wait.  Therefore, a
1215 timer's execution may be delayed if Emacs is busy.  However, the time of
1216 execution is very precise if Emacs is idle.
1218 @defun run-at-time time repeat function &rest args
1219 This function arranges to call @var{function} with arguments @var{args}
1220 at time @var{time}.  The argument @var{function} is a function to call
1221 later, and @var{args} are the arguments to give it when it is called.
1222 The time @var{time} is specified as a string.
1224 Absolute times may be specified in a wide variety of formats; this
1225 function tries to accept all the commonly used date formats.  Valid
1226 formats include these two,
1228 @example
1229 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
1231 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
1232 @end example
1234 @noindent
1235 where in both examples all fields are numbers; the format that
1236 @code{current-time-string} returns is also allowed, and many others
1237 as well.
1239 To specify a relative time, use numbers followed by units.
1240 For example:
1242 @table @samp
1243 @item 1 min
1244 denotes 1 minute from now.
1245 @item 1 min 5 sec
1246 denotes 65 seconds from now.
1247 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1248 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1249 @end table
1251 For relative time values, Emacs considers a month to be exactly thirty
1252 days, and a year to be exactly 365.25 days.
1254 If @var{time} is a number (integer or floating point), that specifies a
1255 relative time measured in seconds.
1257 The argument @var{repeat} specifies how often to repeat the call.  If
1258 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
1259 called just once, at @var{time}.  If @var{repeat} is a number, it
1260 specifies a repetition period measured in seconds.
1262 In most cases, @var{repeat} has no effect on when @emph{first} call
1263 takes place---@var{time} alone specifies that.  There is one exception:
1264 if @var{time} is @code{t}, then the timer runs whenever the time is a
1265 multiple of @var{repeat} seconds after the epoch.  This is useful for
1266 functions like @code{display-time}.
1268 The function @code{run-at-time} returns a timer value that identifies
1269 the particular scheduled future action.  You can use this value to call
1270 @code{cancel-timer} (see below).
1271 @end defun
1273 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1274 Execute @var{body}, but give up after @var{seconds} seconds.  If
1275 @var{body} finishes before the time is up, @code{with-timeout} returns
1276 the value of the last form in @var{body}.  If, however, the execution of
1277 @var{body} is cut short by the timeout, then @code{with-timeout}
1278 executes all the @var{timeout-forms} and returns the value of the last
1279 of them.
1281 This macro works by setting a timer to run after @var{seconds} seconds.  If
1282 @var{body} finishes before that time, it cancels the timer.  If the
1283 timer actually runs, it terminates execution of @var{body}, then
1284 executes @var{timeout-forms}.
1286 Since timers can run within a Lisp program only when the program calls a
1287 primitive that can wait, @code{with-timeout} cannot stop executing
1288 @var{body} while it is in the midst of a computation---only when it
1289 calls one of those primitives.  So use @code{with-timeout} only with a
1290 @var{body} that waits for input, not one that does a long computation.
1291 @end defmac
1293   The function @code{y-or-n-p-with-timeout} provides a simple way to use
1294 a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
1295 Queries}.
1297 @defun run-with-idle-timer secs repeat function &rest args
1298 Set up a timer which runs when Emacs has been idle for @var{secs}
1299 seconds.  The value of @var{secs} may be an integer or a floating point
1300 number.
1302 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1303 Emacs remains idle for a long enough time.  More often @var{repeat} is
1304 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1305 remains idle for @var{secs} seconds.
1307 The function @code{run-with-idle-timer} returns a timer value which you
1308 can use in calling @code{cancel-timer} (see below).
1309 @end defun
1311 @cindex idleness
1312   Emacs becomes ``idle'' when it starts waiting for user input, and it
1313 remains idle until the user provides some input.  If a timer is set for
1314 five seconds of idleness, it runs approximately five seconds after Emacs
1315 first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
1316 will not run again as long as Emacs remains idle, because the duration
1317 of idleness will continue to increase and will not go down to five
1318 seconds again.
1320   Emacs can do various things while idle: garbage collect, autosave or
1321 handle data from a subprocess.  But these interludes during idleness do
1322 not interfere with idle timers, because they do not reset the clock of
1323 idleness to zero.  An idle timer set for 600 seconds will run when ten
1324 minutes have elapsed since the last user command was finished, even if
1325 subprocess output has been accepted thousands of times within those ten
1326 minutes, and even if there have been garbage collections and autosaves.
1328   When the user supplies input, Emacs becomes non-idle while executing the
1329 input.  Then it becomes idle again, and all the idle timers that are
1330 set up to repeat will subsequently run another time, one by one.
1332 @defun cancel-timer timer
1333 Cancel the requested action for @var{timer}, which should be a value
1334 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
1335 This cancels the effect of that call to @code{run-at-time}; the arrival
1336 of the specified time will not cause anything special to happen.
1337 @end defun
1339 @node Terminal Input
1340 @section Terminal Input
1341 @cindex terminal input
1343   This section describes functions and variables for recording or
1344 manipulating terminal input.  See @ref{Display}, for related
1345 functions.
1347 @menu
1348 * Input Modes::         Options for how input is processed.
1349 * Translating Input::   Low level conversion of some characters or events
1350                           into others.
1351 * Recording Input::     Saving histories of recent or all input events.
1352 @end menu
1354 @node Input Modes
1355 @subsection Input Modes
1356 @cindex input modes
1357 @cindex terminal input modes
1359 @defun set-input-mode interrupt flow meta quit-char
1360 This function sets the mode for reading keyboard input.  If
1361 @var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
1362 @code{nil}, then it uses @sc{cbreak} mode.  The default setting is
1363 system-dependent.  Some systems always use @sc{cbreak} mode regardless
1364 of what is specified.
1366 When Emacs communicates directly with X, it ignores this argument and
1367 uses interrupts if that is the way it knows how to communicate.
1369 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1370 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal.  This
1371 has no effect except in @sc{cbreak} mode.  @xref{Flow Control}.
1373 @c Emacs 19 feature
1374 The argument @var{meta} controls support for input character codes
1375 above 127.  If @var{meta} is @code{t}, Emacs converts characters with
1376 the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
1377 Emacs disregards the 8th bit; this is necessary when the terminal uses
1378 it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
1379 Emacs uses all 8 bits of input unchanged.  This is good for terminals
1380 that use 8-bit character sets.
1382 @c Emacs 19 feature
1383 If @var{quit-char} is non-@code{nil}, it specifies the character to
1384 use for quitting.  Normally this character is @kbd{C-g}.
1385 @xref{Quitting}.
1386 @end defun
1388 The @code{current-input-mode} function returns the input mode settings
1389 Emacs is currently using.
1391 @c Emacs 19 feature
1392 @defun current-input-mode
1393 This function returns the current mode for reading keyboard input.  It
1394 returns a list, corresponding to the arguments of @code{set-input-mode},
1395 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1396 which:
1397 @table @var
1398 @item interrupt
1399 is non-@code{nil} when Emacs is using interrupt-driven input.  If
1400 @code{nil}, Emacs is using @sc{cbreak} mode.
1401 @item flow
1402 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1403 flow control for output to the terminal.  This value is meaningful only
1404 when @var{interrupt} is @code{nil}.
1405 @item meta
1406 is @code{t} if Emacs treats the eighth bit of input characters as
1407 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1408 input character; any other value means Emacs uses all eight bits as the
1409 basic character code.
1410 @item quit
1411 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1412 @end table
1413 @end defun
1415 @node Translating Input
1416 @subsection Translating Input Events
1417 @cindex translating input events
1419   This section describes features for translating input events into
1420 other input events before they become part of key sequences.  These
1421 features apply to each event in the order they are described here: each
1422 event is first modified according to @code{extra-keyboard-modifiers},
1423 then translated through @code{keyboard-translate-table} (if applicable),
1424 and finally decoded with the specified keyboard coding system.  If it is
1425 being read as part of a key sequence, it is then added to the sequence
1426 being read; then subsequences containing it are checked first with
1427 @code{function-key-map} and then with @code{key-translation-map}.
1429 @c Emacs 19 feature
1430 @defvar extra-keyboard-modifiers
1431 This variable lets Lisp programs ``press'' the modifier keys on the
1432 keyboard.  The value is a bit mask:
1434 @table @asis
1435 @item 1
1436 The @key{SHIFT} key.
1437 @item 2
1438 The @key{LOCK} key.
1439 @item 4
1440 The @key{CTL} key.
1441 @item 8
1442 The @key{META} key.
1443 @end table
1445 Each time the user types a keyboard key, it is altered as if the
1446 modifier keys specified in the bit mask were held down.
1448 When using a window system, the program can ``press'' any of the
1449 modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
1450 keys can be virtually pressed.
1451 @end defvar
1453 @defvar keyboard-translate-table
1454 This variable is the translate table for keyboard characters.  It lets
1455 you reshuffle the keys on the keyboard without changing any command
1456 bindings.  Its value is normally a char-table, or else @code{nil}.
1458 If @code{keyboard-translate-table} is a char-table
1459 (@pxref{Char-Tables}), then each character read from the keyboard is
1460 looked up in this char-table.  If the value found there is
1461 non-@code{nil}, then it is used instead of the actual input character.
1463 In the example below, we set @code{keyboard-translate-table} to a
1464 char-table.  Then we fill it in to swap the characters @kbd{C-s} and
1465 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.  Subsequently,
1466 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
1467 versa.  (@xref{Flow Control}, for more information on this subject.)
1469 @cindex flow control example
1470 @example
1471 @group
1472 (defun evade-flow-control ()
1473   "Replace C-s with C-\ and C-q with C-^."
1474   (interactive)
1475 @end group
1476 @group
1477   (setq keyboard-translate-table
1478         (make-char-table 'keyboard-translate-table nil))
1479 @end group
1480 @group
1481   ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1482   (aset keyboard-translate-table ?\034 ?\^s)
1483   (aset keyboard-translate-table ?\^s ?\034)
1484 @end group
1485 @group
1486   ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1487   (aset keyboard-translate-table ?\036 ?\^q)
1488   (aset keyboard-translate-table ?\^q ?\036))
1489 @end group
1490 @end example
1492 Note that this translation is the first thing that happens to a
1493 character after it is read from the terminal.  Record-keeping features
1494 such as @code{recent-keys} and dribble files record the characters after
1495 translation.
1496 @end defvar
1498 @defun keyboard-translate from to
1499 This function modifies @code{keyboard-translate-table} to translate
1500 character code @var{from} into character code @var{to}.  It creates
1501 the keyboard translate table if necessary.
1502 @end defun
1504   The remaining translation features translate subsequences of key
1505 sequences being read.  They are implemented in @code{read-key-sequence}
1506 and have no effect on input read with @code{read-event}.
1508 @defvar function-key-map
1509 This variable holds a keymap that describes the character sequences sent
1510 by function keys on an ordinary character terminal.  This keymap has the
1511 same structure as other keymaps, but is used differently: it specifies
1512 translations to make while reading key sequences, rather than bindings
1513 for key sequences.
1515 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1516 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1517 key sequence, it is replaced with the events in @var{v}.
1519 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1520 keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
1521 that sequence of events into the single event @code{pf1}.  We accomplish
1522 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1523 @code{function-key-map}, when using a VT100.
1525 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1526 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1527 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1528 @code{[?\C-c pf1]}.
1530 Entries in @code{function-key-map} are ignored if they conflict with
1531 bindings made in the minor mode, local, or global keymaps.  The intent
1532 is that the character sequences that function keys send should not have
1533 command bindings in their own right---but if they do, the ordinary
1534 bindings take priority.
1536 The value of @code{function-key-map} is usually set up automatically
1537 according to the terminal's Terminfo or Termcap entry, but sometimes
1538 those need help from terminal-specific Lisp files.  Emacs comes with
1539 terminal-specific files for many common terminals; their main purpose is
1540 to make entries in @code{function-key-map} beyond those that can be
1541 deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
1542 @end defvar
1544 @defvar key-translation-map
1545 This variable is another keymap used just like @code{function-key-map}
1546 to translate input events into other events.  It differs from
1547 @code{function-key-map} in two ways:
1549 @itemize @bullet
1550 @item
1551 @code{key-translation-map} goes to work after @code{function-key-map} is
1552 finished; it receives the results of translation by
1553 @code{function-key-map}.
1555 @item
1556 @code{key-translation-map} overrides actual key bindings.  For example,
1557 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
1558 translation takes effect even though @kbd{C-x f} also has a key binding
1559 in the global map.
1560 @end itemize
1562 The intent of @code{key-translation-map} is for users to map one
1563 character set to another, including ordinary characters normally bound
1564 to @code{self-insert-command}.
1565 @end defvar
1567 @cindex key translation function
1568 You can use @code{function-key-map} or @code{key-translation-map} for
1569 more than simple aliases, by using a function, instead of a key
1570 sequence, as the ``translation'' of a key.  Then this function is called
1571 to compute the translation of that key.
1573 The key translation function receives one argument, which is the prompt
1574 that was specified in @code{read-key-sequence}---or @code{nil} if the
1575 key sequence is being read by the editor command loop.  In most cases
1576 you can ignore the prompt value.
1578 If the function reads input itself, it can have the effect of altering
1579 the event that follows.  For example, here's how to define @kbd{C-c h}
1580 to turn the character that follows into a Hyper character:
1582 @example
1583 @group
1584 (defun hyperify (prompt)
1585   (let ((e (read-event)))
1586     (vector (if (numberp e)
1587                 (logior (lsh 1 24) e)
1588               (if (memq 'hyper (event-modifiers e))
1589                   e
1590                 (add-event-modifier "H-" e))))))
1592 (defun add-event-modifier (string e)
1593   (let ((symbol (if (symbolp e) e (car e))))
1594     (setq symbol (intern (concat string
1595                                  (symbol-name symbol))))
1596 @end group
1597 @group
1598     (if (symbolp e)
1599         symbol
1600       (cons symbol (cdr e)))))
1602 (define-key function-key-map "\C-ch" 'hyperify)
1603 @end group
1604 @end example
1606 Finally, if you have enabled keyboard character set decoding using
1607 @code{set-keyboard-coding-system}, decoding is done after the
1608 translations listed above.  @xref{Specifying Coding Systems}.  In future
1609 Emacs versions, character set decoding may be done before the other
1610 translations.
1612 @node Recording Input
1613 @subsection Recording Input
1615 @defun recent-keys
1616 This function returns a vector containing the last 100 input events from
1617 the keyboard or mouse.  All input events are included, whether or not
1618 they were used as parts of key sequences.  Thus, you always get the last
1619 100 input events, not counting events generated by keyboard macros.
1620 (These are excluded because they are less interesting for debugging; it
1621 should be enough to see the events that invoked the macros.)
1622 @end defun
1624 @deffn Command open-dribble-file filename
1625 @cindex dribble file
1626 This function opens a @dfn{dribble file} named @var{filename}.  When a
1627 dribble file is open, each input event from the keyboard or mouse (but
1628 not those from keyboard macros) is written in that file.  A
1629 non-character event is expressed using its printed representation
1630 surrounded by @samp{<@dots{}>}.
1632 You close the dribble file by calling this function with an argument
1633 of @code{nil}.
1635 This function is normally used to record the input necessary to
1636 trigger an Emacs bug, for the sake of a bug report.
1638 @example
1639 @group
1640 (open-dribble-file "~/dribble")
1641      @result{} nil
1642 @end group
1643 @end example
1644 @end deffn
1646   See also the @code{open-termscript} function (@pxref{Terminal Output}).
1648 @node Terminal Output
1649 @section Terminal Output
1650 @cindex terminal output
1652   The terminal output functions send output to the terminal, or keep
1653 track of output sent to the terminal.  The variable @code{baud-rate}
1654 tells you what Emacs thinks is the output speed of the terminal.
1656 @defvar baud-rate
1657 This variable's value is the output speed of the terminal, as far as
1658 Emacs knows.  Setting this variable does not change the speed of actual
1659 data transmission, but the value is used for calculations such as
1660 padding.  It also affects decisions about whether to scroll part of the
1661 screen or repaint---even when using a window system.  (We designed it
1662 this way despite the fact that a window system has no true ``output
1663 speed'', to give you a way to tune these decisions.)
1665 The value is measured in baud.
1666 @end defvar
1668   If you are running across a network, and different parts of the
1669 network work at different baud rates, the value returned by Emacs may be
1670 different from the value used by your local terminal.  Some network
1671 protocols communicate the local terminal speed to the remote machine, so
1672 that Emacs and other programs can get the proper value, but others do
1673 not.  If Emacs has the wrong value, it makes decisions that are less
1674 than optimal.  To fix the problem, set @code{baud-rate}.
1676 @defun baud-rate
1677 This obsolete function returns the value of the variable
1678 @code{baud-rate}.
1679 @end defun
1681 @defun send-string-to-terminal string
1682 This function sends @var{string} to the terminal without alteration.
1683 Control characters in @var{string} have terminal-dependent effects.
1685 One use of this function is to define function keys on terminals that
1686 have downloadable function key definitions.  For example, this is how (on
1687 certain terminals) to define function key 4 to move forward four
1688 characters (by transmitting the characters @kbd{C-u C-f} to the
1689 computer):
1691 @example
1692 @group
1693 (send-string-to-terminal "\eF4\^U\^F")
1694      @result{} nil
1695 @end group
1696 @end example
1697 @end defun
1699 @deffn Command open-termscript filename
1700 @cindex termscript file
1701 This function is used to open a @dfn{termscript file} that will record
1702 all the characters sent by Emacs to the terminal.  It returns
1703 @code{nil}.  Termscript files are useful for investigating problems
1704 where Emacs garbles the screen, problems that are due to incorrect
1705 Termcap entries or to undesirable settings of terminal options more
1706 often than to actual Emacs bugs.  Once you are certain which characters
1707 were actually output, you can determine reliably whether they correspond
1708 to the Termcap specifications in use.
1710 See also @code{open-dribble-file} in @ref{Terminal Input}.
1712 @example
1713 @group
1714 (open-termscript "../junk/termscript")
1715      @result{} nil
1716 @end group
1717 @end example
1718 @end deffn
1720 @node Sound Output
1721 @section Sound Output
1722 @cindex sound
1724   To play sound using Emacs, use the function @code{play-sound}.  Only
1725 certain systems are supported; if you call @code{play-sound} on a system
1726 which cannot really do the job, it gives an error.  Emacs version 20 and
1727 earlier did not support sound at all.
1729   The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
1730 or Sun Audio format (@samp{.au}).
1732 @tindex play-sound
1733 @defun play-sound sound
1734 This function plays a specified sound.  The argument, @var{sound}, has
1735 the form @code{(sound @var{properties}...)}, where the @var{properties}
1736 consist of alternating keywords (particular symbols recognized
1737 specially) and values corresponding to them.
1739 Here is a table of the keywords that are currently meaningful in
1740 @var{sound}, and their meanings:
1742 @table @code
1743 @item :file @var{file}
1744 This specifies the file containing the sound to play.
1745 If the file name is not absolute, it is expanded against
1746 the directory @code{data-directory}.
1748 @item :data @var{data}
1749 This specifies the sound to play without need to refer to a file.  The
1750 value, @var{data}, should be a string containing the same bytes as a
1751 sound file.  We recommend using a unibyte string.
1753 @item :volume @var{volume}
1754 This specifies how loud to play the sound.  It should be a number in the
1755 range of 0 to 1.  The default is to use whatever volume has been
1756 specified before.
1758 @item :device @var{device}
1759 This specifies the system device on which to play the sound, as a
1760 string.  The default device is system-dependent.
1761 @end table
1763 Before actually playing the sound, @code{play-sound}
1764 calls the functions in the list @code{play-sound-functions}.
1765 Each function is called with one argument, @var{sound}.
1766 @end defun
1768 @defun play-sound-file file &optional volume device
1769 @tindex play-sound-file
1770 This function is an alternative interface to playing a sound @var{file}
1771 specifying an optional @var{volume} and @var{device}.
1772 @end defun
1774 @tindex play-sound-functions
1775 @defvar play-sound-functions
1776 A list of functions to be called before playing a sound.  Each function
1777 is called with one argument, a property list that describes the sound.
1778 @end defvar
1780 @node Special Keysyms
1781 @section System-Specific X11 Keysyms
1783 To define system-specific X11 keysyms, set the variable
1784 @code{system-key-alist}.
1786 @defvar system-key-alist
1787 This variable's value should be an alist with one element for each
1788 system-specific keysym.  Each element has the form @code{(@var{code}
1789 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1790 including the ``vendor specific'' bit, 
1791 @ifnottex
1792 -2**28),
1793 @end ifnottex
1794 @tex 
1795 $-2^{28}$),
1796 @end tex
1797 and @var{symbol} is the name for the function key.
1799 For example @code{(168 . mute-acute)} defines a system-specific key (used
1800 by HP X servers) whose numeric code is
1801 @ifnottex
1802 -2**28
1803 @end ifnottex
1804 @tex 
1805 $-2^{28}$
1806 @end tex
1807 + 168.
1809 It is not crucial to exclude from the alist the keysyms of other X
1810 servers; those do no harm, as long as they don't conflict with the ones
1811 used by the X server actually in use.
1813 The variable is always local to the current terminal, and cannot be
1814 buffer-local.  @xref{Multiple Displays}.
1815 @end defvar
1817 @node Flow Control
1818 @section Flow Control
1819 @cindex flow control characters
1821   This section attempts to answer the question ``Why does Emacs use
1822 flow-control characters in its command character set?''  For a second
1823 view on this issue, read the comments on flow control in the
1824 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1825 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1827 @cindex @kbd{C-s}
1828 @cindex @kbd{C-q}
1829   At one time, most terminals did not need flow control, and none used
1830 @code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
1831 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
1832 was natural and uncontroversial.  With so many commands needing key
1833 assignments, of course we assigned meanings to nearly all @sc{ascii}
1834 control characters.
1836   Later, some terminals were introduced which required these characters
1837 for flow control.  They were not very good terminals for full-screen
1838 editing, so Emacs maintainers ignored them.  In later years, flow
1839 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
1840 but by this time it was usually an option.  And the majority of Emacs
1841 users, who can turn flow control off, did not want to switch to less
1842 mnemonic key bindings for the sake of flow control.
1844   So which usage is ``right''---Emacs's or that of some terminal and
1845 concentrator manufacturers?  This question has no simple answer.
1847   One reason why we are reluctant to cater to the problems caused by
1848 @kbd{C-s} and @kbd{C-q} is that they are gratuitous.  There are other
1849 techniques (albeit less common in practice) for flow control that
1850 preserve transparency of the character stream.  Note also that their use
1851 for flow control is not an official standard.  Interestingly, on the
1852 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
1853 @kbd{C-q} were sent by the computer to turn the punch on and off!
1855   As window systems and PC terminal emulators replace character-only
1856 terminals, the flow control problem is gradually disappearing.  For the
1857 mean time, Emacs provides a convenient way of enabling flow control if
1858 you want it: call the function @code{enable-flow-control}.
1860 @deffn Command enable-flow-control
1861 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1862 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1863 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1864 @end deffn
1866 You can use the function @code{enable-flow-control-on} in your
1867 init file to enable flow control automatically on certain
1868 terminal types.
1870 @defun enable-flow-control-on &rest termtypes
1871 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1872 if the terminal type is one of @var{termtypes}.  For example:
1874 @smallexample
1875 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1876 @end smallexample
1877 @end defun
1879   Here is how @code{enable-flow-control} does its job:
1881 @enumerate
1882 @item
1883 @cindex @sc{cbreak}
1884 It sets @sc{cbreak} mode for terminal input, and tells the operating
1885 system to handle flow control, with @code{(set-input-mode nil t)}.
1887 @item
1888 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1889 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}.  Except at its very
1890 lowest level, Emacs never knows that the characters typed were anything
1891 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1892 and @kbd{C-^} even when they are input for other commands.
1893 @xref{Translating Input}.
1894 @end enumerate
1896 If the terminal is the source of the flow control characters, then once
1897 you enable kernel flow control handling, you probably can make do with
1898 less padding than normal for that terminal.  You can reduce the amount
1899 of padding by customizing the Termcap entry.  You can also reduce it by
1900 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1901 speed when calculating the padding needed.  @xref{Terminal Output}.
1903 @node Batch Mode
1904 @section Batch Mode
1905 @cindex batch mode
1906 @cindex noninteractive use
1908   The command-line option @samp{-batch} causes Emacs to run
1909 noninteractively.  In this mode, Emacs does not read commands from the
1910 terminal, it does not alter the terminal modes, and it does not expect
1911 to be outputting to an erasable screen.  The idea is that you specify
1912 Lisp programs to run; when they are finished, Emacs should exit.  The
1913 way to specify the programs to run is with @samp{-l @var{file}}, which
1914 loads the library named @var{file}, and @samp{-f @var{function}}, which
1915 calls @var{function} with no arguments.
1917   Any Lisp program output that would normally go to the echo area,
1918 either using @code{message}, or using @code{prin1}, etc., with @code{t}
1919 as the stream, goes instead to Emacs's standard error descriptor when
1920 in batch mode.  Similarly, input that would normally come from the
1921 minibuffer is read from the standard input descriptor.
1922 Thus, Emacs behaves much like a noninteractive
1923 application program.  (The echo area output that Emacs itself normally
1924 generates, such as command echoing, is suppressed entirely.)
1926 @defvar noninteractive
1927 This variable is non-@code{nil} when Emacs is running in batch mode.
1928 @end defvar