@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node System Interface
automatically when Emacs is installed.
@item
-If the library @file{leim-list.el} exists, Emacs loads it. This
-optional library is intended for registering input methods; Emacs
-looks for it in @code{load-path} (@pxref{Library Search}), skipping
-those directories containing the standard Emacs libraries (since
-@file{leim-list.el} should not exist in those directories).
+It loads any @file{leim-list.el} that it finds in the @code{load-path}
+directories. This file is intended for registering input methods.
+The search is only for any personal @file{leim-list.el} files that you
+may have created; it skips the directories containing the standard Emacs
+libraries (these should contain only a single @file{leim-list.el} file,
+which is compiled into the Emacs executable).
@vindex before-init-time
@item
@item
If started on a text terminal, it loads the terminal-specific
-Lisp library, which is specified by the variable
-@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done
+Lisp library (@pxref{Terminal-Specific}), and runs the hook
+@code{tty-setup-hook}. This is not done
in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
@c Now command-line calls command-line-1.
@item
If @code{initial-buffer-choice} is a string, it visits the file with
-that name. If the @file{*scratch*} buffer exists and is
+that name. If it is a function, it calls the function and selects the
+buffer returned by the function. It it is @code{t}, it selects the
+@file{*scratch*} buffer. If the @file{*scratch*} buffer exists and is
empty, it inserts @code{initial-scratch-message} into that buffer.
@c To make things nice and confusing, the next three items can be
@c daemon/session restore step?
@item
-It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
+It runs @code{emacs-startup-hook}.
@item
It calls @code{frame-notice-user-settings}, which modifies the
If non-@code{nil}, this variable is a string that specifies a file or
directory for Emacs to display after starting up, instead of the
startup screen.
-@ignore
-@c I do not think this should be mentioned. AFAICS it is just a dodge
-@c around inhibit-startup-screen not being settable on a site-wide basis.
+If its value is a function, Emacs calls that function which must
+return a buffer which is then displayed.
If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.
-@end ignore
@end defopt
@defopt inhibit-startup-echo-area-message
@defvar emacs-startup-hook
This normal hook is run, once, just after handling the command line
-arguments, just before @code{term-setup-hook}. In batch mode, Emacs
-does not run either of these hooks.
+arguments. In batch mode, Emacs does not run this hook.
@end defvar
@defvar user-init-file
run on that type of terminal. The library's name is constructed by
concatenating the value of the variable @code{term-file-prefix} and the
terminal type (specified by the environment variable @env{TERM}).
-Normally, @code{term-file-prefix} has the value
-@code{"term/"}; changing this is not recommended. Emacs finds the file
-in the normal manner, by searching the @code{load-path} directories, and
-trying the @samp{.elc} and @samp{.el} suffixes.
+Normally, @code{term-file-prefix} has the value @code{"term/"};
+changing this is not recommended. If there is an entry matching
+@env{TERM} in the @code{term-file-aliases} association list,
+Emacs uses the associated value in place of @env{TERM}.
+Emacs finds the file in the normal manner, by searching the
+@code{load-path} directories, and trying the @samp{.elc} and
+@samp{.el} suffixes.
@cindex Termcap
The usual role of a terminal-specific library is to enable special
keys to send sequences that Emacs can recognize. It may also need to
set or add to @code{input-decode-map} if the Termcap or Terminfo entry
-does not specify all the terminal's function keys. @xref{Terminal
-Input}.
+does not specify all the terminal's function keys. @xref{Terminal Input}.
- When the name of the terminal type contains a hyphen or underscore, and no library
-is found whose name is identical to the terminal's name, Emacs strips
-from the terminal's name the last hyphen or underscore and everything that follows
+ When the name of the terminal type contains a hyphen or underscore,
+and no library is found whose name is identical to the terminal's
+name, Emacs strips from the terminal's name the last hyphen or
+underscore and everything that follows
it, and tries again. This process is repeated until Emacs finds a
matching library, or until there are no more hyphens or underscores in the name
(i.e., there is no terminal-specific library). For example, if the
@file{term/xterm.el}. If necessary, the terminal library can evaluate
@code{(getenv "TERM")} to find the full name of the terminal type.
- 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.
+ Your init file can prevent the loading of the terminal-specific
+library by setting the variable @code{term-file-prefix} to @code{nil}.
You can also arrange to override some of the actions of the
-terminal-specific library by setting the variable
-@code{term-setup-hook}. This is a normal hook that Emacs runs
-at the end of its initialization, after loading both
-your init file and any terminal-specific libraries. You could
-use this hook to define initializations for terminals that do not
+terminal-specific library by using @code{tty-setup-hook}. This is
+a normal hook that Emacs runs after initializing a new text terminal.
+You could use this hook to define initializations for terminals that do not
have their own libraries. @xref{Hooks}.
-@defvar term-file-prefix
+@defopt term-file-prefix
@cindex @env{TERM} environment variable
If the value of this variable is non-@code{nil}, Emacs loads a
terminal-specific initialization file as follows:
terminal-initialization file.
On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
-@end defvar
+@end defopt
-@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.
+@defopt term-file-aliases
+This variable is an an association list mapping terminal types to
+their aliases. For example, an element of the form @code{("vt102"
+. "vt100")} means to treat a terminal of type @samp{vt102} like one of
+type @samp{vt100}.
+@end defopt
-You can use @code{term-setup-hook} to override the definitions made by a
-terminal-specific file.
+@defvar tty-setup-hook
+This variable is a normal hook that Emacs runs after initializing a
+new text terminal. (This applies when Emacs starts up in non-windowed
+mode, and when making a tty @command{emacsclient} connection.) The
+hook runs after loading your init file (if applicable) and the
+terminal-specific Lisp file, so you can use it to adjust the
+definitions made by that file.
For a related feature, @pxref{Window Systems, window-setup-hook}.
@end defvar
By default, the values are integers that are 100 times the system load
averages, but if @var{use-float} is non-@code{nil}, then they are
-returned as floating point numbers without multiplying by 100.
+returned as floating-point numbers without multiplying by 100.
If it is impossible to obtain the load average, this function signals
an error. On some platforms, access to load averages requires
@cindex UID
@defun user-real-uid
This function returns the real @acronym{UID} of the user.
-The value may be a floating point number, in the (unlikely) event that
+The value may be floating point, in the (unlikely) event that
the UID is too large to fit in a Lisp integer.
@end defun
@defun user-uid
This function returns the effective @acronym{UID} of the user.
-The value may be a floating point number.
+The value may be floating point.
@end defun
@cindex GID
@defun group-gid
This function returns the effective @acronym{GID} of the Emacs process.
-The value may be a floating point number.
+The value may be floating point.
@end defun
@defun group-real-gid
This function returns the real @acronym{GID} of the Emacs process.
-The value may be a floating point number.
+The value may be floating point.
@end defun
@defun system-users
integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of
two integers, @code{(@var{sec-high} @var{sec-low})}. The integers
@var{sec-high} and @var{sec-low} give the high and low bits of an
-integer number of seconds. This integer number,
+integer number of seconds. This integer,
@ifnottex
@var{high} * 2**16 + @var{low},
@end ifnottex
@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} (@pxref{Time of Day}).
+This function converts @var{seconds}, the number of seconds since the
+epoch, to a time value and returns that. To convert back, use
+@code{float-time} (@pxref{Time of Day}).
@end defun
@defun format-seconds format-string seconds
@deffn Command run-with-idle-timer secs repeat function &rest args
Set up a timer which runs the next time Emacs is idle for @var{secs}
-seconds. The value of @var{secs} may be an integer or a floating
-point number; a value of the type returned by @code{current-idle-time}
-is also allowed.
+seconds. The value of @var{secs} may be a number or a value of the type
+returned by @code{current-idle-time}.
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
dribble file is open, each input event from the keyboard or mouse (but
not those from keyboard macros) is written in that file. A
non-character event is expressed using its printed representation
-surrounded by @samp{<@dots{}>}.
+surrounded by @samp{<@dots{}>}. Be aware that sensitive information
+(such as passwords) may end up recorded in the dribble file.
You close the dribble file by calling this function with an argument
of @code{nil}.
-
-This function is normally used to record the input necessary to
-trigger an Emacs bug, for the sake of a bug report.
-
-@example
-@group
-(open-dribble-file "~/dribble")
- @result{} nil
-@end group
-@end example
@end deffn
See also the @code{open-termscript} function (@pxref{Terminal Output}).
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit,
@ifnottex
--2**28),
+@minus{}2**28),
@end ifnottex
@tex
$-2^{28}$),
For example @code{(168 . mute-acute)} defines a system-specific key (used
by HP X servers) whose numeric code is
@ifnottex
--2**28
+@minus{}2**28
@end ifnottex
@tex
$-2^{28}$
@item :timeout @var{timeout}
The timeout time in milliseconds since the display of the notification
-at which the notification should automatically close. If -1, the
+at which the notification should automatically close. If @minus{}1, the
notification's expiration time is dependent on the notification
server's settings, and may vary for the type of notification. If 0,
-the notification never expires. Default value is -1.
+the notification never expires. Default value is @minus{}1.
@item :urgency @var{urgency}
The urgency level. It can be @code{low}, @code{normal}, or @code{critical}.