]> code.delx.au - gnu-emacs/blob - lispref/os.texi
Use font-lock-maximum-decoration when setting ada-font-lock-keywords
[gnu-emacs] / lispref / os.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/os
6 @node System Interface, Display, Processes, Top
7 @chapter Operating System Interface
8
9 This chapter is about starting and getting out of Emacs, access to
10 values in the operating system environment, and terminal input, output,
11 and flow control.
12
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.
16
17 @menu
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 * Time of Day:: Getting the current time.
23 * Timers:: Setting a timer to call a function at a certain time.
24 * Terminal Input:: Recording terminal input for debugging.
25 * Terminal Output:: Recording terminal output for debugging.
26 * Special Keysyms:: Defining system-specific key symbols for X windows.
27 * Flow Control:: How to turn output flow control on or off.
28 * Batch Mode:: Running Emacs without terminal interaction.
29 @end menu
30
31 @node Starting Up
32 @section Starting Up Emacs
33
34 This section describes what Emacs does when it is started, and how you
35 can customize these actions.
36
37 @menu
38 * Start-up Summary:: Sequence of actions Emacs performs at start-up.
39 * Init File:: Details on reading the init file (@file{.emacs}).
40 * Terminal-Specific:: How the terminal-specific Lisp file is read.
41 * Command Line Arguments:: How command line arguments are processed,
42 and how you can customize them.
43 @end menu
44
45 @node Start-up Summary
46 @subsection Summary: Sequence of Actions at Start Up
47 @cindex initialization
48 @cindex start up of Emacs
49 @cindex @file{startup.el}
50
51 The order of operations performed (in @file{startup.el}) by Emacs when
52 it is started up is as follows:
53
54 @enumerate
55 @item
56 It loads the initialization library for the window system, if you are
57 using a window system. This library's name is
58 @file{term/@var{windowsystem}-win.el}.
59
60 @item
61 It initializes the X window frame and faces, if appropriate.
62
63 @item
64 It runs the normal hook @code{before-init-hook}.
65
66 @item
67 It loads the library @file{site-start}, unless the option
68 @samp{-no-site-file} was specified. The library's file name is usually
69 @file{site-start.el}.
70 @cindex @file{site-start.el}
71
72 @item
73 It loads the file @file{~/.emacs} unless @samp{-q} was specified on
74 the command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
75 option can specify the user name whose home directory should be used
76 instead of @file{~}.
77
78 @item
79 It loads the library @file{default} unless @code{inhibit-default-init}
80 is non-@code{nil}. (This is not done in @samp{-batch} mode or if
81 @samp{-q} was specified on the command line.) The library's file name
82 is usually @file{default.el}.
83 @cindex @file{default.el}
84
85 @item
86 It runs the normal hook @code{after-init-hook}.
87
88 @item
89 It sets the major mode according to @code{initial-major-mode}, provided
90 the buffer @samp{*scratch*} is still current and still in Fundamental
91 mode.
92
93 @item
94 It loads the terminal-specific Lisp file, if any, except when in batch
95 mode or using a window system.
96
97 @item
98 It displays the initial echo area message, unless you have suppressed
99 that with @code{inhibit-startup-echo-area-message}.
100
101 @item
102 It processes any remaining command line arguments.
103
104 @item
105 It runs @code{term-setup-hook}.
106
107 @item
108 It calls @code{frame-notice-user-settings}, which modifies the
109 parameters of the selected frame according to whatever the init files
110 specify.
111
112 @item
113 It runs @code{window-setup-hook}. @xref{Window Systems}.
114
115 @item
116 It displays copyleft, nonwarranty, and basic use information, provided
117 there were no remaining command line arguments (a few steps above) and
118 the value of @code{inhibit-startup-message} is @code{nil}.
119 @end enumerate
120
121 @defopt inhibit-startup-message
122 This variable inhibits the initial startup messages (the nonwarranty,
123 etc.). If it is non-@code{nil}, then the messages are not printed.
124
125 This variable exists so you can set it in your personal init file, once
126 you are familiar with the contents of the startup message. Do not set
127 this variable in the init file of a new user, or in a way that affects
128 more than one user, because that would prevent new users from receiving
129 the information they are supposed to see.
130 @end defopt
131
132 @defopt inhibit-startup-echo-area-message
133 This variable controls the display of the startup echo area message.
134 You can suppress the startup echo area message by adding text with this
135 form to your @file{.emacs} file:
136
137 @example
138 (setq inhibit-startup-echo-area-message
139 "@var{your-login-name}")
140 @end example
141
142 Simply setting @code{inhibit-startup-echo-area-message} to your login
143 name is not sufficient to inhibit the message; Emacs explicitly checks
144 whether @file{.emacs} contains an expression as shown above. Your login
145 name must appear in the expression as a Lisp string constant.
146
147 This way, you can easily inhibit the message for yourself if you wish,
148 but thoughtless copying of your @file{.emacs} file will not inhibit the
149 message for someone else.
150 @end defopt
151
152 @node Init File
153 @subsection The Init File: @file{.emacs}
154 @cindex init file
155 @cindex @file{.emacs}
156
157 When you start Emacs, it normally attempts to load the file
158 @file{.emacs} from your home directory. This file, if it exists, must
159 contain Lisp code. It is called your @dfn{init file}. The command line
160 switches @samp{-q} and @samp{-u} affect the use of the init file;
161 @samp{-q} says not to load an init file, and @samp{-u} says to load a
162 specified user's init file instead of yours. @xref{Entering Emacs,,,
163 emacs, The GNU Emacs Manual}.
164
165 @cindex default init file
166 A site may have a @dfn{default init file}, which is the library named
167 @file{default.el}. Emacs finds the @file{default.el} file through the
168 standard search path for libraries (@pxref{How Programs Do Loading}).
169 The Emacs distribution does not come with this file; sites may provide
170 one for local customizations. If the default init file exists, it is
171 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
172 specified. But your own personal init file, if any, is loaded first; if
173 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
174 Emacs does not subsequently load the @file{default.el} file.
175
176 Another file for site-customization is @file{site-start.el}. Emacs
177 loads this @emph{before} the user's init file. You can inhibit the
178 loading of this file with the option @samp{-no-site-file}.
179
180 If there is a great deal of code in your @file{.emacs} file, you
181 should move it into another file named @file{@var{something}.el},
182 byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
183 file load the other file using @code{load} (@pxref{Loading}).
184
185 @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
186 examples of how to make various commonly desired customizations in your
187 @file{.emacs} file.
188
189 @defopt inhibit-default-init
190 This variable prevents Emacs from loading the default initialization
191 library file for your session of Emacs. If its value is non-@code{nil},
192 then the default library is not loaded. The default value is
193 @code{nil}.
194 @end defopt
195
196 @defvar before-init-hook
197 @defvarx after-init-hook
198 These two normal hooks are run just before, and just after, loading of
199 the user's init file, @file{default.el}, and/or @file{site-start.el}.
200 @end defvar
201
202 @node Terminal-Specific
203 @subsection Terminal-Specific Initialization
204 @cindex terminal-specific initialization
205
206 Each terminal type can have its own Lisp library that Emacs loads when
207 run on that type of terminal. For a terminal type named @var{termtype},
208 the library is called @file{term/@var{termtype}}. Emacs finds the file
209 by searching the @code{load-path} directories as it does for other
210 files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally,
211 terminal-specific Lisp library is located in @file{emacs/lisp/term}, a
212 subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp
213 libraries are kept.@refill
214
215 The library's name is constructed by concatenating the value of the
216 variable @code{term-file-prefix} and the terminal type. Normally,
217 @code{term-file-prefix} has the value @code{"term/"}; changing this
218 is not recommended.
219
220 The usual function of a terminal-specific library is to enable special
221 keys to send sequences that Emacs can recognize. It may also need to
222 set or add to @code{function-key-map} if the Termcap entry does not
223 specify all the terminal's function keys. @xref{Terminal Input}.
224
225 @cindex Termcap
226 When the name of the terminal type contains a hyphen, only the part of
227 the name before the first hyphen is significant in choosing the library
228 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
229 the @file{term/aaa} library. If necessary, the library can evaluate
230 @code{(getenv "TERM")} to find the full name of the terminal
231 type.@refill
232
233 Your @file{.emacs} file can prevent the loading of the
234 terminal-specific library by setting the variable
235 @code{term-file-prefix} to @code{nil}. This feature is useful when
236 experimenting with your own peculiar customizations.
237
238 You can also arrange to override some of the actions of the
239 terminal-specific library by setting the variable
240 @code{term-setup-hook}. This is a normal hook which Emacs runs using
241 @code{run-hooks} at the end of Emacs initialization, after loading both
242 your @file{.emacs} file and any terminal-specific libraries. You can
243 use this variable to define initializations for terminals that do not
244 have their own libraries. @xref{Hooks}.
245
246 @defvar term-file-prefix
247 @cindex @code{TERM} environment variable
248 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
249 a terminal-specific initialization file as follows:
250
251 @example
252 (load (concat term-file-prefix (getenv "TERM")))
253 @end example
254
255 @noindent
256 You may set the @code{term-file-prefix} variable to @code{nil} in your
257 @file{.emacs} file if you do not wish to load the
258 terminal-initialization file. To do this, put the following in
259 your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
260 @end defvar
261
262 @defvar term-setup-hook
263 This variable is a normal hook that Emacs runs after loading your
264 @file{.emacs} file, the default initialization file (if any) and the
265 terminal-specific Lisp file.
266
267 You can use @code{term-setup-hook} to override the definitions made by a
268 terminal-specific file.
269 @end defvar
270
271 See @code{window-setup-hook} in @ref{Window Systems}, for a related
272 feature.
273
274 @node Command Line Arguments
275 @subsection Command Line Arguments
276 @cindex command line arguments
277
278 You can use command line arguments to request various actions when you
279 start Emacs. Since you do not need to start Emacs more than once per
280 day, and will often leave your Emacs session running longer than that,
281 command line arguments are hardly ever used. As a practical matter, it
282 is best to avoid making the habit of using them, since this habit would
283 encourage you to kill and restart Emacs unnecessarily often. These
284 options exist for two reasons: to be compatible with other editors (for
285 invocation by other programs) and to enable shell scripts to run
286 specific Lisp programs.
287
288 This section describes how Emacs processes command line arguments,
289 and how you can customize them.
290
291 @ignore
292 (Note that some other editors require you to start afresh each time
293 you want to edit a file. With this kind of editor, you will probably
294 specify the file as a command line argument. The recommended way to
295 use GNU Emacs is to start it only once, just after you log in, and do
296 all your editing in the same Emacs process. Each time you want to edit
297 a different file, you visit it with the existing Emacs, which eventually
298 comes to have many files in it ready for editing. Usually you do not
299 kill the Emacs until you are about to log out.)
300 @end ignore
301
302 @defun command-line
303 This function parses the command line that Emacs was called with,
304 processes it, loads the user's @file{.emacs} file and displays the
305 startup messages.
306 @end defun
307
308 @defvar command-line-processed
309 The value of this variable is @code{t} once the command line has been
310 processed.
311
312 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
313 this variable to @code{nil} first in order to cause the new dumped Emacs
314 to process its new command line arguments.
315 @end defvar
316
317 @defvar command-switch-alist
318 @cindex switches on command line
319 @cindex options on command line
320 @cindex command line options
321 The value of this variable is an alist of user-defined command-line
322 options and associated handler functions. This variable exists so you
323 can add elements to it.
324
325 A @dfn{command line option} is an argument on the command line of the
326 form:
327
328 @example
329 -@var{option}
330 @end example
331
332 The elements of the @code{command-switch-alist} look like this:
333
334 @example
335 (@var{option} . @var{handler-function})
336 @end example
337
338 The @var{handler-function} is called to handle @var{option} and receives
339 the option name as its sole argument.
340
341 In some cases, the option is followed in the command line by an
342 argument. In these cases, the @var{handler-function} can find all the
343 remaining command-line arguments in the variable
344 @code{command-line-args-left}. (The entire list of command-line
345 arguments is in @code{command-line-args}.)
346
347 The command line arguments are parsed by the @code{command-line-1}
348 function in the @file{startup.el} file. See also @ref{Command
349 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
350 Manual}.
351 @end defvar
352
353 @defvar command-line-args
354 The value of this variable is the list of command line arguments passed
355 to Emacs.
356 @end defvar
357
358 @defvar command-line-functions
359 This variable's value is a list of functions for handling an
360 unrecognized command-line argument. Each time the next argument to be
361 processed has no special meaning, the functions in this list are called,
362 in order of appearance, until one of them returns a non-@code{nil}
363 value.
364
365 These functions are called with no arguments. They can access the
366 command-line argument under consideration through the variable
367 @code{argi}. The remaining arguments (not including the current one)
368 are in the variable @code{command-line-args-left}.
369
370 When a function recognizes and processes the argument in @code{argi}, it
371 should return a non-@code{nil} value to say it has dealt with that
372 argument. If it has also dealt with some of the following arguments, it
373 can indicate that by deleting them from @code{command-line-args-left}.
374
375 If all of these functions return @code{nil}, then the argument is used
376 as a file name to visit.
377 @end defvar
378
379 @node Getting Out
380 @section Getting Out of Emacs
381 @cindex exiting Emacs
382
383 There are two ways to get out of Emacs: you can kill the Emacs job,
384 which exits permanently, or you can suspend it, which permits you to
385 reenter the Emacs process later. As a practical matter, you seldom kill
386 Emacs---only when you are about to log out. Suspending is much more
387 common.
388
389 @menu
390 * Killing Emacs:: Exiting Emacs irreversibly.
391 * Suspending Emacs:: Exiting Emacs reversibly.
392 @end menu
393
394 @node Killing Emacs
395 @comment node-name, next, previous, up
396 @subsection Killing Emacs
397 @cindex killing Emacs
398
399 Killing Emacs means ending the execution of the Emacs process. The
400 parent process normally resumes control. The low-level primitive for
401 killing Emacs is @code{kill-emacs}.
402
403 @defun kill-emacs &optional exit-data
404 This function exits the Emacs process and kills it.
405
406 If @var{exit-data} is an integer, then it is used as the exit status
407 of the Emacs process. (This is useful primarily in batch operation; see
408 @ref{Batch Mode}.)
409
410 If @var{exit-data} is a string, its contents are stuffed into the
411 terminal input buffer so that the shell (or whatever program next reads
412 input) can read them.
413 @end defun
414
415 All the information in the Emacs process, aside from files that have
416 been saved, is lost when the Emacs is killed. Because killing Emacs
417 inadvertently can lose a lot of work, Emacs queries for confirmation
418 before actually terminating if you have buffers that need saving or
419 subprocesses that are running. This is done in the function
420 @code{save-buffers-kill-emacs}.
421
422 @defvar kill-emacs-query-functions
423 After asking the standard questions, @code{save-buffers-kill-emacs}
424 calls the functions in the list @code{kill-buffer-query-functions}, in
425 order of appearance, with no arguments. These functions can ask for
426 additional confirmation from the user. If any of them returns
427 non-@code{nil}, Emacs is not killed.
428 @end defvar
429
430 @defvar kill-emacs-hook
431 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
432 finished with all file saving and confirmation, it runs the functions in
433 this hook.
434 @end defvar
435
436 @node Suspending Emacs
437 @subsection Suspending Emacs
438 @cindex suspending Emacs
439
440 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
441 control to its superior process, which is usually the shell. This
442 allows you to resume editing later in the same Emacs process, with the
443 same buffers, the same kill ring, the same undo history, and so on. To
444 resume Emacs, use the appropriate command in the parent shell---most
445 likely @code{fg}.
446
447 Some operating systems do not support suspension of jobs; on these
448 systems, ``suspension'' actually creates a new shell temporarily as a
449 subprocess of Emacs. Then you would exit the shell to return to Emacs.
450
451 Suspension is not useful with window systems such as X, because the
452 Emacs job may not have a parent that can resume it again, and in any
453 case you can give input to some other job such as a shell merely by
454 moving to a different window. Therefore, suspending is not allowed
455 when Emacs is an X client.
456
457 @defun suspend-emacs string
458 This function stops Emacs and returns control to the superior process.
459 If and when the superior process resumes Emacs, @code{suspend-emacs}
460 returns @code{nil} to its caller in Lisp.
461
462 If @var{string} is non-@code{nil}, its characters are sent to be read
463 as terminal input by Emacs's superior shell. The characters in
464 @var{string} are not echoed by the superior shell; only the results
465 appear.
466
467 Before suspending, @code{suspend-emacs} runs the normal hook
468 @code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a
469 normal hook; its value was a single function, and if its value was
470 non-@code{nil}, then @code{suspend-emacs} returned immediately without
471 actually suspending anything.
472
473 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
474 @code{suspend-resume-hook}. @xref{Hooks}.
475
476 The next redisplay after resumption will redraw the entire screen,
477 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
478 (@pxref{Refresh Screen}).
479
480 In the following example, note that @samp{pwd} is not echoed after
481 Emacs is suspended. But it is read and executed by the shell.
482
483 @smallexample
484 @group
485 (suspend-emacs)
486 @result{} nil
487 @end group
488
489 @group
490 (add-hook 'suspend-hook
491 (function (lambda ()
492 (or (y-or-n-p
493 "Really suspend? ")
494 (error "Suspend cancelled")))))
495 @result{} (lambda nil
496 (or (y-or-n-p "Really suspend? ")
497 (error "Suspend cancelled")))
498 @end group
499 @group
500 (add-hook 'suspend-resume-hook
501 (function (lambda () (message "Resumed!"))))
502 @result{} (lambda nil (message "Resumed!"))
503 @end group
504 @group
505 (suspend-emacs "pwd")
506 @result{} nil
507 @end group
508 @group
509 ---------- Buffer: Minibuffer ----------
510 Really suspend? @kbd{y}
511 ---------- Buffer: Minibuffer ----------
512 @end group
513
514 @group
515 ---------- Parent Shell ----------
516 lewis@@slug[23] % /user/lewis/manual
517 lewis@@slug[24] % fg
518 @end group
519
520 @group
521 ---------- Echo Area ----------
522 Resumed!
523 @end group
524 @end smallexample
525 @end defun
526
527 @defvar suspend-hook
528 This variable is a normal hook run before suspending.
529 @end defvar
530
531 @defvar suspend-resume-hook
532 This variable is a normal hook run after suspending.
533 @end defvar
534
535 @node System Environment
536 @section Operating System Environment
537 @cindex operating system environment
538
539 Emacs provides access to variables in the operating system environment
540 through various functions. These variables include the name of the
541 system, the user's @sc{uid}, and so on.
542
543 @defvar system-type
544 The value of this variable is a symbol indicating the type of
545 operating system Emacs is operating on. Here is a table of the symbols
546 for the operating systems that Emacs can run on up to version 19.1.
547
548 @table @code
549 @item aix-v3
550 AIX.
551
552 @item berkeley-unix
553 Berkeley BSD.
554
555 @item hpux
556 Hewlett-Packard operating system.
557
558 @item irix
559 Silicon Graphics Irix system.
560
561 @item linux
562 The free Linux operating system.
563
564 @item rtu
565 Masscomp RTU, UCB universe.
566
567 @item unisoft-unix
568 UniSoft UniPlus.
569
570 @item usg-unix-v
571 AT&T System V.
572
573 @item vax-vms
574 VAX VMS.
575
576 @item xenix
577 SCO Xenix 386.
578 @end table
579
580 We do not wish to add new symbols to make finer distinctions unless it
581 is absolutely necessary! In fact, we hope to eliminate some of these
582 alternatives in the future. We recommend using
583 @code{system-configuration} to distinguish between different operating
584 systems.
585 @end defvar
586
587 @defvar system-configuration
588 This variable holds the three-part configuration name for the
589 hardware/software configuration of your system, as a string. The
590 convenient way to test parts of this string is with @code{string-match}.
591 @end defvar
592
593 @defun system-name
594 This function returns the name of the machine you are running on.
595 @example
596 (system-name)
597 @result{} "prep.ai.mit.edu"
598 @end example
599 @end defun
600
601 @defun getenv var
602 @cindex environment variable access
603 This function returns the value of the environment variable @var{var},
604 as a string. Within Emacs, the environment variable values are kept in
605 the Lisp variable @code{process-environment}.
606
607 @example
608 @group
609 (getenv "USER")
610 @result{} "lewis"
611 @end group
612
613 @group
614 lewis@@slug[10] % printenv
615 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
616 USER=lewis
617 @end group
618 @group
619 TERM=ibmapa16
620 SHELL=/bin/csh
621 HOME=/user/lewis
622 @end group
623 @end example
624 @end defun
625
626 @c Emacs 19 feature
627 @deffn Command setenv variable value
628 This command sets the value of the environment variable named
629 @var{variable} to @var{value}. Both arguments should be strings. This
630 function works by modifying @code{process-environment}; binding that
631 variable with @code{let} is also reasonable practice.
632 @end deffn
633
634 @defvar process-environment
635 This variable is a list of strings, each describing one environment
636 variable. The functions @code{getenv} and @code{setenv} work by means
637 of this variable.
638
639 @smallexample
640 @group
641 process-environment
642 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
643 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
644 "USER=lewis"
645 @end group
646 @group
647 "TERM=ibmapa16"
648 "SHELL=/bin/csh"
649 "HOME=/user/lewis")
650 @end group
651 @end smallexample
652 @end defvar
653
654 @defvar invocation-name
655 This variable holds the program name under which Emacs was invoked. The
656 value is a string, and does not include a directory name.
657 @end defvar
658
659 @defvar invocation-directory
660 This variable holds the directory from which the Emacs executable was
661 invoked, or perhaps @code{nil} if that directory cannot be determined.
662 @end defvar
663
664 @defvar installation-directory
665 If non-@code{nil}, this is a directory within which to look for the
666 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
667 when Emacs can't find those directories in their standard installed
668 locations, but can find them in a directory related somehow to the one
669 containing the Emacs executable.
670 @end defvar
671
672 @defun load-average
673 This function returns the current 1-minute, 5-minute and 15-minute
674 load averages in a list. The values are integers that are 100 times
675 the system load averages. (The load averages indicate the number of
676 processes trying to run.)
677
678 @example
679 @group
680 (load-average)
681 @result{} (169 48 36)
682 @end group
683
684 @group
685 lewis@@rocky[5] % uptime
686 11:55am up 1 day, 19:37, 3 users,
687 load average: 1.69, 0.48, 0.36
688 @end group
689 @end example
690 @end defun
691
692 @defun emacs-pid
693 This function returns the process @sc{id} of the Emacs process.
694 @end defun
695
696 @defun setprv privilege-name &optional setp getprv
697 This function sets or resets a VMS privilege. (It does not exist on
698 Unix.) The first arg is the privilege name, as a string. The second
699 argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the
700 privilege is to be turned on or off. Its default is @code{nil}. The
701 function returns @code{t} if successful, @code{nil} otherwise.
702
703 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
704 does not change the privilege, but returns @code{t} or @code{nil}
705 indicating whether the privilege is currently enabled.
706 @end defun
707
708 @node User Identification
709 @section User Identification
710
711 @defun user-login-name
712 This function returns the name under which the user is logged in. If
713 the environment variable @code{LOGNAME} is set, that value is used.
714 Otherwise, if the environment variable @code{USER} is set, that value is
715 used. Otherwise, the value is based on the effective @sc{uid}, not the
716 real @sc{uid}.
717
718 @example
719 @group
720 (user-login-name)
721 @result{} "lewis"
722 @end group
723 @end example
724 @end defun
725
726 @defun user-real-login-name
727 This function returns the user name corresponding to Emacs's real
728 @sc{uid}. This ignores the effective @sc{uid} and ignores the
729 environment variables @code{LOGNAME} and @code{USER}.
730 @end defun
731
732 @defun user-full-name
733 This function returns the full name of the user.
734
735 @example
736 @group
737 (user-full-name)
738 @result{} "Bil Lewis"
739 @end group
740 @end example
741 @end defun
742
743 @defun user-real-uid
744 This function returns the real @sc{uid} of the user.
745
746 @example
747 @group
748 (user-real-uid)
749 @result{} 19
750 @end group
751 @end example
752 @end defun
753
754 @defun user-uid
755 This function returns the effective @sc{uid} of the user.
756 @end defun
757
758 @node Time of Day
759 @section Time of Day
760
761 This section explains how to determine the current time and the time
762 zone.
763
764 @defun current-time-string &optional time-value
765 This function returns the current time and date as a humanly-readable
766 string. The format of the string is unvarying; the number of characters
767 used for each part is always the same, so you can reliably use
768 @code{substring} to extract pieces of it. However, it would be wise to
769 count the characters from the beginning of the string rather than from
770 the end, as additional information may be added at the end.
771
772 @c Emacs 19 feature
773 The argument @var{time-value}, if given, specifies a time to format
774 instead of the current time. The argument should be a cons cell
775 containing two integers, or a list whose first two elements are
776 integers. Thus, you can use times obtained from @code{current-time}
777 (see below) and from @code{file-attributes} (@pxref{File Attributes}).
778
779 @example
780 @group
781 (current-time-string)
782 @result{} "Wed Oct 14 22:21:05 1987"
783 @end group
784 @end example
785 @end defun
786
787 @c Emacs 19 feature
788 @defun current-time
789 This function returns the system's time value as a list of three
790 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
791 @var{high} and @var{low} combine to give the number of seconds since
792 0:00 January 1, 1970, which is
793 @ifinfo
794 @var{high} * 2**16 + @var{low}.
795 @end ifinfo
796 @tex
797 $high*2^{16}+low$.
798 @end tex
799
800 The third element, @var{microsec}, gives the microseconds since the
801 start of the current second (or 0 for systems that return time only on
802 the resolution of a second).
803
804 The first two elements can be compared with file time values such as you
805 get with the function @code{file-attributes}. @xref{File Attributes}.
806 @end defun
807
808 @c Emacs 19 feature
809 @defun current-time-zone &optional time-value
810 This function returns a list describing the time zone that the user is
811 in.
812
813 The value has the form @code{(@var{offset} @var{name})}. Here
814 @var{offset} is an integer giving the number of seconds ahead of UTC
815 (east of Greenwich). A negative value means west of Greenwich. The
816 second element, @var{name} is a string giving the name of the time
817 zone. Both elements change when daylight savings time begins or ends;
818 if the user has specified a time zone that does not use a seasonal time
819 adjustment, then the value is constant through time.
820
821 If the operating system doesn't supply all the information necessary to
822 compute the value, both elements of the list are @code{nil}.
823
824 The argument @var{time-value}, if given, specifies a time to analyze
825 instead of the current time. The argument should be a cons cell
826 containing two integers, or a list whose first two elements are
827 integers. Thus, you can use times obtained from @code{current-time}
828 (see below) and from @code{file-attributes} (@pxref{File Attributes}).
829 @end defun
830
831 @node Timers
832 @section Timers
833
834 You can set up a timer to call a function at a specified future time.
835
836 @defun run-at-time time repeat function &rest args
837 This function arranges to call @var{function} with arguments @var{args}
838 at time @var{time}. The argument @var{function} is a function to call
839 later, and @var{args} are the arguments to give it when it is called.
840 The time @var{time} is specified as a string.
841
842 Absolute times may be specified in a wide variety of formats; The form
843 @samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
844 @var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
845 the format that @code{current-time-string} returns is also allowed.
846
847 To specify a relative time, use numbers followed by units.
848 For example:
849
850 @table @samp
851 @item 1 min
852 denotes 1 minute from now.
853 @item 1 min 5 sec
854 denotes 65 seconds from now.
855 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
856 denotes exactly 103 months, 123 days, and 10862 seconds from now.
857 @end table
858
859 If @var{time} is an integer, that specifies a relative time measured in
860 seconds.
861
862 The argument @var{repeat} specifies how often to repeat the call. If
863 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
864 called just once, at @var{time}. If @var{repeat} is an integer, it
865 specifies a repetition period measured in seconds. In any case, @var{repeat}
866 has no effect on when @emph{first} call takes place---@var{time} specifies
867 that.
868
869 The function @code{run-at-time} returns a timer value that identifies
870 the particular scheduled future action. You can use this value to call
871 @code{cancel-timer}.
872 @end defun
873
874 @defun cancel-timer timer
875 Cancel the requested action for @var{timer}, which should be a value
876 previously returned by @code{run-at-time}. This cancels the effect of
877 that call to @code{run-at-time}; the arrival of the specified time will
878 not cause anything special to happen.
879 @end defun
880
881 @node Terminal Input
882 @section Terminal Input
883 @cindex terminal input
884
885 This section describes functions and variables for recording or
886 manipulating terminal input. See @ref{Display}, for related
887 functions.
888
889 @menu
890 * Input Modes:: Options for how input is processed.
891 * Translating Input:: Low level conversion of some characters or events
892 into others.
893 * Recording Input:: Saving histories of recent or all input events.
894 @end menu
895
896 @node Input Modes
897 @subsection Input Modes
898 @cindex input modes
899 @cindex terminal input modes
900
901 @defun set-input-mode interrupt flow meta quit-char
902 This function sets the mode for reading keyboard input. If
903 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
904 @code{nil}, then it uses @sc{cbreak} mode.
905
906 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
907 @kbd{C-s}) flow control for output to the terminal. This has no effect except
908 in @sc{cbreak} mode. @xref{Flow Control}.
909
910 The default setting is system dependent. Some systems always use
911 @sc{cbreak} mode regardless of what is specified.
912
913 @c Emacs 19 feature
914 The argument @var{meta} controls support for input character codes
915 above 127. If @var{meta} is @code{t}, Emacs converts characters with
916 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
917 Emacs disregards the 8th bit; this is necessary when the terminal uses
918 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
919 Emacs uses all 8 bits of input unchanged. This is good for terminals
920 using European 8-bit character sets.
921
922 @c Emacs 19 feature
923 If @var{quit-char} is non-@code{nil}, it specifies the character to
924 use for quitting. Normally this character is @kbd{C-g}.
925 @xref{Quitting}.
926 @end defun
927
928 The @code{current-input-mode} function returns the input mode settings
929 Emacs is currently using.
930
931 @c Emacs 19 feature
932 @defun current-input-mode
933 This function returns current mode for reading keyboard input. It
934 returns a list, corresponding to the arguments of @code{set-input-mode},
935 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
936 which:
937 @table @var
938 @item interrupt
939 is non-@code{nil} when Emacs is using interrupt-driven input. If
940 @code{nil}, Emacs is using @sc{cbreak} mode.
941 @item flow
942 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
943 flow control for output to the terminal. This value has no effect
944 unless @var{interrupt} is non-@code{nil}.
945 @item meta
946 is non-@code{t} if Emacs treats the eighth bit of input characters as
947 the meta bit; @code{nil} means Emacs clears the eighth bit of every
948 input character; any other value means Emacs uses all eight bits as the
949 basic character code.
950 @item quit
951 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
952 @end table
953 @end defun
954
955 @defvar meta-flag
956 This variable used to control whether to treat the eight bit in keyboard
957 input characters as the @key{Meta} bit. @code{nil} meant no, and
958 anything else meant yes. This variable existed in Emacs versions 18 and
959 earlier but no longer exists in Emacs 19; use @code{set-input-mode}
960 instead.
961 @end defvar
962
963 @node Translating Input
964 @subsection Translating Input Events
965 @cindex translating input events
966
967 This section describes features for translating input events into other
968 input events before they become part of key sequences.
969
970 @c Emacs 19 feature
971 @defvar extra-keyboard-modifiers
972 This variable lets Lisp programs ``press'' the modifier keys on the
973 keyboard. The value is a bit mask:
974
975 @table @asis
976 @item 1
977 The @key{SHIFT} key.
978 @item 2
979 The @key{LOCK} key.
980 @item 4
981 The @key{CTL} key.
982 @item 8
983 The @key{META} key.
984 @end table
985
986 Each time the user types a keyboard key, it is altered as if the
987 modifier keys specified in the bit mask were held down.
988
989 When you use X windows, the program can ``press'' any of the modifier
990 keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
991 be virtually pressed.
992 @end defvar
993
994 @defvar keyboard-translate-table
995 This variable is the translate table for keyboard characters. It lets
996 you reshuffle the keys on the keyboard without changing any command
997 bindings. Its value must be a string or @code{nil}.
998
999 If @code{keyboard-translate-table} is a string, then each character read
1000 from the keyboard is looked up in this string and the character in the
1001 string is used instead. If the string is of length @var{n}, character codes
1002 @var{n} and up are untranslated.
1003
1004 In the example below, we set @code{keyboard-translate-table} to a
1005 string of 128 characters. Then we fill it in to swap the characters
1006 @kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.
1007 Subsequently, typing @kbd{C-\} has all the usual effects of typing
1008 @kbd{C-s}, and vice versa. (@xref{Flow Control} for more information on
1009 this subject.)
1010
1011 @cindex flow control example
1012 @example
1013 @group
1014 (defun evade-flow-control ()
1015 "Replace C-s with C-\ and C-q with C-^."
1016 (interactive)
1017 @end group
1018 @group
1019 (let ((the-table (make-string 128 0)))
1020 (let ((i 0))
1021 (while (< i 128)
1022 (aset the-table i i)
1023 (setq i (1+ i))))
1024 @end group
1025 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1026 (aset the-table ?\034 ?\^s)
1027 (aset the-table ?\^s ?\034)
1028 @group
1029 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1030 (aset the-table ?\036 ?\^q)
1031 (aset the-table ?\^q ?\036)
1032 (setq keyboard-translate-table the-table)))
1033 @end group
1034 @end example
1035
1036 Note that this translation is the first thing that happens to a
1037 character after it is read from the terminal. Record-keeping features
1038 such as @code{recent-keys} and dribble files record the characters after
1039 translation.
1040 @end defvar
1041
1042 @defun keyboard-translate from to
1043 This function modifies @code{keyboard-translate-table} to translate
1044 character code @var{from} into character code @var{to}. It creates
1045 or enlarges the translate table if necessary.
1046 @end defun
1047
1048 @defvar function-key-map
1049 This variable holds a keymap that describes the character sequences
1050 sent by function keys on an ordinary character terminal. This keymap
1051 uses the same data structure as other keymaps, but is used differently: it
1052 specifies translations to make while reading events.
1053
1054 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1055 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1056 key sequence, it is replaced with the events in @var{v}.
1057
1058 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1059 keypad PF1 key is pressed. Therefore, we want Emacs to translate
1060 that sequence of events into the single event @code{pf1}. We accomplish
1061 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1062 @code{function-key-map}, when using a VT100.
1063
1064 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1065 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1066 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1067 @code{[?\C-c pf1]}.
1068
1069 Entries in @code{function-key-map} are ignored if they conflict with
1070 bindings made in the minor mode, local, or global keymaps. The intent
1071 is that the character sequences that function keys send should not have
1072 command bindings in their own right.
1073
1074 The value of @code{function-key-map} is usually set up automatically
1075 according to the terminal's Terminfo or Termcap entry, but sometimes
1076 those need help from terminal-specific Lisp files. Emacs comes with
1077 terminal-specific files for many common terminals; their main purpose is
1078 to make entries in @code{function-key-map} beyond those that can be
1079 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1080
1081 Emacs versions 18 and earlier used totally different means of detecting
1082 the character sequences that represent function keys.
1083 @end defvar
1084
1085 @defvar key-translation-map
1086 This variable is another keymap used just like @code{function-key-map}
1087 to translate input events into other events. It differs from
1088 @code{function-key-map} in two ways:
1089
1090 @itemize @bullet
1091 @item
1092 @code{key-translation-map} goes to work after @code{function-key-map} is
1093 finished; it receives the results of translation by
1094 @code{function-key-map}.
1095
1096 @item
1097 @code{key-translation-map} overrides actual key bindings.
1098 @end itemize
1099
1100 The intent of @code{key-translation-map} is for users to map one
1101 character set to another, including ordinary characters normally bound
1102 to @code{self-insert-command}.
1103 @end defvar
1104
1105 @cindex key translation function
1106 You can use @code{function-key-map} or @code{key-translation-map} for
1107 more than simple aliases, by using a function, instead of a key
1108 sequence, as the ``translation'' of a key. Then this function is called
1109 to compute the translation of that key.
1110
1111 The key translation function receives one argument, which is the prompt
1112 that was specified in @code{read-key-sequence}---or @code{nil} if the
1113 key sequence is being read by the editor command loop. In most cases
1114 you can ignore the prompt value.
1115
1116 If the function reads input itself, it can have the effect of altering
1117 the event that follows. For example, here's how to define @kbd{C-c h}
1118 to turn the character that follows into a Hyper character:
1119
1120 @example
1121 (defun hyperify (prompt)
1122 (let ((e (read-event)))
1123 (vector (if (numberp e)
1124 (logior (lsh 1 20) e)
1125 (if (memq 'hyper (event-modifiers e))
1126 e
1127 (add-event-modifier "H-" e))))))
1128
1129 (defun add-event-modifier (string e)
1130 (let ((symbol (if (symbolp e) e (car e))))
1131 (setq symbol (intern (concat string
1132 (symbol-name symbol))))
1133 (if (symbolp e)
1134 symbol
1135 (cons symbol (cdr e)))))
1136
1137 (define-key function-key-map "\C-ch" 'hyperify)
1138 @end example
1139
1140 @pindex iso-transl
1141 @cindex Latin-1 character set (input)
1142 @cindex ISO Latin-1 characters (input)
1143 The @file{iso-transl} library uses this feature to provide a way of
1144 inputting non-ASCII Latin-1 characters.
1145
1146 @node Recording Input
1147 @subsection Recording Input
1148
1149 @defun recent-keys
1150 This function returns a vector containing the last 100 input events
1151 from the keyboard or mouse. All input events are included, whether or
1152 not they were used as parts of key sequences. Thus, you always get the
1153 last 100 inputs, not counting keyboard macros. (Events from keyboard
1154 macros are excluded because they are less interesting for debugging; it
1155 should be enough to see the events that invoked the macros.)
1156 @end defun
1157
1158 @deffn Command open-dribble-file filename
1159 @cindex dribble file
1160 This function opens a @dfn{dribble file} named @var{filename}. When a
1161 dribble file is open, each input event from the keyboard or mouse (but
1162 not those from keyboard macros) is written in that file. A
1163 non-character event is expressed using its printed representation
1164 surrounded by @samp{<@dots{}>}.
1165
1166 You close the dribble file by calling this function with an argument
1167 of @code{nil}.
1168
1169 This function is normally used to record the input necessary to
1170 trigger an Emacs bug, for the sake of a bug report.
1171
1172 @example
1173 @group
1174 (open-dribble-file "~/dribble")
1175 @result{} nil
1176 @end group
1177 @end example
1178 @end deffn
1179
1180 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1181
1182 @node Terminal Output
1183 @section Terminal Output
1184 @cindex terminal output
1185
1186 The terminal output functions send output to the terminal or keep
1187 track of output sent to the terminal. The variable @code{baud-rate}
1188 tells you what Emacs thinks is the output speed of the terminal.
1189
1190 @defvar baud-rate
1191 This variable's value is the output speed of the terminal, as far as
1192 Emacs knows. Setting this variable does not change the speed of actual
1193 data transmission, but the value is used for calculations such as
1194 padding. It also affects decisions about whether to scroll part of the
1195 screen or repaint---even when using a window system. (We designed it
1196 this way despite the fact that a window system has no true ``output
1197 speed'', to give you a way to tune these decisions.)
1198
1199 The value is measured in baud.
1200 @end defvar
1201
1202 If you are running across a network, and different parts of the
1203 network work at different baud rates, the value returned by Emacs may be
1204 different from the value used by your local terminal. Some network
1205 protocols communicate the local terminal speed to the remote machine, so
1206 that Emacs and other programs can get the proper value, but others do
1207 not. If Emacs has the wrong value, it makes decisions that are less
1208 than optimal. To fix the problem, set @code{baud-rate}.
1209
1210 @defun baud-rate
1211 This function returns the value of the variable @code{baud-rate}. In
1212 Emacs versions 18 and earlier, this was the only way to find out the
1213 terminal speed.
1214 @end defun
1215
1216 @defun send-string-to-terminal string
1217 This function sends @var{string} to the terminal without alteration.
1218 Control characters in @var{string} have terminal-dependent effects.
1219
1220 One use of this function is to define function keys on terminals that
1221 have downloadable function key definitions. For example, this is how on
1222 certain terminals to define function key 4 to move forward four
1223 characters (by transmitting the characters @kbd{C-u C-f} to the
1224 computer):
1225
1226 @example
1227 @group
1228 (send-string-to-terminal "\eF4\^U\^F")
1229 @result{} nil
1230 @end group
1231 @end example
1232 @end defun
1233
1234 @deffn Command open-termscript filename
1235 @cindex termscript file
1236 This function is used to open a @dfn{termscript file} that will record
1237 all the characters sent by Emacs to the terminal. It returns
1238 @code{nil}. Termscript files are useful for investigating problems
1239 where Emacs garbles the screen, problems that are due to incorrect
1240 Termcap entries or to undesirable settings of terminal options more
1241 often than to actual Emacs bugs. Once you are certain which characters
1242 were actually output, you can determine reliably whether they correspond
1243 to the Termcap specifications in use.
1244
1245 See also @code{open-dribble-file} in @ref{Terminal Input}.
1246
1247 @example
1248 @group
1249 (open-termscript "../junk/termscript")
1250 @result{} nil
1251 @end group
1252 @end example
1253 @end deffn
1254
1255 @node Special Keysyms
1256 @section System-Specific X11 Keysyms
1257
1258 To define system-specific X11 keysyms, set the variable
1259 @code{system-key-alist}.
1260
1261 @defvar system-key-alist
1262 This variable's value should be an alist with one element for each
1263 system-specific keysym. An element has this form: @code{(@var{code}
1264 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1265 including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
1266 name for the function key.
1267
1268 For example @code{(168 . mute-acute)} defines a system-specific key used
1269 by HP X servers whose numeric code is (1 << 28) + 168.
1270
1271 It is not a problem if the alist defines keysyms for other X servers, as
1272 long as they don't conflict with the ones used by the X server actually
1273 in use.
1274 @end defvar
1275
1276 @node Flow Control
1277 @section Flow Control
1278 @cindex flow control characters
1279
1280 This section attempts to answer the question ``Why does Emacs choose
1281 to use flow-control characters in its command character set?'' For a
1282 second view on this issue, read the comments on flow control in the
1283 @file{emacs/INSTALL} file from the distribution; for help with Termcap
1284 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
1285
1286 @cindex @kbd{C-s}
1287 @cindex @kbd{C-q}
1288 At one time, most terminals did not need flow control, and none used
1289 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1290 @kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
1291 Emacs, for economy of keystrokes and portability, used nearly all the
1292 @sc{ASCII} control characters, with mnemonic meanings when possible;
1293 thus, @kbd{C-s} for search and @kbd{C-q} for quote.
1294
1295 Later, some terminals were introduced which required these characters
1296 for flow control. They were not very good terminals for full-screen
1297 editing, so Emacs maintainers did not pay attention. In later years,
1298 flow control with @kbd{C-s} and @kbd{C-q} became widespread among
1299 terminals, but by this time it was usually an option. And the majority
1300 of users, who can turn flow control off, were unwilling to switch to
1301 less mnemonic key bindings for the sake of flow control.
1302
1303 So which usage is ``right'', Emacs's or that of some terminal and
1304 concentrator manufacturers? This question has no simple answer.
1305
1306 One reason why we are reluctant to cater to the problems caused by
1307 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1308 techniques (albeit less common in practice) for flow control that
1309 preserve transparency of the character stream. Note also that their use
1310 for flow control is not an official standard. Interestingly, on the
1311 model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
1312 and @kbd{C-q} were sent by the computer to turn the punch on and off!
1313
1314 GNU Emacs version 19 provides a convenient way of enabling flow
1315 control if you want it: call the function @code{enable-flow-control}.
1316
1317 @defun enable-flow-control
1318 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1319 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1320 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1321 @end defun
1322
1323 You can use the function @code{enable-flow-control-on} in your
1324 @file{.emacs} file to enable flow control automatically on certain
1325 terminal types.
1326
1327 @defun enable-flow-control-on &rest termtypes
1328 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1329 if the terminal type is one of @var{termtypes}. For example:
1330
1331 @smallexample
1332 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1333 @end smallexample
1334 @end defun
1335
1336 Here is how @code{enable-flow-control} does its job:
1337
1338 @enumerate
1339 @item
1340 @cindex @sc{cbreak}
1341 It sets @sc{cbreak} mode for terminal input, and tells the operating
1342 system to handle flow control, with @code{(set-input-mode nil t)}.
1343
1344 @item
1345 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1346 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1347 lowest level, Emacs never knows that the characters typed were anything
1348 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1349 and @kbd{C-^} even when they are input for other commands.
1350 @xref{Translating Input}.
1351 @end enumerate
1352
1353 If the terminal is the source of the flow control characters, then once
1354 you enable kernel flow control handling, you probably can make do with
1355 less padding than normal for that terminal. You can reduce the amount
1356 of padding by customizing the Termcap entry. You can also reduce it by
1357 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
1358 speed when calculating the padding needed. @xref{Terminal Output}.
1359
1360 @node Batch Mode
1361 @section Batch Mode
1362 @cindex batch mode
1363 @cindex noninteractive use
1364
1365 The command line option @samp{-batch} causes Emacs to run
1366 noninteractively. In this mode, Emacs does not read commands from the
1367 terminal, it does not alter the terminal modes, and it does not expect
1368 to be outputting to an erasable screen. The idea is that you specify
1369 Lisp programs to run; when they are finished, Emacs should exit. The
1370 way to specify the programs to run is with @samp{-l @var{file}}, which
1371 loads the library named @var{file}, and @samp{-f @var{function}}, which
1372 calls @var{function} with no arguments.
1373
1374 Any Lisp program output that would normally go to the echo area,
1375 either using @code{message} or using @code{prin1}, etc., with @code{t}
1376 as the stream, goes instead to Emacs's standard output descriptor when
1377 in batch mode. Thus, Emacs behaves much like a noninteractive
1378 application program. (The echo area output that Emacs itself normally
1379 generates, such as command echoing, is suppressed entirely.)
1380
1381 @defvar noninteractive
1382 This variable is non-@code{nil} when Emacs is running in batch mode.
1383 @end defvar