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 @c * Special Keysyms:: Defining system-specific key symbols for X windows.
38 @node Starting Up, Getting Out, System Interface, System Interface
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, Init File, Starting Up, Starting Up
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{$XDG_CONFIG_HOME/sxemacs/init.el} unless
86 @samp{-q} was specified on the command line. This is not done in
87 @samp{-batch} mode, though. The @samp{-u} option can specify the
88 user name whose @file{init.el} should be loaded instead@footnote{Note
89 that file and directory permissions may very well hamper the use of
92 If the environment variable, @var{XDG_CONFIG_HOME}, is not set,
93 SXEmacs will try @file{~/.config/sxemacs}, and if that directory
94 does not exist, try @file{~/.sxemacs}.
95 @cindex @file{init.el}
98 It loads the library @file{default} unless @code{inhibit-default-init}
99 is non-@code{nil}. This is not done in @samp{-batch} mode or if
100 @samp{-q} was specified on the command line. The library's file name
101 is usually @file{default.el}.
102 @cindex @file{default.el}
105 It runs the normal hook @code{after-init-hook}.
108 It sets the major mode according to @code{initial-major-mode}, provided
109 the buffer @samp{*scratch*} is still current and still in Fundamental
113 It loads the terminal-specific Lisp file, if any, except when in batch
114 mode or using a window system.
117 It displays the initial echo area message, unless you have suppressed
118 that with @code{inhibit-startup-echo-area-message}.
121 It processes the action arguments from the command line.
124 It runs @code{term-setup-hook}.
127 It calls @code{frame-notice-user-settings}, which modifies the
128 parameters of the selected frame according to whatever the init files
132 It runs @code{window-setup-hook}. @xref{Terminal-Specific}.
135 It calls the command @code{sxemacs-splash-buffer} which displays
136 copyleft, nonwarranty, and basic use information, provided there were no
137 remaining command line arguments (a few steps above) and the value of
138 @code{inhibit-startup-message} is @code{nil}.
141 @defopt inhibit-startup-message
142 This variable inhibits the initial startup messages (the nonwarranty,
143 etc.). If it is non-@code{nil}, then the messages are not printed.
145 This variable exists so you can set it in your personal init file, once
146 you are familiar with the contents of the startup message.
148 Do not set this variable in the init file of a new user, or in a way
149 that affects more than one user, because that would prevent new users
150 from receiving the information they are supposed to see.
153 @defopt inhibit-startup-echo-area-message
154 This variable controls the display of the startup echo area message.
155 You can suppress the startup echo area message by adding text with this
156 form to your @file{init.el} file:
159 (setq inhibit-startup-echo-area-message
160 "@var{your-login-name}")
163 Simply setting @code{inhibit-startup-echo-area-message} to your login
164 name is not sufficient to inhibit the message; Emacs explicitly checks
165 whether @file{init.el} contains an expression as shown above. Your login
166 name must appear in the expression as a Lisp string constant.
168 This way, you can easily inhibit the message for yourself if you wish,
169 but thoughtless copying of your @file{init.el} file will not inhibit the
170 message for someone else.
174 @node Init File, Terminal-Specific, Start-up Summary, Starting Up
175 @subsection The Init File: @file{init.el}
177 @cindex @file{init.el}
179 When you start SXEmacs, it normally attempts to load the file
180 @file{init.el} from the directory set in @code{user-init-directory}.
181 This file, if it exists, must contain Lisp code. It is called your
182 @dfn{init file}. The command line switches @samp{-q} and @samp{-u}
183 affect the use of the init file; @samp{-q} says not to load an init
184 file, and @samp{-u} says to load a specified user's init file instead of
186 @xref{Entering SXEmacs,,,sxemacs, The SXEmacs User's Manual}.
188 @cindex init directory
189 @defvar user-init-directory
190 This variable contains the name of the directory where a user's init
191 files and customisations are stored. In the past, this was hard-coded
192 to @file{~/.sxemacs}, but today the default is normally
193 @file{$XDG_CONFIG_HOME/sxemacs}, or @file{~/.config/sxemacs} if the
194 environment variable, @var{XDG_CONFIG_HOME} is not set. If neither,
195 @file{$XDG_CONFIG_HOME/sxemacs}, nor @file{~/.config/sxemacs} exists,
196 and @file{~/.sxemacs} does exist, then @file{~/.sxemacs} will be used.
198 If no candidates for @code{user-init-directory} exist SXEmacs will
199 create a new directory at @file{$XDG_CONFIG_HOME/sxemacs}, or
200 @file{~/.config/sxemacs} if @var{XDG_CONFIG_HOME} is unset.
203 The location of the init directory can be overridden through one of
204 two methods@enddots{}
208 Using the @samp{-user-init-directory} command line option, which
209 allows the user to set the init directory to any location, providing
210 that file and directory permissions allow access.
212 Setting the environment variable, @var{SXE_USE_LEGACY}, which forces
213 SXEmacs to use the legacy init directory, @file{~/.sxemacs} regardless
214 of the existence of a @var{XDG_CONFIG_HOME} based init directory.
218 @cindex default init file
219 A site may have a @dfn{default init file}, which is the library named
220 @file{default.el}. SXEmacs finds the @file{default.el} file through the
221 standard search path for libraries (@pxref{How Programs Do Loading}).
222 The SXEmacs distribution does not come with this file; sites may provide
223 one for local customizations. If the default init file exists, it is
224 loaded whenever you start SXEmacs, except in batch mode or if @samp{-q} is
225 specified. But your own personal init file, if any, is loaded first; if
226 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
227 SXEmacs does not subsequently load the @file{default.el} file.
229 Another file for site-customization is @file{site-start.el}. SXEmacs
230 loads this @emph{before} the user's init file. You can inhibit the
231 loading of this file with the option @samp{-no-site-file}.
235 @defvar site-run-file
236 This variable specifies the site-customization file to load
237 before the user's init file. Its normal value is @code{"site-start"}.
241 If there is a great deal of code in your @file{init.el} file, you
242 should move it into another file named @file{@var{something}.el},
243 byte-compile it (@pxref{Byte Compilation}), and make your @file{init.el}
244 file load the other file using @code{load} (@pxref{Loading}).
246 @xref{Init File Examples,,, sxemacs, The SXEmacs User's Manual}, for
247 examples of how to make various commonly desired customizations in your
250 @defopt inhibit-default-init
251 This variable prevents SXEmacs from loading the default initialization
252 library file for your session of SXEmacs. If its value is non-@code{nil},
253 then the default library is not loaded. The default value is
257 @defvar before-init-hook
258 @defvarx after-init-hook
259 These two normal hooks are run just before, and just after, loading of
260 the user's init file, @file{default.el}, and/or @file{site-start.el}.
264 @node Terminal-Specific, Command Line Arguments, Init File, Starting Up
265 @subsection Terminal-Specific Initialization
266 @cindex terminal-specific initialization
268 Each terminal type can have its own Lisp library that SXEmacs loads
269 when run on that type of terminal. For a terminal type named
270 @var{termtype}, the library is called @file{term/@var{termtype}}.
271 SXEmacs finds the file by searching the @code{load-path} directories as
272 it does for other files, and trying the @samp{.elc} and @samp{.el}
273 suffixes. Normally, terminal-specific Lisp library is located in
274 @file{sxemacs/lisp/term}, a subdirectory of the @file{sxemacs/lisp}
275 directory in which most SXEmacs Lisp libraries are kept.@refill
277 The library's name is constructed by concatenating the value of the
278 variable @code{term-file-prefix} and the terminal type. Normally,
279 @code{term-file-prefix} has the value @code{"term/"}; changing this
282 The usual function of a terminal-specific library is to enable special
283 keys to send sequences that SXEmacs can recognize. It may also need to
284 set or add to @code{function-key-map} if the Termcap entry does not
285 specify all the terminal's function keys. @xref{Terminal Input}.
288 When the name of the terminal type contains a hyphen, only the part of
289 the name before the first hyphen is significant in choosing the library
290 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
291 the @file{term/aaa} library. If necessary, the library can evaluate
292 @code{(getenv "TERM")} to find the full name of the terminal
295 Your @file{init.el} file can prevent the loading of the
296 terminal-specific library by setting the variable
297 @code{term-file-prefix} to @code{nil}. This feature is useful when
298 experimenting with your own peculiar customizations.
300 You can also arrange to override some of the actions of the
301 terminal-specific library by setting the variable
302 @code{term-setup-hook}. This is a normal hook which SXEmacs runs using
303 @code{run-hooks} at the end of SXEmacs initialization, after loading both
304 your @file{init.el} file and any terminal-specific libraries. You can
305 use this variable to define initializations for terminals that do not
306 have their own libraries. @xref{Hooks}.
308 @defvar term-file-prefix
309 @cindex @code{TERM} environment variable
310 If the @code{term-file-prefix} variable is non-@code{nil}, SXEmacs loads
311 a terminal-specific initialization file as follows:
314 (load (concat term-file-prefix (getenv "TERM")))
318 You may set the @code{term-file-prefix} variable to @code{nil} in your
319 @file{init.el} file if you do not wish to load the
320 terminal-initialization file. To do this, put the following in
321 your @file{init.el} file: @code{(setq term-file-prefix nil)}.
324 @defvar term-setup-hook
325 This variable is a normal hook that SXEmacs runs after loading your
326 @file{init.el} file, the default initialization file (if any) and the
327 terminal-specific Lisp file.
329 You can use @code{term-setup-hook} to override the definitions made by a
330 terminal-specific file.
333 @defvar window-setup-hook
334 This variable is a normal hook which SXEmacs runs after loading your
335 @file{init.el} file and the default initialization file (if any), after
336 loading terminal-specific Lisp code, and after running the hook
337 @code{term-setup-hook}.
341 @node Command Line Arguments, , Terminal-Specific, Starting Up
342 @subsection Command Line Arguments
343 @cindex command line arguments
345 You can use command line arguments to request various actions when you
346 start SXEmacs. Since you do not need to start SXEmacs more than once per
347 day, and will often leave your SXEmacs session running longer than that,
348 command line arguments are hardly ever used. As a practical matter, it
349 is best to avoid making the habit of using them, since this habit would
350 encourage you to kill and restart SXEmacs unnecessarily often. These
351 options exist for two reasons: to be compatible with other editors (for
352 invocation by other programs) and to enable shell scripts to run
353 specific Lisp programs.
355 This section describes how SXEmacs processes command line arguments,
356 and how you can customize them.
358 Note: Some other editors require you to start afresh each time
359 you want to edit a file. With this kind of editor, you will probably
360 specify the file as a command line argument.
362 The recommended way to use SXEmacs is to start it only once, just after
363 you log in, and do all your editing in the same SXEmacs process. Each
364 time you want to edit a different file, you visit it with the existing
365 SXEmacs, which eventually comes to have many files in it ready for
366 editing. Usually you do not kill the SXEmacs until you are about to log
370 This function parses the command line that SXEmacs was called with,
371 processes it, loads the user's @file{init.el} file and displays the
375 @defvar command-line-processed
376 The value of this variable is @code{t} once the command line has been
379 If you redump SXEmacs by calling @code{dump-emacs}, you may wish to set
380 this variable to @code{nil} first in order to cause the new dumped
381 SXEmacs to process its new command line arguments.
384 @defvar command-switch-alist
385 @cindex switches on command line
386 @cindex options on command line
387 @cindex command line options
388 The value of this variable is an alist of user-defined command-line
389 options and associated handler functions. This variable exists so you
390 can add elements to it.
392 A @dfn{command line option} is an argument on the command line of the
399 The elements of the @code{command-switch-alist} look like this:
402 (@var{option} . @var{handler-function})
405 The @var{handler-function} is called to handle @var{option} and receives
406 the option name as its sole argument.
408 In some cases, the option is followed in the command line by an
409 argument. In these cases, the @var{handler-function} can find all the
410 remaining command-line arguments in the variable
411 @code{command-line-args-left}. The entire list of command-line
412 arguments is in @code{command-line-args}.
414 The command line arguments are parsed by the @code{command-line-1}
415 function in the @file{startup.el} file. See also @ref{Command
416 Switches, , Command Line Switches and Arguments, sxemacs, The SXEmacs
420 @defvar command-line-args
421 The value of this variable is the list of command line arguments passed
425 @defvar command-line-functions
426 This variable's value is a list of functions for handling an
427 unrecognized command-line argument. Each time the next argument to be
428 processed has no special meaning, the functions in this list are called,
429 in order of appearance, until one of them returns a non-@code{nil}
432 These functions are called with no arguments. They can access the
433 command-line argument under consideration through the variable
434 @code{argi}. The remaining arguments (not including the current one)
435 are in the variable @code{command-line-args-left}.
437 When a function recognizes and processes the argument in @code{argi}, it
438 should return a non-@code{nil} value to say it has dealt with that
439 argument. If it has also dealt with some of the following arguments, it
440 can indicate that by deleting them from @code{command-line-args-left}.
442 If all of these functions return @code{nil}, then the argument is used
443 as a file name to visit.
447 @node Getting Out, System Environment, Starting Up, System Interface
448 @section Getting out of SXEmacs
449 @cindex exiting SXEmacs
451 There are two ways to get out of SXEmacs: you can kill the SXEmacs job,
452 which exits permanently, or you can suspend it, which permits you to
453 reenter the SXEmacs process later. As a practical matter, you seldom kill
454 SXEmacs---only when you are about to log out. Suspending is much more
458 * Killing SXEmacs:: Exiting SXEmacs irreversibly.
459 * Suspending SXEmacs:: Exiting SXEmacs reversibly.
463 @node Killing SXEmacs, Suspending SXEmacs, Getting Out, Getting Out
464 @subsection Killing SXEmacs
465 @cindex killing SXEmacs
467 Killing SXEmacs means ending the execution of the SXEmacs process. The
468 parent process normally resumes control. The low-level primitive for
469 killing SXEmacs is @code{kill-emacs}.
471 @deffn Command kill-emacs &optional exit-data
472 This function exits the SXEmacs process and kills it.
474 If @var{exit-data} is an integer, then it is used as the exit status
475 of the SXEmacs process. This is useful primarily in batch operation; see
478 If @var{exit-data} is a string, its contents are stuffed into the
479 terminal input buffer so that the shell (or whatever program next reads
480 input) can read them.
483 All the information in the SXEmacs process, aside from files that have
484 been saved, is lost when the SXEmacs is killed. Because killing SXEmacs
485 inadvertently can lose a lot of work, SXEmacs queries for confirmation
486 before actually terminating if you have buffers that need saving or
487 subprocesses that are running. This is done in the function
488 @code{save-buffers-kill-emacs}.
490 @defvar kill-emacs-query-functions
491 After asking the standard questions, @code{save-buffers-kill-emacs}
492 calls the functions in the list @code{kill-buffer-query-functions}, in
493 order of appearance, with no arguments. These functions can ask for
494 additional confirmation from the user. If any of them returns
495 non-@code{nil}, SXEmacs is not killed.
498 @defvar kill-emacs-hook
499 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
500 finished with all file saving and confirmation, it runs the functions in
505 @node Suspending SXEmacs, , Killing SXEmacs, Getting Out
506 @subsection Suspending SXEmacs
507 @cindex suspending SXEmacs
509 @dfn{Suspending SXEmacs} means stopping SXEmacs temporarily and
510 returning control to its superior process, which is usually the shell.
511 This allows you to resume editing later in the same SXEmacs process,
512 with the same buffers, the same kill ring, the same undo history, and so
513 on. To resume SXEmacs, use the appropriate command in the parent
514 shell---most likely @code{fg}.
516 Some operating systems do not support suspension of jobs; on these
517 systems, ``suspension'' actually creates a new shell temporarily as a
518 subprocess of SXEmacs. Then you would exit the shell to return to
521 Suspension is not useful with window systems such as X, because the
522 SXEmacs job may not have a parent that can resume it again, and in any
523 case you can give input to some other job such as a shell merely by
524 moving to a different window. Nonetheless, you can use the
525 suspend-or-iconify feature in this case.
527 @deffn Command suspend-emacs &optional stuffstring
528 This function stops SXEmacs and returns control to the superior process.
529 If and when the superior process resumes SXEmacs, @code{suspend-emacs}
530 returns @code{nil} to its caller in Lisp.
532 If optional arg @var{stuffstring} is non-@code{nil}, its characters are
533 sent to be read as terminal input by SXEmacs's superior shell. The
534 characters in @var{stuffstring} are not echoed by the superior shell;
535 only the results appear.
537 Before suspending, @code{suspend-emacs} runs the normal hook
539 @ignore @c who cares?! -hrop
540 In Emacs version 18, @code{suspend-hook} was not
541 a normal hook; its value was a single function, and if its value was
542 non-@code{nil}, then @code{suspend-emacs} returned immediately without
543 actually suspending anything.
546 After the user resumes SXEmacs, @code{suspend-emacs} runs the normal
547 hook @code{suspend-resume-hook}. @xref{Hooks}.
549 The next redisplay after resumption will redraw the entire screen,
550 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
551 (@pxref{Refresh Screen}).
553 In the following example, note that @samp{pwd} is not echoed after
554 SXEmacs is suspended. But it is read and executed by the shell.
563 (add-hook 'suspend-hook
567 (error "Suspend cancelled")))))
568 @result{} (lambda nil
569 (or (y-or-n-p "Really suspend? ")
570 (error "Suspend cancelled")))
573 (add-hook 'suspend-resume-hook
574 (function (lambda () (message "Resumed!"))))
575 @result{} (lambda nil (message "Resumed!"))
578 (suspend-emacs "pwd")
582 ---------- Buffer: Minibuffer ----------
583 Really suspend? @kbd{y}
584 ---------- Buffer: Minibuffer ----------
588 ---------- Parent Shell ----------
589 lewis@@slug[23] % /user/lewis/manual
594 ---------- Echo Area ----------
601 This variable is a normal hook run before suspending.
604 @defvar suspend-resume-hook
605 This variable is a normal hook run after suspending.
609 @node System Environment, User Identification, Getting Out, System Interface
610 @section Operating System Environment
611 @cindex operating system environment
613 SXEmacs provides access to variables in the operating system
614 environment through various functions. These variables include the name
615 of the system, the user's @sc{uid}, and so on.
618 The value of this variable is a symbol indicating the type of operating
619 system SXEmacs is operating on. Here is a table of the possible values:
629 Data General DGUX operating system.
632 A GNU system using the GNU HURD and Mach.
635 Hewlett-Packard HPUX operating system.
638 Silicon Graphics Irix system.
641 A GNU system using the Linux kernel.
644 NeXT Mach-based system.
647 Masscomp RTU, UCB universe.
659 We do not wish to add new symbols to make finer distinctions unless it
660 is absolutely necessary! In fact, we hope to eliminate some of these
661 alternatives in the future. We recommend using
662 @code{system-configuration} to distinguish between different operating
666 @defvar system-configuration
667 This variable holds the three-part configuration name for the
668 hardware/software configuration of your system, as a string. The
669 convenient way to test parts of this string is with @code{string-match}.
673 This function returns the name of the machine you are running on.
676 @result{} "micky.math.tu-berlin.de"
681 @comment this seems not correct -hrop
683 The symbol @code{system-name} is a variable as well as a function. In
684 fact, the function returns whatever value the variable
685 @code{system-name} currently holds. Thus, you can set the variable
686 @code{system-name} in case Emacs is confused about the name of your
687 system. The variable is also useful for constructing frame titles
688 (@pxref{Frame Titles}).
691 @defvar mail-host-address
692 If this variable is non-@code{nil}, it is used instead of
693 @code{system-name} for purposes of generating email addresses. For
694 example, it is used when constructing the default value of
695 @code{user-mail-address}. @xref{User Identification}. Since this is
696 done when SXEmacs starts up, the value actually used is the one saved
697 when SXEmacs was dumped. @xref{Building SXEmacs}.
700 @deffn Command getenv var &optional interactivep
701 @cindex environment variable access
702 This function returns the value of the environment variable @var{var},
703 as a string. Within SXEmacs, the environment variable values are kept
704 in the Lisp variable @code{process-environment}.
706 When invoked interactively, @code{getenv} prints the value in the echo area.
715 lewis@@slug[10] % printenv
716 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
727 @deffn Command setenv variable &optional value unset
728 This command sets the value of the environment variable named
729 @var{variable} to @var{value}. Both arguments should be strings. This
730 function works by modifying @code{process-environment}; binding that
731 variable with @code{let} is also reasonable practice.
734 @defvar process-environment
735 This variable is a list of strings, each describing one environment
736 variable. The functions @code{getenv} and @code{setenv} work by
737 manipulating this variable.
742 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
743 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
754 @defvar path-separator
755 This variable holds a string which says which character separates
756 directories in a search path (as found in an environment variable). Its
757 value is @code{":"} for Unix and GNU systems.
760 @defvar invocation-name
761 This variable holds the program name under which SXEmacs was invoked.
762 The value is a string, and does not include a directory name.
765 @defvar invocation-directory
766 This variable holds the directory from which the SXEmacs executable was
767 invoked, or perhaps @code{nil} if that directory cannot be determined.
770 @ignore @c gah, void again :( -hrop
771 @defvar installation-directory
772 If non-@code{nil}, this is a directory within which to look for the
773 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
774 when Emacs can't find those directories in their standard installed
775 locations, but can find them in a directory related somehow to the one
776 containing the SXEmacs executable.
780 @defun load-average &optional use-floats
781 This function returns a list of the current 1-minute, 5-minute and
782 15-minute load averages. The values are integers that are 100 times the
783 system load averages. The load averages indicate the number of
784 processes trying to run.
786 When optional @var{use-floats} is non-@code{nil}, floats will be
787 returned instead of integers. These floats are not multiplied by 100.
792 @result{} (169 158 164)
794 @result{} (1.69921875 1.58984375 1.640625)
798 lewis@@rocky[5] % uptime
799 8:06pm up 16 day(s), 21:57, 40 users,
800 load average: 1.68, 1.59, 1.64
804 If the 5-minute or 15-minute load averages are not available, return a
805 shortened list, containing only those averages which are available.
807 On some systems, this function may require special privileges to run, or
808 it may be unimplemented for the particular system type. In that case,
809 the function will signal an error.
813 This function returns the process @sc{id} of the SXEmacs process.
817 @node User Identification, Time of Day, System Environment, System Interface
818 @section User Identification
820 @defvar user-mail-address
821 This holds the nominal email address of the user who is using SXEmacs.
822 When SXEmacs starts up, it computes a default value that is usually right,
823 but users often set this themselves when the default value is not right.
826 @defun user-login-name &optional uid
827 If you do not specify @var{uid}, this function returns the name under
828 which the user is logged in. If the environment variable @code{LOGNAME}
829 is set, that value is used. Otherwise, if the environment variable
830 @code{USER} is set, that value is used. Otherwise, the value is based
831 on the effective @sc{uid}, not the real @sc{uid}.
833 If you specify @var{uid}, the value is the user name that corresponds
834 to @var{uid} (which should be an integer).
844 @defun user-real-login-name
845 This function returns the user name corresponding to SXEmacs's real
846 @sc{uid}. This ignores the effective @sc{uid} and ignores the
847 environment variables @code{LOGNAME} and @code{USER}.
850 @defvar user-full-name
851 This variable holds the name of the user running this SXEmacs. It is
852 initialized at startup time from the value of @code{NAME} environment
853 variable. You can change the value of this variable to alter the result
854 of the @code{user-full-name} function.
857 @defun user-full-name &optional user
858 This function returns the full name of @var{user}. If @var{user} is
859 @code{nil}, it defaults to the user running this SXEmacs. In that case,
860 the value of @code{user-full-name} variable, if non-@code{nil}, will be
863 If @var{user} is specified explicitly, @code{user-full-name} variable is
869 @result{} "Hrvoje Niksic"
870 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
872 @result{} "Hrvoje \"Niksa\" Niksic"
873 (user-full-name "hniksic")
874 @result{} "Hrvoje Niksic"
879 @vindex user-full-name
880 @vindex user-real-login-name
881 @vindex user-login-name
882 The symbols @code{user-login-name}, @code{user-real-login-name} and
883 @code{user-full-name} are variables as well as functions. The functions
884 return the same values that the variables hold. These variables allow
885 you to ``fake out'' SXEmacs by telling the functions what to return. The
886 variables are also useful for constructing frame titles (@pxref{Frame
890 This function returns the real @sc{uid} of the user.
901 This function returns the effective @sc{uid} of the user.
904 @defun user-home-directory
905 This function returns the ``@code{HOME}'' directory of the user, and is
906 intended to replace occurrences of ``@code{(getenv "HOME")}''. Under
907 Unix systems, the following is done:
911 Return the value of ``@code{(getenv "HOME")}'', if set.
914 Return ``/'', as a fallback, but issue a warning. Future versions of
915 SXEmacs will also attempt to lookup the @code{HOME} directory via
916 @code{getpwent()}, but this has not yet been implemented.
921 @node Time of Day, Time Conversion, User Identification, System Interface
924 This section explains how to determine the current time and the time
927 @defun current-time-string &optional time-value
928 This function returns the current time and date as a humanly-readable
929 string. The format of the string is unvarying; the number of characters
930 used for each part is always the same, so you can reliably use
931 @code{substring} to extract pieces of it. It is wise to count the
932 characters from the beginning of the string rather than from the end, as
933 additional information may be added at the end.
936 The argument @var{time-value}, if given, specifies a time to format
937 instead of the current time. The argument should be a list whose first
938 two elements are integers. Thus, you can use times obtained from
939 @code{current-time} (see below) and from @code{file-attributes}
940 (@pxref{File Attributes}).
944 (current-time-string)
945 @result{} "Fri May 6 21:35:58 2005"
952 This function returns the system's time value as a list of three
953 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
954 @var{high} and @var{low} combine to give the number of seconds since
955 0:00 January 1, 1970, which is
957 @var{high} * 2^16 + @var{low}.
963 The third element, @var{microsec}, gives the microseconds since the
964 start of the current second or 0 for systems that return time only on
965 the resolution of a second.
967 The first two elements can be compared with file time values such as you
968 get with the function @code{file-attributes}. @xref{File Attributes}.
972 @defun current-time-zone &optional time-value
973 This function returns a list describing the time zone that the user is
976 The value has the form @code{(@var{offset} @var{name})}. Here
977 @var{offset} is an integer giving the number of seconds ahead of UTC
978 (east of Greenwich). A negative value means west of Greenwich. The
979 second element, @var{name} is a string giving the name of the time
980 zone. Both elements change when daylight savings time begins or ends;
981 if the user has specified a time zone that does not use a seasonal time
982 adjustment, then the value is constant through time.
984 If the operating system doesn't supply all the information necessary to
985 compute the value, both elements of the list are @code{nil}.
987 The argument @var{time-value}, if given, specifies a time to analyze
988 instead of the current time. The argument should be a cons cell
989 containing two integers, or a list whose first two elements are
990 integers. Thus, you can use times obtained from @code{current-time}
991 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
995 @node Time Conversion, Timers, Time of Day, System Interface
996 @section Time Conversion
998 These functions convert time values (lists of two or three integers)
999 to strings or to calendrical information. There is also a function to
1000 convert calendrical information to a time value. You can get time
1001 values from the functions @code{current-time} (@pxref{Time of Day}) and
1002 @code{file-attributes} (@pxref{File Attributes}).
1004 @defun format-time-string format-string &optional time
1005 This function converts @var{time} to a string according to
1006 @var{format-string}. If @var{time} is omitted, it defaults to the
1007 current time. The argument @var{format-string} may contain
1008 @samp{%}-sequences which say to substitute parts of the time. Here is a
1009 table of what the @samp{%}-sequences mean:
1013 This stands for the abbreviated name of the day of week.
1015 This stands for the full name of the day of week.
1017 This stands for the abbreviated name of the month.
1019 This stands for the full name of the month.
1021 This is a synonym for @samp{%x %X}.
1023 This has a locale-specific meaning. In the default locale (named C), it
1024 is equivalent to @samp{%A, %B %e, %Y}.
1026 This stands for the day of month, zero-padded.
1028 This is a synonym for @samp{%m/%d/%y}.
1030 This stands for the day of month, blank-padded.
1032 This is a synonym for @samp{%b}.
1034 This stands for the hour (00-23).
1036 This stands for the hour (00-12).
1038 This stands for the day of the year (001-366).
1040 This stands for the hour (0-23), blank padded.
1042 This stands for the hour (1-12), blank padded.
1044 This stands for the month (01-12).
1046 This stands for the minute (00-59).
1048 This stands for a newline.
1050 This stands for @samp{AM} or @samp{PM}, as appropriate.
1052 This is a synonym for @samp{%I:%M:%S %p}.
1054 This is a synonym for @samp{%H:%M}.
1056 This stands for the seconds (00-60).
1058 This stands for a tab character.
1060 This is a synonym for @samp{%H:%M:%S}.
1062 This stands for the week of the year (01-52), assuming that weeks
1065 This stands for the numeric day of week (0-6). Sunday is day 0.
1067 This stands for the week of the year (01-52), assuming that weeks
1070 This has a locale-specific meaning. In the default locale (named C), it
1071 is equivalent to @samp{%D}.
1073 This has a locale-specific meaning. In the default locale (named C), it
1074 is equivalent to @samp{%T}.
1076 This stands for the year without century (00-99).
1078 This stands for the year with century.
1080 This stands for the time zone abbreviation.
1084 @defun decode-time &optional specified-time
1085 This function converts a time value into calendrical information. The
1086 optional @var{specified-time} should be a list of
1087 (@var{high} @var{low} . @var{ignored}) or (@var{high} . @var{low}), as from
1088 @code{current-time} and @code{file-attributes}, or @code{nil} to use the
1091 The return value is a list of nine elements, as follows:
1094 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1097 Here is what the elements mean:
1101 The number of seconds past the minute, as an integer between 0 and 59.
1103 The number of minutes past the hour, as an integer between 0 and 59.
1105 The hour of the day, as an integer between 0 and 23.
1107 The day of the month, as an integer between 1 and 31.
1109 The month of the year, as an integer between 1 and 12.
1111 The year, an integer typically greater than 1900.
1113 The day of week, as an integer between 0 and 6, where 0 stands for
1116 @code{t} if daylight savings time is effect, otherwise @code{nil}.
1118 An integer indicating the time zone, as the number of seconds east of
1122 Note: Common Lisp has different meanings for @var{dow} and
1126 @defun encode-time seconds minutes hour day month year &optional zone
1127 This function is the inverse of @code{decode-time}. It converts seven
1128 items of calendrical data into a time value. For the meanings of the
1129 arguments, see the table above under @code{decode-time}.
1131 Year numbers less than 100 are treated just like other year numbers. If
1132 you want them to stand for years above 1900, you must alter them yourself
1133 before you call @code{encode-time}.
1135 The optional argument @var{zone} defaults to the current time zone and
1136 its daylight savings time rules. If specified, it can be either a list
1137 (as you would get from @code{current-time-zone}) or an integer (as you
1138 would get from @code{decode-time}). The specified zone is used without
1139 any further alteration for daylight savings time.
1143 @node Timers, Terminal Input, Time Conversion, System Interface
1144 @section Timers for Delayed Execution
1146 You can set up a timer to call a function at a specified future time.
1148 @c All different in FSF 19
1149 @defun add-timeout secs function object &optional resignal
1150 This function adds a timeout, to be signaled after the timeout period
1151 has elapsed. @var{secs} is a number of seconds, expressed as an integer
1152 or a float. @var{function} will be called after that many seconds have
1153 elapsed, with one argument, the given @var{object}. If the optional
1154 @var{resignal} argument is provided, then after this timeout expires,
1155 @code{add-timeout} will automatically be called again with
1156 @var{resignal} as the first argument.
1158 This function returns an object which is the @dfn{id} of this particular
1159 timeout. You can pass that object to @code{disable-timeout} to turn off
1160 the timeout before it has been signalled.
1162 The number of seconds may be expressed as a floating-point number, in which
1163 case some fractional part of a second will be used. Caveat: the usable
1164 timeout granularity will vary from system to system.
1166 Adding a timeout causes a timeout event to be returned by
1167 @code{next-event}, and the function will be invoked by
1168 @code{dispatch-event}, so if SXEmacs is in a tight loop, the function will
1169 not be invoked until the next call to sit-for or until the return to
1170 top-level (the same is true of process filters).
1172 WARNING: if you are thinking of calling add-timeout from inside of a
1173 callback function as a way of resignalling a timeout, think again. There
1174 is a race condition. That's why the @var{resignal} argument exists.
1176 NOTE: In FSF Emacs, this function is called @code{run-at-time} and
1177 has different semantics.
1180 @defun disable-timeout id
1181 Cancel the requested action for @var{id}, which should be a value
1182 previously returned by @code{add-timeout}. This cancels the effect of
1183 that call to @code{add-timeout}; the arrival of the specified time will
1184 not cause anything special to happen.
1186 NOTE: In FSF Emacs, this function is called @code{cancel-timer}.
1190 @node Terminal Input, Terminal Output, Timers, System Interface
1191 @section Terminal Input
1192 @cindex terminal input
1194 This section describes functions and variables for recording or
1195 manipulating terminal input. See @ref{Display}, for related
1199 * Input Modes:: Options for how input is processed.
1200 * Translating Input:: Low level conversion of some characters or events
1202 * Recording Input:: Saving histories of recent or all input events.
1206 @node Input Modes, Translating Input, Terminal Input, Terminal Input
1207 @subsection Input Modes
1209 @cindex terminal input modes
1211 @defun set-input-mode interrupt flow meta &optional quit-char console
1212 This function sets the mode for reading keyboard input. If
1213 @var{interrupt} is non-null, then SXEmacs uses input interrupts. If it is
1214 @code{nil}, then it uses @sc{cbreak} mode. When SXEmacs communicates
1215 directly with X, it ignores this argument and uses interrupts if that is
1216 the way it knows how to communicate.
1218 If @var{flow} is non-@code{nil}, then SXEmacs uses @sc{xon/xoff} (@kbd{C-q},
1219 @kbd{C-s}) flow control for output to the terminal. This has no effect except
1220 in @sc{cbreak} mode. @xref{Flow Control}.
1222 The default setting is system dependent. Some systems always use
1223 @sc{cbreak} mode regardless of what is specified.
1226 The argument @var{meta} controls support for input character codes
1227 above 127. If @var{meta} is @code{t}, SXEmacs converts characters with
1228 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1229 SXEmacs disregards the 8th bit; this is necessary when the terminal uses
1230 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1231 SXEmacs uses all 8 bits of input unchanged. This is good for terminals
1232 using European 8-bit character sets.
1235 If @var{quit-char} is non-@code{nil}, it specifies the character to
1236 use for quitting. Normally this character is @kbd{C-g}.
1240 The @code{current-input-mode} function returns the input mode settings
1241 SXEmacs is currently using.
1244 @defun current-input-mode &optional console
1245 This function returns current mode for reading keyboard input. It
1246 returns a list, corresponding to the arguments of @code{set-input-mode},
1247 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1251 is non-@code{nil} when SXEmacs is using interrupt-driven input. If
1252 @code{nil}, SXEmacs is using @sc{cbreak} mode.
1254 is non-@code{nil} if SXEmacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1255 flow control for output to the terminal. This value has no effect
1256 unless @var{interrupt} is non-@code{nil}.
1258 is @code{t} if SXEmacs treats the eighth bit of input characters as
1259 the meta bit; @code{nil} means SXEmacs clears the eighth bit of every
1260 input character; any other value means SXEmacs uses all eight bits as
1261 the basic character code.
1263 is the character SXEmacs currently uses for quitting, usually @kbd{C-g}.
1268 @node Translating Input, Recording Input, Input Modes, Terminal Input
1269 @subsection Translating Input Events
1270 @cindex translating input events
1272 This section describes features for translating input events into other
1273 input events before they become part of key sequences.
1275 @ignore Not in SXEmacs yet.
1277 @defvar extra-keyboard-modifiers
1278 This variable lets Lisp programs ``press'' the modifier keys on the
1279 keyboard. The value is a bit mask:
1283 The @key{SHIFT} key.
1292 Each time the user types a keyboard key, it is altered as if the
1293 modifier keys specified in the bit mask were held down.
1295 When using X windows, the program can ``press'' any of the modifier
1296 keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
1297 be virtually pressed.
1301 @defvar keyboard-translate-table
1302 This variable is the translate table for keyboard characters. It lets
1303 you reshuffle the keys on the keyboard without changing any command
1304 bindings. Its value must be a string or @code{nil}.
1306 If @code{keyboard-translate-table} is a string, then each character read
1307 from the keyboard is looked up in this string and the character in the
1308 string is used instead. If the string is of length @var{n}, character codes
1309 @var{n} and up are untranslated.
1311 In the example below, we set @code{keyboard-translate-table} to a
1312 string of 128 characters. Then we fill it in to swap the characters
1313 @kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.
1314 Subsequently, typing @kbd{C-\} has all the usual effects of typing
1315 @kbd{C-s}, and vice versa. @xref{Flow Control}.
1317 @cindex flow control example
1320 (defun evade-flow-control ()
1321 "Replace C-s with C-\ and C-q with C-^."
1325 (let ((the-table (make-string 128 0)))
1328 (aset the-table i i)
1331 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
1332 (aset the-table ?\034 ?\^s)
1333 (aset the-table ?\^s ?\034)
1335 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
1336 (aset the-table ?\036 ?\^q)
1337 (aset the-table ?\^q ?\036)
1338 (setq keyboard-translate-table the-table)))
1342 Note: This translation is the first thing that happens to a
1343 character after it is read from the terminal. Record-keeping features
1344 such as @code{recent-keys} and dribble files record the characters after
1348 @defun keyboard-translate &rest pairs
1349 This function modifies @code{keyboard-translate-table} to translate
1350 character code @var{from} into character code @var{to}. It creates
1351 or enlarges the translate table if necessary. Multiple
1352 @var{from}-@var{to} pairs may be specified.
1355 @defvar function-key-map
1356 This variable holds a keymap that describes the character sequences
1357 sent by function keys on an ordinary character terminal. This keymap
1358 uses the same data structure as other keymaps, but is used differently: it
1359 specifies translations to make while reading events.
1361 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
1362 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
1363 key sequence, it is replaced with the events in @var{v}.
1365 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
1366 keypad PF1 key is pressed. Therefore, we want SXEmacs to translate
1367 that sequence of events into the single event @code{pf1}. We accomplish
1368 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
1369 @code{function-key-map}, when using a VT100.
1371 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
1372 @key{ESC} O P}; later the function @code{read-key-sequence} translates
1373 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
1376 Entries in @code{function-key-map} are ignored if they conflict with
1377 bindings made in the minor mode, local, or global keymaps. The intent
1378 is that the character sequences that function keys send should not have
1379 command bindings in their own right.
1381 The value of @code{function-key-map} is usually set up automatically
1382 according to the terminal's Terminfo or Termcap entry, but sometimes
1383 those need help from terminal-specific Lisp files. SXEmacs comes with
1384 terminal-specific files for many common terminals; their main purpose is
1385 to make entries in @code{function-key-map} beyond those that can be
1386 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
1388 Note: Emacs versions 18 and earlier used totally different means of
1389 detecting the character sequences that represent function keys.
1392 @defvar key-translation-map
1393 This variable is another keymap used just like @code{function-key-map}
1394 to translate input events into other events. It differs from
1395 @code{function-key-map} in two ways:
1399 @code{key-translation-map} goes to work after @code{function-key-map} is
1400 finished; it receives the results of translation by
1401 @code{function-key-map}.
1404 @code{key-translation-map} overrides actual key bindings.
1407 The intent of @code{key-translation-map} is for users to map one
1408 character set to another, including ordinary characters normally bound
1409 to @code{self-insert-command}.
1412 @cindex key translation function
1413 You can use @code{function-key-map} or @code{key-translation-map} for
1414 more than simple aliases, by using a function, instead of a key
1415 sequence, as the ``translation'' of a key. Then this function is called
1416 to compute the translation of that key.
1418 The key translation function receives one argument, which is the prompt
1419 that was specified in @code{read-key-sequence}---or @code{nil} if the
1420 key sequence is being read by the editor command loop. In most cases
1421 you can ignore the prompt value.
1423 If the function reads input itself, it can have the effect of altering
1424 the event that follows. For example, here's how to define @kbd{C-c h}
1425 to turn the character that follows into a Hyper character:
1429 (defun hyperify (prompt)
1430 (let ((e (read-event)))
1431 (vector (if (numberp e)
1432 (logior (lsh 1 20) e)
1433 (if (memq 'hyper (event-modifiers e))
1435 (add-event-modifier "H-" e))))))
1437 (defun add-event-modifier (string e)
1438 (let ((symbol (if (symbolp e) e (car e))))
1439 (setq symbol (intern (concat string
1440 (symbol-name symbol))))
1445 (cons symbol (cdr e)))))
1447 (define-key function-key-map "\C-ch" 'hyperify)
1452 @cindex Latin-1 character set (input)
1453 @cindex ISO Latin-1 characters (input)
1454 The @file{iso-transl} library uses this feature to provide a way of
1455 inputting non-ASCII Latin-1 characters.
1458 @node Recording Input, , Translating Input, Terminal Input
1459 @subsection Recording Input
1461 @defun recent-keys &optional number
1462 This function returns a vector containing recent input events from the
1463 keyboard or mouse. By default, 100 events are recorded, which is how
1464 many @code{recent-keys} returns.
1466 All input events are included, whether or not they were used as parts of
1467 key sequences. Thus, you always get the last 100 inputs, not counting
1468 keyboard macros. Events from keyboard macros are excluded because they
1469 are less interesting for debugging; it should be enough to see the
1470 events that invoked the macros.
1472 If @var{number} is specified, not more than @var{number} events will be
1473 returned. You may change the number of stored events using
1474 @code{set-recent-keys-ring-size}.
1477 @defun recent-keys-ring-size
1478 This function returns the number of recent events stored internally.
1479 This is also the maximum number of events @code{recent-keys} can
1480 return. By default, 100 events are stored.
1483 @defun set-recent-keys-ring-size size
1484 This function changes the number of events stored by SXEmacs and returned
1485 by @code{recent-keys}.
1487 For example, @code{(set-recent-keys-ring-size 250)} will make SXEmacs
1488 remember last 250 events and will make @code{recent-keys} return last
1489 250 events by default.
1492 @deffn Command open-dribble-file filename
1493 @cindex dribble file
1494 This function opens a @dfn{dribble file} named @var{filename}. When a
1495 dribble file is open, each input event from the keyboard or mouse (but
1496 not those from keyboard macros) is written in that file. A
1497 non-character event is expressed using its printed representation
1498 surrounded by @samp{<@dots{}>}.
1500 You close the dribble file by calling this function with an argument
1503 This function is normally used to record the input necessary to
1504 trigger an SXEmacs bug, for the sake of a bug report.
1508 (open-dribble-file "~/dribble")
1514 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1517 @node Terminal Output, Flow Control, Terminal Input, System Interface
1518 @section Terminal Output
1519 @cindex terminal output
1521 The terminal output functions send output to the terminal or keep
1522 track of output sent to the terminal. The function
1523 @code{device-baud-rate} tells you what SXEmacs thinks is the output speed
1526 @defun device-baud-rate &optional device
1527 This function's value is the output speed of the terminal associated
1528 with @var{device}, as far as SXEmacs knows. @var{device} defaults to the
1529 selected device (usually the only device) if omitted.
1531 Changing this value does not change the speed of actual data
1532 transmission, but the value is used for calculations such as padding.
1533 This value has no effect for window-system devices.
1535 This is different in FSF Emacs, where the baud rate also affects
1536 decisions about whether to scroll part of the screen or repaint, even
1537 when using a window system.
1539 The value is measured in bits per second.
1542 SXEmacs attempts to automatically initialize the baud rate by querying
1543 the terminal. If you are running across a network, however, and
1544 different parts of the network work are at different baud rates, the
1545 value returned by SXEmacs may be different from the value used by your
1548 Some network protocols communicate the local terminal speed to the
1549 remote machine, so that SXEmacs and other programs can get the proper
1550 value, but others do not. If SXEmacs has the wrong value, it makes
1551 decisions that are less than optimal. To fix the problem, use
1552 @code{set-device-baud-rate}.
1554 @defun set-device-baud-rate device baud-rate
1555 This function sets the output speed of @var{device}. See
1556 @code{device-baud-rate}. @var{device} defaults to the selected device
1557 (usually the only device) if @code{nil}.
1560 @defun send-string-to-terminal char-or-string &optional stdout-p device
1561 This function sends @var{char-or-string} to the terminal without
1562 alteration. Control characters in @var{char-or-string} have
1563 terminal-dependent effects.
1565 If @var{device} is @code{nil}, this function writes to SXEmacs's
1566 stderr, or to stdout if @var{stdout-p} is non-@code{nil}. Otherwise,
1567 @var{device} should be a tty or stream device, and the function writes
1568 to the device's normal or error output, according to @var{stdout-p}.
1570 One use of this function is to define function keys on terminals that
1571 have downloadable function key definitions. For example, this is how on
1572 certain terminals to define function key 4 to move forward four
1573 characters by transmitting the characters @kbd{C-u C-f} to the
1578 (send-string-to-terminal "\eF4\^U\^F")
1584 @deffn Command open-termscript filename
1585 @cindex termscript file
1586 This function is used to open a @dfn{termscript file} that will record
1587 all the characters sent by SXEmacs to the terminal. If there are
1588 multiple tty or stream devices, all characters sent to all such devices
1591 The function returns @code{nil}. Termscript files are useful for
1592 investigating problems where SXEmacs garbles the screen, problems that
1593 are due to incorrect Termcap entries or to undesirable settings of
1594 terminal options more often than to actual SXEmacs bugs.
1596 Once you are certain which characters were actually output, you can
1597 determine reliably whether they correspond to the Termcap specifications
1600 A @code{nil} value for @var{filename} stops recording terminal output.
1602 See also @code{open-dribble-file} in @ref{Terminal Input}.
1606 (open-termscript "../junk/termscript")
1612 @c @ignore Not in SXEmacs
1613 @c @node Special Keysyms, Flow Control, Terminal Output, System Interface
1614 @c @section System-Specific X11 Keysyms
1616 @c To define system-specific X11 keysyms, set the variable
1617 @c @code{system-key-alist}.
1619 @c @defvar system-key-alist
1620 @c This variable's value should be an alist with one element for each
1621 @c system-specific keysym. An element has this form: @code{(@var{code}
1622 @c . @var{symbol})}, where @var{code} is the numeric keysym code (not
1623 @c including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
1624 @c name for the function key.
1626 @c For example @code{(168 . mute-acute)} defines a system-specific key used
1627 @c by HP X servers whose numeric code is (1 << 28) + 168.
1629 @c It is not a problem if the alist defines keysyms for other X servers, as
1630 @c long as they don't conflict with the ones used by the X server actually
1633 @c The variable is always local to the current X terminal and cannot be
1634 @c buffer-local. @xref{Multiple Displays}.
1639 @node Flow Control, Batch Mode, Terminal Output, System Interface
1640 @section Flow Control
1641 @cindex flow control characters
1643 This section attempts to answer the question ``Why does SXEmacs choose
1644 to use flow-control characters in its command character set?'' For a
1645 second view on this issue, read the comments on flow control in the
1646 @file{sxemacs/INSTALL} file from the distribution; for help with Termcap
1647 entries and DEC terminal concentrators, see @file{sxemacs/etc/TERMS}.
1651 At one time, most terminals did not need flow control, and none used
1652 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
1653 @kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
1655 XEmacs, for economy of keystrokes and portability, used nearly all the
1656 @sc{ascii} control characters, with mnemonic meanings when possible;
1657 thus, @kbd{C-s} for search and @kbd{C-q} for quote.
1659 Later, some terminals were introduced which required these characters
1660 for flow control. They were not very good terminals for full-screen
1661 editing, so XEmacs maintainers did not pay attention. In later years,
1662 flow control with @kbd{C-s} and @kbd{C-q} became widespread among
1663 terminals, but by this time it was usually an option. And the majority
1664 of users, who can turn flow control off, were unwilling to switch to
1665 less mnemonic key bindings for the sake of flow control.
1667 So which usage is ``right'', XEmacs's or that of some terminal and
1668 concentrator manufacturers? This question has no simple answer.
1670 One reason why we are reluctant to cater to the problems caused by
1671 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
1672 techniques (albeit less common in practice) for flow control that
1673 preserve transparency of the character stream.
1675 Note also that their use for flow control is not an official standard.
1676 Interestingly, on the model 33 teletype with a paper tape punch (which
1677 is very old), @kbd{C-s} and @kbd{C-q} were sent by the computer to turn
1678 the punch on and off!
1680 As X servers and other window systems replace character-only
1681 terminals, this problem is gradually being cured. For the mean time,
1682 (S)XEmacs provides a convenient way of enabling flow control if you want
1684 call the function @code{enable-flow-control}.
1686 @deffn Command enable-flow-control &optional argument
1687 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
1688 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
1689 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
1691 With optional argument @var{argument} (interactively the prefix
1692 argument), enable flow control mode if @var{argument} is positive; else
1696 You can use the function @code{enable-flow-control-on} in your
1697 @file{init.el} file to enable flow control automatically on certain
1700 @defun enable-flow-control-on &rest termtypes
1701 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
1702 if the terminal type is one of @var{termtypes}. For example:
1705 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
1709 Here is how @code{enable-flow-control} does its job:
1714 It sets @sc{cbreak} mode for terminal input, and tells the operating
1715 system to handle flow control, with @code{(set-input-mode nil t)}.
1718 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
1719 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
1720 lowest level, SXEmacs never knows that the characters typed were anything
1721 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
1722 and @kbd{C-^} even when they are input for other commands.
1723 @xref{Translating Input}.
1726 If the terminal is the source of the flow control characters, then once
1727 you enable kernel flow control handling, you probably can do with
1728 less padding than normal for that terminal. You can reduce the amount
1729 of padding by customizing the Termcap entry. You can also reduce it by
1730 setting @code{baud-rate} to a smaller value so that SXEmacs uses a
1731 smaller speed when calculating the padding needed.
1732 @xref{Terminal Output}.
1735 @node Batch Mode, , Flow Control, System Interface
1738 @cindex noninteractive use
1740 The command line option @samp{-batch} causes SXEmacs to run
1741 noninteractively. In this mode, SXEmacs does not read commands from the
1742 terminal, it does not alter the terminal modes, and it does not expect
1743 to be outputting to an erasable screen. The idea is that you specify
1744 Lisp programs to run; when they are finished, SXEmacs should exit. The
1745 way to specify the programs to run is with @samp{-l @var{file}}, which
1746 loads the library named @var{file}, and @samp{-f @var{function}}, which
1747 calls @var{function} with no arguments.
1749 Any Lisp program output that would normally go to the echo area,
1750 either using @code{message} or using @code{prin1}, etc., with @code{t}
1751 as the stream, goes instead to SXEmacs's standard error descriptor when
1752 in batch mode. Thus, SXEmacs behaves much like a noninteractive
1753 application program. The echo area output that SXEmacs itself normally
1754 generates, such as command echoing, is suppressed entirely.
1756 @defun noninteractive
1757 This function returns non-@code{nil} when SXEmacs is running in batch
1761 @defvar noninteractive
1762 This variable is non-@code{nil} when SXEmacs is running in batch mode.
1763 Setting this variable to @code{nil}, however, will not change whether
1764 SXEmacs is running in batch mode, and will not change the return value
1765 of the @code{noninteractive} function.