@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/os
-@node System Interface, Packaging, Display, Top
+@node System Interface
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
* X11 Keysyms:: Operating on key symbols for X Windows.
* Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with X Session Management.
+* Notifications:: Desktop notifications.
* Dynamic Libraries:: On-demand loading of support libraries.
@end menu
automatically when Emacs is installed.
@item
-It registers input methods by loading any @file{leim-list.el} file
-found in the @code{load-path}.
-
-@c It removes PWD from the environment if it is not accurate.
-@c It abbreviates default-directory.
-
-@c Now normal-top-level calls command-line.
+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).
@vindex before-init-time
@item
@c set-locale-environment
@item
It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
+if requested by environment variables such as @env{LANG}.
@item
It does some basic parsing of the command-line arguments.
It runs the normal hook @code{after-init-hook}.
@item
-If the buffer @samp{*scratch*} exists and is still in Fundamental mode
+If the buffer @file{*scratch*} exists and is still in Fundamental mode
(as it should be by default), it sets its major mode according to
@code{initial-major-mode}.
@item
If @code{initial-buffer-choice} is a string, it visits the file with
-that name. If the @samp{*scratch*} buffer exists and is
+that name. 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
@defopt inhibit-startup-screen
This variable, if non-@code{nil}, inhibits the startup screen. In
-that case, Emacs typically displays the @samp{*scratch*} buffer; but
+that case, Emacs typically displays the @file{*scratch*} buffer; but
see @code{initial-buffer-choice}, below.
Do not set this variable in the init file of a new user, or in a way
@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 @code{t}, Emacs displays the @samp{*scratch*} buffer.
+If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.
@end ignore
@end defopt
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. You can also use the Custom interface. 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
+constant. You can also use the Customize interface. 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 init
file will not inhibit the message for someone else.
@end defopt
@defopt initial-scratch-message
This variable, if non-@code{nil}, should be a string, which is
-inserted into the @samp{*scratch*} buffer when Emacs starts up. If it
-is @code{nil}, the @samp{*scratch*} buffer is empty.
+inserted into the @file{*scratch*} buffer when Emacs starts up. If it
+is @code{nil}, the @file{*scratch*} buffer is empty.
@end defopt
@noindent
stronger @samp{-Q}) says not to load an init file, while @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
+option is specified, Emacs uses the @env{LOGNAME} environment
+variable, or the @env{USER} (most systems) or @env{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
Each terminal type can have its own Lisp library that Emacs loads when
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 @code{TERM}).
+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
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
+(i.e., there is no terminal-specific library). For example, if the
terminal name is @samp{xterm-256color} and there is no
@file{term/xterm-256color.el} library, Emacs tries to load
@file{term/xterm.el}. If necessary, the terminal library can evaluate
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 its initialization, after loading both
+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
have their own libraries. @xref{Hooks}.
@defvar term-file-prefix
-@cindex @code{TERM} environment variable
+@cindex @env{TERM} environment variable
If the value of this variable is non-@code{nil}, Emacs loads a
terminal-specific initialization file as follows:
init file if you do not wish to load the
terminal-initialization file.
-On MS-DOS, Emacs sets the @code{TERM} environment variable to @samp{internal}.
+On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
@end defvar
@defvar term-setup-hook
@end menu
@node Killing Emacs
-@comment node-name, next, previous, up
@subsection Killing Emacs
@cindex killing Emacs
higher-level command @kbd{C-x C-c}
(@code{save-buffers-kill-terminal}). @xref{Exiting,,, emacs, The GNU
Emacs Manual}. It is also called automatically if Emacs receives a
-@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g. when the
+@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g., when the
controlling terminal is disconnected), or if it receives a
@code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}).
This normal hook is run by @code{kill-emacs}, before it kills Emacs.
Because @code{kill-emacs} can be called in situations where user
-interaction is impossible (e.g. when the terminal is disconnected),
+interaction is impossible (e.g., when the terminal is disconnected),
functions on this hook should not attempt to interact with the user.
If you want to interact with the user when Emacs is shutting down, use
@code{kill-emacs-query-functions}, described below.
@defvar system-configuration
This variable holds the standard GNU configuration name for the
-hardware/software configuration of your system, as a string. The
-convenient way to test parts of this string is with
-@code{string-match}.
+hardware/software configuration of your system, as a string. For
+example, a typical value for a 64-bit GNU/Linux system is
+@samp{"x86_64-unknown-linux-gnu"}.
@end defvar
@cindex system type and name
@defvar system-type
The value of this variable is a symbol indicating the type of operating
-system Emacs is operating on. Here is a table of the possible values:
+system Emacs is running on. The possible values are:
@table @code
@item aix
@item gnu/linux
A GNU/Linux system---that is, a variant GNU system, using the Linux
-kernel. (These systems are the ones people often call ``Linux,'' but
+kernel. (These systems are the ones people often call ``Linux'', but
actually Linux is just the kernel, not the whole system.)
@item gnu/kfreebsd
Silicon Graphics Irix system.
@item ms-dos
-Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
-MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
-MS-Windows.
+Microsoft's DOS@. Emacs compiled with DJGPP for MS-DOS binds
+@code{system-type} to @code{ms-dos} even when you run it on MS-Windows.
@item usg-unix-v
AT&T Unix System V.
@item windows-nt
-Microsoft Windows NT and later. The same executable supports Windows
-9X, but the value of @code{system-type} is @code{windows-nt} in either
-case.
+Microsoft Windows NT, 9X and later. The value of @code{system-type}
+is always @code{windows-nt}, e.g., even on Windows 7.
@end table
We do not wish to add new symbols to make finer distinctions unless it
is absolutely necessary! In fact, we hope to eliminate some of these
-alternatives in the future. We recommend using
-@code{system-configuration} to distinguish between different operating
-systems.
+alternatives in the future. If you need to make a finer distinction
+than @code{system-type} allows for, you can test
+@code{system-configuration}, e.g., against a regexp.
@end defvar
@defun system-name
-This function returns the name of the machine you are running on.
-@example
-(system-name)
- @result{} "www.gnu.org"
-@end example
+This function returns the name of the machine you are running on, as a
+string.
@end defun
The symbol @code{system-name} is a variable as well as a function. In
system. The variable is also useful for constructing frame titles
(@pxref{Frame Titles}).
+@c FIXME seems like this section is not the best place for this option?
@defopt mail-host-address
If this variable is non-@code{nil}, it is used instead of
@code{system-name} for purposes of generating email addresses. For
@code{user-mail-address}. @xref{User Identification}. (Since this is
done when Emacs starts up, the value actually used is the one saved when
Emacs was dumped. @xref{Building Emacs}.)
+@c FIXME sounds like should probably give this a :set-after and some
+@c custom-initialize-delay voodoo.
@end defopt
@deffn Command getenv var &optional frame
@cindex environment variable access
This function returns the value of the environment variable @var{var},
as a string. @var{var} should be a string. If @var{var} is undefined
-in the environment, @code{getenv} returns @code{nil}. If returns
-@samp{""} if @var{var} is set but null. Within Emacs, the environment
-variable values are kept in the Lisp variable @code{process-environment}.
+in the environment, @code{getenv} returns @code{nil}. It returns
+@samp{""} if @var{var} is set but null. Within Emacs, a list of environment
+variables and their values is kept in the variable @code{process-environment}.
@example
@group
(getenv "USER")
@result{} "lewis"
@end group
+@end example
+The shell command @code{printenv} prints all or part of the environment:
+
+@example
@group
-lewis@@slug[10] % printenv
-PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+bash$ printenv
+PATH=/usr/local/bin:/usr/bin:/bin
USER=lewis
@end group
@group
-TERM=ibmapa16
-SHELL=/bin/csh
-HOME=/user/lewis
+TERM=xterm
+SHELL=/bin/bash
+HOME=/home/lewis
@end group
+@dots{}
@end example
@end deffn
-@c Emacs 19 feature
-@deffn Command setenv variable &optional value
+@deffn Command setenv variable &optional value substitute
This command sets the value of the environment variable named
@var{variable} to @var{value}. @var{variable} should be a string.
Internally, Emacs Lisp can handle any string. However, normally
of letters, digits and underscores, starting with a letter or
underscore. Otherwise, errors may occur if subprocesses of Emacs try
to access the value of @var{variable}. If @var{value} is omitted or
-@code{nil}, @code{setenv} removes @var{variable} from the environment.
-Otherwise, @var{value} should be a string.
+@code{nil} (or, interactively, with a prefix argument), @code{setenv}
+removes @var{variable} from the environment. Otherwise, @var{value}
+should be a string.
+
+If the optional argument @var{substitute} is non-@code{nil}, Emacs
+calls the function @code{substitute-env-vars} to expand any
+environment variables in @var{value}.
@code{setenv} works by modifying @code{process-environment}; binding
that variable with @code{let} is also reasonable practice.
@smallexample
@group
process-environment
-@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
- "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+@result{} ("PATH=/usr/local/bin:/usr/bin:/bin"
"USER=lewis"
@end group
@group
- "TERM=ibmapa16"
- "SHELL=/bin/csh"
- "HOME=/user/lewis")
+ "TERM=xterm"
+ "SHELL=/bin/bash"
+ "HOME=/home/lewis"
+ @dots{})
@end group
@end smallexample
@defvar initial-environment
This variable holds the list of environment variables Emacs inherited
-from its parent process. It is computed during startup, see
-@ref{Startup Summary}.
+from its parent process when Emacs started.
@end defvar
@defvar path-separator
-This variable holds a string which says which character separates
+This variable holds a string that says which character separates
directories in a search path (as found in an environment variable). Its
-value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
-and MS-Windows.
+value is @code{":"} for Unix and GNU systems, and @code{";"} for MS systems.
@end defvar
@defun parse-colon-path 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}.
+This function takes a search path string such as the value of
+the @env{PATH} environment variable, and splits it at the separators,
+returning a list of directory names. @code{nil} in this list means
+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")
@defvar invocation-directory
This variable holds the directory from which the Emacs executable was
-invoked, or perhaps @code{nil} if that directory cannot be determined.
+invoked, or @code{nil} if that directory cannot be determined.
@end defvar
@defvar installation-directory
If non-@code{nil}, this is a directory within which to look for the
-@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
+@file{lib-src} and @file{etc} subdirectories. In an installed Emacs,
+it is normally @code{nil}. It is non-@code{nil}
when Emacs can't find those directories in their standard installed
locations, but can find them in a directory related somehow to the one
-containing the Emacs executable.
+containing the Emacs executable (i.e., @code{invocation-directory}).
@end defvar
@defun load-average &optional use-float
-This function returns the current 1-minute, 5-minute, and 15-minute load
-averages, in a list.
+This function returns the current 1-minute, 5-minute, and 15-minute
+system load averages, in a list. The load average indicates the
+number of processes trying to run on the system.
By default, the values are integers that are 100 times the system load
-averages, which indicate the average number of processes trying to run.
-If @var{use-float} is non-@code{nil}, then they are returned
-as floating point numbers and without multiplying by 100.
+averages, but if @var{use-float} is non-@code{nil}, then they are
+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
installing Emacs as setuid or setgid so that it can read kernel
information, and that usually isn't advisable.
+@c FIXME which platforms are these? Are they still relevant?
If the 1-minute load average is available, but the 5- or 15-minute
averages are not, this function returns a shortened list containing
(load-average t)
@result{} (1.69 0.48 0.36)
@end group
-
-@group
-lewis@@rocky[5] % uptime
- 11:55am up 1 day, 19:37, 3 users,
- load average: 1.69, 0.48, 0.36
-@end group
@end example
+
+The shell command @code{uptime} returns similar information.
@end defun
@defun emacs-pid
@defvar tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
-The value is @code{nil} if Emacs is running under a window system.
+@c FIXME? Seems untrue since 23.1. For me, it is 0.
+@c The value is @code{nil} if Emacs is running under a window system.
@end defvar
@node User Identification
@end defopt
@defun user-login-name &optional uid
-If you don't specify @var{uid}, this function returns the name under
-which the user is logged in. If the environment variable @code{LOGNAME}
-is set, that value is used. Otherwise, if the environment variable
-@code{USER} is set, that value is used. Otherwise, the value is based
-on the effective @acronym{UID}, not the real @acronym{UID}.
+This function returns the name under which the user is logged in.
+It uses the environment variables @env{LOGNAME} or @env{USER} if
+either is set. Otherwise, the value is based on the effective
+@acronym{UID}, not the real @acronym{UID}.
-If you specify @var{uid}, the value is the user name that corresponds
-to @var{uid} (which should be an integer), or @code{nil} if there is
-no such user.
-
-@example
-@group
-(user-login-name)
- @result{} "lewis"
-@end group
-@end example
+If you specify @var{uid} (a number), the result is the user name that
+corresponds to @var{uid}, or @code{nil} if there is no such user.
@end defun
@defun user-real-login-name
This function returns the user name corresponding to Emacs's real
-@acronym{UID}. This ignores the effective @acronym{UID} and ignores the
-environment variables @code{LOGNAME} and @code{USER}.
+@acronym{UID}. This ignores the effective @acronym{UID}, and the
+environment variables @env{LOGNAME} and @env{USER}.
@end defun
@defun user-full-name &optional uid
This function returns the full name of the logged-in user---or the value
-of the environment variable @code{NAME}, if that is set.
+of the environment variable @env{NAME}, if that is set.
-@c "Bil" is the correct spelling.
-@example
-@group
-(user-full-name)
- @result{} "Bil Lewis"
-@end group
-@end example
-
-If the Emacs job's user-id does not correspond to any known user (and
-provided @code{NAME} is not set), the value is @code{"unknown"}.
+If the Emacs process's user-id does not correspond to any known user (and
+provided @code{NAME} is not set), the result is @code{"unknown"}.
If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
or a string (a login name). Then @code{user-full-name} returns the full
@defun user-real-uid
This function returns the real @acronym{UID} of the user.
-The value may be a floating point number.
-
-@example
-@group
-(user-real-uid)
- @result{} 19
-@end group
-@end example
+The value may be a floating point number, in the (unlikely) event that
+the UID is too large to fit in a Lisp integer.
@end defun
@defun user-uid
The value may be a floating point number.
@end defun
+@defun group-gid
+This function returns the effective @acronym{GID} of the Emacs process.
+The value may be a floating point number.
+@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.
+@end defun
+
+@defun system-users
+This function returns a list of strings, listing the user names on the
+system. If Emacs cannot retrieve this information, the return value
+is a list containing just the value of @code{user-real-login-name}.
+@end defun
+
+@cindex user groups
+@defun system-groups
+This function returns a list of strings, listing the names of user
+groups on the system. If Emacs cannot retrieve this information, the
+return value is @code{nil}.
+@end defun
+
+
@node Time of Day
@section Time of Day
zone.
@cindex epoch
- Most of these functions represent time as a list of either three
+ Most of these functions represent time as a list of either four
+integers, @code{(@var{sec-high} @var{sec-low} @var{microsec}
+@var{picosec})}, or of three
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
UTC) to the specified time. The third list element @var{microsec}, if
present, gives the number of microseconds from the start of that
second to the specified time.
-
- The return value of @code{current-time} represents time using three
-integers, while the timestamps in the return value of
-@code{file-attributes} use two integers (@pxref{Definition of
-file-attributes}). In function arguments, e.g.@: the @var{time-value}
-argument to @code{current-time-string}, both two- and three-integer
+Similarly, the fourth list element @var{picosec}, if present, gives
+the number of picoseconds from the start of that microsecond to the
+specified time.
+
+ The return value of @code{current-time} represents time using four
+integers, as do the timestamps in the return value of
+@code{file-attributes} (@pxref{Definition of
+file-attributes}). In function arguments, e.g., the @var{time-value}
+argument to @code{current-time-string}, two-, three-, and four-integer
lists are accepted. You can convert times from the list
representation into standard human-readable strings using
@code{current-time}, or to other forms using the @code{decode-time}
@defun current-time-string &optional time-value
This function returns the current time and date as a human-readable
-string. The format of the string is unvarying; the number of
-characters used for each part is always the same, so you can reliably
-use @code{substring} to extract pieces of it. You should count
+string. The format does not vary for the initial part of the string,
+which contains the day of week, month, day of month, and time of day
+in that order: the number of characters used for these fields is
+always the same, so you can reliably
+use @code{substring} to extract them. You should count
characters from the beginning of the string rather than from the end,
-as additional information may some day be added at the end.
+as the year might not have exactly four digits, and additional
+information may some day be added at the end.
The argument @var{time-value}, if given, specifies a time to format
(represented as a list of integers), instead of the current time.
@end defun
@defun current-time
-This function returns the current time, represented as a list of three
-integers @code{(@var{sec-high} @var{sec-low} @var{microsec})}. On
-systems with only one-second time resolutions, @var{microsec} is 0.
+This function returns the current time, represented as a list of four
+integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}.
+These integers have trailing zeros on systems that return time with
+lower resolutions. On all current machines @var{picosec} is a
+multiple of 1000, but this may change as higher-resolution clocks
+become available.
@end defun
@defun float-time &optional time-value
as a list of integers) to analyze instead of the current time.
@end defun
-The current time zone is determined by the @samp{TZ} environment
+The current time zone is determined by the @env{TZ} environment
variable. @xref{System Environment}. For example, you can tell Emacs
-to use universal time with @code{(setenv "TZ" "UTC0")}. If @samp{TZ}
+to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ}
is not in the environment, Emacs uses a platform-dependent default
time zone.
@node Time Conversion
@section Time Conversion
- These functions convert time values (lists of two or three integers,
+ These functions convert time values (lists of two to four integers,
as explained in the previous section) into calendrical information and
vice versa.
Many 32-bit operating systems are limited to time values containing
32 bits of information; these systems typically handle only the times
-from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.
+from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC@.
However, 64-bit and some 32-bit operating systems have larger time
values, and can represent times far in the past or future.
The optional argument @var{zone} defaults to the current time zone and
its daylight saving time rules. If specified, it can be either a list
(as you would get from @code{current-time-zone}), a string as in the
-@code{TZ} environment variable, @code{t} for Universal Time, or an
+@env{TZ} environment variable, @code{t} for Universal Time, or an
integer (as you would get from @code{decode-time}). The specified
zone is used without any further alteration for daylight saving time.
@node Time Parsing
@section Parsing and Formatting Times
- These functions convert time values (lists of two or three integers)
-to text in a string, and vice versa.
+ These functions convert time values to text in a string, and vice versa.
+Time values are lists of two to four integers (@pxref{Time of Day}).
@defun date-to-time string
This function parses the time-string @var{string} and returns the
This stands for the nanoseconds (000000000-999999999). To ask for
fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for
microseconds, etc. Any excess digits are discarded, without rounding.
-Currently Emacs time stamps are at best microsecond resolution so the
-last three digits generated by plain @samp{%N} are always zero.
@item %p
This stands for @samp{AM} or @samp{PM}, as appropriate.
@item %r
The integer number of seconds.
@item %z
Non-printing control flag. When it is used, other specifiers must be
-given in the order of decreasing size, i.e.@: years before days, hours
+given in the order of decreasing size, i.e., years before days, hours
before minutes, etc. Nothing will be produced in the result string to
the left of @samp{%z} until the first non-zero conversion is
encountered. For example, the default format used by
@defun get-internal-run-time
This function returns the processor run time used by Emacs as a list
-of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
-integers @var{high} and @var{low} combine to give the number of
-seconds, which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds (or 0 for
-systems that return time with the resolution of only one second).
+of four integers: @code{(@var{high} @var{low} @var{microsec}
+@var{picosec})}, using the same format as @code{current-time}
+(@pxref{Time of Day}).
Note that the time returned by this function excludes the time Emacs
was not using the processor, and if the Emacs process has several
seconds after the last invocation, don't use the @var{repeat} argument.
Instead, the timer function should explicitly reschedule the timer.
-@defvar timer-max-repeats
+@defopt timer-max-repeats
This variable's value specifies the maximum number of times to repeat
calling a timer function in a row, when many previously scheduled
calls were unavoidably delayed.
-@end defvar
+@end defopt
@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
Execute @var{body}, but give up after @var{seconds} seconds. If
input. Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.
+ Do not write an idle timer function containing a loop which does a
+certain amount of processing each time around, and exits when
+@code{(input-pending-p)} is non-@code{nil}. This approach seems very
+natural but has two problems:
+
+@itemize
+@item
+It blocks out all process output (since Emacs accepts process output
+only while waiting).
+
+@item
+It blocks out any idle timers that ought to run during that time.
+@end itemize
+
+@noindent
+Similarly, do not write an idle timer function that sets up another
+idle timer (including the same idle timer) with @var{secs} argument
+less than or equal to the current idleness time. Such a timer will
+run almost immediately, and continue running again and again, instead
+of waiting for the next time Emacs becomes idle. The correct approach
+is to reschedule with an appropriate increment of the current value of
+the idleness time, as described below.
+
@defun current-idle-time
If Emacs is idle, this function returns the length of time Emacs has
-been idle, as a list of three integers: @code{(@var{sec-high}
-@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the
-high and low bits for the number of seconds and @var{microsec} is the
-additional number of microseconds (@pxref{Time of Day}).
+been idle, as a list of four integers: @code{(@var{sec-high}
+@var{sec-low} @var{microsec} @var{picosec})}, using the same format as
+@code{current-time} (@pxref{Time of Day}).
When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
This is a convenient way to test whether Emacs is idle.
+@end defun
-The main use of this function is when an idle timer function wants to
-``take a break'' for a while. It can set up another idle timer to
-call the same function again, after a few seconds more idleness.
-Here's an example:
+ The main use of @code{current-idle-time} is when an idle timer
+function wants to ``take a break'' for a while. It can set up another
+idle timer to call the same function again, after a few seconds more
+idleness. Here's an example:
-@smallexample
-(defvar resume-timer nil
- "Timer that `timer-function' used to reschedule itself, or nil.")
+@example
+(defvar my-resume-timer nil
+ "Timer for `my-timer-function' to reschedule itself, or nil.")
-(defun timer-function ()
- ;; @r{If the user types a command while @code{resume-timer}}
+(defun my-timer-function ()
+ ;; @r{If the user types a command while @code{my-resume-timer}}
;; @r{is active, the next time this function is called from}
- ;; @r{its main idle timer, deactivate @code{resume-timer}.}
- (when resume-timer
- (cancel-timer resume-timer))
+ ;; @r{its main idle timer, deactivate @code{my-resume-timer}.}
+ (when my-resume-timer
+ (cancel-timer my-resume-timer))
...@var{do the work for a while}...
(when @var{taking-a-break}
- (setq resume-timer
+ (setq my-resume-timer
(run-with-idle-timer
;; Compute an idle time @var{break-length}
;; more than the current value.
(time-add (current-idle-time)
(seconds-to-time @var{break-length}))
nil
- 'timer-function))))
-@end smallexample
-@end defun
-
- Do not write an idle timer function containing a loop which does a
-certain amount of processing each time around, and exits when
-@code{(input-pending-p)} is non-@code{nil}. This approach seems very
-natural but has two problems:
-
-@itemize
-@item
-It blocks out all process output (since Emacs accepts process output
-only while waiting).
-
-@item
-It blocks out any idle timers that ought to run during that time.
-@end itemize
-
-@noindent
-The correct approach is for the idle timer to reschedule itself after
-a brief pause, using the method in the @code{timer-function} example
-above.
+ 'my-timer-function))))
+@end example
@node Terminal Input
@section Terminal Input
(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
has no effect except in @sc{cbreak} mode.
-@c Emacs 19 feature
The argument @var{meta} controls support for input character codes
above 127. If @var{meta} is @code{t}, Emacs converts characters with
the 8th bit set into Meta characters. If @var{meta} is @code{nil},
Emacs uses all 8 bits of input unchanged. This is good for terminals
that use 8-bit character sets.
-@c Emacs 19 feature
If @var{quit-char} is non-@code{nil}, it specifies the character to
use for quitting. Normally this character is @kbd{C-g}.
@xref{Quitting}.
The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.
-@c Emacs 19 feature
@defun current-input-mode
This function returns the current mode for reading keyboard input. It
returns a list, corresponding to the arguments of @code{set-input-mode},
This function returns a vector containing the last 300 input events from
the keyboard or mouse. All input events are included, whether or not
they were used as parts of key sequences. Thus, you always get the last
-100 input events, not counting events generated by keyboard macros.
+300 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.)
Each function is called with one argument, @var{sound}.
@end defun
-@defun play-sound-file file &optional volume device
+@deffn Command play-sound-file file &optional volume device
This function is an alternative interface to playing a sound @var{file}
specifying an optional @var{volume} and @var{device}.
-@end defun
+@end deffn
@defvar play-sound-functions
A list of functions to be called before playing a sound. Each function
shutdown.
@end defvar
-Here is an example that just inserts some text into @samp{*scratch*} when
+Here is an example that just inserts some text into @file{*scratch*} when
Emacs is restarted by the session manager.
@example
@end group
@end example
+@node Notifications
+@section Desktop Notifications
+@cindex desktop notifications
+
+Emacs is able to send @dfn{notifications} on systems that support the
+freedesktop.org Desktop Notifications Specification. In order to use
+this functionality, Emacs must have been compiled with D-Bus support,
+and the @code{notifications} library must be loaded.
+
+@defun notifications-notify &rest params
+This function sends a notification to the desktop via D-Bus,
+consisting of the parameters specified by the @var{params} arguments.
+These arguments should consist of alternating keyword and value pairs.
+The supported keywords and values are as follows:
+
+@table @code
+@item :bus @var{bus}
+The D-Bus bus. This argument is needed only if a bus other than
+@code{:session} shall be used.
+
+@item :title @var{title}
+The notification title.
+
+@item :body @var{text}
+The notification body text. Depending on the implementation of the
+notification server, the text could contain HTML markups, like
+@samp{"<b>bold text</b>"}, hyperlinks, or images. Special HTML
+characters must be encoded, as @samp{"Contact
+<postmaster@@localhost>!"}.
+
+@item :app-name @var{name}
+The name of the application sending the notification. The default is
+@code{notifications-application-name}.
+
+@item :replaces-id @var{id}
+The notification @var{id} that this notification replaces. @var{id}
+must be the result of a previous @code{notifications-notify} call.
+
+@item :app-icon @var{icon-file}
+The file name of the notification icon. If set to @code{nil}, no icon
+is displayed. The default is @code{notifications-application-icon}.
+
+@item :actions (@var{key} @var{title} @var{key} @var{title} ...)
+A list of actions to be applied. @var{key} and @var{title} are both
+strings. The default action (usually invoked by clicking the
+notification) should have a key named @samp{"default"}. The title can
+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
+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.
+
+@item :urgency @var{urgency}
+The urgency level. It can be @code{low}, @code{normal}, or @code{critical}.
+
+@item :action-items
+When this keyword is given, the @var{title} string of the actions is
+interpreted as icon name.
+
+@item :category @var{category}
+The type of notification this is, a string. See the
+@uref{http://developer.gnome.org/notification-spec/#categories,
+Desktop Notifications Specification} for a list of standard
+categories.
+
+@item :desktop-entry @var{filename}
+This specifies the name of the desktop filename representing the
+calling program, like @samp{"emacs"}.
+
+@item :image-data (@var{width} @var{height} @var{rowstride} @var{has-alpha} @var{bits} @var{channels} @var{data})
+This is a raw data image format that describes the width, height,
+rowstride, whether there is an alpha channel, bits per sample,
+channels and image data, respectively.
+
+@item :image-path @var{path}
+This is represented either as a URI (@samp{file://} is the only URI
+schema supported right now) or a name in a freedesktop.org-compliant
+icon theme from @samp{$XDG_DATA_DIRS/icons}.
+
+@item :sound-file @var{filename}
+The path to a sound file to play when the notification pops up.
+
+@item :sound-name @var{name}
+A themable named sound from the freedesktop.org sound naming
+specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the
+notification pops up. Similar to the icon name, only for sounds. An
+example would be @samp{"message-new-instant"}.
+
+@item :suppress-sound
+Causes the server to suppress playing any sounds, if it has that
+ability.
+
+@item :resident
+When set the server will not automatically remove the notification
+when an action has been invoked. The notification will remain resident
+in the server until it is explicitly removed by the user or by the
+sender. This hint is likely only useful when the server has the
+@code{:persistence} capability.
+
+@item :transient
+When set the server will treat the notification as transient and
+by-pass the server's persistence capability, if it should exist.
+
+@item :x @var{position}
+@itemx :y @var{position}
+Specifies the X, Y location on the screen that the
+notification should point to. Both arguments must be used together.
+
+@item :on-action @var{function}
+Function to call when an action is invoked. The notification @var{id}
+and the @var{key} of the action are passed as arguments to the
+function.
+
+@item :on-close @var{function}
+Function to call when the notification has been closed by timeout or
+by the user. The function receive the notification @var{id} and the closing
+@var{reason} as arguments:
+
+@itemize
+@item @code{expired} if the notification has expired
+@item @code{dismissed} if the notification was dismissed by the user
+@item @code{close-notification} if the notification was closed by a call to
+@code{notifications-close-notification}
+@item @code{undefined} if the notification server hasn't provided a reason
+@end itemize
+@end table
+
+Which parameters are accepted by the notification server can be
+checked via @code{notifications-get-capabilities}.
+
+This function returns a notification id, an integer, which can be used
+to manipulate the notification item with
+@code{notifications-close-notification} or the @code{:replaces-id}
+argument of another @code{notifications-notify} call. For example:
+
+@example
+@group
+(defun my-on-action-function (id key)
+ (message "Message %d, key \"%s\" pressed" id key))
+ @result{} my-on-action-function
+@end group
+
+@group
+(defun my-on-close-function (id reason)
+ (message "Message %d, closed due to \"%s\"" id reason))
+ @result{} my-on-close-function
+@end group
+
+@group
+(notifications-notify
+ :title "Title"
+ :body "This is <b>important</b>."
+ :actions '("Confirm" "I agree" "Refuse" "I disagree")
+ :on-action 'my-on-action-function
+ :on-close 'my-on-close-function)
+ @result{} 22
+@end group
+
+@group
+A message window opens on the desktop. Press "I agree"
+ @result{} Message 22, key "Confirm" pressed
+ Message 22, closed due to "dismissed"
+@end group
+@end example
+@end defun
+
+@defun notifications-close-notification id &optional bus
+This function closes a notification with identifier @var{id}.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}.
+@end defun
+
+@defun notifications-get-capabilities &optional bus
+Returns the capabilities of the notification server, a list of
+symbols. @var{bus} can be a string denoting a D-Bus connection, the
+default is @code{:session}. The following capabilities can be
+expected:
+
+@table @code
+@item :actions
+The server will provide the specified actions to the user.
+
+@item :body
+Supports body text.
+
+@item :body-hyperlinks
+The server supports hyperlinks in the notifications.
+
+@item :body-images
+The server supports images in the notifications.
+
+@item :body-markup
+Supports markup in the body text.
+
+@item :icon-multi
+The server will render an animation of all the frames in a given image
+array.
+
+@item :icon-static
+Supports display of exactly 1 frame of any given image array. This
+value is mutually exclusive with @code{:icon-multi}.
+
+@item :persistence
+The server supports persistence of notifications.
+
+@item :sound
+The server supports sounds on notifications.
+@end table
+
+Further vendor-specific caps start with @code{:x-vendor}, like
+@code{:x-gnome-foo-cap}.
+@end defun
+
+@defun notifications-get-server-information &optional bus
+Return information on the notification server, a list of strings.
+@var{bus} can be a string denoting a D-Bus connection, the default is
+@code{:session}. The returned list is @code{(@var{name} @var{vendor}
+@var{version} @var{spec-version})}.
+
+@table @var
+@item name
+The product name of the server.
+
+@item vendor
+The vendor name. For example, @samp{"KDE"}, @samp{"GNOME"}.
+
+@item version
+The server's version number.
+
+@item spec-version
+The specification version the server is compliant with.
+@end table
+
+If @var{SPEC_VERSION} is @code{nil}, the server supports a
+specification prior to @samp{"1.0"}.
+@end defun
+
+
@node Dynamic Libraries
@section Dynamically Loaded Libraries
@cindex dynamic libraries
strings giving alternate filenames for that library.
Emacs tries to load the library from the files in the order they
-appear in the list; if none is found, the running session of Emacs
-won't have access to that library, and the features that depend on the
-library will be unavailable.
+appear in the list; if none is found, the Emacs session won't have
+access to that library, and the features it provides will be
+unavailable.
Image support on some platforms uses this facility. Here's an example
of setting this variable for supporting images on MS-Windows:
-@lisp
+@example
(setq dynamic-library-alist
'((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll")
(png "libpng12d.dll" "libpng12.dll" "libpng.dll"
- "libpng13d.dll" "libpng13.dll")
- (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll" "jpeg.dll")
+ "libpng13d.dll" "libpng13.dll")
+ (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll"
+ "jpeg.dll")
(tiff "libtiff3.dll" "libtiff.dll")
(gif "giflib4.dll" "libungif4.dll" "libungif.dll")
(svg "librsvg-2-2.dll")
(gdk-pixbuf "libgdk_pixbuf-2.0-0.dll")
(glib "libglib-2.0-0.dll")
(gobject "libgobject-2.0-0.dll")))
-@end lisp
+@end example
Note that image types @code{pbm} and @code{xbm} do not need entries in
this variable because they do not depend on external libraries and are
HCoop / bpt / emacs.git / blobdiff