@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
@node System Interface, Antinews, Display, Top
@node Startup Summary
@subsection Summary: Sequence of Actions at Startup
-@cindex initialization
+@cindex initialization of Emacs
@cindex startup of Emacs
@cindex @file{startup.el}
@code{string-match}.
@end defvar
+@cindex system type and name
@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 possible values:
@node User Identification
@section User Identification
+@cindex user identification
@defvar init-file-user
This variable says which user's init files should be used by
@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;
+zone. Both elements change when daylight saving 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.
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}.
+@code{t} if daylight saving time is effect, otherwise @code{nil}.
@item zone
An integer indicating the time zone, as the number of seconds east of
Greenwich.
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
+its daylight saving 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.
+zone is used without any further alteration for daylight saving 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
@node Processor Run Time
@section Processor Run time
+@cindex processor run time
@defun get-internal-run-time
This function returns the processor run time used by Emacs as a list
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.
+to be annoying. If a timer function needs to allow quitting, it
+should use @code{with-local-quit} (@pxref{Quitting}). For example, if
+a timer function calls @code{accept-process-output} to receive output
+from an external process, that call should be wrapped inside
+@code{with-local-quit}, to ensure that @kbd{C-g} works if the external
+process hangs.
It is usually a bad idea for timer functions to alter buffer
contents. When they do, they usually should call @code{undo-boundary}
@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.
+(integer or floating point), the timer is scheduled to run again every
+@var{repeat} seconds after @var{time}. 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}
-@end example
-
-@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.
+Absolute times may be specified using a string with a limited variety
+of formats, and are taken to be times @emph{today}, even if already in
+the past. The recognized forms are @samp{@var{xxxx}},
+@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
+and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
+@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
+@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
+@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
+to separate the hour and minute parts.
To specify a relative time as a string, use numbers followed by units.
For example:
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.
+(integer or floating point), that specifies a relative time measured in
+seconds. The result of @code{encode-time} can also be used to specify
+an absolute value for @var{time}.
In most cases, @var{repeat} has no effect on when @emph{first} call
takes place---@var{time} alone specifies that. There is one exception:
@code{cancel-timer} (see below).
@end deffn
+ A repeating timer nominally ought to run every @var{repeat} seconds,
+but remember that any invocation of a timer can be late. Lateness of
+one repetition has no effect on the scheduled time of the next
+repetition. For instance, if Emacs is busy computing for long enough
+to cover three scheduled repetitions of the timer, and then starts to
+wait, it will immediately call the timer function three times in
+immediate succession (presuming no other timers trigger before or
+between them). If you want a timer to run again no less than @var{n}
+seconds after the last invocation, don't use the @var{repeat} argument.
+Instead, the timer function should explicitly reschedule the timer.
+
+@defvar timer-max-repeats
+This variable's value specifies the maximum number of times to repeat
+calling a timer function in a row, when many previously scheduled
+calls were unavoidably delayed.
+@end defvar
+
@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
@c Emacs 19 feature
@defun current-idle-time
-This function returns the length of time Emacs has been idle, 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 of idleness, which is
+If Emacs is idle, this function returns the length of time Emacs has
+been idle, 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 of idleness, which is
@ifnottex
@var{high} * 2**16 + @var{low}.
@end ifnottex
start of the current second (or 0 for systems that return time with
the resolution of only one second).
+When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
+This is a convenient way to test whether Emacs is idle.
+
The main use of this function is when an idle timer function wants to
``take a break'' for a while. It can set up another idle timer to
call the same function again, after a few seconds more idleness.
@node Recording Input
@subsection Recording Input
+@cindex recording input
@defun recent-keys
-This function returns a vector containing the last 100 input events from
+This function returns a vector containing the last 300 input events from
the keyboard or mouse. All input events are included, whether or not
they were used as parts of key sequences. Thus, you always get the last
100 input events, not counting events generated by keyboard macros.
@node X11 Keysyms
@section Operating on X11 Keysyms
+@cindex X11 keysyms
To define system-specific X11 keysyms, set the variable
@code{system-key-alist}.
@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
HCoop / bpt / emacs.git / blobdiff