@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
@node System Interface, Antinews, Calendar, Top
* 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).
+* Time Calculations:: Adding, subtracting, comparing times, etc.
* 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.
+* X11 Keysyms:: Operating on key symbols for X Windows
* Flow Control:: How to turn output flow control on or off.
* Batch Mode:: Running Emacs without terminal interaction.
+* Session Management:: Saving and restoring state with X Session Management.
@end menu
@node Starting Up
@file{site-start.el}.
@cindex @file{site-start.el}
-@item
+@item
It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
@samp{-no-init-file}, 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
+@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
the buffer @samp{*scratch*} is still current and still in Fundamental
mode.
-@item
+@item
It loads the terminal-specific Lisp file, if any, except when in batch
mode or using a window system.
It displays the initial echo area message, unless you have suppressed
that with @code{inhibit-startup-echo-area-message}.
-@item
+@item
It processes the action arguments from the command line.
-@item
+@item
It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
@item
parameters of the selected frame according to whatever the init files
specify.
-@item
+@item
It runs @code{window-setup-hook}. @xref{Window Systems}.
-@item
+@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
Emacs.
@end defvar
- @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
+ @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@file{.emacs} file.
uses @samp{internal} as the terminal type.
@end defvar
-@defvar term-setup-hook
+@defvar term-setup-hook
This variable is a normal hook that Emacs runs after loading your
init file, the default initialization file (if any) and the
terminal-specific Lisp file.
-@var{option}
@end example
-The elements of the @code{command-switch-alist} look like this:
+The elements of the @code{command-switch-alist} look like this:
@example
(@var{option} . @var{handler-function})
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}.
+Arguments, , Command Line Arguments, emacs, The GNU Emacs Manual}.
@end defvar
@defvar command-line-args
@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. This hook is not run in batch mode.
@end defvar
@node 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 Windows or MS Windows).
+a window system (X or MS Windows).
@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
@item berkeley-unix
Berkeley BSD.
+@item cygwin
+Cygwin.
+
@item dgux
Data General DGUX operating system.
process-environment
@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
"PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
- "USER=lewis"
+ "USER=lewis"
@end group
@group
- "TERM=ibmapa16"
+ "TERM=ibmapa16"
"SHELL=/bin/csh"
"HOME=/user/lewis")
@end group
@end smallexample
+
+If @code{process-environment} contains ``duplicate'' elements that
+specify the same environment variable, the first of these elements
+specifies the variable, and the other ``duplicates'' are ignored.
@end defvar
@defvar path-separator
@defun user-real-uid
This function returns the real @sc{uid} of the user.
+The value may be a floating point number.
@example
@group
@end defun
@defun user-uid
-This function returns the effective @sc{uid} of the user.
+This function returns the effective @sc{uid} of the user.
+The value may be a floating point number.
@end defun
@node Time of Day
(see above) and from @code{file-attributes} (@pxref{File Attributes}).
@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
+
@node Time Conversion
@section Time Conversion
traditional Gregorian years do; for example, the year number @minus{}37
represents the Gregorian year 38 B.C@.
+@defun date-to-time string
+This function parses the time-string @var{string} and returns the
+corresponding time value.
+@end defun
+
@defun format-time-string format-string &optional time universal
This function converts @var{time} (or the current time, if @var{time} is
omitted) to a string according to @var{format-string}. The argument
string using that same coding system.
@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:
+@defun seconds-to-time seconds
+This function converts @var{seconds}, a floating point number of
+seconds since the epoch, to a time value and returns that. To perform
+the inverse conversion, use @code{float-time}.
+@end defun
+
+@defun decode-time &optional time
+This function converts a time value into calendrical information. If
+you don't specify @var{time}, it decodes the current time. 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})
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.
+For instance, years before 1970 do not work on some systems;
+on others, years as early as 1901 do work.
+@end defun
+
+@node Time Calculations
+@section Time Calculations
+
+ These functions perform calendrical computations using time values
+(the kind of list that @code{current-time} returns).
+
+@defun time-less-p t1 t2
+This returns @code{t} if time value @var{t1} is less than time value
+@var{t2}.
+@end defun
+
+@defun time-subtract t1 t2
+This returns the time difference @var{t1} @minus{} @var{t2} between
+two time values, in the same format as a time value.
+@end defun
+
+@defun time-add t1 t2
+This returns the sum of two time values, one of which ought to
+represent a time difference rather than a point in time.
+Here is how to add a number of seconds to a time value:
+
+@example
+(time-add @var{time} (seconds-to-time @var{seconds}))
+@end example
+@end defun
+
+@defun time-to-days time
+This function returns the number of days between the beginning of year
+1 and @var{time}.
+@end defun
+
+@defun time-to-day-in-year time
+This returns the day number within the year corresponding to @var{time}.
+@end defun
+
+@defun date-leap-year-p year
+This function returns @code{t} if @var{year} is a leap year.
@end defun
@node 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 @dfn{timer} to call a function at a specified
+future time or after a certain length of idleness.
Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
timer's execution may be delayed if Emacs is busy. However, the time of
execution is very precise if Emacs is idle.
+ Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
+function, because quitting out of many timer functions can leave
+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 calls 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
100 input events, not counting events generated by keyboard macros.
(These are excluded because they are less interesting for debugging; it
should be enough to see the events that invoked the macros.)
+
+A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
+causes this function to return an empty vector immediately afterward.
@end defun
@deffn Command open-dribble-file filename
is called with one argument, a property list that describes the sound.
@end defvar
-@node Special Keysyms
-@section System-Specific X11 Keysyms
+@node X11 Keysyms
+@section Operating on X11 Keysyms
To define system-specific X11 keysyms, set the variable
@code{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,
+including the ``vendor specific'' bit,
@ifnottex
-2**28),
@end ifnottex
-@tex
+@tex
$-2^{28}$),
@end tex
and @var{symbol} is the name for the function key.
@ifnottex
-2**28
@end ifnottex
-@tex
+@tex
$-2^{28}$
@end tex
+ 168.
buffer-local. @xref{Multiple Displays}.
@end defvar
+You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
+
+@defvar x-alt-keysym
+@defvarx x-meta-keysym
+@defvarx x-hyper-keysym
+@defvarx x-super-keysym
+The name of the keysym that should stand for the Alt modifier
+(respectively, for Meta, Hyper, and Super). For example, here is
+how to swap the Meta and Alt modifiers within Emacs:
+@lisp
+(setq x-alt-keysym 'meta)
+(setq x-meta-keysym 'alt)
+@end lisp
+@end defvar
+
@node Flow Control
@section Flow Control
@cindex flow control characters
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
+in batch mode. Similarly, input that would normally come from the
+minibuffer is read from the standard input descriptor.
+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.)
@defvar noninteractive
This variable is non-@code{nil} when Emacs is running in batch mode.
@end defvar
+
+@node Session Management
+@section Session Management
+@cindex session manager
+
+Emacs supports the X Session Management Protocol for suspension and
+restart of applications. In the X Window System, a program called the
+@dfn{session manager} has the responsibility to keep track of the
+applications that are running. During shutdown, the session manager
+asks applications to save their state, and delays the actual shutdown
+until they respond. An application can also cancel the shutdown.
+
+When the session manager restarts a suspended session, it directs
+these applications to individually reload their saved state. It does
+this by specifying a special command-line argument that says what
+saved session to restore. For Emacs, this argument is @samp{--smid
+@var{session}}.
+
+@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 functions can use @code{insert} to add
+Lisp code to this buffer. At the end, Emacs saves the buffer in a
+file that Emacs 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
+
+Here is an example that just inserts some text into *scratch* when
+Emacs is restarted by the session manager.
+
+@example
+@group
+(add-hook 'emacs-save-session-functions 'save-yourself-test)
+@end group
+
+@group
+(defun save-yourself-test ()
+ (insert "(save-excursion
+ (switch-to-buffer \"*scratch*\")
+ (insert \"I am restored\"))")
+ nil)
+@end group
+@end example
+
+@ignore
+ arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
+@end ignore
HCoop / bpt / emacs.git / blobdiff