2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/os.info
8 @node System Interface, X-Windows, Processes, Top
9 @chapter Operating System Interface
11 This chapter is about starting and getting out of SXEmacs, access to
12 values in the operating system environment, and terminal input, output,
15 @xref{Building SXEmacs}, for related information. See also
16 @ref{Display}, for additional operating system status information
17 pertaining to the terminal and the screen.
20 * Starting Up:: Customizing SXEmacs start-up processing.
21 * Getting Out:: How exiting works (permanent or temporary).
22 * System Environment:: Distinguish the name and kind of system.
23 * User Identification:: Finding the name and user id of the user.
24 * Time of Day:: Getting the current time.
25 * Time Conversion:: Converting a time from numeric form to a string, or
26 to calendrical data (or vice versa).
27 * Timers:: Setting a timer to call a function at a certain time.
28 * Terminal Input:: Recording terminal input for debugging.
29 * Terminal Output:: Recording terminal output for debugging.
30 * Flow Control:: How to turn output flow control on or off.
31 * Batch Mode:: Running SXEmacs without terminal interaction.
34 * Special Keysyms:: Defining system-specific key symbols for X windows.
39 @section Starting Up SXEmacs
41 This section describes what SXEmacs does when it is started, and how you
42 can customize these actions.
45 * Start-up Summary:: Sequence of actions SXEmacs performs at start-up.
46 * Init File:: Details on reading the init file (@file{init.el}).
47 * Terminal-Specific:: How the terminal-specific Lisp file is read.
48 * Command Line Arguments:: How command line arguments are processed,
49 and how you can customize them.
53 @node Start-up Summary
54 @subsection Summary: Sequence of Actions at Start Up
55 @cindex initialization
56 @cindex start up of SXEmacs
57 @cindex @file{startup.el}
59 The order of operations performed (in @file{startup.el}) by SXEmacs when
60 it is started up is as follows:
64 It loads the initialization library for the window system, if you are
65 using a window system. This library's name is
66 @file{term/@var{windowsystem}-win.el}.
69 It processes the initial options. Some of them are handled even earlier
73 It initializes the X window frame and faces, if appropriate.
76 It runs the normal hook @code{before-init-hook}.
79 It loads the library @file{site-start}, unless the option
80 @samp{-no-site-file} was specified. The library's file name is usually
82 @cindex @file{site-start.el}
85 It loads the file @file{~/.sxemacs/init.el} unless @samp{-q} was
86 specified on the command line. This is not done in @samp{-batch} mode,
87 though. The @samp{-u} option can specify the user name whose home
88 directory should be used instead of @file{~}.
90 If the directory @file{~/.sxemacs} or @file{init.el} in there does not
91 exist, SXEmacs tries to read @file{init.el} in @file{~/.xemacs}.
92 If this also fails, it looks for a @file{~/.emacs}.
93 @cindex @file{init.el}
96 It loads the library @file{default} unless @code{inhibit-default-init}
97 is non-@code{nil}. This is not done in @samp{-batch} mode or if
98 @samp{-q} was specified on the command line. The library's file name
99 is usually @file{default.el}.
100 @cindex @file{default.el}
103 It runs the normal hook @code{after-init-hook}.
106 It sets the major mode according to @code{initial-major-mode}, provided
107 the buffer @samp{*scratch*} is still current and still in Fundamental
111 It loads the terminal-specific Lisp file, if any, except when in batch
112 mode or using a window system.
115 It displays the initial echo area message, unless you have suppressed
116 that with @code{inhibit-startup-echo-area-message}.
119 It processes the action arguments from the command line.
122 It runs @code{term-setup-hook}.
125 It calls @code{frame-notice-user-settings}, which modifies the
126 parameters of the selected frame according to whatever the init files
130 It runs @code{window-setup-hook}. @xref{Terminal-Specific}.
133 It calls the command @code{sxemacs-splash-buffer} which displays
134 copyleft, nonwarranty, and basic use information, provided there were no
135 remaining command line arguments (a few steps above) and the value of
136 @code{inhibit-startup-message} is @code{nil}.
139 @defopt inhibit-startup-message
140 This variable inhibits the initial startup messages (the nonwarranty,
141 etc.). If it is non-@code{nil}, then the messages are not printed.
143 This variable exists so you can set it in your personal init file, once
144 you are familiar with the contents of the startup message.
146 Do not set this variable in the init file of a new user, or in a way
147 that affects more than one user, because that would prevent new users
148 from receiving the information they are supposed to see.
151 @defopt inhibit-startup-echo-area-message
152 This variable controls the display of the startup echo area message.
153 You can suppress the startup echo area message by adding text with this
154 form to your @file{init.el} file:
157 (setq inhibit-startup-echo-area-message
158 "@var{your-login-name}")
161 Simply setting @code{inhibit-startup-echo-area-message} to your login
162 name is not sufficient to inhibit the message; Emacs explicitly checks
163 whether @file{init.el} contains an expression as shown above. Your login
164 name must appear in the expression as a Lisp string constant.
166 This way, you can easily inhibit the message for yourself if you wish,
167 but thoughtless copying of your @file{init.el} file will not inhibit the
168 message for someone else.
173 @subsection The Init File: @file{init.el}
175 @cindex @file{init.el}
177 When you start SXEmacs, it normally attempts to load the file
178 @file{init.el} from your @file{.sxemacs} directory in your home
179 directory. This file, if it exists, must contain Lisp code. It is
180 called your @dfn{init file}. The command line switches @samp{-q} and
181 @samp{-u} affect the use of the init file; @samp{-q} says not to load an
182 init file, and @samp{-u} says to load a specified user's init file
184 @xref{Entering SXEmacs,,,sxemacs, The SXEmacs User's Manual}.
186 @cindex default init file
187 A site may have a @dfn{default init file}, which is the library named
188 @file{default.el}. SXEmacs finds the @file{default.el} file through the
189 standard search path for libraries (@pxref{How Programs Do Loading}).
190 The SXEmacs distribution does not come with this file; sites may provide
191 one for local customizations. If the default init file exists, it is
192 loaded whenever you start SXEmacs, except in batch mode or if @samp{-q} is
193 specified. But your own personal init file, if any, is loaded first; if
194 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
195 SXEmacs does not subsequently load the @file{default.el} file.
197 Another file for site-customization is @file{site-start.el}. SXEmacs
198 loads this @emph{before} the user's init file. You can inhibit the
199 loading of this file with the option @samp{-no-site-file}.
203 @defvar site-run-file
204 This variable specifies the site-customization file to load
205 before the user's init file. Its normal value is @code{"site-start"}.
209 If there is a great deal of code in your @file{init.el} file, you
210 should move it into another file named @file{@var{something}.el},
211 byte-compile it (@pxref{Byte Compilation}), and make your @file{init.el}
212 file load the other file using @code{load} (@pxref{Loading}).
214 @xref{Init File Examples,,, sxemacs, The SXEmacs User's Manual}, for
215 examples of how to make various commonly desired customizations in your
218 @defopt inhibit-default-init
219 This variable prevents SXEmacs from loading the default initialization
220 library file for your session of SXEmacs. If its value is non-@code{nil},
221 then the default library is not loaded. The default value is
225 @defvar before-init-hook
226 @defvarx after-init-hook
227 These two normal hooks are run just before, and just after, loading of
228 the user's init file, @file{default.el}, and/or @file{site-start.el}.
232 @node Terminal-Specific
233 @subsection Terminal-Specific Initialization
234 @cindex terminal-specific initialization
236 Each terminal type can have its own Lisp library that SXEmacs loads
237 when run on that type of terminal. For a terminal type named
238 @var{termtype}, the library is called @file{term/@var{termtype}}.
239 SXEmacs finds the file by searching the @code{load-path} directories as
240 it does for other files, and trying the @samp{.elc} and @samp{.el}
241 suffixes. Normally, terminal-specific Lisp library is located in
242 @file{sxemacs/lisp/term}, a subdirectory of the @file{sxemacs/lisp}
243 directory in which most SXEmacs Lisp libraries are kept.@refill
245 The library's name is constructed by concatenating the value of the
246 variable @code{term-file-prefix} and the terminal type. Normally,
247 @code{term-file-prefix} has the value @code{"term/"}; changing this
250 The usual function of a terminal-specific library is to enable special
251 keys to send sequences that SXEmacs can recognize. It may also need to
252 set or add to @code{function-key-map} if the Termcap entry does not
253 specify all the terminal's function keys. @xref{Terminal Input}.
256 When the name of the terminal type contains a hyphen, only the part of
257 the name before the first hyphen is significant in choosing the library
258 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
259 the @file{term/aaa} library. If necessary, the library can evaluate
260 @code{(getenv "TERM")} to find the full name of the terminal
263 Your @file{init.el} file can prevent the loading of the
264 terminal-specific library by setting the variable
265 @code{term-file-prefix} to @code{nil}. This feature is useful when
266 experimenting with your own peculiar customizations.
268 You can also arrange to override some of the actions of the
269 terminal-specific library by setting the variable
270 @code{term-setup-hook}. This is a normal hook which SXEmacs runs using
271 @code{run-hooks} at the end of SXEmacs initialization, after loading both
272 your @file{init.el} file and any terminal-specific libraries. You can
273 use this variable to define initializations for terminals that do not
274 have their own libraries. @xref{Hooks}.
276 @defvar term-file-prefix
277 @cindex @code{TERM} environment variable
278 If the @code{term-file-prefix} variable is non-@code{nil}, SXEmacs loads
279 a terminal-specific initialization file as follows:
282 (load (concat term-file-prefix (getenv "TERM")))
286 You may set the @code{term-file-prefix} variable to @code{nil} in your
287 @file{init.el} file if you do not wish to load the
288 terminal-initialization file. To do this, put the following in
289 your @file{init.el} file: @code{(setq term-file-prefix nil)}.
292 @defvar term-setup-hook
293 This variable is a normal hook that SXEmacs runs after loading your
294 @file{init.el} file, the default initialization file (if any) and the
295 terminal-specific Lisp file.
297 You can use @code{term-setup-hook} to override the definitions made by a
298 terminal-specific file.
301 @defvar window-setup-hook
302 This variable is a normal hook which SXEmacs runs after loading your
303 @file{init.el} file and the default initialization file (if any), after
304 loading terminal-specific Lisp code, and after running the hook
305 @code{term-setup-hook}.
309 @node Command Line Arguments
310 @subsection Command Line Arguments
311 @cindex command line arguments
313 You can use command line arguments to request various actions when you
314 start SXEmacs. Since you do not need to start SXEmacs more than once per
315 day, and will often leave your SXEmacs session running longer than that,
316 command line arguments are hardly ever used. As a practical matter, it
317 is best to avoid making the habit of using them, since this habit would
318 encourage you to kill and restart SXEmacs unnecessarily often. These
319 options exist for two reasons: to be compatible with other editors (for
320 invocation by other programs) and to enable shell scripts to run
321 specific Lisp programs.
323 This section describes how SXEmacs processes command line arguments,
324 and how you can customize them.
326 Note: Some other editors require you to start afresh each time
327 you want to edit a file. With this kind of editor, you will probably
328 specify the file as a command line argument.
330 The recommended way to use SXEmacs is to start it only once, just after
331 you log in, and do all your editing in the same SXEmacs process. Each
332 time you want to edit a different file, you visit it with the existing
333 SXEmacs, which eventually comes to have many files in it ready for
334 editing. Usually you do not kill the SXEmacs until you are about to log
338 This function parses the command line that SXEmacs was called with,
339 processes it, loads the user's @file{init.el} file and displays the
343 @defvar command-line-processed
344 The value of this variable is @code{t} once the command line has been
347 If you redump SXEmacs by calling @code{dump-emacs}, you may wish to set
348 this variable to @code{nil} first in order to cause the new dumped
349 SXEmacs to process its new command line arguments.
352 @defvar command-switch-alist
353 @cindex switches on command line
354 @cindex options on command line
355 @cindex command line options
356 The value of this variable is an alist of user-defined command-line
357 options and associated handler functions. This variable exists so you
358 can add elements to it.
360 A @dfn{command line option} is an argument on the command line of the
367 The elements of the @code{command-switch-alist} look like this:
370 (@var{option} . @var{handler-function})
373 The @var{handler-function} is called to handle @var{option} and receives
374 the option name as its sole argument.
376 In some cases, the option is followed in the command line by an
377 argument. In these cases, the @var{handler-function} can find all the
378 remaining command-line arguments in the variable
379 @code{command-line-args-left}. The entire list of command-line
380 arguments is in @code{command-line-args}.
382 The command line arguments are parsed by the @code{command-line-1}
383 function in the @file{startup.el} file. See also @ref{Command
384 Switches, , Command Line Switches and Arguments, sxemacs, The SXEmacs
388 @defvar command-line-args
389 The value of this variable is the list of command line arguments passed
393 @defvar command-line-functions
394 This variable's value is a list of functions for handling an
395 unrecognized command-line argument. Each time the next argument to be
396 processed has no special meaning, the functions in this list are called,
397 in order of appearance, until one of them returns a non-@code{nil}
400 These functions are called with no arguments. They can access the
401 command-line argument under consideration through the variable
402 @code{argi}. The remaining arguments (not including the current one)
403 are in the variable @code{command-line-args-left}.
405 When a function recognizes and processes the argument in @code{argi}, it
406 should return a non-@code{nil} value to say it has dealt with that
407 argument. If it has also dealt with some of the following arguments, it
408 can indicate that by deleting them from @code{command-line-args-left}.
410 If all of these functions return @code{nil}, then the argument is used
411 as a file name to visit.
416 @section Getting out of SXEmacs
417 @cindex exiting SXEmacs
419 There are two ways to get out of SXEmacs: you can kill the SXEmacs job,
420 which exits permanently, or you can suspend it, which permits you to
421 reenter the SXEmacs process later. As a practical matter, you seldom kill
422 SXEmacs---only when you are about to log out. Suspending is much more
426 * Killing SXEmacs:: Exiting SXEmacs irreversibly.
427 * Suspending SXEmacs:: Exiting SXEmacs reversibly.
431 @node Killing SXEmacs
432 @subsection Killing SXEmacs
433 @cindex killing SXEmacs
435 Killing SXEmacs means ending the execution of the SXEmacs process. The
436 parent process normally resumes control. The low-level primitive for
437 killing SXEmacs is @code{kill-emacs}.
439 @deffn Command kill-emacs &optional exit-data
440 This function exits the SXEmacs process and kills it.
442 If @var{exit-data} is an integer, then it is used as the exit status
443 of the SXEmacs process. This is useful primarily in batch operation; see
446 If @var{exit-data} is a string, its contents are stuffed into the
447 terminal input buffer so that the shell (or whatever program next reads
448 input) can read them.
451 All the information in the SXEmacs process, aside from files that have
452 been saved, is lost when the SXEmacs is killed. Because killing SXEmacs
453 inadvertently can lose a lot of work, SXEmacs queries for confirmation
454 before actually terminating if you have buffers that need saving or
455 subprocesses that are running. This is done in the function
456 @code{save-buffers-kill-emacs}.
458 @defvar kill-emacs-query-functions
459 After asking the standard questions, @code{save-buffers-kill-emacs}
460 calls the functions in the list @code{kill-buffer-query-functions}, in
461 order of appearance, with no arguments. These functions can ask for
462 additional confirmation from the user. If any of them returns
463 non-@code{nil}, SXEmacs is not killed.
466 @defvar kill-emacs-hook
467 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
468 finished with all file saving and confirmation, it runs the functions in
473 @node Suspending SXEmacs
474 @subsection Suspending SXEmacs
475 @cindex suspending SXEmacs
477 @dfn{Suspending SXEmacs} means stopping SXEmacs temporarily and
478 returning control to its superior process, which is usually the shell.
479 This allows you to resume editing later in the same SXEmacs process,
480 with the same buffers, the same kill ring, the same undo history, and so
481 on. To resume SXEmacs, use the appropriate command in the parent
482 shell---most likely @code{fg}.
484 Some operating systems do not support suspension of jobs; on these
485 systems, ``suspension'' actually creates a new shell temporarily as a
486 subprocess of SXEmacs. Then you would exit the shell to return to
489 Suspension is not useful with window systems such as X, because the
490 SXEmacs job may not have a parent that can resume it again, and in any
491 case you can give input to some other job such as a shell merely by
492 moving to a different window. Nonetheless, you can use the
493 suspend-or-iconify feature in this case.
495 @deffn Command suspend-emacs &optional stuffstring
496 This function stops SXEmacs and returns control to the superior process.
497 If and when the superior process resumes SXEmacs, @code{suspend-emacs}
498 returns @code{nil} to its caller in Lisp.
500 If optional arg @var{stuffstring} is non-@code{nil}, its characters are
501 sent to be read as terminal input by SXEmacs's superior shell. The
502 characters in @var{stuffstring} are not echoed by the superior shell;
503 only the results appear.
505 Before suspending, @code{suspend-emacs} runs the normal hook
507 @ignore @c who cares?! -hrop
508 In Emacs version 18, @code{suspend-hook} was not
509 a normal hook; its value was a single function, and if its value was
510 non-@code{nil}, then @code{suspend-emacs} returned immediately without
511 actually suspending anything.
514 After the user resumes SXEmacs, @code{suspend-emacs} runs the normal
515 hook @code{suspend-resume-hook}. @xref{Hooks}.
517 The next redisplay after resumption will redraw the entire screen,
518 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
519 (@pxref{Refresh Screen}).
521 In the following example, note that @samp{pwd} is not echoed after
522 SXEmacs is suspended. But it is read and executed by the shell.
531 (add-hook 'suspend-hook
535 (error "Suspend cancelled")))))
536 @result{} (lambda nil
537 (or (y-or-n-p "Really suspend? ")
538 (error "Suspend cancelled")))
541 (add-hook 'suspend-resume-hook
542 (function (lambda () (message "Resumed!"))))
543 @result{} (lambda nil (message "Resumed!"))
546 (suspend-emacs "pwd")
550 ---------- Buffer: Minibuffer ----------
551 Really suspend? @kbd{y}
552 ---------- Buffer: Minibuffer ----------
556 ---------- Parent Shell ----------
557 lewis@@slug[23] % /user/lewis/manual
562 ---------- Echo Area ----------
569 This variable is a normal hook run before suspending.
572 @defvar suspend-resume-hook
573 This variable is a normal hook run after suspending.
577 @node System Environment
578 @section Operating System Environment
579 @cindex operating system environment
581 SXEmacs provides access to variables in the operating system
582 environment through various functions. These variables include the name
583 of the system, the user's @sc{uid}, and so on.
586 The value of this variable is a symbol indicating the type of operating
587 system SXEmacs is operating on. Here is a table of the possible values:
597 Data General DGUX operating system.
600 A GNU system using the GNU HURD and Mach.
603 Hewlett-Packard HPUX operating system.
606 Silicon Graphics Irix system.
609 A GNU system using the Linux kernel.
612 NeXT Mach-based system.
615 Masscomp RTU, UCB universe.
627 We do not wish to add new symbols to make finer distinctions unless it
628 is absolutely necessary! In fact, we hope to eliminate some of these
629 alternatives in the future. We recommend using
630 @code{system-configuration} to distinguish between different operating
634 @defvar system-configuration
635 This variable holds the three-part configuration name for the
636 hardware/software configuration of your system, as a string. The
637 convenient way to test parts of this string is with @code{string-match}.
641 This function returns the name of the machine you are running on.
644 @result{} "micky.math.tu-berlin.de"
649 @comment this seems not correct -hrop
651 The symbol @code{system-name} is a variable as well as a function. In
652 fact, the function returns whatever value the variable
653 @code{system-name} currently holds. Thus, you can set the variable
654 @code{system-name} in case Emacs is confused about the name of your
655 system. The variable is also useful for constructing frame titles
656 (@pxref{Frame Titles}).
659 @defvar mail-host-address
660 If this variable is non-@code{nil}, it is used instead of
661 @code{system-name} for purposes of generating email addresses. For
662 example, it is used when constructing the default value of
663 @code{user-mail-address}. @xref{User Identification}. Since this is
664 done when SXEmacs starts up, the value actually used is the one saved
665 when SXEmacs was dumped. @xref{Building SXEmacs}.
668 @deffn Command getenv var &optional interactivep
669 @cindex environment variable access
670 This function returns the value of the environment variable @var{var},
671 as a string. Within SXEmacs, the environment variable values are kept
672 in the Lisp variable @code{process-environment}.
674 When invoked interactively, @code{getenv} prints the value in the echo area.
683 lewis@@slug[10] % printenv
684 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
695 @deffn Command setenv variable &optional value unset
696 This command sets the value of the environment variable named
697 @var{variable} to @var{value}. Both arguments should be strings. This
698 function works by modifying @code{process-environment}; binding that
699 variable with @code{let} is also reasonable practice.
702 @defvar process-environment
703 This variable is a list of strings, each describing one environment
704 variable. The functions @code{getenv} and @code{setenv} work by
705 manipulating this variable.
710 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
711 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
722 @defvar path-separator
723 This variable holds a string which says which character separates
724 directories in a search path (as found in an environment variable). Its
725 value is @code{":"} for Unix and GNU systems.
728 @defvar invocation-name
729 This variable holds the program name under which SXEmacs was invoked.
730 The value is a string, and does not include a directory name.
733 @defvar invocation-directory
734 This variable holds the directory from which the SXEmacs executable was
735 invoked, or perhaps @code{nil} if that directory cannot be determined.
738 @ignore @c gah, void again :( -hrop
739 @defvar installation-directory
740 If non-@code{nil}, this is a directory within which to look for the
741 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
742 when Emacs can't find those directories in their standard installed
743 locations, but can find them in a directory related somehow to the one
744 containing the SXEmacs executable.
748 @defun load-average &optional use-floats
749 This function returns a list of the current 1-minute, 5-minute and
750 15-minute load averages. The values are integers that are 100 times the
751 system load averages. The load averages indicate the number of
752 processes trying to run.
754 When optional @var{use-floats} is non-@code{nil}, floats will be
755 returned instead of integers. These floats are not multiplied by 100.
760 @result{} (169 158 164)
762 @result{} (1.69921875 1.58984375 1.640625)
766 lewis@@rocky[5] % uptime
767 8:06pm up 16 day(s), 21:57, 40 users,
768 load average: 1.68, 1.59, 1.64
772 If the 5-minute or 15-minute load averages are not available, return a
773 shortened list, containing only those averages which are available.
775 On some systems, this function may require special privileges to run, or
776 it may be unimplemented for the particular system type. In that case,
777 the function will signal an error.
781 This function returns the process @sc{id} of the SXEmacs process.
785 @node User Identification
786 @section User Identification
788 @defvar user-mail-address
789 This holds the nominal email address of the user who is using SXEmacs.
790 When SXEmacs starts up, it computes a default value that is usually right,
791 but users often set this themselves when the default value is not right.
794 @defun user-login-name &optional uid
795 If you do not specify @var{uid}, this function returns the name under
796 which the user is logged in. If the environment variable @code{LOGNAME}
797 is set, that value is used. Otherwise, if the environment variable
798 @code{USER} is set, that value is used. Otherwise, the value is based
799 on the effective @sc{uid}, not the real @sc{uid}.
801 If you specify @var{uid}, the value is the user name that corresponds
802 to @var{uid} (which should be an integer).
812 @defun user-real-login-name
813 This function returns the user name corresponding to SXEmacs's real
814 @sc{uid}. This ignores the effective @sc{uid} and ignores the
815 environment variables @code{LOGNAME} and @code{USER}.
818 @defvar user-full-name
819 This variable holds the name of the user running this SXEmacs. It is
820 initialized at startup time from the value of @code{NAME} environment
821 variable. You can change the value of this variable to alter the result
822 of the @code{user-full-name} function.
825 @defun user-full-name &optional user
826 This function returns the full name of @var{user}. If @var{user} is
827 @code{nil}, it defaults to the user running this SXEmacs. In that case,
828 the value of @code{user-full-name} variable, if non-@code{nil}, will be
831 If @var{user} is specified explicitly, @code{user-full-name} variable is
837 @result{} "Hrvoje Niksic"
838 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
840 @result{} "Hrvoje \"Niksa\" Niksic"
841 (user-full-name "hniksic")
842 @result{} "Hrvoje Niksic"
847 @vindex user-full-name
848 @vindex user-real-login-name
849 @vindex user-login-name
850 The symbols @code{user-login-name}, @code{user-real-login-name} and
851 @code{user-full-name} are variables as well as functions. The functions
852 return the same values that the variables hold. These variables allow
853 you to ``fake out'' SXEmacs by telling the functions what to return. The
854 variables are also useful for constructing frame titles (@pxref{Frame
858 This function returns the real @sc{uid} of the user.
869 This function returns the effective @sc{uid} of the user.
872 @defun user-home-directory
873 This function returns the ``@code{HOME}'' directory of the user, and is
874 intended to replace occurrences of ``@code{(getenv "HOME")}''. Under
875 Unix systems, the following is done:
879 Return the value of ``@code{(getenv "HOME")}'', if set.
882 Return ``/'', as a fallback, but issue a warning. Future versions of
883 SXEmacs will also attempt to lookup the @code{HOME} directory via
884 @code{getpwent()}, but this has not yet been implemented.
892 This section explains how to determine the current time and the time
895 @defun current-time-string &optional time-value
896 This function returns the current time and date as a humanly-readable
897 string. The format of the string is unvarying; the number of characters
898 used for each part is always the same, so you can reliably use
899 @code{substring} to extract pieces of it. It is wise to count the
900 characters from the beginning of the string rather than from the end, as
901 additional information may be added at the end.
904 The argument @var{time-value}, if given, specifies a time to format
905 instead of the current time. The argument should be a list whose first
906 two elements are integers. Thus, you can use times obtained from
907 @code{current-time} (see below) and from @code{file-attributes}
908 (@pxref{File Attributes}).
912 (current-time-string)
913 @result{} "Fri May 6 21:35:58 2005"
920 This function returns the system's time value as a list of three
921 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
922 @var{high} and @var{low} combine to give the number of seconds since
923 0:00 January 1, 1970, which is
925 @var{high} * 2^16 + @var{low}.
931 The third element, @var{microsec}, gives the microseconds since the
932 start of the current second or 0 for systems that return time only on
933 the resolution of a second.
935 The first two elements can be compared with file time values such as you
936 get with the function @code{file-attributes}. @xref{File Attributes}.
940 @defun current-time-zone &optional time-value
941 This function returns a list describing the time zone that the user is
944 The value has the form @code{(@var{offset} @var{name})}. Here
945 @var{offset} is an integer giving the number of seconds ahead of UTC
946 (east of Greenwich). A negative value means west of Greenwich. The
947 second element, @var{name} is a string giving the name of the time
948 zone. Both elements change when daylight savings time begins or ends;
949 if the user has specified a time zone that does not use a seasonal time
950 adjustment, then the value is constant through time.
952 If the operating system doesn't supply all the information necessary to
953 compute the value, both elements of the list are @code{nil}.
955 The argument @var{time-value}, if given, specifies a time to analyze
956 instead of the current time. The argument should be a cons cell
957 containing two integers, or a list whose first two elements are
958 integers. Thus, you can use times obtained from @code{current-time}
959 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
963 @node Time Conversion
964 @section Time Conversion
966 These functions convert time values (lists of two or three integers)
967 to strings or to calendrical information. There is also a function to
968 convert calendrical information to a time value. You can get time
969 values from the functions @code{current-time} (@pxref{Time of Day}) and
970 @code{file-attributes} (@pxref{File Attributes}).
972 @defun format-time-string format-string &optional time
973 This function converts @var{time} to a string according to
974 @var{format-string}. If @var{time} is omitted, it defaults to the
975 current time. The argument @var{format-string} may contain
976 @samp{%}-sequences which say to substitute parts of the time. Here is a
977 table of what the @samp{%}-sequences mean:
981 This stands for the abbreviated name of the day of week.
983 This stands for the full name of the day of week.
985 This stands for the abbreviated name of the month.
987 This stands for the full name of the month.
989 This is a synonym for @samp{%x %X}.
991 This has a locale-specific meaning. In the default locale (named C), it
992 is equivalent to @samp{%A, %B %e, %Y}.
994 This stands for the day of month, zero-padded.
996 This is a synonym for @samp{%m/%d/%y}.
998 This stands for the day of month, blank-padded.
1000 This is a synonym for @samp{%b}.
1002 This stands for the hour (00-23).
1004 This stands for the hour (00-12).
1006 This stands for the day of the year (001-366).
1008 This stands for the hour (0-23), blank padded.
1010 This stands for the hour (1-12), blank padded.
1012 This stands for the month (01-12).
1014 This stands for the minute (00-59).
1016 This stands for a newline.
1018 This stands for @samp{AM} or @samp{PM}, as appropriate.
1020 This is a synonym for @samp{%I:%M:%S %p}.
1022 This is a synonym for @samp{%H:%M}.
1024 This stands for the seconds (00-60).
1026 This stands for a tab character.
1028 This is a synonym for @samp{%H:%M:%S}.
1030 This stands for the week of the year (01-52), assuming that weeks
1033 This stands for the numeric day of week (0-6). Sunday is day 0.
1035 This stands for the week of the year (01-52), assuming that weeks
1038 This has a locale-specific meaning. In the default locale (named C), it
1039 is equivalent to @samp{%D}.
1041 This has a locale-specific meaning. In the default locale (named C), it
1042 is equivalent to @samp{%T}.
1044 This stands for the year without century (00-99).
1046 This stands for the year with century.
1048 This stands for the time zone abbreviation.
1052 @defun decode-time &optional specified-time
1053 This function converts a time value into calendrical information. The
1054 optional @var{specified-time} should be a list of
1055 (@var{high} @var{low} . @var{ignored}) or (@var{high} . @var{low}), as from
1056 @code{current-time} and @code{file-attributes}, or @code{nil} to use the
1059 The return value is a list of nine elements, as follows:
1062 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1065 Here is what the elements mean:
1069 The number of seconds past the minute, as an integer between 0 and 59.
1071 The number of minutes past the hour, as an integer between 0 and 59.
1073 The hour of the day, as an integer between 0 and 23.
1075 The day of the month, as an integer between 1 and 31.
1077 The month of the year, as an integer between 1 and 12.
1079 The year, an integer typically greater than 1900.
1081 The day of week, as an integer between 0 and 6, where 0 stands for
1084 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1086 An integer indicating the time zone, as the number of seconds east of
1090 Note: Common Lisp has different meanings for @var{dow} and
1094 @defun encode-time seconds minutes hour day month year &optional zone
1095 This function is the inverse of @code{decode-time}. It converts seven
1096 items of calendrical data into a time value. For the meanings of the
1097 arguments, see the table above under @code{decode-time}.
1099 Year numbers less than 100 are treated just like other year numbers. If
1100 you want them to stand for years above 1900, you must alter them yourself
1101 before you call @code{encode-time}.
1103 The optional argument @var{zone} defaults to the current time zone and
1104 its daylight savings time rules. If specified, it can be either a list
1105 (as you would get from @code{current-time-zone}) or an integer (as you
1106 would get from @code{decode-time}). The specified zone is used without
1107 any further alteration for daylight savings time.
1112 @section Timers for Delayed Execution
1114 You can set up a timer to call a function at a specified future time.
1116 @c All different in FSF 19
1117 @defun add-timeout secs function object &optional resignal
1118 This function adds a timeout, to be signaled after the timeout period
1119 has elapsed. @var{secs} is a number of seconds, expressed as an integer
1120 or a float. @var{function} will be called after that many seconds have
1121 elapsed, with one argument, the given @var{object}. If the optional
1122 @var{resignal} argument is provided, then after this timeout expires,
1123 @code{add-timeout} will automatically be called again with
1124 @var{resignal} as the first argument.
1126 This function returns an object which is the @dfn{id} of this particular
1127 timeout. You can pass that object to @code{disable-timeout} to turn off
1128 the timeout before it has been signalled.
1130 The number of seconds may be expressed as a floating-point number, in which
1131 case some fractional part of a second will be used. Caveat: the usable
1132 timeout granularity will vary from system to system.
1134 Adding a timeout causes a timeout event to be returned by
1135 @code{next-event}, and the function will be invoked by
1136 @code{dispatch-event}, so if SXEmacs is in a tight loop, the function will
1137 not be invoked until the next call to sit-for or until the return to
1138 top-level (the same is true of process filters).
1140 WARNING: if you are thinking of calling add-timeout from inside of a
1141 callback function as a way of resignalling a timeout, think again. There
1142 is a race condition. That's why the @var{resignal} argument exists.
1144 NOTE: In FSF Emacs, this function is called @code{run-at-time} and
1145 has different semantics.
1148 @defun disable-timeout id
1149 Cancel the requested action for @var{id}, which should be a value
1150 previously returned by @code{add-timeout}. This cancels the effect of
1151 that call to @code{add-timeout}; the arrival of the specified time will
1152 not cause anything special to happen.
1154 NOTE: In FSF Emacs, this function is called @code{cancel-timer}.
1158 @node Terminal Input
1159 @section Terminal Input
1160 @cindex terminal input
1162 This section describes functions and variables for recording or
1163 manipulating terminal input. See @ref{Display}, for related
1167 * Input Modes:: Options for how input is processed.
1168 * Translating Input:: Low level conversion of some characters or events
1170 * Recording Input:: Saving histories of recent or all input events.
1175 @subsection Input Modes
1177 @cindex terminal input modes
1179 @defun set-input-mode interrupt flow meta &optional quit-char console
1180 This function sets the mode for reading keyboard input. If
1181 @var{interrupt} is non-null, then SXEmacs uses input interrupts. If it is
1182 @code{nil}, then it uses @sc{cbreak} mode. When SXEmacs communicates
1183 directly with X, it ignores this argument and uses interrupts if that is
1184 the way it knows how to communicate.
1186 If @var{flow} is non-@code{nil}, then SXEmacs uses @sc{xon/xoff} (@kbd{C-q},
1187 @kbd{C-s}) flow control for output to the terminal. This has no effect except
1188 in @sc{cbreak} mode. @xref{Flow Control}.
1190 The default setting is system dependent. Some systems always use
1191 @sc{cbreak} mode regardless of what is specified.
1194 The argument @var{meta} controls support for input character codes
1195 above 127. If @var{meta} is @code{t}, SXEmacs converts characters with
1196 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1197 SXEmacs disregards the 8th bit; this is necessary when the terminal uses
1198 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1199 SXEmacs uses all 8 bits of input unchanged. This is good for terminals
1200 using European 8-bit character sets.
1203 If @var{quit-char} is non-@code{nil}, it specifies the character to
1204 use for quitting. Normally this character is @kbd{C-g}.
1208 The @code{current-input-mode} function returns the input mode settings
1209 SXEmacs is currently using.
1212 @defun current-input-mode &optional console
1213 This function returns current mode for reading keyboard input. It
1214 returns a list, corresponding to the arguments of @code{set-input-mode},
1215 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1219 is non-@code{nil} when SXEmacs is using interrupt-driven input. If
1220 @code{nil}, SXEmacs is using @sc{cbreak} mode.
1222 is non-@code{nil} if SXEmacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1223 flow control for output to the terminal. This value has no effect
1224 unless @var{interrupt} is non-@code{nil}.
1226 is @code{t} if SXEmacs treats the eighth bit of input characters as
1227 the meta bit; @code{nil} means SXEmacs clears the eighth bit of every
1228 input character; any other value means SXEmacs uses all eight bits as
1229 the basic character code.
1231 is the character SXEmacs currently uses for quitting, usually @kbd{C-g}.
1236 @node Translating Input
1237 @subsection Translating Input Events
1238 @cindex translating input events
1240 This section describes features for translating input events into other
1241 input events before they become part of key sequences.
1243 @ignore Not in SXEmacs yet.
1245 @defvar extra-keyboard-modifiers
1246 This variable lets Lisp programs ``press'' the modifier keys on the
1247 keyboard. The value is a bit mask:
1251 The @key{SHIFT} key.
1260 Each time the user types a keyboard key, it is altered as if the
1261 modifier keys specified in the bit mask were held down.
1263 When using X windows, the program can ``press'' any of the modifier
1264 keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
1265 be virtually pressed.
1269 @defvar keyboard-translate-table
1270 This variable is the translate table for keyboard characters. It lets
1271 you reshuffle the keys on the keyboard without changing any command
1272 bindings. Its value must be a string or @code{nil}.
1274 If @code{keyboard-translate-table} is a string, then each character read
1275 from the keyboard is looked up in this string and the character in the
1276 string is used instead. If the string is of length @var{n}, character codes
1277 @var{n} and up are untranslated.
1279 In the example below, we set @code{keyboard-translate-table} to a
1280 string of 128 characters. Then we fill it in to swap the characters
1281 @kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.
1282 Subsequently, typing @kbd{C-\} has all the usual effects of typing
1283 @kbd{C-s}, and vice versa. @xref{Flow Control}.
1285 @cindex flow control example
1288 (defun evade-flow-control ()
1289 "Replace C-s with C-\ and C-q with C-^."
1293 (let ((the-table (make-string 128 0)))
1296 (aset the-table i i)
1299 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1300 (aset the-table ?\034 ?\^s)
1301 (aset the-table ?\^s ?\034)
1303 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1304 (aset the-table ?\036 ?\^q)
1305 (aset the-table ?\^q ?\036)
1306 (setq keyboard-translate-table the-table)))
1310 Note: This translation is the first thing that happens to a
1311 character after it is read from the terminal. Record-keeping features
1312 such as @code{recent-keys} and dribble files record the characters after
1316 @defun keyboard-translate &rest pairs
1317 This function modifies @code{keyboard-translate-table} to translate
1318 character code @var{from} into character code @var{to}. It creates
1319 or enlarges the translate table if necessary. Multiple
1320 @var{from}-@var{to} pairs may be specified.
1323 @defvar function-key-map
1324 This variable holds a keymap that describes the character sequences
1325 sent by function keys on an ordinary character terminal. This keymap
1326 uses the same data structure as other keymaps, but is used differently: it
1327 specifies translations to make while reading events.
1329 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1330 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1331 key sequence, it is replaced with the events in @var{v}.
1333 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1334 keypad PF1 key is pressed. Therefore, we want SXEmacs to translate
1335 that sequence of events into the single event @code{pf1}. We accomplish
1336 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1337 @code{function-key-map}, when using a VT100.
1339 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1340 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1341 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1344 Entries in @code{function-key-map} are ignored if they conflict with
1345 bindings made in the minor mode, local, or global keymaps. The intent
1346 is that the character sequences that function keys send should not have
1347 command bindings in their own right.
1349 The value of @code{function-key-map} is usually set up automatically
1350 according to the terminal's Terminfo or Termcap entry, but sometimes
1351 those need help from terminal-specific Lisp files. SXEmacs comes with
1352 terminal-specific files for many common terminals; their main purpose is
1353 to make entries in @code{function-key-map} beyond those that can be
1354 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1356 Note: Emacs versions 18 and earlier used totally different means of
1357 detecting the character sequences that represent function keys.
1360 @defvar key-translation-map
1361 This variable is another keymap used just like @code{function-key-map}
1362 to translate input events into other events. It differs from
1363 @code{function-key-map} in two ways:
1367 @code{key-translation-map} goes to work after @code{function-key-map} is
1368 finished; it receives the results of translation by
1369 @code{function-key-map}.
1372 @code{key-translation-map} overrides actual key bindings.
1375 The intent of @code{key-translation-map} is for users to map one
1376 character set to another, including ordinary characters normally bound
1377 to @code{self-insert-command}.
1380 @cindex key translation function
1381 You can use @code{function-key-map} or @code{key-translation-map} for
1382 more than simple aliases, by using a function, instead of a key
1383 sequence, as the ``translation'' of a key. Then this function is called
1384 to compute the translation of that key.
1386 The key translation function receives one argument, which is the prompt
1387 that was specified in @code{read-key-sequence}---or @code{nil} if the
1388 key sequence is being read by the editor command loop. In most cases
1389 you can ignore the prompt value.
1391 If the function reads input itself, it can have the effect of altering
1392 the event that follows. For example, here's how to define @kbd{C-c h}
1393 to turn the character that follows into a Hyper character:
1397 (defun hyperify (prompt)
1398 (let ((e (read-event)))
1399 (vector (if (numberp e)
1400 (logior (lsh 1 20) e)
1401 (if (memq 'hyper (event-modifiers e))
1403 (add-event-modifier "H-" e))))))
1405 (defun add-event-modifier (string e)
1406 (let ((symbol (if (symbolp e) e (car e))))
1407 (setq symbol (intern (concat string
1408 (symbol-name symbol))))
1413 (cons symbol (cdr e)))))
1415 (define-key function-key-map "\C-ch" 'hyperify)
1420 @cindex Latin-1 character set (input)
1421 @cindex ISO Latin-1 characters (input)
1422 The @file{iso-transl} library uses this feature to provide a way of
1423 inputting non-ASCII Latin-1 characters.
1426 @node Recording Input
1427 @subsection Recording Input
1429 @defun recent-keys &optional number
1430 This function returns a vector containing recent input events from the
1431 keyboard or mouse. By default, 100 events are recorded, which is how
1432 many @code{recent-keys} returns.
1434 All input events are included, whether or not they were used as parts of
1435 key sequences. Thus, you always get the last 100 inputs, not counting
1436 keyboard macros. Events from keyboard macros are excluded because they
1437 are less interesting for debugging; it should be enough to see the
1438 events that invoked the macros.
1440 If @var{number} is specified, not more than @var{number} events will be
1441 returned. You may change the number of stored events using
1442 @code{set-recent-keys-ring-size}.
1445 @defun recent-keys-ring-size
1446 This function returns the number of recent events stored internally.
1447 This is also the maximum number of events @code{recent-keys} can
1448 return. By default, 100 events are stored.
1451 @defun set-recent-keys-ring-size size
1452 This function changes the number of events stored by SXEmacs and returned
1453 by @code{recent-keys}.
1455 For example, @code{(set-recent-keys-ring-size 250)} will make SXEmacs
1456 remember last 250 events and will make @code{recent-keys} return last
1457 250 events by default.
1460 @deffn Command open-dribble-file filename
1461 @cindex dribble file
1462 This function opens a @dfn{dribble file} named @var{filename}. When a
1463 dribble file is open, each input event from the keyboard or mouse (but
1464 not those from keyboard macros) is written in that file. A
1465 non-character event is expressed using its printed representation
1466 surrounded by @samp{<@dots{}>}.
1468 You close the dribble file by calling this function with an argument
1471 This function is normally used to record the input necessary to
1472 trigger an SXEmacs bug, for the sake of a bug report.
1476 (open-dribble-file "~/dribble")
1482 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1485 @node Terminal Output
1486 @section Terminal Output
1487 @cindex terminal output
1489 The terminal output functions send output to the terminal or keep
1490 track of output sent to the terminal. The function
1491 @code{device-baud-rate} tells you what SXEmacs thinks is the output speed
1494 @defun device-baud-rate &optional device
1495 This function's value is the output speed of the terminal associated
1496 with @var{device}, as far as SXEmacs knows. @var{device} defaults to the
1497 selected device (usually the only device) if omitted.
1499 Changing this value does not change the speed of actual data
1500 transmission, but the value is used for calculations such as padding.
1501 This value has no effect for window-system devices.
1503 This is different in FSF Emacs, where the baud rate also affects
1504 decisions about whether to scroll part of the screen or repaint, even
1505 when using a window system.
1507 The value is measured in bits per second.
1510 SXEmacs attempts to automatically initialize the baud rate by querying
1511 the terminal. If you are running across a network, however, and
1512 different parts of the network work are at different baud rates, the
1513 value returned by SXEmacs may be different from the value used by your
1516 Some network protocols communicate the local terminal speed to the
1517 remote machine, so that SXEmacs and other programs can get the proper
1518 value, but others do not. If SXEmacs has the wrong value, it makes
1519 decisions that are less than optimal. To fix the problem, use
1520 @code{set-device-baud-rate}.
1522 @defun set-device-baud-rate device baud-rate
1523 This function sets the output speed of @var{device}. See
1524 @code{device-baud-rate}. @var{device} defaults to the selected device
1525 (usually the only device) if @code{nil}.
1528 @defun send-string-to-terminal char-or-string &optional stdout-p device
1529 This function sends @var{char-or-string} to the terminal without
1530 alteration. Control characters in @var{char-or-string} have
1531 terminal-dependent effects.
1533 If @var{device} is @code{nil}, this function writes to SXEmacs's
1534 stderr, or to stdout if @var{stdout-p} is non-@code{nil}. Otherwise,
1535 @var{device} should be a tty or stream device, and the function writes
1536 to the device's normal or error output, according to @var{stdout-p}.
1538 One use of this function is to define function keys on terminals that
1539 have downloadable function key definitions. For example, this is how on
1540 certain terminals to define function key 4 to move forward four
1541 characters by transmitting the characters @kbd{C-u C-f} to the
1546 (send-string-to-terminal "\eF4\^U\^F")
1552 @deffn Command open-termscript filename
1553 @cindex termscript file
1554 This function is used to open a @dfn{termscript file} that will record
1555 all the characters sent by SXEmacs to the terminal. If there are
1556 multiple tty or stream devices, all characters sent to all such devices
1559 The function returns @code{nil}. Termscript files are useful for
1560 investigating problems where SXEmacs garbles the screen, problems that
1561 are due to incorrect Termcap entries or to undesirable settings of
1562 terminal options more often than to actual SXEmacs bugs.
1564 Once you are certain which characters were actually output, you can
1565 determine reliably whether they correspond to the Termcap specifications
1568 A @code{nil} value for @var{filename} stops recording terminal output.
1570 See also @code{open-dribble-file} in @ref{Terminal Input}.
1574 (open-termscript "../junk/termscript")
1580 @ignore Not in SXEmacs
1581 @node Special Keysyms
1582 @section System-Specific X11 Keysyms
1584 To define system-specific X11 keysyms, set the variable
1585 @code{system-key-alist}.
1587 @defvar system-key-alist
1588 This variable's value should be an alist with one element for each
1589 system-specific keysym. An element has this form: @code{(@var{code}
1590 . @var{symbol})}, where @var{code} is the numeric keysym code (not
1591 including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
1592 name for the function key.
1594 For example @code{(168 . mute-acute)} defines a system-specific key used
1595 by HP X servers whose numeric code is (1 << 28) + 168.
1597 It is not a problem if the alist defines keysyms for other X servers, as
1598 long as they don't conflict with the ones used by the X server actually
1601 The variable is always local to the current X terminal and cannot be
1602 buffer-local. @xref{Multiple Displays}.
1608 @section Flow Control
1609 @cindex flow control characters
1611 This section attempts to answer the question ``Why does SXEmacs choose
1612 to use flow-control characters in its command character set?'' For a
1613 second view on this issue, read the comments on flow control in the
1614 @file{sxemacs/INSTALL} file from the distribution; for help with Termcap
1615 entries and DEC terminal concentrators, see @file{sxemacs/etc/TERMS}.
1619 At one time, most terminals did not need flow control, and none used
1620 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1621 @kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
1623 XEmacs, for economy of keystrokes and portability, used nearly all the
1624 @sc{ascii} control characters, with mnemonic meanings when possible;
1625 thus, @kbd{C-s} for search and @kbd{C-q} for quote.
1627 Later, some terminals were introduced which required these characters
1628 for flow control. They were not very good terminals for full-screen
1629 editing, so XEmacs maintainers did not pay attention. In later years,
1630 flow control with @kbd{C-s} and @kbd{C-q} became widespread among
1631 terminals, but by this time it was usually an option. And the majority
1632 of users, who can turn flow control off, were unwilling to switch to
1633 less mnemonic key bindings for the sake of flow control.
1635 So which usage is ``right'', XEmacs's or that of some terminal and
1636 concentrator manufacturers? This question has no simple answer.
1638 One reason why we are reluctant to cater to the problems caused by
1639 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1640 techniques (albeit less common in practice) for flow control that
1641 preserve transparency of the character stream.
1643 Note also that their use for flow control is not an official standard.
1644 Interestingly, on the model 33 teletype with a paper tape punch (which
1645 is very old), @kbd{C-s} and @kbd{C-q} were sent by the computer to turn
1646 the punch on and off!
1648 As X servers and other window systems replace character-only
1649 terminals, this problem is gradually being cured. For the mean time,
1650 (S)XEmacs provides a convenient way of enabling flow control if you want
1652 call the function @code{enable-flow-control}.
1654 @deffn Command enable-flow-control &optional argument
1655 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1656 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1657 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1659 With optional argument @var{argument} (interactively the prefix
1660 argument), enable flow control mode if @var{argument} is positive; else
1664 You can use the function @code{enable-flow-control-on} in your
1665 @file{init.el} file to enable flow control automatically on certain
1668 @defun enable-flow-control-on &rest termtypes
1669 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1670 if the terminal type is one of @var{termtypes}. For example:
1673 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1677 Here is how @code{enable-flow-control} does its job:
1682 It sets @sc{cbreak} mode for terminal input, and tells the operating
1683 system to handle flow control, with @code{(set-input-mode nil t)}.
1686 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1687 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1688 lowest level, SXEmacs never knows that the characters typed were anything
1689 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1690 and @kbd{C-^} even when they are input for other commands.
1691 @xref{Translating Input}.
1694 If the terminal is the source of the flow control characters, then once
1695 you enable kernel flow control handling, you probably can do with
1696 less padding than normal for that terminal. You can reduce the amount
1697 of padding by customizing the Termcap entry. You can also reduce it by
1698 setting @code{baud-rate} to a smaller value so that SXEmacs uses a
1699 smaller speed when calculating the padding needed.
1700 @xref{Terminal Output}.
1706 @cindex noninteractive use
1708 The command line option @samp{-batch} causes SXEmacs to run
1709 noninteractively. In this mode, SXEmacs does not read commands from the
1710 terminal, it does not alter the terminal modes, and it does not expect
1711 to be outputting to an erasable screen. The idea is that you specify
1712 Lisp programs to run; when they are finished, SXEmacs should exit. The
1713 way to specify the programs to run is with @samp{-l @var{file}}, which
1714 loads the library named @var{file}, and @samp{-f @var{function}}, which
1715 calls @var{function} with no arguments.
1717 Any Lisp program output that would normally go to the echo area,
1718 either using @code{message} or using @code{prin1}, etc., with @code{t}
1719 as the stream, goes instead to SXEmacs's standard error descriptor when
1720 in batch mode. Thus, SXEmacs behaves much like a noninteractive
1721 application program. The echo area output that SXEmacs itself normally
1722 generates, such as command echoing, is suppressed entirely.
1724 @defun noninteractive
1725 This function returns non-@code{nil} when SXEmacs is running in batch
1729 @defvar noninteractive
1730 This variable is non-@code{nil} when SXEmacs is running in batch mode.
1731 Setting this variable to @code{nil}, however, will not change whether
1732 SXEmacs is running in batch mode, and will not change the return value
1733 of the @code{noninteractive} function.