X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/cb6c95a394d9a9d2f068bf8ee240f2d2297867d1..7e31acf6b81fdce7258077645bc239767c484841:/doc/lispref/os.texi diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 38ebcccb68..b63b932b4d 100644 --- 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 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 @@ -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 -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. @@ -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 -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 @@ -208,7 +210,7 @@ empty, it inserts @code{initial-scratch-message} into that buffer. @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 @@ -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. -@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 @@ -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 -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 @@ -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}). -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 @@ -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. - 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: @@ -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}. -@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 @@ -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 -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 @@ -1154,24 +1159,24 @@ Titles}). @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 @@ -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 -integer number of seconds. This integer number, +integer number of seconds. This integer, @ifnottex @var{high} * 2**16 + @var{low}, @end ifnottex @@ -1523,9 +1528,9 @@ 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} (@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 @@ -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} -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 @@ -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 -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}). @@ -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 --2**28), +@minus{}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 --2**28 +@minus{}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 -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}.