comparison lispref/os.texi @ 56369:6578797626ea

Various small changes in addition to: (Killing Emacs): Expand and clarify description of `kill-emacs-query-functions' and `kill-emacs-hook'. (System Environment): Expand and clarify description of `getenv' and `setenv'. (Timers): Clarify description of `run-at-time'. (Translating Input): Correct description of `extra-keyboard-modifiers'. (Flow Control): Correct description of `enable-flow-control'.

56368:b752a1228fc1

@defvar after-init-hook
This normal hook is run, once, just after loading all the init files
(the user's init file, @file{default.el}, and/or @file{site-start.el}),
before loading the terminal-specific library and processing the
command-line arguments.
@end defvar

@defvar emacs-startup-hook
@tindex emacs-startup-hook
This normal hook is run, once, just after handling the command line
arguments, just before @code{term-setup-hook}.
@end defvar

@defvar user-init-file
@tindex user-init-file
This variable holds the file name of the user's init file.  If the
actual init file loaded is a compiled file, such as @file{.emacs.elc},
the value refers to the corresponding source file.
@end defvar

@node Terminal-Specific

  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
order of appearance, with no arguments.  These functions can ask for
additional confirmation from the user.  If any of them returns
@code{nil}, Emacs is not killed.
@end defvar

@defvar kill-emacs-hook
This variable is a normal hook; once @code{save-buffers-kill-emacs} is
finished with all file saving and confirmation, it runs the functions in
this hook.  This hook is not run in batch mode.
@end defvar

@node Suspending Emacs
@subsection Suspending Emacs
@cindex suspending Emacs

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 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.

If @var{string} is non-@code{nil}, its characters are sent to be read

@group
(add-hook 'suspend-hook
          (function (lambda ()
                      (or (y-or-n-p
                            "Really suspend? ")
                          (error "Suspend cancelled")))))
     @result{} (lambda nil
          (or (y-or-n-p "Really suspend? ")
              (error "Suspend cancelled")))
@end group
@group
(add-hook 'suspend-resume-hook
          (function (lambda () (message "Resumed!"))))
     @result{} (lambda nil (message "Resumed!"))

@end defvar

@deffn Command getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
as a string.  Within Emacs, the environment variable values are kept in
the Lisp variable @code{process-environment}.

@example
@group
(getenv "USER")
     @result{} "lewis"

@end group
@end example
@end deffn

@c Emacs 19 feature
@deffn Command setenv variable value
This command sets the value of the environment variable named
@var{variable} to @var{value}.  Both arguments should be strings.  This
function works by modifying @code{process-environment}; binding that
variable with @code{let} is also reasonable practice.
@end deffn

@defvar process-environment
This variable is a list of strings, each describing one environment
variable.  The functions @code{getenv} and @code{setenv} work by means

If it is impossible to obtain the load average, this function signals
an error.  On some platforms, access to load averages requires
installing Emacs as setuid or setgid so that it can read kernel
information, and that usually isn't advisable.

@example
@group
(load-average)
     @result{} (169 48 36)
@end group

@end group
@end example
@end defun

@defun emacs-pid
This function returns the process @acronym{ID} of the Emacs process.
@end defun

@defvar tty-erase-char
This variable holds the erase character that was selected
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.

is set, that value is used.  Otherwise, if the environment variable
@code{USER} is set, that value is used.  Otherwise, the value is based
on the effective @acronym{UID}, not the real @acronym{UID}.

If you specify @var{uid}, the value is the user name that corresponds
to @var{uid} (which should be an integer).

@example
@group
(user-login-name)
     @result{} "lewis"

@end example

If the Emacs job's user-id does not correspond to any known user (and
provided @code{NAME} is not set), the value is @code{"unknown"}.

If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
or a string (a login name).  Then @code{user-full-name} returns the full
name corresponding to that user-id or login name.  If you specify a
user-id or login name that isn't defined, it returns @code{nil}.
@end defun

@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
instead of the current time.  The argument should be a list whose first
two elements are integers.  Thus, you can use times obtained from
@code{current-time} (see below) and from @code{file-attributes}
(@pxref{File Attributes}).

@example
@group
(current-time-string)
     @result{} "Wed Oct 14 22:21:05 1987"

@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
@ifnottex
@var{high} * 2**16 + @var{low}.
@end ifnottex
@tex
$high*2^{16}+low$.

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

@c Emacs 19 feature
@defun current-time-zone &optional time-value
This function returns a list describing the time zone that the user is

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
compute the value, both elements of the list are @code{nil}.

The argument @var{time-value}, if given, specifies a time to analyze
instead of the current time.  The argument should be a cons cell
containing two integers, or a list whose first two elements are
integers.  Thus, you can use times obtained from @code{current-time}
(see above) and from @code{file-attributes} (@pxref{File Attributes}).
@end defun

@defun set-time-zone-rule tz
This function specifies the local time zone according to @var{tz}.  If
@var{tz} is @code{nil}, that means to use an implementation-defined
default time zone.  If @var{tz} is @code{t}, that means to use
Universal Time.
@end defun

@defun float-time &optional time-value
This function returns the current time as a floating-point number of
seconds since the epoch.  The argument @var{time-value}, if given,
specifies a time to convert instead of the current time.  The argument
should have the same form as for @code{current-time-string} (see
above), and it also accepts the output of @code{current-time} and
@code{file-attributes}.

@emph{Warning}: Since the result is floating point, it may not be
exact.  Do not use this function if precise time stamps are required.
@end defun

  These functions convert time values (lists of two or three integers)
to strings or to calendrical information.  There is also a function to
convert calendrical information to a time value.  You can get time
values from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{File Attributes}).

Many operating systems are limited to time values that contain 32 bits
of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
operating systems have larger time values, and can represent times far

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

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
@code{decode-time}).  The specified zone is used without any further
alteration for daylight savings time.

If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
used as @var{zone}, and the arguments in between are ignored.  This
feature makes it possible to use the elements of a list returned by

things in an inconsistent state.  This is normally unproblematical
because most timer functions don't do a lot of work.  Indeed, for a
timer to call a function that takes substantial time to run is likely
to be annoying.

@defun run-at-time time repeat function &rest args
This function arranges to call @var{function} with arguments @var{args}
at time @var{time}.  The argument @var{function} is a function to call
later, and @var{args} are the arguments to give it when it is called.
The time @var{time} is specified as a string.

Absolute times may be specified in a wide variety of formats; this
function tries to accept all the commonly used date formats.  Valid
formats include these two,

@example
@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}

@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}

@noindent
where in both examples all fields are numbers; the format that
@code{current-time-string} returns is also allowed, and many others
as well.

To specify a relative time, use numbers followed by units.
For example:

@table @samp
@item 1 min
denotes 1 minute 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
called just once, at @var{time}.  If @var{repeat} is a number, it
specifies a repetition period measured in seconds.

In most cases, @var{repeat} has no effect on when @emph{first} call
takes place---@var{time} alone specifies that.  There is one exception:
if @var{time} is @code{t}, then the timer runs whenever the time is a
multiple of @var{repeat} seconds after the epoch.  This is useful for
functions like @code{display-time}.

The function @code{run-at-time} returns a timer value that identifies
the particular scheduled future action.  You can use this value to call
@code{cancel-timer} (see below).
@end defun

@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
Execute @var{body}, but give up after @var{seconds} seconds.  If
@var{body} finishes before the time is up, @code{with-timeout} returns
the value of the last form in @var{body}.  If, however, the execution of

  The function @code{y-or-n-p-with-timeout} provides a simple way to use
a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
Queries}.

@defun run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for @var{secs}
seconds.  The value of @var{secs} may be an integer or a floating point
number.

If @var{repeat} is @code{nil}, the timer runs just once, the first time

non-@code{nil}, which means to run the timer @emph{each time} Emacs
remains idle for @var{secs} seconds.

The function @code{run-with-idle-timer} returns a timer value which you
can use in calling @code{cancel-timer} (see below).
@end defun

@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

set up to repeat will subsequently run another time, one by one.

@defun cancel-timer timer
Cancel the requested action for @var{timer}, which should be a value
previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
This cancels the effect of that call to @code{run-at-time}; the arrival
of the specified time will not cause anything special to happen.
@end defun

@node Terminal Input
@section Terminal Input
@cindex terminal input

@node Input Modes
@subsection Input Modes
@cindex input modes
@cindex terminal input modes

@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.

@code{function-key-map} and then with @code{key-translation-map}.

@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard.  The value is a bit mask:

@table @asis
@item 1
The @key{SHIFT} key.
@item 2
The @key{LOCK} key.
@item 4
The @key{CTL} key.
@item 8
The @key{META} key.
@end table

Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.

When using a window system, the program can ``press'' any of the
modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
keys can be virtually pressed.
@end defvar

@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.

Note that this translation is the first thing that happens to a
character after it is read from the terminal.  Record-keeping features
such as @code{recent-keys} and dribble files record the characters after
translation.
@end defvar

@defun keyboard-translate from to
This function modifies @code{keyboard-translate-table} to translate
character code @var{from} into character code @var{to}.  It creates

@end group
@end example

Finally, if you have enabled keyboard character set decoding using
@code{set-keyboard-coding-system}, decoding is done after the
translations listed above.  @xref{Specifying Coding Systems}.  In future
Emacs versions, character set decoding may be done before the other
translations.

@node Recording Input
@subsection Recording Input

Termcap entries or to undesirable settings of terminal options more
often than to 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 @code{open-dribble-file} in @ref{Terminal Input}.

@example
@group
(open-termscript "../junk/termscript")
     @result{} nil

  As window systems and PC terminal emulators replace character-only
terminals, the flow control problem is gradually disappearing.  For the
mean time, Emacs provides a convenient way of enabling flow control if
you want it: call the function @code{enable-flow-control}.

@deffn Command enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
@end deffn

You can use the function @code{enable-flow-control-on} in your
init file to enable flow control automatically on certain
terminal types.

@enumerate
@item
@cindex @sc{cbreak}
It sets @sc{cbreak} mode for terminal input, and tells the operating
system to handle flow control, with @code{(set-input-mode nil t)}.

@item
It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
@kbd{C-^} into @kbd{C-s} and @kbd{C-q}.  Except at its very
lowest level, Emacs never knows that the characters typed were anything

@defvar emacs-save-session-functions
@tindex emacs-save-session-functions
Emacs supports saving state by using a hook called
@code{emacs-save-session-functions}.  Each function in this hook is
called when the session manager tells Emacs that the window system is
shutting down.  The functions are called with the current buffer set
to a temporary buffer.  Each function can use @code{insert} to add
Lisp code to this buffer.  At the end, Emacs saves the buffer in a
file that another Emacs will later load in order to restart the saved session.

If a function in @code{emacs-save-session-functions} returns
non-@code{nil}, Emacs tells the session manager to cancel the
shutdown.
@end defvar

56369:6578797626ea

@defvar after-init-hook
This normal hook is run, once, just after loading all the init files
(the user's init file, @file{default.el}, and/or @file{site-start.el}),
before loading the terminal-specific library and processing the
command-line action arguments.
@end defvar

@defvar emacs-startup-hook
@tindex emacs-startup-hook
This normal hook is run, once, just after handling the command line
arguments, just before @code{term-setup-hook}.
@end defvar

@defvar user-init-file
@tindex user-init-file
This variable holds the absolute file name of the user's init file.  If the
actual init file loaded is a compiled file, such as @file{.emacs.elc},
the value refers to the corresponding source file.
@end defvar

@node Terminal-Specific

  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}, the higher level function from which
@code{kill-emacs} is usually called.

@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
order of appearance, with no arguments.  These functions can ask for
additional confirmation from the user.  If any of them returns
@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
does not run the remaining functions in this hook.  Calling
@code{kill-emacs} directly does not run this hook.
@end defvar

@defvar kill-emacs-hook
This variable is a normal hook; once @code{save-buffers-kill-emacs} is
finished with all file saving and confirmation, it calls
@code{kill-emacs} which runs the functions in this hook.
@code{kill-emacs} does not run this hook in batch mode.

@code{kill-emacs} may be invoked directly (that is not via
@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
similar situations where interaction with the user is not possible.
Thus, if your hook needs to interact with the user, put it on
@code{kill-emacs-query-functions}; if it needs to run regardless of
how Emacs is killed, put it on @code{kill-emacs-hook}.
@end defvar

@node Suspending Emacs
@subsection Suspending Emacs
@cindex suspending Emacs

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 or MS Windows).

@defun suspend-emacs &optional 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.

If @var{string} is non-@code{nil}, its characters are sent to be read

@group
(add-hook 'suspend-hook
          (function (lambda ()
                      (or (y-or-n-p
                            "Really suspend? ")
                          (error "Suspend canceled")))))
     @result{} (lambda nil
          (or (y-or-n-p "Really suspend? ")
              (error "Suspend canceled")))
@end group
@group
(add-hook 'suspend-resume-hook
          (function (lambda () (message "Resumed!"))))
     @result{} (lambda nil (message "Resumed!"))

@end defvar

@deffn Command getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
as a string.  @var{var} should be a string.  If @var{var} is undefined
in the environment, @code{getenv} returns @code{nil}.  If returns
@samp{""} if @var{var} is set but null.  Within Emacs, the environment
variable values are kept in the Lisp variable @code{process-environment}.

@example
@group
(getenv "USER")
     @result{} "lewis"

@end group
@end example
@end deffn

@c Emacs 19 feature
@deffn Command setenv variable &optional value
This command sets the value of the environment variable named
@var{variable} to @var{value}.  @var{variable} should be a string.
Internally, Emacs Lisp can handle any string.  However, normally
@var{variable} should be a valid shell identifier, that is, a sequence
of letters, digits and underscores, starting with a letter or
underscore.  Otherwise, errors may occur if subprocesses of Emacs try
to access the value of @var{variable}.  If @var{value} is omitted or
@code{nil}, @code{setenv} removes @var{variable} from the environment.
Otherwise, @var{value} should be a string.

@code{setenv} works by modifying @code{process-environment}; binding
that variable with @code{let} is also reasonable practice.

@code{setenv} returns the new value of @var{variable}, or @code{nil}
if it removed @var{variable} from the environment.
@end deffn

@defvar process-environment
This variable is a list of strings, each describing one environment
variable.  The functions @code{getenv} and @code{setenv} work by means

If it is impossible to obtain the load average, this function signals
an error.  On some platforms, access to load averages requires
installing Emacs as setuid or setgid so that it can read kernel
information, and that usually isn't advisable.

If the 1-minute load average is available, but the 5- or 15-minute
averages are not, this function returns a shortened list containing
the available averages.

@example
@group
(load-average)
     @result{} (169 48 36)
@end group

@end group
@end example
@end defun

@defun emacs-pid
This function returns the process @acronym{ID} of the Emacs process,
as an integer.
@end defun

@defvar tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
The value is @code{nil} if Emacs is running under a window system.
@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.  @code{""} stands for the user who
originally logged in.  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.

is set, that value is used.  Otherwise, if the environment variable
@code{USER} is set, that value is used.  Otherwise, the value is based
on the effective @acronym{UID}, not the real @acronym{UID}.

If you specify @var{uid}, the value is the user name that corresponds
to @var{uid} (which should be an integer), or @code{nil} if there is
no such user.

@example
@group
(user-login-name)
     @result{} "lewis"

@end example

If the Emacs job's user-id does not correspond to any known user (and
provided @code{NAME} is not set), the value is @code{"unknown"}.

If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
or a string (a login name).  Then @code{user-full-name} returns the full
name corresponding to that user-id or login name.  If you specify a
user-id or login name that isn't defined, it returns @code{nil}.
@end defun

@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
instead of the current time.  The argument should be a list whose first
two elements are integers.  Thus, you can use times obtained from
@code{current-time} (see below) and from @code{file-attributes}
(@pxref{Definition of file-attributes}).  @var{time-value} can also be
a cons of two integers, but this is considered obsolete.

@example
@group
(current-time-string)
     @result{} "Wed Oct 14 22:21:05 1987"

@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 UTC (Coordinated Universal Time), which is
@ifnottex
@var{high} * 2**16 + @var{low}.
@end ifnottex
@tex
$high*2^{16}+low$.

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{Definition of file-attributes}.
@end defun

@c Emacs 19 feature
@defun current-time-zone &optional time-value
This function returns a list describing the time zone that the user is

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
compute the value, the unknown elements of the list are @code{nil}.

The argument @var{time-value}, if given, specifies a time to analyze
instead of the current time.  The argument should have the same form
as for @code{current-time-string} (see above).  Thus, you can use
times obtained from @code{current-time} (see above) and from
@code{file-attributes}.  @xref{Definition of file-attributes}.
@end defun

@defun set-time-zone-rule tz
This function specifies the local time zone according to @var{tz}.  If
@var{tz} is @code{nil}, that means to use an implementation-defined
default time zone.  If @var{tz} is @code{t}, that means to use
Universal Time.  Otherwise, @var{tz} should be a string specifying a
time zone rule.
@end defun

@defun float-time &optional time-value
This function returns the current time as a floating-point number of
seconds since the epoch.  The argument @var{time-value}, if given,
specifies a time to convert instead of the current time.  The argument
should have the same form as for @code{current-time-string} (see
above).  Thus, it accepts the output of @code{current-time} and
@code{file-attributes}.

@emph{Warning}: Since the result is floating point, it may not be
exact.  Do not use this function if precise time stamps are required.
@end defun

  These functions convert time values (lists of two or three integers)
to strings or to calendrical information.  There is also a function to
convert calendrical information to a time value.  You can get time
values from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{Definition of file-attributes}).

Many operating systems are limited to time values that contain 32 bits
of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
operating systems have larger time values, and can represent times far

Here is what the elements mean:

@table @var
@item seconds
The number of seconds past the minute, as an integer between 0 and 59.
On some operating systems, this is 60 for leap seconds.
@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

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, @code{t} for Universal Time, or an
integer (as you would get from @code{decode-time}).  The specified
zone is used without any further alteration for daylight savings time.

If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
used as @var{zone}, and the arguments in between are ignored.  This
feature makes it possible to use the elements of a list returned by

things in an inconsistent state.  This is normally unproblematical
because most timer functions don't do a lot of work.  Indeed, for a
timer to call a function that takes substantial time to run is likely
to be annoying.

@deffn Command run-at-time time repeat function &rest args
This sets up a timer that calls the function @var{function} with
arguments @var{args} at time @var{time}.  If @var{repeat} is a number
(integer or floating point), the timer also runs every @var{repeat}
seconds after that.  If @var{repeat} is @code{nil}, the timer runs
only once.

@var{time} may specify an absolute or a relative time.

Absolute times may be specified in a wide variety of formats; this
function tries to accept all the commonly used date formats.  The most
convenient formats are strings.  Valid such formats include these two,

@example
@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}

@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}

@noindent
where in both examples all fields are numbers; the format that
@code{current-time-string} returns is also allowed, and many others
as well.

To specify a relative time as a string, use numbers followed by units.
For example:

@table @samp
@item 1 min
denotes 1 minute 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.

Not all convenient formats are strings.  If @var{time} is a number
(integer or floating point), that specifies a relative time measured
in seconds.

In most cases, @var{repeat} has no effect on when @emph{first} call
takes place---@var{time} alone specifies that.  There is one exception:
if @var{time} is @code{t}, then the timer runs whenever the time is a
multiple of @var{repeat} seconds after the epoch.  This is useful for
functions like @code{display-time}.

The function @code{run-at-time} returns a timer value that identifies
the particular scheduled future action.  You can use this value to call
@code{cancel-timer} (see below).
@end deffn

@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
Execute @var{body}, but give up after @var{seconds} seconds.  If
@var{body} finishes before the time is up, @code{with-timeout} returns
the value of the last form in @var{body}.  If, however, the execution of

  The function @code{y-or-n-p-with-timeout} provides a simple way to use
a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
Queries}.

@deffn Command run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for @var{secs}
seconds.  The value of @var{secs} may be an integer or a floating point
number.

If @var{repeat} is @code{nil}, the timer runs just once, the first time

non-@code{nil}, which means to run the timer @emph{each time} Emacs
remains idle for @var{secs} seconds.

The function @code{run-with-idle-timer} returns a timer value which you
can use in calling @code{cancel-timer} (see below).
@end deffn

@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

set up to repeat will subsequently run another time, one by one.

@defun cancel-timer timer
Cancel the requested action for @var{timer}, which should be a value
previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
This cancels the effect of that call to one of these functions; the
arrival of the specified time will not cause anything special to happen.
@end defun

@node Terminal Input
@section Terminal Input
@cindex terminal input

@node Input Modes
@subsection Input Modes
@cindex input modes
@cindex terminal input modes

@defun set-input-mode interrupt flow meta &optional 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.

@code{function-key-map} and then with @code{key-translation-map}.

@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard.  The value is a character.  Only the modifiers of the
character matter.  Each time the user types a keyboard key, it is
altered as if those modifier keys were held down.  For instance, if
you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
keyboard input characters typed during the scope of the binding will
have the control and meta modifiers applied to them.  The character
@code{?\C-@@}, equivalent to the integer 0, does not count as a control
character for this purpose, but as a character with no modifiers.
Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
modification.

When using a window system, the program can ``press'' any of the
modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
keys can be virtually pressed.

Note that this variable applies only to events that really come from
the keyboard, and has no effect on mouse events or any other events.
@end defvar

@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}.
(It can also be a string or vector, but this is considered obsolete.)

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.

Note that this translation is the first thing that happens to a
character after it is read from the terminal.  Record-keeping features
such as @code{recent-keys} and dribble files record the characters after
translation.

Note also that this translation is done before the characters are
supplied to input methods (@pxref{Input Methods}).  Use
@code{translation-table-for-input} (@pxref{Translation of Characters}),
if you want to translate characters after input methods operate.
@end defvar

@defun keyboard-translate from to
This function modifies @code{keyboard-translate-table} to translate
character code @var{from} into character code @var{to}.  It creates

@end group
@end example

Finally, if you have enabled keyboard character set decoding using
@code{set-keyboard-coding-system}, decoding is done after the
translations listed above.  @xref{Terminal I/O Encoding}.  In future
Emacs versions, character set decoding may be done before the other
translations.

@node Recording Input
@subsection Recording Input

Termcap entries or to undesirable settings of terminal options more
often than to 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.

You close the termscript file by calling this function with an
argument of @code{nil}.

See also @code{open-dribble-file} in @ref{Recording Input}.

@example
@group
(open-termscript "../junk/termscript")
     @result{} nil

  As window systems and PC terminal emulators replace character-only
terminals, the flow control problem is gradually disappearing.  For the
mean time, Emacs provides a convenient way of enabling flow control if
you want it: call the function @code{enable-flow-control}.

@deffn Command enable-flow-control &optional arg
When @var{arg} is a positive integer, this function enables use of
@kbd{C-s} and @kbd{C-q} for output flow control, and provides the
characters @kbd{C-\} and @kbd{C-^} as aliases for them using
@code{keyboard-translate-table} (@pxref{Translating Input}).

When @var{arg} is a negative integer or zero, it disables these
features.  When @var{arg} is @code{nil} or omitted, it toggles.
Interactively, @var{arg} is the prefix argument.  If non-@code{nil},
its numeric value is used.
@end deffn

You can use the function @code{enable-flow-control-on} in your
init file to enable flow control automatically on certain
terminal types.

@enumerate
@item
@cindex @sc{cbreak}
It sets @sc{cbreak} mode for terminal input, and tells the operating
system to handle flow control.  This is done using @code{set-input-mode}.

@item
It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
@kbd{C-^} into @kbd{C-s} and @kbd{C-q}.  Except at its very
lowest level, Emacs never knows that the characters typed were anything

@defvar emacs-save-session-functions
@tindex emacs-save-session-functions
Emacs supports saving state by using a hook called
@code{emacs-save-session-functions}.  Each function in this hook is
called when the session manager tells Emacs that the window system is
shutting down.  The functions are called with no arguments and with the
current buffer set to a temporary buffer.  Each function can use
@code{insert} to add Lisp code to this buffer.  At the end, Emacs
saves the buffer in a file that a subsequent Emacs invocation will
load in order to restart the saved session.

If a function in @code{emacs-save-session-functions} returns
non-@code{nil}, Emacs tells the session manager to cancel the
shutdown.
@end defvar