Operating System Interface
**************************

This chapter is about starting and getting out of Emacs, access to values in the operating system environment, and terminal input, output and flow control.

See Building Emacs, for related information.  See also Emacs Display, for additional operating system status information which pertain to the terminal and the screen.

Starting Up Emacs
=================

This section describes what Emacs does when it is started, and how you can customize these actions.

Summary: Sequence of Actions at Start Up
----------------------------------------

The order of operations performed (in startup.el) by Emacs when it is started up is as follows:

 1. It loads .emacs unless -q was specified on command line. (This is not done in -batch mode.)  .emacs is found in the user's home directory; the -u option can specify the user name whose home directory should be used.

 2. It loads default.el unless inhibit-default-init is non-nil.  (This is not done in -batch mode or if -q was specified on command line.)

 3. It loads the terminal-specific Lisp file, if any, except when in batch mode.

 4. It runs term-setup-hook.

 5. It runs window-setup-hook.

 6. It displays copyleft and nonwarranty, plus basic use information, unless the value of inhibit-startup-message is non-nil.

     This display is also inhibited in batch mode, and if the current buffer is not *scratch*.

 7. It processes any remaining command line arguments.

 -- User Option: inhibit-startup-message
     This variable inhibits the initial startup messages (the nonwarranty, etc.).  If it is non-nil, then the messages are not printed.

     This variable exists so you can set it in your personal init file, once you are familiar with the contents of the startup message.  Do not set this variable in the init file of a new user, or in a way that affects more than one user, because that would prevent new users from receiving the information they are supposed to see.

The Init File: .emacs
---------------------

When you start Emacs, it normally attempts to load the file .emacs from your home directory.  This file, if it exists, must contain Lisp code.  It is called your init file.  The command line switches -q and -u can be used to control the use of the init file; -q says not to load an init file, and -u says to load a specified user's init file instead of yours.  See Entering Emacs (The GNU Emacs Manual).

Emacs may also have a default init file, which is the library named default.el.  Emacs finds the default.el file through the standard search path for libraries (see How Programs Do Loading).  The Emacs distribution does not have any such file; you may create one at your site for local customizations.  If the default init file exists, it is loaded whenever you start Emacs, except in batch mode or if -q is specified.  But your own personal init file, if any, is loaded first; if it sets inhibit-default-init to a non-nil value, then Emacs will not load the default.el file.

If there is a great deal of code in your .emacs file, you should move it into another file named SOMETHING.el, byte-compile it (see Byte Compilation), and make your .emacs file load the other file using load (see Loading).

See Init File Examples (The GNU Emacs Manual), for examples of how to make various commonly desired customizations in your .emacs file.

 -- User Option: inhibit-default-init
     This variable prevents Emacs from loading the default initialization library file for your session of Emacs.  If its value is non-nil, then the default library is not loaded.  The default value is nil.

Terminal-Specific Initialization
--------------------------------

Each terminal type can have its own Lisp library that Emacs will load when run on that type of terminal.  For a terminal type named TERMTYPE, the library is called term/TERMTYPE.  Emacs finds the file by searching the load-path directories as it does for other files, and trying the .elc and .el suffixes. Normally, terminal-specific Lisp library is located in emacs/lisp/term, a subdirectory of the emacs/lisp directory in which most Emacs Lisp libraries are kept.

The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type.  Normally, term-file-prefix has the value "term/"; changing this is not recommended.

The usual purpose of a terminal-specific library is to define the escape sequences used by a terminal's function keys.  See the file term/vt100.el for an example of a terminal-specific library.

Function keys are handled by a two-level procedure.  The first level is dependent on the specific type of terminal and maps Emacs's input sequences to the function keys that they represent.  The second level is independent of terminal type and is customized by users; function keys are mapped into meanings at this level.  The terminal-specific library handles the first level of the process and the library keypad.el handles the second level of mapping.

When the name of the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name.  Thus, terminal types aaa-48 and aaa-30-rv both use the term/aaa library.  If necessary, the library can evaluate (getenv "TERM") to find the full name of the terminal type.

Your .emacs file can prevent the loading of the terminal-specific library by setting term-file-prefix to nil.  This feature is very useful when experimenting with your own peculiar customizations.

You can also arrange to override some of the actions of the terminal-specific library by setting the variable term-setup-hook.  If it is not nil, Emacs calls the value of the variable term-setup-hook as a function of no arguments at the end of Emacs initialization, after Emacs has already loaded both your .emacs file and any terminal-specific libraries.  You can use this variable to define initializations for terminals that do not have their own libraries.

 -- Variable: term-file-prefix
     If the term-file-prefix variable is non-nil, Emacs loads a terminal-specific initialization file as follows:

          (load (concat term-file-prefix (getenv "TERM")))

     You may set the term-file-prefix variable to nil in your .emacs file if you do not wish to load the terminal-initialization file.  To do this, put the following in your .emacs file: (setq term-file-prefix nil).

 -- Variable: term-setup-hook
     The value of this variable is either nil or a function to be called by Emacs after loading your .emacs file, the default initialization file (if any) and after loading terminal-specific Lisp code.  The function is called with no arguments.

     You can use term-setup-hook to override the definitions made by a terminal-specific file.

See also window-setup-hook in Window Systems.

Command Line Arguments
----------------------

You can use command line arguments to request various actions when you start Emacs.  Since you do not need to start Emacs more than once per day, and will often leave your Emacs session running longer than that, command line arguments are hardly ever used.  As a practical matter, it is best to avoid making the habit of using them, since this habit would encourage you to kill and restart Emacs unnecessarily often.  These options exist for two reasons: to be compatible with other editors (for invocation by other programs) and to enable shell scripts to run specific Lisp programs.

 -- Function: command-line
     This function parses the command line which Emacs was called with, processes it, loads the user's .emacs file and displays the initial nonwarranty information, etc.

 -- Variable: command-line-processed
     The value of this variable is t once the command line has been processed.

     If you redump Emacs by calling dump-emacs, you must set this variable to nil first in order to cause the new dumped Emacs to process its new command line arguments.

 -- Variable: command-switch-alist
     The value of this variable is an alist of user-defined command-line options and associated handler functions.  This variable exists so you can add elements to it.

     A command line option is an argument on the command line of the form:

          -OPTION

     The elements of the command-switch-alist look like this:

          (OPTION . HANDLER-FUNCTION)

     For each element, the HANDLER-FUNCTION receives the switch name as its sole argument.

     In some cases, the option is followed in the command line by an argument.  In these cases, the HANDLER-FUNCTION can find all the remaining command-line arguments in the variable command-line-args-left.  (The entire list of command-line arguments is in command-line-args.)

     The command line arguments are parsed by the command-line-1 function in the startup.el file.  See also Command Line Switches and Arguments (The GNU Emacs Manual).

 -- Variable: command-line-args
     The value of this variable is the arguments passed by the shell to Emacs, as a list of strings.

Getting out of Emacs
====================

There are two ways to get out of Emacs: you can kill the Emacs job, which exits permanently, or you can suspend it, which permits you to reenter the Emacs process later.  As a practical matter, you seldom kill Emacs---only when you are about to log out.  Suspending is much more common.

Killing Emacs
-------------

Killing Emacs means ending the execution of the Emacs process. It will return to its superior process.

All the information in the Emacs process, aside from files that have been saved, is lost when the Emacs is killed.  Because killing Emacs inadvertently can lose a lot of work, Emacs will query for confirmation before actually terminating if you have buffers that need saving or subprocesses that are running.

 -- Function: kill-emacs &optional no-query
     This function exits the Emacs process and kills it.

     Normally, if there are modified files or if there are running processes, kill-emacs asks the user for confirmation before exiting.  However, if NO-QUERY is supplied and non-nil, then Emacs exits without confirmation.

     If NO-QUERY is an integer, then it is used as the exit status of the Emacs process.  (This is useful primarily in batch operation; see Batch Mode.)

     If NO-QUERY is a string, its contents are stuffed into the terminal input buffer so that the shell (or whatever program next reads input) can read them.

 -- Variable: kill-emacs-hook
     The value of the kill-emacs-hook variable is either nil or is that of a function to be called by kill-emacs.  The hook is called before anything else is done by kill-emacs.

Suspending Emacs
----------------

Suspending Emacs means stopping Emacs temporarily and returning control to its superior process, which is usually the shell.  This allows you to resume editing later in the same Emacs process, with the same buffers, the same kill ring, the same undo history, and so on.  To resume Emacs, use the appropriate command in the parent shell---most likely fg.

Some operating systems do not support suspension of jobs; on these systems, ``suspension'' actually creates a new shell temporarily as a subprocess of Emacs.  Then you would exit the shell to return to Emacs.

Suspension is not useful with window systems such as X Windows, because the Emacs job may not have a parent that can resume it again, and in any case you can give input to some other job such as a shell merely by moving to a different window.  Therefore, suspending is not allowed under X Windows.

 -- Function: suspend-emacs string
     This function stops Emacs and returns to the superior process.  It returns nil.

     If STRING is non-nil, its characters are sent to be read as terminal input by Emacs's superior shell.  The characters in STRING will not be echoed by the superior shell; just the results will appear.

     Before suspending, Emacs examines the symbol suspend-hook.  If it is bound, and its value is non-nil, then the value is called as a function of no arguments.  If the function returns non-nil, then suspend-emacs returns immediately and suspension does not occur.

     After Emacs resumes, the symbol suspend-resume-hook is examined.  If it is bound and non-nil, then the value is called as a function of no arguments.

     The next redisplay after resumption will redraw the entire screen, unless no-redraw-on-reenter is set (see Screen Attributes).

     In the following example, note that pwd is not echoed after Emacs is suspended.  But it is read and executed by the shell.

          (suspend-emacs)
               => nil

          (setq suspend-hook
              (function (lambda ()
                        (not (y-or-n-p "Really suspend? ")))))
               => (lambda nil (not (y-or-n-p "Really suspend? ")))
          (setq suspend-resume-hook
              (function (lambda () (message "Resumed!"))))
               => (lambda nil (message "Resumed!"))
          (suspend-emacs "pwd")
               => nil
          ---------- Buffer: Minibuffer ----------
          Really suspend? y

          ---------- Parent Shell ----------
          lewis@slug[23] % /user/lewis/manual
          lewis@slug[24] % fg

          ---------- Echo Area ----------
          Resumed!

 -- Variable: suspend-hook
     The value of the suspend-hook variable, if not nil, is called as a function with no arguments by suspend-emacs before Emacs is actually suspended.  If the function returns non-nil, then suspension does not take place.

 -- Variable: suspend-resume-hook
     The value of the suspend-resume-hook variable, if not nil, is called as a function with no arguments after resumption of an Emacs session that was suspended with suspend-emacs.

Operating System Environment
============================

Emacs provides access to variables in the operating system environment through various functions.  These variables include the name of the system, the user's UID, and so on.

 -- Variable: system-type
     The value of this variable is a symbol indicating the type of operating system Emacs is operating on.  Here is a table of the symbols for the operating systems that Emacs can run on up to version 18.51.

     berkeley-unix
          Berkeley BSD 4.1, 4.2, or 4.3.

     hpux
          Hewlett-Packard operating system, version 5, 6, or 7.

     silicon-graphics-unix
          Silicon Graphics Iris 3.5 or 3.6.

     rtu
          RTU 3.0, UCB universe.

     unisoft-unix
          UniSoft's UniPlus 5.0 or 5.2.

     usg-unix-v
          AT&T's System V.0, System V Release 2.0, 2.2, or 3.

     vax-vms
          VMS VMS version 4 or 5.

     xenix
          SCO Xenix 386 Release 2.2.

     We do not wish to add new symbols to make finer distinctions unless it is absolutely necessary!  In fact, it would be nice to eliminate a couple of possibilities in the future.

 -- Function: getenv var
     This function returns the value of the environment variable VAR, as a string.

          (getenv "USER")
               => "lewis"

          lewis@slug[10] % printenv
          PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
          USER=lewis
          TERM=ibmapa16
          SHELL=/bin/csh
          HOME=/user/lewis

 -- Function: user-login-name
     This function returns the name under which the user is logged in. This is based on the effective UID, not the real UID.

          (user-login-name)
               => "lewis"

 -- Function: user-real-login-name
     This function returns the name under which the user logged in. This is based on the real UID, not the effective UID.  This differs from user-login-name only when running with the setuid bit.

 -- Function: user-full-name
     This function returns the full name of the user.

          (user-full-name)
               => "Bil Lewis"

 -- Function: user-real-uid
     This function returns the real UID of the user.

          (user-real-uid)
               => 19

 -- Function: user-uid
     This function returns the effective UID of the user.

 -- Function: system-name
     This function returns the name of the machine you are running on.

          (system-name)
               => "prep.ai.mit.edu"

 -- Function: current-time-string
     This function returns the current time and date as a humanly-readable string.  The format of the string is unvarying; the number of characters used for each part is always the same, so you can reliably use substring to extract pieces of it.  However, it would be wise to count the characters from the beginning of the string rather than from the end, as additional information describing the time zone may be added in version 19.

          (current-time-string)
               => "Wed Oct 14 22:21:05 1987"

 -- Function: load-average
     This function returns the current 1 minute, 5 minute and 15 minute load averages in a list.  The values are integers that are 100 times the system load averages.  (The load averages indicate the number of processes trying to run.)

          (load-average)
               => (169 48 36)

          lewis@rocky[5] % uptime
           11:55am  up 1 day, 19:37,  3 users,  load average: 1.69, 0.48, 0.36

 -- Function: setprv privilege-name &optional setp getprv
     This function sets or resets a VMS privilege.  (It does not exist on Unix.)  The first arg is the privilege name, as a string.  The second argument, SETP, is t or nil, indicating whether the privilege is to be turned on or off.  Its default is nil.  The function returns t if success, nil if not.

     If the third argument, GETPRV, is non-nil, setprv does not change the privilege, but returns t or nil indicating whether the privilege is currently enabled.

Terminal Input
==============

The terminal input functions and variables keep track of or manipulate terminal input.

See Emacs Display, for related functions.

 -- Function: recent-keys
     This function returns a string comprising the last 100 characters read from the terminal.  These are the last 100 characters read by Emacs, no exceptions.

          (recent-keys)
          => "erminal.  These are the last 100 characters read by Emacs, no
          exceptions.

          @example
          (recent-keys)^U^X^E"

     Here the string @example is a Texinfo command that was inserted in the source file for the manual, and ^U^X^E are the characters that were typed to evaluate the expression (recent-keys).

 -- Command: open-dribble-file filename
     This function opens a dribble file named FILENAME.  When a dribble file is open, Emacs copies all keyboard input characters to that file.  (The contents of keyboard macros are not typed on the keyboard so they are not copied to the dribble file.)

     You close the dribble file by calling this function with an argument of "".  The function always returns nil.

     This function is normally used to record the input necessary to trigger an Emacs bug, for the sake of a bug report.

          (open-dribble-file "$j/dribble")
               => nil

See also the open-termscript function (see Terminal Output).

 -- Function: set-input-mode interrupt flow quit-char
     This function sets the mode for reading keyboard input.  If INTERRUPT is non-null, then Emacs uses input interrupts.  If it is nil, then it uses CBREAK mode.

     If FLOW is non-nil, then Emacs uses XON/XOFF (C-q, C-s) flow control for output to terminal.  This has no effect except in CBREAK mode.  See Flow Control.

     The normal setting is system dependent.  Some systems always use CBREAK mode regardless of what is specified.

     If QUIT-CHAR is non-nil, it specifies the character to use for quitting.  Normally this is 7, the code for C-g. See Quitting.

 -- Variable: meta-flag
     This variable tells Emacs whether to treat the 0200 bit in keyboard input as the Meta bit.  nil means no, and anything else means yes.  In version 19, meta-flag will be a function instead of a variable.

 -- Variable: keyboard-translate-table
     This variable defines the translate table for keyboard input.  This allows the user to redefine the keys on the keyboard without changing any command bindings.  Its value must be a string or nil.

     If keyboard-translate-table is a string, then each character read from the keyboard is looked up in this string and the character in the string is used instead.  If the string is of length N, character codes N and up are untranslated.

     In the example below, keyboard-translate-table is set to a string of 128 characters.  Then the characters C-s and C-\ are swapped and the characters C-q and C-^ are swapped. After executing this function, typing C-\ has all the usual effects of typing C-s, and vice versa.  (see Flow Control for more information on this subject.)

          (defun evade-flow-control ()
            "Replace C-s with C-\ and C-q with C-^."
            (interactive)
            (let ((the-table (make-string 128 0)))
              (let ((i 0))
                (while (< i 128)
                  (aset the-table i i)
                  (setq i (1+ i))))

              ;; Swap C-s and C-\.
              (aset the-table ?\034 ?\^s)
              (aset the-table ?\^s ?\034)
              ;; Swap C-q and C-^.
              (aset the-table ?\036 ?\^q)
              (aset the-table ?\^q ?\036)

              (setq keyboard-translate-table the-table)))

     Note that this translation is the first thing that happens after a character is read from the terminal.  As a result, record-keeping features such as recent-keys and open-dribble-file record the translated characters.

Terminal Output
===============

The terminal output functions send or keep track of output sent from the computer to the terminal.  The baud-rate function tells you what Emacs thinks is the output baud rate of the terminal.

 -- Function: baud-rate
     This function returns the output baud rate of the terminal.

          (baud-rate)
               => 9600

     If you are running across a network, and different parts of the network work at different baud rates, the value returned by Emacs may be different from the value used by your local terminal.  Some network protocols communicate the local terminal speed to the remote machine, so that Emacs and other programs can get the proper value, but others do not.  If the machine where Emacs is running has the wrong speed setting, you can specify the right speed using the stty program.  However, you will have to start Emacs afresh to make this take effect.

     Note: In version 19, baud-rate is a variable so that you can change it conveniently within Emacs.

 -- Function: send-string-to-terminal string
     This function sends STRING to the terminal without alteration. Control characters in STRING will have terminal-dependent effects.

     One use of this function is to define function keys on terminals that have downloadable function key definitions.  For example, this is how on certain terminals to define function key 4 to move forward four characters (by transmitting the characters C-u C-f to the computer):

          (send-string-to-terminal "\eF4\^U\^F")
               => nil

 -- Command: open-termscript filename
     This function is used to open a termscript file that will record all the characters sent by Emacs to the terminal.  It returns nil.  Termscript files are useful for investigating problems where Emacs garbles the screen, problems which are due to incorrect termcap entries or to undesirable settings of terminal options more often than actual Emacs bugs.  Once you are certain which characters were actually output, you can determine reliably whether they correspond to the termcap specifications in use.

     See also open-dribble-file in Terminal Input.

          (open-termscript "../junk/termscript")
               => nil

Flow Control
============

This section attempts to answer the question ``Why does Emacs choose to use flow-control characters in its command character set?''  For a second view on this issue, read the comments on flow control in the emacs/INSTALL file from the distribution; for help with termcaps and DEC terminal concentrators, see emacs/etc/TERMS.

At one time, most terminals did not need flow control.  This meant that the choice of C-s and C-q as command characters was reasonable.  Emacs, for economy of keystrokes and portability, chose to use the control characters in the ASCII character set, and tried to make the assignments mnemonic (thus, C-s for search and C-q for quote).

Later, some terminals were introduced which used these characters for flow control.  They were not very good terminals, so Emacs maintainers did not pay attention.  In later years, the practice became widespread among terminals, but by this time it was usually an option.  And the majority of users, who can turn flow control off, were unwilling to switch to less mnemonic key bindings for the sake of flow control.

So which usage is ``right'', Emacs's or that of some terminal and concentrator manufacturers?  This is a rhetorical (or religious) question; it has no simple answer.

One reason why we are reluctant to cater to the problems caused by C-s and C-q is that they are gratuitous.  There are other techniques (albeit less common in practice) for flow control that preserve transparency of the character stream.  Note also that their use for flow control is not an official standard.  Interestingly, on the model 33 teletype with a paper tape punch (which is very old), C-s and C-q were sent by the computer to turn the punch on and off!

GNU Emacs (version 18.48 and later) provides several options for coping with terminals or front-ends that insist on using flow control characters.  Listed in estimated order of preference, these options are as follows:

 1. Have Emacs run in CBREAK mode with the kernel handling flow control.  Issue (set-input-mode nil t) from .emacs.  After doing this, it is necessary to find other keys to bind to the commands isearch-forward and quoted-insert.  The usual nominees are C-^ and C-\.  There are two ways to get this effect:

      1. Use the keyboard-translate-table to cause C-^ and C-\ to be received by Emacs as though C-s and C-q were typed.  Emacs (except at its very lowest level) never knows that the characters typed were anything but C-s and C-q, so the use of these keys inside isearch-forward still works---typing C-^ while incremental searching will move the cursor to the next match, etc.  For example:

               (setq keyboard-translate-table (make-string 128 0))
               (let ((i 0))
                 (while (< i 128)
                   (aset keyboard-translate-table i i)
                   (setq i (1+ i))))

                 ;; Swap C-s and C-\.
                 (aset the-table ?\034 ?\^s)
                 (aset the-table ?\^s ?\034)
                 ;; Swap C-q and C-^.
                 (aset the-table ?\036 ?\^q)
                 (aset the-table ?\^q ?\036)))

      2. Simply rebind the keys C-^ and C-\ to isearch-forward and quoted-insert.  To use the new keys to repeat searches, it is necessary to set search-repeat-char to C-^ as well.

 2. Don't use CBREAK mode, but cause C-s and C-q to be bound to a null command.  The problem with this solution is that the flow control characters were probably sent because whatever sent them is falling behind on the characters being sent to it.  The characters that find their way to the terminal screen will not in general be those that are intended.  Also, it will be be necessary to find other keys to bind to isearch-forward and quoted-insert; see the previous alternative.

     Here is a suitable null command:

          (defun noop ()
            "Do nothing; return nil."
            (interactive))

 3. Don't use CBREAK mode, and unset the C-s and C-q keys with the global-unset-key function.  This is similar to the previous alternative, except that the flow control characters will probably cause beeps or visible bells.

     Note that if the terminal is the source of the flow control characters and kernel flow control handling is enabled, you probably will not have to send padding characters as specified in a termcap or terminfo entry. In this case, it may be possible to customize a termcap entry to provide better Emacs performance on the assumption that flow control is in use. This effect can also be simulated by announcing (with stty or its equivalent) that the terminal is running at a very slow speed, provided you are communicating across a network so that stty does not actually try to change the line speed.

Batch Mode
==========

The command line option -batch causes Emacs to run noninteractively.  In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen.  The idea is that you will specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with -l FILE, which causes the library named FILE to be loaded, and -f FUNCTION, which causes FUNCTION to be called with no arguments.

Any Lisp program output that would normally go to the echo area, either using message or using prin1, etc., with t as the stream, will actually go to Emacs's standard output descriptor when in batch mode.  Thus, Emacs behaves much like a noninteractive application program.  (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.)

 -- Variable: noninteractive
     This variable is non-nil when Emacs is running in batch mode.