@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
-values in the operating system environment, and terminal input, output,
-and flow control.
+values in the operating system environment, and terminal input, output.
@xref{Building Emacs}, for related information. @xref{Display}, for
additional operating system status information pertaining to the
* 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
@cindex @file{startup.el}
When Emacs is started up, it performs the following operations
-(which are defined in @file{startup.el}):
+(see @code{normal-top-level} in @file{startup.el}):
@enumerate
@item
in their turn. The files @file{subdirs.el} are normally generated
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).
+
@vindex before-init-time
@item
It sets the variable @code{before-init-time} to the value of
@code{after-init-time} to @code{nil}, which signals to Lisp programs
that Emacs is being initialized.
+@c set-locale-environment
+@item
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @env{LANG}.
+
+@item
+It does some basic parsing of the command-line arguments.
+
@vindex initial-window-system@r{, and startup}
@vindex window-system-initialization-alist
@item
-It loads the initialization library for the window system specified by
-the variable @code{initial-window-system} (@pxref{Window Systems,
-initial-window-system}). This library's name is
-@file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
-value of @code{initial-window-system}. From that library, it calls
-the appropriate initialization function. The initialization function
-for each supported window system is specified by
-@code{window-system-initialization-alist}.
+If not running in batch mode, it initializes the window system that
+the variable @code{initial-window-system} specifies (@pxref{Window
+Systems, initial-window-system}). The initialization function for
+each supported window system is specified by
+@code{window-system-initialization-alist}. If the value
+of @code{initial-window-system} is @var{windowsystem}, then the
+appropriate initialization function is defined in the file
+@file{term/@var{windowsystem}-win.el}. This file should have been
+compiled into the Emacs executable when it was built.
@item
-It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
+It runs the normal hook @code{before-init-hook}.
@item
-It processes the initial options. (Some of them are handled
-even earlier than this.)
+If appropriate, it creates a graphical frame. This is not done if the
+options @samp{--batch} or @samp{--daemon} were specified.
@item
-It runs the normal hook @code{before-init-hook}.
+It initializes the initial frame's faces, and sets up the menu bar
+and tool bar if needed. If graphical frames are supported, it sets up
+the tool bar even if the current frame is not a graphical one, since a
+graphical frame may be created later on.
@item
-It initializes the window frame and faces, if appropriate, and turns
-on the menu bar and tool bar, if the initial frame needs them.
+It use @code{custom-reevaluate-setting} to re-initialize the members
+of the list @code{custom-delayed-init-variables}. These are any
+pre-loaded user options whose default value depends on the run-time,
+rather than build-time, context.
+@xref{Building Emacs, custom-initialize-delay}.
+
+@c @item
+@c It registers the colors available for tty frames.
@item
It loads the library @file{site-start}, if it exists. This is not
(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the
option @samp{--batch} was specified.
+@item
+If @code{package-enable-at-startup} is non-@code{nil}, it calls the
+function @code{package-initialize} to activate any optional Emacs Lisp
+package that has been installed. @xref{Packaging Basics}.
+
@vindex after-init-time
@item
It sets the variable @code{after-init-time} to the value of
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 started on a text-only terminal, it loads the terminal-specific
+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
in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
+@c Now command-line calls command-line-1.
+
@item
It displays the initial echo area message, unless you have suppressed
that with @code{inhibit-startup-echo-area-message}.
@item
-It processes the action arguments from the command line.
+It processes any command-line options that were not handled earlier.
+@c This next one is back in command-line, but the remaining bits of
+@c command-line-1 are not done if noninteractive.
@item
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. Furthermore, 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
+@c called from two places. If displaying a startup screen, they are
+@c called in command-line-1 before the startup screen is shown.
+@c inhibit-startup-hooks is then set and window-setup-hook set to nil.
+@c If not displaying a startup screen, they are are called in
+@c normal-top-level.
+@c FIXME? So it seems they can be called before or after the
+@c daemon/session restore step?
+
@item
It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
@item
It runs @code{window-setup-hook}. @xref{Window Systems}.
+@item
+It displays the @dfn{startup screen}, which is a special buffer that
+contains information about copyleft and basic Emacs usage. This is
+not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice}
+are non-@code{nil}, or if the @samp{--no-splash} or @samp{-Q} command-line
+options were specified.
+
+@c End of command-line-1.
+
+@c Back to command-line from command-line-1.
+
+@c This is the point at which we actually exit in batch mode, but the
+@c last few bits of command-line-1 are not done in batch mode.
+
@item
If the option @code{--daemon} was specified, it calls
@code{server-start} and detaches from the controlling terminal.
@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
-@item
-It displays the @dfn{startup screen}, which is a special buffer that
-contains information about copyleft and basic Emacs usage. This is
-not done if @code{initial-buffer-choice} or
-@code{inhibit-startup-screen} are @code{nil}, nor if the
-@samp{--no-splash} or @samp{-Q} command-line options were specified.
-
@item
If started by the X session manager, it calls
@code{emacs-session-restore} passing it as argument the ID of the
previous session. @xref{Session Management}.
+
+@c End of command-line.
+
+@c Back to normal-top-level from command-line.
+
@end enumerate
+@noindent
+The following options affect some aspects of the startup sequence.
+
@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
@end defopt
@defopt initial-buffer-choice
-This variable, if non-@code{nil}, determines a file or buffer for
-Emacs to display after starting up, instead of the startup screen. If
-its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. If
-its value is a string, that specifies the name of a file for Emacs to
-visit.
+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 @code{t}, Emacs displays the @file{*scratch*} buffer.
+@end ignore
@end defopt
@defopt inhibit-startup-echo-area-message
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
+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
+The following command-line options affect some aspects of the startup
+sequence. @xref{Initial Options,,, emacs, The GNU Emacs Manual}.
+
+@table @code
+@item --no-splash
+Do not display a splash screen.
+
+@item --batch
+Run without an interactive terminal. @xref{Batch Mode}.
+
+@item --daemon
+Do not initialize any display; just start a server in the background.
+
+@item --no-init-file
+@itemx -Q
+Do not load either the init file, or the @file{default} library.
+
+@item --no-site-file
+Do not load the @file{site-start} library.
+
+@item --quick
+@itemx -Q
+Equivalent to @samp{-q --no-site-file --no-splash}.
+@c and --no-site-lisp, but let's not mention that here.
+@end table
+
+
@node Init File
-@subsection The Init File, @file{.emacs}
+@subsection The Init File
@cindex init file
@cindex @file{.emacs}
+@cindex @file{init.el}
When you start Emacs, it normally attempts to load your @dfn{init
file}. This is either a file named @file{.emacs} or @file{.emacs.el}
in your home directory, or a file named @file{init.el} in a
-subdirectory named @file{.emacs.d} in your home directory. Whichever
-place you use, you can also compile the file (@pxref{Byte
+subdirectory named @file{.emacs.d} in your home directory.
+@ignore
+Whichever place you use, you can also compile the file (@pxref{Byte
Compilation}); then the actual file loaded will be @file{.emacs.elc}
or @file{init.elc}.
+@end ignore
The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
control whether and where to find the init file; @samp{-q} (and the
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
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 @file{default.el}. Emacs finds the @file{default.el} file
-through the standard search path for libraries (@pxref{How Programs Do
-Loading}). The Emacs distribution does not come with this file; sites
-may provide one for local customizations. If the default init file
-exists, it is loaded whenever you start Emacs, except in batch mode or
-if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
+ An Emacs installation may have a @dfn{default init file}, which is a
+Lisp library named @file{default.el}. Emacs finds this file through
+the standard search path for libraries (@pxref{How Programs Do
+Loading}). The Emacs distribution does not come with this file; it is
+intended for local customizations. If the default init file exists,
+it is loaded whenever you start Emacs. But your own personal init
file, if any, is loaded first; if it sets @code{inhibit-default-init}
to a non-@code{nil} value, then Emacs does not subsequently load the
-@file{default.el} file.
+@file{default.el} file. In batch mode, or if you specify @samp{-q}
+(or @samp{-Q}), Emacs loads neither your personal init file nor
+the default init file.
Another file for site-customization is @file{site-start.el}. Emacs
loads this @emph{before} the user's init file. You can inhibit the
user's init file. Its normal value is @code{"site-start"}. The only
way you can change it with real effect is to do so before dumping
Emacs.
+@c So why even mention it here. I imagine it is almost never changed.
@end defopt
@xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
@file{.emacs} file.
@defopt inhibit-default-init
-This variable prevents Emacs from loading the default initialization
-library file for your session of Emacs. If its value is non-@code{nil},
-then the default library is not loaded. The default value is
-@code{nil}.
+If this variable is non-@code{nil}, it prevents Emacs from loading the
+default initialization library file. The default value is @code{nil}.
@end defopt
@defvar before-init-hook
This normal hook is run, once, just before loading all the init files
-(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+(@file{site-start.el}, your init file, and @file{default.el}).
(The only way to change it with real effect is before dumping Emacs.)
@end defvar
@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 loading the terminal-specific library and processing the
-command-line action arguments.
+(@file{site-start.el}, your init file, and @file{default.el}),
+before loading the terminal-specific library (if started on a text
+terminal) and processing the command-line action arguments.
@end defvar
@defvar emacs-startup-hook
This normal hook is run, once, just after handling the command line
-arguments, just before @code{term-setup-hook}.
+arguments, just before @code{term-setup-hook}. In batch mode, Emacs
+does not run either of these hooks.
@end defvar
@defvar user-init-file
@defvar user-emacs-directory
This variable holds the name of the @file{.emacs.d} directory. It is
-ordinarily @file{~/.emacs.d}, but differs on some platforms.
+@file{~/.emacs.d} on all platforms but MS-DOS.
@end defvar
@node Terminal-Specific
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
trying the @samp{.elc} and @samp{.el} suffixes.
@cindex Termcap
- The usual function 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}.
+ 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}.
- When the name of the terminal type contains a hyphen, and no library
+ 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 and everything that follows
+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 in the name (the
-latter means the terminal doesn't have any library specific to it).
-Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
-libraries, Emacs will try the same library @file{term/aaa.el} for
-terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
-library can evaluate @code{(getenv "TERM")} to find the full name of
-the terminal type.@refill
+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
+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
+@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
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 which Emacs runs using
-@code{run-hooks} at the end of Emacs initialization, after loading both
-your init file and any terminal-specific libraries. You can
-use this variable to define initializations for terminals that do not
+@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
have their own libraries. @xref{Hooks}.
@defvar term-file-prefix
-@cindex @code{TERM} environment variable
-If the @code{term-file-prefix} 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:
@example
(load (concat term-file-prefix (getenv "TERM")))
@noindent
You may set the @code{term-file-prefix} variable to @code{nil} in your
init file if you do not wish to load the
-terminal-initialization file. To do this, put the following in
-your init file: @code{(setq term-file-prefix nil)}.
+terminal-initialization file.
-On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
-uses @samp{internal} as the terminal type.
+On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
@end defvar
@defvar term-setup-hook
You can use @code{term-setup-hook} to override the definitions made by a
terminal-specific file.
-@end defvar
- See @code{window-setup-hook} in @ref{Window Systems}, for a related
-feature.
+For a related feature, @pxref{Window Systems, window-setup-hook}.
+@end defvar
@node Command-Line Arguments
@subsection Command-Line Arguments
@cindex command-line arguments
- You can use command-line arguments to request various actions when you
-start Emacs. Since you do not need to start Emacs more than once per
-day, and will often leave your Emacs session running longer than that,
-command-line arguments are hardly ever used. As a practical matter, it
-is best to avoid making the habit of using them, since this habit would
-encourage you to kill and restart Emacs unnecessarily often. These
-options exist for two reasons: to be compatible with other editors (for
-invocation by other programs) and to enable shell scripts to run
-specific Lisp programs.
-
- This section describes how Emacs processes command-line arguments,
-and how you can customize them.
-
-@ignore
- (Note that some other editors require you to start afresh each time
-you want to edit a file. With this kind of editor, you will probably
-specify the file as a command-line argument. The recommended way to
-use GNU Emacs is to start it only once, just after you log in, and do
-all your editing in the same Emacs process. Each time you want to edit
-a different file, you visit it with the existing Emacs, which eventually
-comes to have many files in it ready for editing. Usually you do not
-kill the Emacs until you are about to log out.)
-@end ignore
+ You can use command-line arguments to request various actions when
+you start Emacs. Note that the recommended way of using Emacs is to
+start it just once, after logging in, and then do all editing in the same
+Emacs session (@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}).
+For this reason, you might not use command-line arguments very often;
+nonetheless, they can be useful when invoking Emacs from session
+scripts or debugging Emacs. This section describes how Emacs
+processes command-line arguments.
@defun command-line
This function parses the command line that Emacs was called with,
-processes it, loads the user's init file and displays the
-startup messages.
+processes it, and (amongst other things) loads the user's init file and
+displays the startup messages.
@end defun
@defvar command-line-processed
@cindex switches on command line
@cindex options on command line
@cindex command-line options
-The value of this variable is an alist of user-defined command-line
-options and associated handler functions. This variable exists so you
-can add elements to it.
+This variable is an alist of user-defined command-line options and
+associated handler functions. By default it is empty, but you can
+add elements if you wish.
A @dfn{command-line option} is an argument on the command line, which
has the form:
@defvar command-line-args-left
@vindex argv
The value of this variable is the list of command-line arguments that
-have not yet been processed. @code{argv} is an alias for this.
+have not yet been processed.
+@c Don't mention this, since it is a "bad name for a dynamically bound variable"
+@c @code{argv} is an alias for this.
@end defvar
@defvar command-line-functions
argument. If it has also dealt with some of the following arguments, it
can indicate that by deleting them from @code{command-line-args-left}.
-If all of these functions return @code{nil}, then the argument is used
+If all of these functions return @code{nil}, then the argument is treated
as a file name to visit.
@end defvar
There are two ways to get out of Emacs: you can kill the Emacs job,
which exits permanently, or you can suspend it, which permits you to
-reenter the Emacs process later. As a practical matter, you seldom kill
-Emacs---only when you are about to log out. Suspending is much more
-common.
+reenter the Emacs process later. (In a graphical environment, you can
+of course simply switch to another application without doing anything
+special to Emacs, then switch back to Emacs when you want.)
@menu
* Killing Emacs:: Exiting Emacs irreversibly.
@end menu
@node Killing Emacs
-@comment node-name, next, previous, up
@subsection Killing Emacs
@cindex killing Emacs
- Killing Emacs means ending the execution of the Emacs process. The
-parent process normally resumes control. The low-level primitive for
-killing Emacs is @code{kill-emacs}.
+ Killing Emacs means ending the execution of the Emacs process.
+If you started Emacs from a terminal, the parent process normally
+resumes control. The low-level primitive for killing Emacs is
+@code{kill-emacs}.
@deffn Command kill-emacs &optional exit-data
This command calls the hook @code{kill-emacs-hook}, then exits the
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.
@subsection Suspending Emacs
@cindex suspending Emacs
- On text-only terminals, it is possible to @dfn{suspend Emacs}, which
+ On text terminals, it is possible to @dfn{suspend Emacs}, which
means stopping Emacs temporarily and returning control to its superior
process, which is usually the shell. This allows you to resume
editing later in the same Emacs process, with the same buffers, the
Suspending works only on a terminal device from which the Emacs
session was started. We call that device the @dfn{controlling
terminal} of the session. Suspending is not allowed if the
-controlling terminal is a graphical terminal.
-
- Some operating systems do not support suspension of jobs; on these
-systems, ``suspension'' actually creates a new shell temporarily as a
-subprocess of Emacs. Then you would exit the shell to return to Emacs.
+controlling terminal is a graphical terminal. Suspending is usually
+not relevant in graphical environments, since you can simply switch to
+another application without doing anything special to Emacs.
+
+@c FIXME? Are there any systems Emacs still supports that do not
+@c have SIGTSTP?
+@cindex SIGTSTP
+ Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do
+not support suspension of jobs; on these systems, ``suspension''
+actually creates a new shell temporarily as a subprocess of Emacs.
+Then you would exit the shell to return to Emacs.
@deffn Command suspend-emacs &optional string
This function stops Emacs and returns control to the superior process.
@xref{Multiple Terminals}.
If @var{string} is non-@code{nil}, its characters are sent to Emacs's
-superior shell, to be read as terminal input. The characters in
-@var{string} are not echoed by the superior shell; only the results
-appear.
+superior shell, to be read as terminal input.
+@c FIXME? It seems to me that shell does echo STRING.
+The characters in @var{string} are not echoed by the superior shell;
+only the results appear.
Before suspending, @code{suspend-emacs} runs the normal hook
@code{suspend-hook}. After the user resumes Emacs,
unless the variable @code{no-redraw-on-reenter} is non-@code{nil}.
@xref{Refresh Screen}.
-In the following example, note that @samp{pwd} is not echoed after
-Emacs is suspended. But it is read and executed by the shell.
+Here is an example of how you could use these hooks:
@smallexample
-@group
-(suspend-emacs)
- @result{} nil
-@end group
-
@group
(add-hook 'suspend-hook
- (function (lambda ()
- (or (y-or-n-p
- "Really suspend? ")
- (error "Suspend canceled")))))
- @result{} (lambda nil
- (or (y-or-n-p "Really suspend? ")
- (error "Suspend canceled")))
-@end group
-@group
-(add-hook 'suspend-resume-hook
- (function (lambda () (message "Resumed!"))))
- @result{} (lambda nil (message "Resumed!"))
-@end group
-@group
-(suspend-emacs "pwd")
- @result{} nil
+ (lambda () (or (y-or-n-p "Really suspend? ")
+ (error "Suspend canceled"))))
@end group
+(add-hook 'suspend-resume-hook (lambda () (message "Resumed!")
+ (sit-for 2)))
+@end smallexample
+@c The sit-for prevents the ``nil'' that suspend-emacs returns
+@c hiding the message.
+
+Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}:
+
+@smallexample
@group
---------- Buffer: Minibuffer ----------
Really suspend? @kbd{y}
@group
---------- Parent Shell ----------
-lewis@@slug[23] % /user/lewis/manual
-lewis@@slug[24] % fg
+bash$ /home/username
+bash$ fg
@end group
@group
Resumed!
@end group
@end smallexample
+
+@c FIXME? AFAICS, it is echoed.
+Note that @samp{pwd} is not echoed after Emacs is suspended. But it
+is read and executed by the shell.
@end deffn
@defvar suspend-hook
@defun resume-tty &optional tty
This function resumes the previously suspended terminal device
-@var{tty}; @var{tty} can be a terminal object, a frame (meaning the
-terminal for that frame), or @code{nil} (meaning the terminal for the
-selected frame).
+@var{tty}; where @var{tty} has the same possible values as it does
+for @code{suspend-tty}.
@vindex resume-tty-functions
This function reopens the terminal device, re-initializes it, and
-redraws its with that terminal's selected frame. It then runs the
+redraws it with that terminal's selected frame. It then runs the
hook @code{resume-tty-functions}, passing the terminal object as an
argument to each function.
If the same device is already used by another Emacs terminal, this
-function signals an error.
+function signals an error. If @var{tty} is not suspended, this
+function does nothing.
@end defun
-@defun controlling-tty-p &optional terminal
-This function returns non-@code{nil} if @var{terminal} is the
-controlling terminal of the Emacs session; @code{terminal} can be a
+@defun controlling-tty-p &optional tty
+This function returns non-@code{nil} if @var{tty} is the
+controlling terminal of the Emacs session; @var{tty} can be a
terminal object, a frame (meaning the terminal for that frame), or
@code{nil} (meaning the terminal for the selected frame).
@end defun
@deffn Command suspend-frame
This command @dfn{suspends} a frame. For GUI frames, it calls
-@code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
-frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
-depending on whether the frame is displayed on the controlling
-terminal device or not.
+@code{iconify-frame} (@pxref{Visibility of Frames}); for frames on
+text terminals, it calls either @code{suspend-emacs} or
+@code{suspend-tty}, depending on whether the frame is displayed on the
+controlling terminal device or not.
@end deffn
@node System Environment
@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}.
-
-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.
+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}.
-@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
- This section explains how to determine the current time and the time
+ This section explains how to determine the current time and time
zone.
+@cindex epoch
+ 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
+integer number of seconds. This integer number,
+@ifnottex
+@var{high} * 2**16 + @var{low},
+@end ifnottex
+@tex
+$high*2^{16}+low$,
+@end tex
+is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970
+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.
+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}
+and @code{format-time-string} functions documented in the following
+sections.
+
@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. It is wise to count the
-characters from the beginning of the string rather than from the end, as
-additional information may some day be added at the end.
+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 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
-instead of the current time. This argument should have the same form
-as the times obtained from @code{current-time} (see below) and from
-@code{file-attributes} (@pxref{Definition of file-attributes}). It
-should be a list whose first two elements are integers; a third
-(microsecond) element, if present, is ignored. @var{time-value} can
-also be a cons of two integers, but this usage is obsolete.
+(represented as a list of integers), instead of the current time.
@example
@group
@end defun
@defun current-time
-This function returns the system's time value 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 since
-0:00 January 1, 1970 UTC (Coordinated Universal Time), 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 since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
-
-The first two elements can be compared with file time values such as you
-get with the function @code{file-attributes}.
-@xref{Definition of file-attributes}.
+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
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). Thus, it accepts the output of @code{current-time} and
-@code{file-attributes} (@pxref{Definition of file-attributes}).
+seconds since the epoch. The optional argument @var{time-value}, if
+given, specifies a time (represented as a list of integers) to convert
+instead of the current time.
@emph{Warning}: Since the result is floating point, it may not be
exact. Do not use this function if precise time stamps are required.
If the operating system doesn't supply all the information necessary to
compute the value, the unknown elements of the list are @code{nil}.
-The argument @var{time-value}, if given, specifies a time to analyze
-instead of the current time. The argument should have the same form
-as for @code{current-time-string} (see above). Thus, you can use
-times obtained from @code{current-time} (see above) and from
-@code{file-attributes}. @xref{Definition of file-attributes}.
+The argument @var{time-value}, if given, specifies a time (represented
+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)
-to calendrical information and vice versa. You can get time values
-from the functions @code{current-time} (@pxref{Time of Day}) and
-@code{file-attributes} (@pxref{Definition of file-attributes}).
+ 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 that contain 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. However, 64-bit
-and some 32-bit operating systems have larger time values, and can
-represent times far in the past or future.
+ 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@.
+However, 64-bit and some 32-bit operating systems have larger time
+values, and can represent times far in the past or future.
Time conversion functions always use the Gregorian calendar, even
for dates before the Gregorian calendar was introduced. Year numbers
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
work just like ordinary timers.
@deffn Command run-with-idle-timer secs repeat function &rest args
-Set up a timer which runs when Emacs has been 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}
+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.
If @var{repeat} is @code{nil}, the timer runs just once, the first time
@end deffn
@cindex idleness
- Emacs becomes ``idle'' when it starts waiting for user input, and it
-remains idle until the user provides some input. If a timer is set for
-five seconds of idleness, it runs approximately five seconds after Emacs
-first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
-will not run again as long as Emacs remains idle, because the duration
-of idleness will continue to increase and will not go down to five
-seconds again.
+ Emacs becomes @dfn{idle} when it starts waiting for user input, and
+it remains idle until the user provides some input. If a timer is set
+for five seconds of idleness, it runs approximately five seconds after
+Emacs first becomes idle. Even if @var{repeat} is non-@code{nil},
+this timer will not run again as long as Emacs remains idle, because
+the duration of idleness will continue to increase and will not go
+down to five seconds again.
Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess. But these interludes during idleness do
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.
-@c Emacs 19 feature
+ 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{high} @var{low}
-@var{microsec})}. The integers @var{high} and @var{low} combine to
-give the number of seconds of idleness, 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 since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
+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
-
- Some idle timer functions in user Lisp packages have a loop that
-does a certain amount of processing each time around, and exits when
-@code{(input-pending-p)} is non-@code{nil}. That 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
-To avoid these problems, don't use that technique. Instead, write
-such idle timers to reschedule themselves 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.)
@cindex sound
To play sound using Emacs, use the function @code{play-sound}. Only
-certain systems are supported; if you call @code{play-sound} on a system
-which cannot really do the job, it gives an error. Emacs version 20 and
-earlier did not support sound at all.
+certain systems are supported; if you call @code{play-sound} on a
+system which cannot really do the job, it gives an error.
The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).
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