@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node System Interface
@chapter Operating System Interface
* 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.
+* Desktop Notifications:: Desktop notifications.
+* File Notifications:: File 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.
+It loads any @file{leim-list.el} that it finds in the @code{load-path}
+directories. This file is intended for registering input methods.
+The search is only for any personal @file{leim-list.el} files that you
+may have created; it skips the directories containing the standard Emacs
+libraries (these should contain only a single @file{leim-list.el} file,
+which is compiled into the Emacs executable).
@vindex before-init-time
@item
@item
If @code{initial-buffer-choice} is a string, it visits the file with
-that name. If the @file{*scratch*} buffer exists and is
+that name. If it is a function, it calls the function and selects the
+buffer returned by the function. It it is @code{t}, it selects the
+@file{*scratch*} buffer. If the @file{*scratch*} buffer exists and is
empty, it inserts @code{initial-scratch-message} into that buffer.
@c To make things nice and confusing, the next three items can be
It runs @code{window-setup-hook}. @xref{Window Systems}.
@item
+@cindex startup screen
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}
If non-@code{nil}, this variable is a string that specifies a file or
directory for Emacs to display after starting up, instead of the
startup screen.
-@ignore
-@c I do not think this should be mentioned. AFAICS it is just a dodge
-@c around inhibit-startup-screen not being settable on a site-wide basis.
+If its value is a function, Emacs calls that function which must
+return a buffer which is then displayed.
If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.
-@end ignore
@end defopt
@defopt inhibit-startup-echo-area-message
Do not initialize any display; just start a server in the background.
@item --no-init-file
-@itemx -Q
+@itemx -q
Do not load either the init file, or the @file{default} library.
@item --no-site-file
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
The value of this variable is @code{t} once the command line has been
processed.
-If you redump Emacs by calling @code{dump-emacs}, you may wish to set
-this variable to @code{nil} first in order to cause the new dumped Emacs
-to process its new command-line arguments.
+If you redump Emacs by calling @code{dump-emacs} (@pxref{Building
+Emacs}), you may wish to set this variable to @code{nil} first in
+order to cause the new dumped Emacs to process its new command-line
+arguments.
@end defvar
@defvar command-switch-alist
In some cases, the option is followed in the command line by an
argument. In these cases, the @var{handler-function} can find all the
remaining command-line arguments in the variable
-@code{command-line-args-left}. (The entire list of command-line
-arguments is in @code{command-line-args}.)
+@code{command-line-args-left} (see below). (The entire list of
+command-line arguments is in @code{command-line-args}.)
The command-line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file. See also @ref{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.
Silicon Graphics Irix system.
@item ms-dos
-Microsoft's DOS. Emacs compiled with DJGPP for MS-DOS binds
+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
@item windows-nt
Microsoft Windows NT, 9X and later. The value of @code{system-type}
-is always @code{windows-nt}, e.g. even on Windows 7.
+is always @code{windows-nt}, e.g., even on Windows 7.
@end table
is absolutely necessary! In fact, we hope to eliminate some of these
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.
+@code{system-configuration}, e.g., against a regexp.
@end defvar
@defun system-name
removes @var{variable} from the environment. Otherwise, @var{value}
should be a string.
+@c FIXME: Document `substitute-env-vars'? --xfq
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}.
Lisp packages that load files of customizations, or any other sort of
user profile, should obey this variable in deciding where to find it.
They should load the profile of the user name found in this variable.
-If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
-option was used, then Lisp packages should not load any customization
-files or user profile.
+If @code{init-file-user} is @code{nil}, meaning that the @samp{-q},
+@samp{-Q}, or @samp{-batch} option was used, then Lisp packages should
+not load any customization files or user profile.
@end defvar
@defopt user-mail-address
variables are also useful for constructing frame titles (@pxref{Frame
Titles}).
+@cindex UID
@defun user-real-uid
This function returns the real @acronym{UID} of the user.
The value may be a floating point number, in the (unlikely) event that
The value may be a floating point number.
@end defun
+@cindex GID
+@defun group-gid
+This function returns the effective @acronym{GID} of the Emacs process.
+The value may be a floating point number.
+@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}
-and @code{format-time-string} functions documented in the following
-sections.
+@code{current-time-string}, 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
@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
@end defun
@defun current-time-zone &optional time-value
+@cindex time zone, current
This function returns a list describing the time zone that the user is
in.
@node Time Conversion
@section Time Conversion
+@cindex calendrical information
- 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.
@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
@item %h
This is a synonym for @samp{%b}.
@item %H
-This stands for the hour (00-23).
+This stands for the hour (00--23).
@item %I
-This stands for the hour (01-12).
+This stands for the hour (01--12).
@item %j
-This stands for the day of the year (001-366).
+This stands for the day of the year (001--366).
@item %k
-This stands for the hour (0-23), blank padded.
+This stands for the hour (0--23), blank padded.
@item %l
-This stands for the hour (1-12), blank padded.
+This stands for the hour (1--12), blank padded.
@item %m
-This stands for the month (01-12).
+This stands for the month (01--12).
@item %M
-This stands for the minute (00-59).
+This stands for the minute (00--59).
@item %n
This stands for a newline.
@item %N
-This stands for the nanoseconds (000000000-999999999). To ask for
+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
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
-This stands for the seconds (00-59).
+This stands for the seconds (00--59).
@item %t
This stands for a tab character.
@item %T
This is a synonym for @samp{%H:%M:%S}.
@item %U
-This stands for the week of the year (01-52), assuming that weeks
+This stands for the week of the year (01--52), assuming that weeks
start on Sunday.
@item %w
-This stands for the numeric day of week (0-6). Sunday is day 0.
+This stands for the numeric day of week (0--6). Sunday is day 0.
@item %W
-This stands for the week of the year (01-52), assuming that weeks
+This stands for the week of the year (01--52), assuming that weeks
start on Monday.
@item %x
This has a locale-specific meaning. In the default locale (named
This has a locale-specific meaning. In the default locale (named
@samp{C}), it is equivalent to @samp{%T}.
@item %y
-This stands for the year without century (00-99).
+This stands for the year without century (00--99).
@item %Y
This stands for the year with century.
@item %Z
@defun seconds-to-time seconds
This function converts @var{seconds}, a floating point number of
seconds since the epoch, to a time value and returns that. To perform
-the inverse conversion, use @code{float-time}.
+the inverse conversion, use @code{float-time} (@pxref{Time of Day}).
@end defun
@defun format-seconds format-string seconds
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
both elapsed and processor time, used by the Emacs process.
@deffn Command emacs-uptime &optional format
+@cindex uptime of Emacs
This function returns a string representing the Emacs
@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
running. The string is formatted by @code{format-seconds} according
@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
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
@defun set-input-mode interrupt flow meta &optional quit-char
This function sets the mode for reading keyboard input. If
-@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode. The default setting is
-system-dependent. Some systems always use @sc{cbreak} mode regardless
-of what is specified.
+@var{interrupt} is non-@code{nil}, then Emacs uses input interrupts.
+If it is @code{nil}, then it uses @sc{cbreak} mode. The default
+setting is system-dependent. Some systems always use @sc{cbreak} mode
+regardless of what is specified.
When Emacs communicates directly with X, it ignores this argument and
uses interrupts if that is the way it knows how to communicate.
(@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.)
were actually output, you can determine reliably whether they correspond
to the Termcap specifications in use.
-You close the termscript file by calling this function with an
-argument of @code{nil}.
-
-See also @code{open-dribble-file} in @ref{Recording Input}.
-
@example
@group
(open-termscript "../junk/termscript")
@result{} nil
@end group
@end example
+
+You close the termscript file by calling this function with an
+argument of @code{nil}.
+
+See also @code{open-dribble-file} in @ref{Recording Input}.
@end deffn
@node Sound Output
certain systems are supported; if you call @code{play-sound} on a
system which cannot really do the job, it gives an error.
+@c FIXME: Add indexes for Au and WAV? --xfq
The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).
@var{session}}.
@defvar emacs-save-session-functions
+@cindex session file
Emacs supports saving state via a hook called
@code{emacs-save-session-functions}. Emacs runs this hook when the
session manager tells it that the window system is shutting down. The
@end group
@end example
-@node Notifications
+@node Desktop Notifications
@section Desktop Notifications
@cindex desktop notifications
+@cindex notifications, on desktop
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.
+and the @code{notifications} library must be loaded. @xref{Top, ,
+D-Bus,dbus,D-Bus integration in Emacs}.
@defun notifications-notify &rest params
This function sends a notification to the desktop via D-Bus,
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.
+@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
interpreted as icon name.
@item :category @var{category}
-The type of notification this is, a string.
+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
@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}, like @samp{"mail-message-new"}.
+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.
@end example
@end defun
-@defun notifications-close-notification id
+@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
-Returns the capabilities of the notification server, a list of strings.
-The following capabilities can be expected:
+@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
@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 File Notifications
+@section Notifications on File Changes
+@cindex file notifications
+@cindex watch, for filesystem events
+
+Several operating systems support watching of filesystems for changes
+of files. If configured properly, Emacs links a respective library
+like @file{gfilenotify}, @file{inotify}, or @file{w32notify}
+statically. These libraries enable watching of filesystems on the
+local machine.
+
+It is also possible to watch filesystems on remote machines,
+@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}
+This does not depend on one of the libraries linked to Emacs.
+
+Since all these libraries emit different events on notified file
+changes, there is the Emacs library @code{filenotify} which provides a
+unique interface.
+
+@defun file-notify-add-watch file flags callback
+Add a watch for filesystem events pertaining to @var{file}. This
+arranges for filesystem events pertaining to @var{file} to be reported
+to Emacs.
+
+The returned value is a descriptor for the added watch. Its type
+depends on the underlying library, it cannot be assumed to be an
+integer as in the example below. It should be used for comparison by
+@code{equal} only.
+
+If the @var{file} cannot be watched for some reason, this function
+signals a @code{file-notify-error} error.
+
+Sometimes, mounted filesystems cannot be watched for file changes.
+This is not detected by this function, a non-@code{nil} return value
+does not guarantee that changes on @var{file} will be notified.
+
+@var{flags} is a list of conditions to set what will be watched for.
+It can include the following symbols:
+
+@table @code
+@item change
+watch for file changes
+@item attribute-change
+watch for file attribute changes, like permissions or modification
+time
+@end table
+
+If @var{file} is a directory, changes for all files in that directory
+will be notified. This does not work recursively.
+
+When any event happens, Emacs will call the @var{callback} function
+passing it a single argument @var{event}, which is of the form
+
+@lisp
+(@var{descriptor} @var{action} @var{file} [@var{file1}])
+@end lisp
+
+@var{descriptor} is the same object as the one returned by this
+function. @var{action} is the description of the event. It could be
+any one of the following symbols:
+
+@table @code
+@item created
+@var{file} was created
+@item deleted
+@var{file} was deleted
+@item changed
+@var{file} has changed
+@item renamed
+@var{file} has been renamed to @var{file1}
+@item attribute-changed
+a @var{file} attribute was changed
+@end table
+
+@var{file} and @var{file1} are the name of the file(s) whose event is
+being reported. For example:
+
+@example
+@group
+(require 'filenotify)
+ @result{} filenotify
+@end group
+
+@group
+(defun my-notify-callback (event)
+ (message "Event %S" event))
+ @result{} my-notify-callback
+@end group
+
+@group
+(file-notify-add-watch
+ "/tmp" '(change attribute-change) 'my-notify-callback)
+ @result{} 35025468
+@end group
+
+@group
+(write-region "foo" nil "/tmp/foo")
+ @result{} Event (35025468 created "/tmp/.#foo")
+ Event (35025468 created "/tmp/foo")
+ Event (35025468 changed "/tmp/foo")
+ Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(write-region "bla" nil "/tmp/foo")
+ @result{} Event (35025468 created "/tmp/.#foo")
+ Event (35025468 changed "/tmp/foo") [2 times]
+ Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(set-file-modes "/tmp/foo" (default-file-modes))
+ @result{} Event (35025468 attribute-changed "/tmp/foo")
+@end group
+@end example
+
+Whether the action @code{renamed} is returned, depends on the used
+watch library. It can be expected, when a directory is watched, and
+both @var{file} and @var{file1} belong to this directory. Otherwise,
+the actions @code{deleted} and @code{created} could be returned in a
+random order.
+
+@example
+@group
+(rename-file "/tmp/foo" "/tmp/bla")
+ @result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla")
+@end group
+
+@group
+(file-notify-add-watch
+ "/var/tmp" '(change attribute-change) 'my-notify-callback)
+ @result{} 35025504
+@end group
+
+@group
+(rename-file "/tmp/bla" "/var/tmp/bla")
+ @result{} ;; gfilenotify
+ Event (35025468 renamed "/tmp/bla" "/var/tmp/bla")
+
+ @result{} ;; inotify
+ Event (35025504 created "/var/tmp/bla")
+ Event (35025468 deleted "/tmp/bla")
+@end group
+@end example
+@end defun
+
+@defun file-notify-rm-watch descriptor
+Removes an existing file watch specified by its @var{descriptor}.
+@var{descriptor} should be an object returned by
+@code{file-notify-add-watch}.
+@end defun
@node Dynamic Libraries
@section Dynamically Loaded 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