comparison lispref/os.texi @ 25751:467b88fab665

*** empty log message ***

25750:f1968a807f56

  @xref{Building Emacs}, for related information.  See also
@ref{Display}, for additional operating system status information
pertaining to the terminal and the screen.

@menu
* Starting Up::         Customizing Emacs start-up processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::		Getting the current time.
* Time Conversion::     Converting a time from numeric form to a string, or
                          to calendrical data (or vice versa).
* Timers::		Setting a timer to call a function at a certain time.
* Terminal Input::      Recording terminal input for debugging.
* Terminal Output::     Recording terminal output for debugging.
* Special Keysyms::     Defining system-specific key symbols for X windows.
* Flow Control::        How to turn output flow control on or off.
* Batch Mode::          Running Emacs without terminal interaction.
@end menu

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

@menu
* Start-up Summary::        Sequence of actions Emacs performs at start-up.
* Init File::               Details on reading the init file (@file{.emacs}).
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command Line Arguments::  How command line arguments are processed,
                              and how you can customize them.
@end menu

@node Start-up Summary
@subsection Summary: Sequence of Actions at Start Up
@cindex initialization
@cindex start up of Emacs
@cindex @file{startup.el}

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

@cindex @file{site-start.el}

@item 
It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
specified on the command line.  The @samp{-u} option can specify another
user name whose home directory should be used instead of @file{~}.

@item 
It loads the library @file{default}, unless @code{inhibit-default-init}
is non-@code{nil}.  (This is not done in @samp{-batch} mode or if
@samp{-q} was specified on the command line.)  The library's file name

@item 
It runs @code{window-setup-hook}.  @xref{Window Systems}.

@item 
It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command line arguments (a few steps above),
the value of @code{inhibit-startup-message} is @code{nil}, and the
buffer is still empty.
@end enumerate

@defopt inhibit-startup-message

@subsection The Init File: @file{.emacs}
@cindex init file
@cindex @file{.emacs}

  When you start Emacs, it normally attempts to load the file
@file{.emacs} from your home directory.  This file, if it exists, must
contain Lisp code.  It is called your @dfn{init file}.  The command line
switches @samp{-q} and @samp{-u} affect the use of the init file;
@samp{-q} says not to load an init file, and @samp{-u} says to load a
specified user's init file instead of yours.  @xref{Entering Emacs,,,
emacs, The GNU Emacs Manual}.

@cindex default init file
  A site may have a @dfn{default init file}, which is the library named
@file{default.el}.  Emacs finds the @file{default.el} file through the
standard search path for libraries (@pxref{How Programs Do Loading}).

way you can change it with real effect is to do so before dumping
Emacs.
@end defvar

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

  @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@file{.emacs} file.

@cindex terminal-specific initialization

  Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal.  The library's name is constructed by
concatenating the value of the variable @code{term-file-prefix} and the
terminal type.  Normally, @code{term-file-prefix} has the value
@code{"term/"}; changing this is not recommended.  Emacs finds the file
in the normal manner, by searching the @code{load-path} directories, and
trying the @samp{.elc} and @samp{.el} suffixes.

  The usual function of a terminal-specific library is to enable special

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

@defvar term-setup-hook 
This variable is a normal hook that Emacs runs after loading your
@file{.emacs} file, the default initialization file (if any) and the

@end defvar

  See @code{window-setup-hook} in @ref{Window Systems}, for a related
feature.

@node Command Line Arguments
@subsection Command Line Arguments
@cindex 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.

  This section describes how Emacs processes command line arguments,
and how you can customize them.

@ignore
  (Note that some other editors require you to start afresh each time
you want to edit a file.  With this kind of editor, you will probably
specify the file as a command line argument.  The recommended way to
use GNU Emacs is to start it only once, just after you log in, and do
all your editing in the same Emacs process.  Each time you want to edit
a different file, you visit it with the existing Emacs, which eventually
comes to have many files in it ready for editing.  Usually you do not
kill the Emacs until you are about to log out.)

The value of this variable is @code{t} once the command line has been
processed.

If you redump Emacs by calling @code{dump-emacs}, you may wish to set
this variable to @code{nil} first in order to cause the new dumped Emacs
to process its new command line arguments.
@end defvar

@defvar command-switch-alist
@cindex switches on command line
@cindex options on command line
@cindex command line options
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 @dfn{command line option} is an argument on the command line of the
form:

@example
-@var{option}
@end example

@example
(@var{option} . @var{handler-function})
@end example

The @var{handler-function} is called to handle @var{option} and receives
the option name as its sole argument.

In some cases, the option is followed in the command line by an
argument.  In these cases, the @var{handler-function} can find all the
remaining command-line arguments in the variable
@code{command-line-args-left}.  (The entire list of command-line
arguments is in @code{command-line-args}.)

The command line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file.  See also @ref{Command
Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
Manual}.
@end defvar

@defvar command-line-args
The value of this variable is the list of command line arguments passed
to Emacs.
@end defvar

@defvar command-line-functions
This variable's value is a list of functions for handling an

terminal input buffer so that the shell (or whatever program next reads
input) can read them.
@end defun

  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 queries for confirmation
before actually terminating if you have buffers that need saving or
subprocesses that are running.  This is done in the function
@code{save-buffers-kill-emacs}.

@defvar kill-emacs-query-functions
After asking the standard questions, @code{save-buffers-kill-emacs}
calls the functions in the list @code{kill-emacs-query-functions}, in

  Suspension is not useful with window systems, 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 when Emacs is using
a window system.

@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
If and when the superior process resumes Emacs, @code{suspend-emacs}
returns @code{nil} to its caller in Lisp.

@end group
@end smallexample
@end defun

@defvar suspend-hook
This variable is a normal hook run before suspending.
@end defvar

@defvar suspend-resume-hook
This variable is a normal hook run after suspending.
@end defvar

@node System Environment
@section Operating System Environment
@cindex operating system environment

@item irix
Silicon Graphics Irix system.

@item ms-dos
Microsoft MS-DOS ``operating system.''

@item next-mach
NeXT Mach-based system.

@item rtu

@item vax-vms
VAX VMS.

@item windows-nt
Microsoft windows NT.

@item xenix
SCO Xenix 386.
@end table

@defvar path-separator
This variable holds a string which says which character separates
directories in a search path (as found in an environment variable).  Its
value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
and Windows NT.
@end defvar

@defvar invocation-name
This variable holds the program name under which Emacs was invoked.  The
value is a string, and does not include a directory name.

in the system's terminal driver, before Emacs was started.
@end defvar

@defun 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, @var{setp}, is @code{t} or @code{nil}, indicating whether the
privilege is to be turned on or off.  Its default is @code{nil}.  The
function returns @code{t} if successful, @code{nil} otherwise.

  If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
does not change the privilege, but returns @code{t} or @code{nil}
indicating whether the privilege is currently enabled.
@end defun

@node User Identification
@section User Identification

@defvar init-file-user
This variable says which user's init files should be used by Emacs---or
@code{nil} if none.  The value reflects command line options such as
@samp{-q} or @samp{-u @var{user}}.

Lisp packages that load files of customizations, or any other sort of
user profile, should obey this variable in deciding where to find it.
They should load the profile of the user name found in this variable.

environment variables @code{LOGNAME} and @code{USER}.
@end defun

@defun user-full-name &optional uid
This function returns the full name of the logged-in user---or the value
of the environment variables @code{NAME}, if that is set.

@example
@group
(user-full-name)
     @result{} "Bil Lewis"
@end group

@c Emacs 19 feature
@defun current-time
This function returns the system's time value as a list of three
integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
@var{high} and @var{low} combine to give the number of seconds since
0:00 January 1, 1970, which is
@ifinfo
@var{high} * 2**16 + @var{low}.
@end ifinfo
@tex
$high*2^{16}+low$.
@end tex

The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time only on
the resolution of a second).

The first two elements can be compared with file time values such as you
get with the function @code{file-attributes}.  @xref{File Attributes}.
@end defun

in.

The value has the form @code{(@var{offset} @var{name})}.  Here
@var{offset} is an integer giving the number of seconds ahead of UTC
(east of Greenwich).  A negative value means west of Greenwich.  The
second element, @var{name} is a string giving the name of the time
zone.  Both elements change when daylight savings time begins or ends;
if the user has specified a time zone that does not use a seasonal time
adjustment, then the value is constant through time.

If the operating system doesn't supply all the information necessary to

@item %h
This is a synonym for @samp{%b}.
@item %H
This stands for the hour (00-23).
@item %I
This stands for the hour (00-12).
@item %j
This stands for the day of the year (001-366).
@item %k
This stands for the hour (0-23), blank padded.
@item %l

@item %r
This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
This stands for the seconds (00-60).
@item %t
This stands for a tab character.
@item %T
This is a synonym for @samp{%H:%M:%S}.
@item %U

@end example

Here is what the elements mean:

@table @var
@item sec
The number of seconds past the minute, as an integer between 0 and 59.
@item minute
The number of minutes past the hour, as an integer between 0 and 59.
@item hour
The hour of the day, as an integer between 0 and 23.
@item day
The day of the month, as an integer between 1 and 31.

@defun encode-time seconds minutes hour day month year &optional @dots{}zone
This function is the inverse of @code{decode-time}.  It converts seven
items of calendrical data into a time value.  For the meanings of the
arguments, see the table above under @code{decode-time}.

Year numbers less than 100 are treated just like other year numbers.  If
you want them to stand for years above 1900, you must alter them yourself
before you call @code{encode-time}.

The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules.  If specified, it can be either a list
(as you would get from @code{current-time-zone}), a string as in the
@code{TZ} environment variable, or an integer (as you would get from

@example
(apply 'encode-time (decode-time @dots{}))
@end example

You can perform simple date arithmetic by using out-of-range values for
the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
arguments; for example, day 0 means the day preceding the given month.

The operating system puts limits on the range of possible time values;
if you try to encode a time that is out of range, an error results.
@end defun

denotes 65 seconds from now.
@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
denotes exactly 103 months, 123 days, and 10862 seconds from now.
@end table

If @var{time} is a number (integer or floating point), that specifies a
relative time measured in seconds.

The argument @var{repeat} specifies how often to repeat the call.  If
@var{repeat} is @code{nil}, there are no repetitions; @var{function} is

@cindex idleness
  Emacs becomes ``idle'' when it starts waiting for user input, and it
remains idle until the user provides some input.  If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first became idle.  Even if its @var{repeat} is true, this timer will
not run again as long as Emacs remains idle, because the duration of
idleness will continue to increase and will not go down to five seconds
again.

  Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess.  But these interludes during idleness do
not interfere with idle timers, because they do not reset the clock of
idleness to zero.  An idle timer set for 600 seconds will run when ten
minutes have elapsed since the last user command was finished, even if
subprocess output has been accepted thousands of times within those ten
minutes, even if there have been garbage collections and autosaves.

  When the user supplies input, Emacs becomes non-idle while executing the
input.  Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.

@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input.  If
@var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
@code{nil}, then it uses @sc{cbreak} mode.  The default setting is
system dependent.  Some systems always use @sc{cbreak} mode regardless
of what is specified.

When Emacs communicates directly with X, it ignores this argument and
uses interrupts if that is the way it knows how to communicate.

The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.

@c Emacs 19 feature
@defun current-input-mode
This function returns current mode for reading keyboard input.  It
returns a list, corresponding to the arguments of @code{set-input-mode},
of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
which:
@table @var
@item interrupt

@defvar keyboard-translate-table
This variable is the translate table for keyboard characters.  It lets
you reshuffle the keys on the keyboard without changing any command
bindings.  Its value is normally a char-table, or else @code{nil}.

If @code{keyboard-translate-table} is a char-table, then each character
read from the keyboard is looked up in this character.  If the value
found there is non-@code{nil}, then it is used instead of the
actual input character.

In the example below, we set @code{keyboard-translate-table} to a
char-table.  Then we fill it in to swap the characters @kbd{C-s} and
@kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.  Subsequently,
typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice

@node Terminal Output
@section Terminal Output
@cindex terminal output

  The terminal output functions send output to the terminal or keep
track of output sent to the terminal.  The variable @code{baud-rate}
tells you what Emacs thinks is the output speed of the terminal.

@defvar baud-rate
This variable's value is the output speed of the terminal, as far as

@defun send-string-to-terminal string
This function sends @var{string} to the terminal without alteration.
Control characters in @var{string} 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 @kbd{C-u C-f} to the
computer):

@example
@group

     @result{} nil
@end group
@end example
@end deffn

@node Special Keysyms
@section System-Specific X11 Keysyms

To define system-specific X11 keysyms, set the variable
@code{system-key-alist}.

@defvar system-key-alist
This variable's value should be an alist with one element for each
system-specific keysym.  An element has this form: @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit, 
@ifinfo 
-2**28),
@end ifinfo
@tex 
$-2^{28}$),
@end tex
and @var{symbol} is the name for the function key.

For example @code{(168 . mute-acute)} defines a system-specific key used
by HP X servers whose numeric code is
@ifinfo 
-2**28
@end ifinfo
@tex 
$-2^{28}$

@cindex @kbd{C-q}
  At one time, most terminals did not need flow control, and none used
@code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial.  With so many commands needing key
assignments, of course we assigned meanings to nearly all @sc{ASCII}
control characters.

  Later, some terminals were introduced which required these characters
for flow control.  They were not very good terminals for full-screen
editing, so Emacs maintainers ignored them.  In later years, flow

@node Batch Mode
@section Batch Mode
@cindex batch mode
@cindex noninteractive use

  The command line option @samp{-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 specify
Lisp programs to run; when they are finished, Emacs should exit.  The
way to specify the programs to run is with @samp{-l @var{file}}, which
loads the library named @var{file}, and @samp{-f @var{function}}, which
calls @var{function} with no arguments.

  Any Lisp program output that would normally go to the echo area,
either using @code{message} or using @code{prin1}, etc., with @code{t}
as the stream, goes instead to Emacs's standard error 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.)

25751:467b88fab665

  @xref{Building Emacs}, for related information.  See also
@ref{Display}, for additional operating system status information
pertaining to the terminal and the screen.

@menu
* Starting Up::         Customizing Emacs startup processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::		Getting the current time.
* Time Conversion::     Converting a time from numeric form to a string, or
                          to calendrical data (or vice versa).
* Timers::		Setting a timer to call a function at a certain time.
* Terminal Input::      Recording terminal input for debugging.
* Terminal Output::     Recording terminal output for debugging.
* Sound Output::        Playing sounds on the computer's speaker.
* Special Keysyms::     Defining system-specific key symbols for X windows.
* Flow Control::        How to turn output flow control on or off.
* Batch Mode::          Running Emacs without terminal interaction.
@end menu

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

@menu
* Startup Summary::         Sequence of actions Emacs performs at startup.
* Init File::               Details on reading the init file (@file{.emacs}).
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command-Line Arguments::  How command-line arguments are processed,
                              and how you can customize them.
@end menu

@node Startup Summary
@subsection Summary: Sequence of Actions at Startup
@cindex initialization
@cindex startup of Emacs
@cindex @file{startup.el}

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

@cindex @file{site-start.el}

@item 
It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
specified on the command line.  The @samp{-u} option can specify another
user whose home directory should be used instead of @file{~}.

@item 
It loads the library @file{default}, unless @code{inhibit-default-init}
is non-@code{nil}.  (This is not done in @samp{-batch} mode or if
@samp{-q} was specified on the command line.)  The library's file name

@item 
It runs @code{window-setup-hook}.  @xref{Window Systems}.

@item 
It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command-line arguments (a few steps above),
the value of @code{inhibit-startup-message} is @code{nil}, and the
buffer is still empty.
@end enumerate

@defopt inhibit-startup-message

@subsection The Init File: @file{.emacs}
@cindex init file
@cindex @file{.emacs}

  When you start Emacs, it normally attempts to load the file
@file{.emacs} from your home directory.  This file is called your
@dfn{init file}.  If it exists, it must contain Lisp code.  The
command-line switches @samp{-q} and @samp{-u} affect the use of the init
file; @samp{-q} says not to load an init file, and @samp{-u} says to
load a specified user's init file instead of yours.  @xref{Entering
Emacs,,, emacs, The GNU Emacs Manual}.

@cindex default init file
  A site may have a @dfn{default init file}, which is the library named
@file{default.el}.  Emacs finds the @file{default.el} file through the
standard search path for libraries (@pxref{How Programs Do Loading}).

way you can change it with real effect is to do so before dumping
Emacs.
@end defvar

  If there is a great deal of code in your @file{.emacs} file, you
can make it load faster by renaming it to @file{.emacs.el}
and then byte-compiling it (@pxref{Byte Compilation}).

  @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@file{.emacs} file.

@cindex terminal-specific initialization

  Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal.  The library's name is constructed by
concatenating the value of the variable @code{term-file-prefix} and the
terminal type (specified by the environment variable @code{TERM}).
Normally, @code{term-file-prefix} has the value
@code{"term/"}; changing this is not recommended.  Emacs finds the file
in the normal manner, by searching the @code{load-path} directories, and
trying the @samp{.elc} and @samp{.el} suffixes.

  The usual function of a terminal-specific library is to enable special

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

On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
uses @samp{internal} as the terminal type.
@end defvar

@defvar term-setup-hook 
This variable is a normal hook that Emacs runs after loading your
@file{.emacs} file, the default initialization file (if any) and the

@end defvar

  See @code{window-setup-hook} in @ref{Window Systems}, for a related
feature.

@node Command-Line Arguments
@subsection Command-Line Arguments
@cindex 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.

  This section describes how Emacs processes command-line arguments,
and how you can customize them.

@ignore
  (Note that some other editors require you to start afresh each time
you want to edit a file.  With this kind of editor, you will probably
specify the file as a command-line argument.  The recommended way to
use GNU Emacs is to start it only once, just after you log in, and do
all your editing in the same Emacs process.  Each time you want to edit
a different file, you visit it with the existing Emacs, which eventually
comes to have many files in it ready for editing.  Usually you do not
kill the Emacs until you are about to log out.)

The value of this variable is @code{t} once the command line has been
processed.

If you redump Emacs by calling @code{dump-emacs}, you may wish to set
this variable to @code{nil} first in order to cause the new dumped Emacs
to process its new command-line arguments.
@end defvar

@defvar command-switch-alist
@cindex switches on command line
@cindex options on command line
@cindex command-line options
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 @dfn{command-line option} is an argument on the command line, which
has the form:

@example
-@var{option}
@end example

@example
(@var{option} . @var{handler-function})
@end example

The @sc{car}, @var{option}, is a string, the name of a command-line
option (not including the initial hyphen).  The @var{handler-function}
is called to handle @var{option}, and receives the option name as its
sole argument.

In some cases, the option is followed in the command line by an
argument.  In these cases, the @var{handler-function} can find all the
remaining command-line arguments in the variable
@code{command-line-args-left}.  (The entire list of command-line
arguments is in @code{command-line-args}.)

The command-line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file.  See also @ref{Command
Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
Manual}.
@end defvar

@defvar command-line-args
The value of this variable is the list of command-line arguments passed
to Emacs.
@end defvar

@defvar command-line-functions
This variable's value is a list of functions for handling an

terminal input buffer so that the shell (or whatever program next reads
input) can read them.
@end defun

  All the information in the Emacs process, aside from files that have
been saved, is lost when the Emacs process is killed.  Because killing
Emacs inadvertently can lose a lot of work, Emacs queries for
confirmation before actually terminating if you have buffers that need
saving or subprocesses that are running.  This is done in the function
@code{save-buffers-kill-emacs}.

@defvar kill-emacs-query-functions
After asking the standard questions, @code{save-buffers-kill-emacs}
calls the functions in the list @code{kill-emacs-query-functions}, in

  Suspension is not useful with window systems, 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 when Emacs is using
a window system (X Windows or MS Windows).

@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
If and when the superior process resumes Emacs, @code{suspend-emacs}
returns @code{nil} to its caller in Lisp.

@end group
@end smallexample
@end defun

@defvar suspend-hook
This variable is a normal hook that Emacs runs before suspending.
@end defvar

@defvar suspend-resume-hook
This variable is a normal hook that Emacs runs on resuming
after a suspension.
@end defvar

@node System Environment
@section Operating System Environment
@cindex operating system environment

@item irix
Silicon Graphics Irix system.

@item ms-dos
Microsoft MS-DOS ``operating system.''  Emacs compiled with DJGPP for
MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
MS-Windows.

@item next-mach
NeXT Mach-based system.

@item rtu

@item vax-vms
VAX VMS.

@item windows-nt
Microsoft windows NT.  The same executable supports Windows 9X, but the
value of @code{system-type} is @code{windows-nt} in either case.

@item xenix
SCO Xenix 386.
@end table

@defvar path-separator
This variable holds a string which says which character separates
directories in a search path (as found in an environment variable).  Its
value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
and MS-Windows.
@end defvar

@defvar invocation-name
This variable holds the program name under which Emacs was invoked.  The
value is a string, and does not include a directory name.

in the system's terminal driver, before Emacs was started.
@end defvar

@defun setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege.  (It does not exist on
other systems.)  The first argument is the privilege name, as a string.
The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
whether the privilege is to be turned on or off.  Its default is
@code{nil}.  The function returns @code{t} if successful, @code{nil}
otherwise.

  If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
does not change the privilege, but returns @code{t} or @code{nil}
indicating whether the privilege is currently enabled.
@end defun

@node User Identification
@section User Identification

@defvar init-file-user
This variable says which user's init files should be used by Emacs---or
@code{nil} if none.  The value reflects command-line options such as
@samp{-q} or @samp{-u @var{user}}.

Lisp packages that load files of customizations, or any other sort of
user profile, should obey this variable in deciding where to find it.
They should load the profile of the user name found in this variable.

environment variables @code{LOGNAME} and @code{USER}.
@end defun

@defun user-full-name &optional uid
This function returns the full name of the logged-in user---or the value
of the environment variable @code{NAME}, if that is set.

@c "Bil" is the correct spelling.
@example
@group
(user-full-name)
     @result{} "Bil Lewis"
@end group

@c Emacs 19 feature
@defun current-time
This function returns the system's time value as a list of three
integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
@var{high} and @var{low} combine to give the number of seconds since
0:00 January 1, 1970 (local time), which is
@ifinfo
@var{high} * 2**16 + @var{low}.
@end ifinfo
@tex
$high*2^{16}+low$.
@end tex

The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time with
the resolution of only one second).

The first two elements can be compared with file time values such as you
get with the function @code{file-attributes}.  @xref{File Attributes}.
@end defun

in.

The value has the form @code{(@var{offset} @var{name})}.  Here
@var{offset} is an integer giving the number of seconds ahead of UTC
(east of Greenwich).  A negative value means west of Greenwich.  The
second element, @var{name}, is a string giving the name of the time
zone.  Both elements change when daylight savings time begins or ends;
if the user has specified a time zone that does not use a seasonal time
adjustment, then the value is constant through time.

If the operating system doesn't supply all the information necessary to

@item %h
This is a synonym for @samp{%b}.
@item %H
This stands for the hour (00-23).
@item %I
This stands for the hour (01-12).
@item %j
This stands for the day of the year (001-366).
@item %k
This stands for the hour (0-23), blank padded.
@item %l

@item %r
This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
This stands for the seconds (00-59).
@item %t
This stands for a tab character.
@item %T
This is a synonym for @samp{%H:%M:%S}.
@item %U

@end example

Here is what the elements mean:

@table @var
@item seconds
The number of seconds past the minute, as an integer between 0 and 59.
@item minutes
The number of minutes past the hour, as an integer between 0 and 59.
@item hour
The hour of the day, as an integer between 0 and 23.
@item day
The day of the month, as an integer between 1 and 31.

@defun encode-time seconds minutes hour day month year &optional @dots{}zone
This function is the inverse of @code{decode-time}.  It converts seven
items of calendrical data into a time value.  For the meanings of the
arguments, see the table above under @code{decode-time}.

Year numbers less than 100 are not treated specially.  If you want them
to stand for years above 1900, you must alter them yourself before you
call @code{encode-time}.

The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules.  If specified, it can be either a list
(as you would get from @code{current-time-zone}), a string as in the
@code{TZ} environment variable, or an integer (as you would get from

@example
(apply 'encode-time (decode-time @dots{}))
@end example

You can perform simple date arithmetic by using out-of-range values for
the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
arguments; for example, day 0 means the day preceding the given month.

The operating system puts limits on the range of possible time values;
if you try to encode a time that is out of range, an error results.
@end defun

denotes 65 seconds from now.
@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
denotes exactly 103 months, 123 days, and 10862 seconds from now.
@end table

For relative time values, Emacs considers a month to be exactly thirty
days, and a year to be exactly 365.25 days.

If @var{time} is a number (integer or floating point), that specifies a
relative time measured in seconds.

The argument @var{repeat} specifies how often to repeat the call.  If
@var{repeat} is @code{nil}, there are no repetitions; @var{function} is

@cindex idleness
  Emacs becomes ``idle'' when it starts waiting for user input, and it
remains idle until the user provides some input.  If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
will not run again as long as Emacs remains idle, because the duration
of idleness will continue to increase and will not go down to five
seconds again.

  Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess.  But these interludes during idleness do
not interfere with idle timers, because they do not reset the clock of
idleness to zero.  An idle timer set for 600 seconds will run when ten
minutes have elapsed since the last user command was finished, even if
subprocess output has been accepted thousands of times within those ten
minutes, and even if there have been garbage collections and autosaves.

  When the user supplies input, Emacs becomes non-idle while executing the
input.  Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.

@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input.  If
@var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
@code{nil}, then it uses @sc{cbreak} mode.  The default setting is
system-dependent.  Some systems always use @sc{cbreak} mode regardless
of what is specified.

When Emacs communicates directly with X, it ignores this argument and
uses interrupts if that is the way it knows how to communicate.

The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.

@c Emacs 19 feature
@defun current-input-mode
This function returns the current mode for reading keyboard input.  It
returns a list, corresponding to the arguments of @code{set-input-mode},
of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
which:
@table @var
@item interrupt

@defvar keyboard-translate-table
This variable is the translate table for keyboard characters.  It lets
you reshuffle the keys on the keyboard without changing any command
bindings.  Its value is normally a char-table, or else @code{nil}.

If @code{keyboard-translate-table} is a char-table
(@pxref{Char-Tables}), then each character read from the keyboard is
looked up in this char-table.  If the value found there is
non-@code{nil}, then it is used instead of the actual input character.

In the example below, we set @code{keyboard-translate-table} to a
char-table.  Then we fill it in to swap the characters @kbd{C-s} and
@kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.  Subsequently,
typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice

@node Terminal Output
@section Terminal Output
@cindex terminal output

  The terminal output functions send output to the terminal, or keep
track of output sent to the terminal.  The variable @code{baud-rate}
tells you what Emacs thinks is the output speed of the terminal.

@defvar baud-rate
This variable's value is the output speed of the terminal, as far as

@defun send-string-to-terminal string
This function sends @var{string} to the terminal without alteration.
Control characters in @var{string} 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 @kbd{C-u C-f} to the
computer):

@example
@group

     @result{} nil
@end group
@end example
@end deffn

@node Sound Output
@section Sound Output
@cindex sound

  To play sound using Emacs, use the function @code{play-sound}.  Only
certain systems are supported; if you call @code{play-sound} on a system
which cannot really do the job, it gives an error.  Emacs version 20 and
earlier did not support sound at all.

  The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).

@tindex play-sound
@defun play-sound sound
This function plays a specified sound.  The argument, @var{sound}, has
the form @code{(sound @var{properties}...)}, where the @var{properties}
consist of alternating keywords (particular symbols recognized
specially) and values corresponding to them.

Here is a table of the keywords that are currently meaningful in
@var{sound}, and their meanings:

@table @code
@item :file @var{file}
This specifies the file containing the sound to play.
If the file name is not absolute, it is expanded against
the directory @code{data-directory}.

@item :volume @var{volume}
This specifies how loud to play the sound.  It should be a number in the
range of 0 to 1.  The default is to use whatever volume has been
specified before.
@end table

Before actually playing the sound, @code{play-sound}
calls the functions in the list @code{play-sound-functions}.
Each function is called with one argument, @var{sound}.
@end defun

@tindex play-sound-functions
@defvar play-sound-functions
A list of functions to be called before playing a sound.  Each function
is called with one argument, a property list that describes the sound.
@end defvar

@node Special Keysyms
@section System-Specific X11 Keysyms

To define system-specific X11 keysyms, set the variable
@code{system-key-alist}.

@defvar system-key-alist
This variable's value should be an alist with one element for each
system-specific keysym.  Each element has the form @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit, 
@ifinfo 
-2**28),
@end ifinfo
@tex 
$-2^{28}$),
@end tex
and @var{symbol} is the name for the function key.

For example @code{(168 . mute-acute)} defines a system-specific key (used
by HP X servers) whose numeric code is
@ifinfo 
-2**28
@end ifinfo
@tex 
$-2^{28}$

@cindex @kbd{C-q}
  At one time, most terminals did not need flow control, and none used
@code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial.  With so many commands needing key
assignments, of course we assigned meanings to nearly all @sc{ascii}
control characters.

  Later, some terminals were introduced which required these characters
for flow control.  They were not very good terminals for full-screen
editing, so Emacs maintainers ignored them.  In later years, flow

@node Batch Mode
@section Batch Mode
@cindex batch mode
@cindex noninteractive use

  The command-line option @samp{-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 specify
Lisp programs to run; when they are finished, Emacs should exit.  The
way to specify the programs to run is with @samp{-l @var{file}}, which
loads the library named @var{file}, and @samp{-f @var{function}}, which
calls @var{function} with no arguments.

  Any Lisp program output that would normally go to the echo area,
either using @code{message}, or using @code{prin1}, etc., with @code{t}
as the stream, goes instead to Emacs's standard error 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.)