@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-2013 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
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
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
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
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}
+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
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.
@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.
@item %p
@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
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
@end group
@end example
-@node Notifications
+@node Desktop Notifications
@section Desktop Notifications
@cindex desktop notifications
specification prior to @samp{"1.0"}.
@end defun
+@node File Notifications
+@section Notifications on File Changes
+@cindex file notifications
+
+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
HCoop / bpt / emacs.git / blobdiff