@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
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 number of picoseconds from the start of that microsecond to the
specified time.
- The return value of @code{current-time} represents time using three
+ 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.
@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.
@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
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.)
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
@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 Dynamic Libraries
@section Dynamically Loaded Libraries