* 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.
using a window system. This library's name is
@file{term/@var{windowsystem}-win.el}.
+@item
+It processes the initial options. (Some of them are handled
+even earlier than this.)
+
@item
It initializes the X window frame and faces, if appropriate.
that with @code{inhibit-startup-echo-area-message}.
@item
-It processes any remaining command line arguments.
+It processes the action arguments from the command line.
@item
It runs @code{term-setup-hook}.
loads this @emph{before} the user's init file. You can inhibit the
loading of this file with the option @samp{-no-site-file}.
+@defvar site-run-file
+This variable specifies the site-customization file to load
+before the user's init file. Its normal value is @code{"site-start"}.
+@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}
system, the user's @sc{uid}, and so on.
@defvar 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 19.1.
+The value of this variable is a symbol indicating the type of operating
+system Emacs is operating on. Here is a table of the possible values:
@table @code
@item aix-v3
@item berkeley-unix
Berkeley BSD.
+@item dgux
+Data General DGUX operating system.
+
+@item gnu
+A GNU system (using the GNU kernel, which consists of the HURD and Mach).
+
+@item gnu/linux
+A variant GNU system using the Linux kernel.
+
@item hpux
-Hewlett-Packard operating system.
+Hewlett-Packard HPUX operating system.
@item irix
Silicon Graphics Irix system.
-@item linux
-The free Linux operating system.
+@item ms-dos
+Microsoft MS-DOS ``operating system.''
+
+@item next-mach
+NeXT Mach-based system.
@item rtu
Masscomp RTU, UCB universe.
@item vax-vms
VAX VMS.
+@item windows-nt
+Microsoft windows NT.
+
@item xenix
SCO Xenix 386.
@end table
@end example
@end defun
+@vindex system-name
+ The symbol @code{system-name} is a variable as well as a function. In
+fact, the function returns whatever value the variable
+@code{system-name} currently holds. Thus, you can set the variable
+@code{system-name} in case Emacs is confused about the name of your
+system. The variable is also useful for constructing frame titles
+(@pxref{Frame Titles}).
+
+@defvar mail-host-address
+If this variable is non-@code{nil}, it is used instead of
+@code{system-name} for purposes of generating email addresses. For
+example, it is used when constructing the default value of
+@code{user-mail-address}. @xref{User Identification}. (Since this is
+done when Emacs starts up, the value actually used is the one saved when
+Emacs was dumped. @xref{Building Emacs}.)
+@end defvar
+
@defun getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
@end smallexample
@end defvar
+@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.
@node User Identification
@section User Identification
-@defun user-login-name
-This function returns the name under which the user is logged in. If
-the environment variable @code{LOGNAME} 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 @sc{uid}, not the
-real @sc{uid}.
+@defvar user-mail-address
+This holds the nominal email address of the user who is using Emacs.
+Emacs normally sets this variable to a default value after reading your
+init files, but not if you have already set it. So you can set the
+variable to some other value in your @file{~/.emacs} file if you do not
+want to use the default value.
+@end defvar
+
+@defun user-login-name &optional uid
+If you don't specify @var{uid}, this function returns the name under
+which the user is logged in. If the environment variable @code{LOGNAME}
+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 @sc{uid}, not the real @sc{uid}.
+
+If you specify @var{uid}, the value is the user name that corresponds
+to @var{uid} (which should be an integer).
@example
@group
@end example
@end defun
+@vindex user-full-name
+@vindex user-real-login-name
+@vindex user-login-name
+ The symbols @code{user-login-name}, @code{user-real-login-name} and
+@code{user-full-name} are variables as well as functions. The functions
+return the same values that the variables hold. These variables allow
+you to ``fake out'' Emacs by telling the functions what to return. The
+variables are also useful for constructing frame titles (@pxref{Frame
+Titles}).
+
@defun user-real-uid
This function returns the real @sc{uid} of the user.
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
-@code{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 may be added at the end.
+@code{substring} to extract pieces of it. It is wise to count the
+characters from the beginning of the string rather than from the end, as
+additional information may be added at the end.
@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 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 below) and from @code{file-attributes} (@pxref{File Attributes}).
+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
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 below) and from @code{file-attributes} (@pxref{File Attributes}).
+(see above) and from @code{file-attributes} (@pxref{File Attributes}).
+@end defun
+
+@node Time Conversion
+@section Time Conversion
+
+ 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
+in the past or future.
+
+Time conversion functions always use the Gregorian calendar, even for
+dates before the Gregorian calendar was introduced. Year numbers count
+the number of years since the year 1 B.C., and do not skip zero as
+traditional Gregorian years do; for example, the year number -37
+represents the Gregorian year 38 B.C@.
+
+@defun format-time-string format-string time
+This function converts @var{time} to a string according to
+@var{format-string}. The argument @var{format-string} may contain
+@samp{%}-sequences which say to substitute parts of the time. Here is a
+table of what the @samp{%}-sequences mean:
+
+@table @samp
+@item %a
+This stands for the abbreviated name of the day of week.
+@item %A
+This stands for the full name of the day of week.
+@item %b
+This stands for the abbreviated name of the month.
+@item %B
+This stands for the full name of the month.
+@item %c
+This is a synonym for @samp{%x %X}.
+@item %C
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%A, %B %e, %Y}.
+@item %d
+This stands for the day of month, zero-padded.
+@item %D
+This is a synonym for @samp{%m/%d/%y}.
+@item %e
+This stands for the day of month, blank-padded.
+@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
+This stands for the hour (1-12), blank padded.
+@item %m
+This stands for the month (01-12).
+@item %M
+This stands for the minute (00-59).
+@item %n
+This stands for a newline.
+@item %p
+This stands for @samp{AM} or @samp{PM}, as appropriate.
+@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
+This stands for the week of the year (01-52), assuming that weeks
+start on Sunday.
+@item %w
+This stands for the numeric day of week (0-6). Sunday is day 0.
+@item %W
+This stands for the week of the year (01-52), assuming that weeks
+start on Monday.
+@item %x
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%D}.
+@item %X
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%T}.
+@item %y
+This stands for the year without century (00-99).
+@item %Y
+This stands for the year with century.
+@item %Z
+This stands for the time zone abbreviation.
+@end table
+@end defun
+
+@defun decode-time time
+This function converts a time value into calendrical information. The
+return value is a list of nine elements, as follows:
+
+@example
+(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
+@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.
+@item month
+The month of the year, as an integer between 1 and 12.
+@item year
+The year, an integer typically greater than 1900.
+@item dow
+The day of week, as an integer between 0 and 6, where 0 stands for
+Sunday.
+@item dst
+@code{t} if daylight savings time is effect, otherwise @code{nil}.
+@item zone
+An integer indicating the time zone, as the number of seconds east of
+Greenwich.
+@end table
+
+Note that Common Lisp has different meanings for @var{dow} and
+@var{zone}.
+@end defun
+
+@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}) 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
+@code{decode-time} as the arguments to @code{encode-time}, like this:
+
+@example
+(apply 'encode-time (decode-time @dots{}))
+@end example
@end defun
@node Timers
-@section Timers
+@section Timers for Delayed Execution
+@cindex timer
+
+ You can set up a @dfn{timer} to call a function at a specified future time or
+after a certain length of idleness.
-You can set up a timer to call a function at a specified future time.
+ Emacs cannot run a timer at any arbitrary point in a Lisp program; it
+can run them only when Emacs could accept output from a subprocess:
+namely, while waiting or inside certain primitive functions such as
+@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a
+timer's execution may be delayed if Emacs is busy. However, the time of
+execution is very precise if Emacs is idle.
@defun run-at-time time repeat function &rest args
This function arranges to call @var{function} with arguments @var{args}
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; The form
+Absolute times may be specified in a variety of formats; The form
@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
@var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
the format that @code{current-time-string} returns is also allowed.
denotes exactly 103 months, 123 days, and 10862 seconds from now.
@end table
-If @var{time} is an integer, that specifies a relative time measured in
-seconds.
+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 an integer, it
-specifies a repetition period measured in seconds. In any case, @var{repeat}
-has no effect on when @emph{first} call takes place---@var{time} specifies
-that.
+called just once, at @var{time}. If @var{repeat} is a number, it
+specifies a repetition period measured in seconds. In any case,
+@var{repeat} has no effect on when @emph{first} call takes
+place---@var{time} alone specifies that.
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}.
+@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
+@var{body} is cut short by the timeout, then @code{with-timeout}
+executes all the @var{timeout-forms} and returns the value of the last
+of them.
+
+This macro works by set a timer to run after @var{seconds} seconds. If
+@var{body} finishes before that time, it cancels the timer. If the
+timer actually runs, it terminates execution of @var{body}, then
+executes @var{timeout-forms}.
+
+Since timers can run within a Lisp program only when the program calls a
+primitive that can wait, @code{with-timeout} cannot stop executing
+@var{body} while it is in the midst of a computation---only when it
+calls one of those primitives. So use @code{with-timeout} only with a
+@var{body} that waits for input, not one that does a long computation.
+@end defmac
+
+ 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
+Emacs remains idle for a long enough time. More often @var{repeat} is
+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
+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
+have little effect on idle timers. 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 cancel-timer timer
Cancel the requested action for @var{timer}, which should be a value
-previously returned by @code{run-at-time}. 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.
+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
@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.
+@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates
+directly with X, it ignores this argument and uses interrupts if that is
+the way it knows how to communicate.
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
@kbd{C-s}) flow control for output to the terminal. This has no effect except
flow control for output to the terminal. This value has no effect
unless @var{interrupt} is non-@code{nil}.
@item meta
-is non-@code{t} if Emacs treats the eighth bit of input characters as
+is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
input character; any other value means Emacs uses all eight bits as the
basic character code.
@end table
@end defun
-@defvar meta-flag
-This variable used to control whether to treat the eight bit in keyboard
-input characters as the @key{Meta} bit. @code{nil} meant no, and
-anything else meant yes. This variable existed in Emacs versions 18 and
-earlier but no longer exists in Emacs 19; use @code{set-input-mode}
-instead.
-@end defvar
-
@node Translating Input
@subsection Translating Input Events
@cindex translating input events
- This section describes features for translating input events into other
-input events before they become part of key sequences.
+ This section describes features for translating input events into
+other input events before they become part of key sequences. These
+features apply to each event in the order they are described here: each
+event is first modified according to @code{extra-keyboard-modifiers},
+then translated through @code{keyboard-translate-table} (if applicable).
+If it is being read as part of a key sequence, it is then added to the
+sequece being read; then subsequences containing it are checked first
+with @code{function-key-map} and then with @code{key-translation-map}.
@c Emacs 19 feature
@defvar extra-keyboard-modifiers
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 you use X windows, the program can ``press'' any of the modifier
+When using X windows, 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
or enlarges the translate table if necessary.
@end defun
+ The remaining translation features translate subsequences of key
+sequences being read. They are implemented in @code{read-key-sequence}
+and have no effect on @code{read-char}.
+
@defvar function-key-map
This variable holds a keymap that describes the character sequences
sent by function keys on an ordinary character terminal. This keymap
uses the same data structure as other keymaps, but is used differently: it
-specifies translations to make while reading events.
+specifies translations to make while reading event sequences.
If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
@code{function-key-map}.
@item
-@code{key-translation-map} overrides actual key bindings.
+@code{key-translation-map} overrides actual key bindings. For example,
+if @kbd{C-x f} has a binding in @code{key-translation-map}, that
+translation takes effect even though @kbd{C-x f} also has a key binding
+in the global map.
@end itemize
The intent of @code{key-translation-map} is for users to map one
to turn the character that follows into a Hyper character:
@example
+@group
(defun hyperify (prompt)
(let ((e (read-event)))
(vector (if (numberp e)
(let ((symbol (if (symbolp e) e (car e))))
(setq symbol (intern (concat string
(symbol-name symbol))))
+@end group
+@group
(if (symbolp e)
symbol
(cons symbol (cdr e)))))
(define-key function-key-map "\C-ch" 'hyperify)
+@end group
@end example
@pindex iso-transl
It is not a problem if the alist defines keysyms for other X servers, as
long as they don't conflict with the ones used by the X server actually
in use.
+
+The variable is always local to the current X terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
@node Flow Control
model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
and @kbd{C-q} were sent by the computer to turn the punch on and off!
- GNU Emacs version 19 provides a convenient way of enabling flow
-control if you want it: call the function @code{enable-flow-control}.
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+Emacs provides a convenient way of enabling flow control if you want it:
+call the function @code{enable-flow-control}.
@defun enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
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 output descriptor when
+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.)