Merge from emacs-24; up to 2014-04-01T20:18:12Z!eggert@cs.ucla.edu

[bpt/emacs.git] / doc / lispref / os.texi

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 38ebccc..b63b932 100644 (file)
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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
 @c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node System Interface


@@ -175,8 +175,8 @@ If the buffer @file{*scratch*} exists and is still in Fundamental mode
 
 @item
 If started on a text terminal, it loads the terminal-specific
 
 @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.
 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
 
 @c Now command-line calls command-line-1.


@@ -195,7 +195,9 @@ It now exits if the option @code{--batch} was specified.
 
 @item
 If @code{initial-buffer-choice} is a string, it visits the file with
 
 @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
 empty, it inserts @code{initial-scratch-message} into that buffer.
 
 @c To make things nice and confusing, the next three items can be


@@ -208,7 +210,7 @@ empty, it inserts @code{initial-scratch-message} into that buffer.
 @c daemon/session restore step?
 
 @item
 @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
 
 @item
 It calls @code{frame-notice-user-settings}, which modifies the


@@ -271,11 +273,9 @@ aliases for this variable.
 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.
 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.
 If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.

-@end ignore

 @end defopt
 
 @defopt inhibit-startup-echo-area-message
 @end defopt
 
 @defopt inhibit-startup-echo-area-message


@@ -408,8 +408,7 @@ terminal) and processing the command-line action arguments.
 
 @defvar emacs-startup-hook
 This normal hook is run, once, just after handling the command line
 
 @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
 @end defvar
 
 @defvar user-init-file


@@ -431,21 +430,24 @@ This variable holds the name of the @file{.emacs.d} directory.  It is
 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}).
 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
 
 @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
 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


@@ -454,20 +456,16 @@ terminal name is @samp{xterm-256color} and there is no
 @file{term/xterm.el}.  If necessary, the terminal library can evaluate
 @code{(getenv "TERM")} to find the full name of the terminal type.
 
 @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
 
   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}.
 
 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:
 @cindex @env{TERM} environment variable
 If the value of this variable is non-@code{nil}, Emacs loads a
 terminal-specific initialization file as follows:


@@ -482,15 +480,22 @@ init file if you do not wish to load the
 terminal-initialization file.
 
 On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
 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
 
 For a related feature, @pxref{Window Systems, window-setup-hook}.
 @end defvar


@@ -1048,7 +1053,7 @@ number of processes trying to run on the system.
 
 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
 
 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
 
 If it is impossible to obtain the load average, this function signals
 an error.  On some platforms, access to load averages requires


@@ -1154,24 +1159,24 @@ Titles}).
 @cindex UID
 @defun user-real-uid
 This function returns the real @acronym{UID} of the user.
 @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 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.
 @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.
 @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
 @end defun
 
 @defun system-users


@@ -1201,7 +1206,7 @@ integers, @code{(@var{sec-high} @var{sec-low} @var{microsec}
 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
 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
 @ifnottex
 @var{high} * 2**16 + @var{low},
 @end ifnottex


@@ -1523,9 +1528,9 @@ system.
 @end defun
 
 @defun seconds-to-time seconds
 @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
 @end defun
 
 @defun format-seconds format-string seconds


@@ -1810,9 +1815,8 @@ work just like ordinary timers.
 
 @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}
 
 @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
 
 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


@@ -1997,20 +2001,11 @@ 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
 not those from keyboard macros) is written in that file.  A
 non-character event is expressed using its printed representation
 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}.
 
 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}).
 @end deffn
 
   See also the @code{open-termscript} function (@pxref{Terminal Output}).


@@ -2160,7 +2155,7 @@ 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,
 @ifnottex
 . @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}$),
 @end ifnottex
 @tex
 $-2^{28}$),


@@ -2170,7 +2165,7 @@ and @var{symbol} is the name for the function key.
 For example @code{(168 . mute-acute)} defines a system-specific key (used
 by HP X servers) whose numeric code is
 @ifnottex
 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}$
 @end ifnottex
 @tex
 $-2^{28}$


@@ -2334,10 +2329,10 @@ be anything, though implementations are free not to display it.
 
 @item :timeout @var{timeout}
 The timeout time in milliseconds since the display of the notification
 
 @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,
 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}.
 
 @item :urgency @var{urgency}
 The urgency level.  It can be @code{low}, @code{normal}, or @code{critical}.