@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
-@node System Interface, Tips, Calendar, Top
+@node System Interface, Antinews, Calendar, Top
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
* 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
@enumerate
@item
-It adds subdirectories to @code{load-path}, by running the file
-named @file{subdirs.el} in each directory that is listed.
+It adds subdirectories to @code{load-path}, by running the file named
+@file{subdirs.el} in each directory in the list. Normally this file
+adds the directory's subdirectories to the list, and these will be
+scanned in their turn. The files @file{subdirs.el} are normally
+generated automatically by Emacs installation.
@item
It sets the language environment and the terminal coding system,
@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{~}.
+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
It loads the library @file{default}, unless @code{inhibit-default-init}
It processes the action arguments from the command line.
@item
-It runs @code{term-setup-hook}.
+It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
@item
It calls @code{frame-notice-user-settings}, which modifies the
@defopt inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message.
You can suppress the startup echo area message by adding text with this
-form to your @file{.emacs} file:
+form to your init file:
@example
(setq inhibit-startup-echo-area-message
"@var{your-login-name}")
@end example
-Emacs explicitly checks for an expression as shown above in your
-@file{.emacs} file; your login name must appear in the expression as a
-Lisp string constant. Other methods of setting
+Emacs explicitly checks for an expression as shown above in your init
+file; your login name must appear in the expression as a Lisp string
+constant. Other methods of setting
@code{inhibit-startup-echo-area-message} to the same value do not
inhibit the startup message.
This way, you can easily inhibit the message for yourself if you wish,
-but thoughtless copying of your @file{.emacs} file will not inhibit the
-message for someone else.
+but thoughtless copying of your init file will not inhibit the message
+for someone else.
@end defopt
@node Init File
-@subsection The Init File: @file{.emacs}
+@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}.
+ When you start Emacs, it normally attempts to load your @dfn{init
+file}, a file in your home directory. Its normal name is @file{.emacs},
+but you can alternatively call it @file{.emacs.el}, which enables you to
+byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
+will be @file{.emacs.elc}.
+
+ The command-line switches @samp{-q} and @samp{-u} control whether and
+where to find the init file; @samp{-q} says not to load an init file,
+and @samp{-u @var{user}} says to load @var{user}'s init file instead of
+yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
+neither option is specified, Emacs uses the @code{LOGNAME} environment
+variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
+systems) variable, to find your home directory and thus your init file;
+this way, even if you have su'd, Emacs still loads your own init file.
+If those environment variables are absent, though, Emacs uses your
+user-id to find your home directory.
@cindex default init file
A site may have a @dfn{default init file}, which is the library named
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.
@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 the terminal-specific initialization.
+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
@code{(getenv "TERM")} to find the full name of the terminal
type.@refill
- Your @file{.emacs} file can prevent the loading of the
+ Your init file can prevent the loading of the
terminal-specific library by setting the variable
@code{term-file-prefix} to @code{nil}. This feature is useful when
experimenting with your own peculiar customizations.
terminal-specific library by setting the variable
@code{term-setup-hook}. This is a normal hook which Emacs runs using
@code{run-hooks} at the end of Emacs initialization, after loading both
-your @file{.emacs} file and any terminal-specific libraries. You can
+your init file and any terminal-specific libraries. You can
use this variable to define initializations for terminals that do not
have their own libraries. @xref{Hooks}.
@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
+init 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)}.
+your init 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.
@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
+init file, the default initialization file (if any) and the
terminal-specific Lisp file.
You can use @code{term-setup-hook} to override the definitions made by a
@defun command-line
This function parses the command line that Emacs was called with,
-processes it, loads the user's @file{.emacs} file and displays the
+processes it, loads the user's init file and displays the
startup messages.
@end defun
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.
Emacs was dumped. @xref{Building Emacs}.)
@end defvar
-@defun getenv var
+@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
HOME=/user/lewis
@end group
@end example
-@end defun
+@end deffn
@c Emacs 19 feature
@deffn Command setenv variable value
"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
and MS-Windows.
@end defvar
+@defun parse-colon-path path
+@tindex parse-colon-path
+This function takes a search path string such as would be the value of
+the @code{PATH} environment variable, and splits it at the separators,
+returning a list of directory names. @code{nil} in this list stands for
+``use the current directory.'' Although the function's name says
+``colon,'' it actually uses the value of @code{path-separator}.
+
+@example
+(parse-colon-path ":/foo:/bar")
+ @result{} (nil "/foo/" "/bar/")
+@end example
+@end defun
+
@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.
@end defun
@defvar tty-erase-char
-@tindex tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
@end defvar
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
+variable to some other value in your init file if you do not
want to use the default value.
@end defvar
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
+@ifnottex
@var{high} * 2**16 + @var{low}.
-@end ifinfo
+@end ifnottex
@tex
$high*2^{16}+low$.
@end tex
(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 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:
+@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
+@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
@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
because that is how @samp{%S} normally pads to two positions.
+
+The characters @samp{E} and @samp{O} act as modifiers when used between
+@samp{%} and one of the letters in the table above. @samp{E} specifies
+using the current locale's ``alternative'' version of the date and time.
+In a Japanese locale, for example, @code{%Ex} might yield a date format
+based on the Japanese Emperors' reigns. @samp{E} is allowed in
+@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
+@samp{%EY}.
+
+@samp{O} means to use the current locale's ``alternative''
+representation of numbers, instead of the ordinary decimal digits. This
+is allowed with most letters, all the ones that output numbers.
+
+If @var{universal} is non-@code{nil}, that means to describe the time as
+Universal Time; @code{nil} means describe it using what Emacs believes
+is the local time zone (see @code{current-time-zone}).
+
+This function uses the C library function @code{strftime} to do most of
+the work. In order to communicate with that function, it first encodes
+its argument using the coding system specified by
+@code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
+returns the resulting string, @code{format-time-string} decodes the
+string using that same coding system.
+@end defun
+
+@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 time
@var{dow} and @var{zone}.
@end defun
-@defun encode-time seconds minutes hour day month year &optional @dots{}zone
+@defun encode-time seconds minutes hour day month year &optional 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}.
+to stand for years above 1900, or years above 2000, 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
if you try to encode a time that is out of range, an error results.
@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
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
+@deffn Command open-dribble-file filename
@cindex dribble file
This function opens a @dfn{dribble file} named @var{filename}. When a
dribble file is open, each input event from the keyboard or mouse (but
If the file name is not absolute, it is expanded against
the directory @code{data-directory}.
+@item :data @var{data}
+This specifies the sound to play without need to refer to a file. The
+value, @var{data}, should be a string containing the same bytes as a
+sound file. We recommend using a unibyte string.
+
@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.
+
+@item :device @var{device}
+This specifies the system device on which to play the sound, as a
+string. The default device is system-dependent.
@end table
Before actually playing the sound, @code{play-sound}
Each function is called with one argument, @var{sound}.
@end defun
+@defun play-sound-file file &optional volume device
+@tindex play-sound-file
+This function is an alternative interface to playing a sound @var{file}
+specifying an optional @var{volume} and @var{device}.
+@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
+@node X11 Keysyms
+@section Operating on X11 Keysyms
To define system-specific X11 keysyms, set the variable
@code{system-key-alist}.
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
+@ifnottex
-2**28),
-@end ifinfo
+@end ifnottex
@tex
$-2^{28}$),
@end tex
For example @code{(168 . mute-acute)} defines a system-specific key (used
by HP X servers) whose numeric code is
-@ifinfo
+@ifnottex
-2**28
-@end ifinfo
+@end ifnottex
@tex
$-2^{28}$
@end tex
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
@end deffn
You can use the function @code{enable-flow-control-on} in your
-@file{.emacs} file to enable flow control automatically on certain
+init file to enable flow control automatically on certain
terminal types.
@defun enable-flow-control-on &rest termtypes
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
HCoop / bpt / emacs.git / blobdiff