1 files changed, 71 insertions, 80 deletions

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 59685087ae8..5b302c883ad 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -64,7 +64,7 @@ another.  An overview of D-Bus can be found at
 * Alternative Buses::           Alternative buses and environments.
 * Errors and Events::           Errors and events.
 * Monitoring Messages::         Monitoring messages.
-* Inhibitor Locks::             Inhibit system shutdowns and sleep states.
+* File Descriptors::            Handle file descriptors.
 * Index::                       Index including concepts, functions, variables.
 
 * GNU Free Documentation License:: The license for this documentation.
@@ -1212,7 +1212,7 @@ which carries the input parameters to the object owning the method to
 be called, and a reply message returning the resulting output
 parameters from the object.
 
-@defun dbus-call-method bus service path interface method &optional :timeout timeout :authorizable auth &rest args
+@defun dbus-call-method bus service path interface method &optional :timeout timeout :authorizable auth :keep-fd &rest args
 @anchor{dbus-call-method}
 This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
 either the keyword @code{:system} or the keyword @code{:session}.
@@ -1245,6 +1245,11 @@ running):
 @result{} "/org/freedesktop/systemd1/job/17508"
 @end lisp
 
+If the parameter @code{:keep-fd} is given, and the return message has a
+first argument with a D-Bus type @code{:unix-fd}, the returned file
+descriptor is kept internally, and can be used in a later call of
+@code{dbus--close-fd} (@pxref{File Descriptors}).
+
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in
 @ref{Type Conversion}.
@@ -1324,7 +1329,7 @@ emulate the @code{lshal} command on GNU/Linux systems:
 @cindex method calls, asynchronous
 @cindex asynchronous method calls
 
-@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout :authorizable auth &rest args
+@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout :authorizable auth :keep-fd &rest args
 This function calls @var{method} on the D-Bus @var{bus}
 asynchronously.  @var{bus} is either the keyword @code{:system} or the
 keyword @code{:session}.
@@ -1347,6 +1352,11 @@ If the parameter @code{:authorizable} is given and the following
 @var{auth} is non-@code{nil}, the invoked method may interactively
 prompt the user for authorization.  The default is @code{nil}.
 
+If the parameter @code{:keep-fd} is given, and the return message has a
+first argument with a D-Bus type @code{:unix-fd}, the returned file
+descriptor is kept internally, and can be used in a later call of
+@code{dbus--close-fd} (@pxref{File Descriptors}).
+
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in
 @ref{Type Conversion}.
@@ -2205,109 +2215,90 @@ switches to the monitor buffer.
 @end deffn
 
 
-@node Inhibitor Locks
-@chapter Inhibit system shutdowns and sleep states
-
-@uref{https://systemd.io/INHIBITOR_LOCKS/, Systemd} includes a logic to
-inhibit system shutdowns and sleep states.  It can be controlled by a
-D-Bus API@footnote{@uref{https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html}}.
-Because this API includes handling of file descriptors, not all
-functions can be implemented by simple D-Bus method calls.  Therefore,
-the following functions are provided.
-
-@defun dbus-make-inhibitor-lock what why &optional block
-This function creates an inhibitor for system shutdowns and sleep states.
-
-@var{what} is a colon-separated string of lock types: @samp{shutdown},
-@samp{sleep}, @samp{idle}, @samp{handle-power-key},
-@samp{handle-suspend-key}, @samp{handle-hibernate-key},
-@samp{handle-lid-switch}. Example: @samp{shutdown:idle}.
-
-@c@var{who} is a descriptive string of who is taking the lock.  If it is
-@c@code{nil}, it defaults to @samp{Emacs}.
+@node File Descriptors
+@chapter Handle file descriptors
 
-@var{why} is a descriptive string of why the lock is taken. Example:
-@samp{Package Update in Progress}.
+Methods offered by the D-Bus API could return a file descriptor, which
+must be handled further.  This is indicated by the @code{:keep-fd}
+parameter when calling the method (@pxref{dbus-call-method}).
 
-The optional @var{block} is the mode of the inhibitor lock, either
-@samp{block} (@var{block} is non-@code{nil}), or @samp{delay}.
-
-Note, that the @code{who} argument of the inhibitor lock object of the
-systemd manager is always set to the string @samp{Emacs}.
-
-It returns a file descriptor or @code{nil}, if the lock cannot be
-acquired.  If there is already an inhibitor lock for the triple
-@code{(WHAT WHY BLOCK)}, this lock is returned.  Example:
+For example, @uref{https://systemd.io/INHIBITOR_LOCKS/, Systemd}
+includes a logic to inhibit system shutdowns and sleep states.  It can
+be controlled by a the method @samp{Inhibit} of interface
+@samp{org.freedesktop.login1.Manager}@footnote{@uref{https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html}}.
+This function returns a file descriptor, which must be used to unlock
+the locked resource, some of which lock the system.  In order to keep
+this file descriptor internally, the respective D-Bus method call looks
+like (@var{what}, @var{who}, @var{why} and @var{mode} are
+method-specific string arguments)
 
 @lisp
-(dbus-make-inhibitor-lock "sleep" "Test")
+(dbus-call-method
+ :system
+ "org.freedesktop.login1" "/org/freedesktop/login1"
+ "org.freedesktop.login1.Manager" "Inhibit"
+ :keep-fd WHAT WHO WHY MODE)
 
 @result{} 25
 @end lisp
-@end defun
 
-@defun dbus-registered-inhibitor-locks
-Return registered inhibitor locks, an alist.
-This allows to check, whether other packages of the running Emacs
-instance have acquired an inhibitor lock as well.
+The inhibition lock is unlocked, when the returned file descriptor is
+removed from the file system.  This cannot be achieved on Lisp level.
+Therefore, there is the function @code{dbus--fd-close} to performs this
+task (see below).
+
+@strong{Note}: When the Emacs process itself dies, all such locks are
+released.
 
-An entry in this list is a list @code{(@var{fd} @var{what} @var{why}
-@var{block})}.  The car of the list is the file descriptor retrieved
-from a @code{dbus-make-inhibitor-lock} call.  The cdr of the list
-represents the three arguments @code{dbus-make-inhibitor-lock} was
-called with.  Example:
+@strong{Note}: The following functions are internal to the D-Bus
+implementation of Emacs.  Use them with care.
+
+@defun dbus--fd-open filename
+Open @var{filename} and return the respective read-only file descriptor.
+This is another function to keep a file descriptor internally.  The
+returned file descriptor can be closed by @code{dbus--fd-close}.
+Example:
 
 @lisp
-(dbus-registered-inhibitor-locks)
+(dbus--fd-open "~/.emacs")
 
-@result{} ((25 "sleep" "Test" nil))
+@result{} 20
 @end lisp
 @end defun
 
-@defun dbus-close-inhibitor-lock lock
-Close inhibitor lock file descriptor.
-
-@var{lock}, a file descriptor, must be the result of a
-@code{dbus-make-inhibitor-lock} call.  It returns @code{t} in case of
-success, or @code{nil} if it isn't be possible to close the lock, or if
-the lock is closed already.  Example:
+@defun dbus--fd-close fd
+Close file descriptor @var{fd}.
+@var{fd} must be the result of a @code{dbus-call-method} or
+@code{dbus--fd-open} call, see @code{dbus--registered-fds}.  It returns
+@code{t} in case of success, or @code{nil} if it isn’t be possible to
+close the file descriptor, or if the file descriptor is closed already.
+Example:
 
 @lisp
-(dbus-close-inhibitor-lock 25)
+(dbus--fd-close 25)
 
 @result{} t
-
 @end lisp
 @end defun
 
-A typical scenario for these functions is to register for the
-D-Bus signal @samp{org.freedesktop.login1.Manager.PrepareForSleep}:
+@defun dbus--registered-fds
+Return registered file descriptors, an alist.
+The key is an open file descriptor, retrieved via
+@code{dbus-call-method} or @code{dbus--open-fd}.  The value is a string
+@var{object-path} or @var{filename}, which represents the arguments the
+function was called with.  Those values are not needed for further
+operations; they are just shown for information.
 
-@lisp
-(defvar my-inhibitor-lock
-        (dbus-make-inhibitor-lock "sleep" "Test"))
+This alist allows to check, whether other packages of the running Emacs
+instance have acquired a file descriptor as well.  Example:
 
-(defun my-dbus-PrepareForSleep-handler (start)
-  (if start ;; The system goes down for sleep
-      (progn
-        @dots{}
-        ;; Release inhibitor lock.
-        (when (natnump my-inhibitor-lock)
-          (dbus-close-inhibitor-lock my-inhibitor-lock)
-          (setq my-inhibitor-lock nil)))
-    ;; Reacquire inhibitor lock.
-    (setq my-inhibitor-lock
-          (dbus-make-inhibitor-lock "sleep" "Test"))))
-
-(dbus-register-signal
- :system "org.freedesktop.login1" "/org/freedesktop/login1"
- "org.freedesktop.login1.Manager" "PrepareForSleep"
- #'my-dbus-PrepareForSleep-handler)
+@lisp
+(dbus--registered-fds)
 
-@result{} ((:signal :system "org.freedesktop.login1.Manager" "PrepareForSleep")
-    ("org.freedesktop.login1" "/org/freedesktop/login1"
-      my-dbus-PrepareForSleep-handler))
+@result{} ((20 . "/home/user/.emacs")
+   (25 . "/org/freedesktop/login1"))
 @end lisp
+@end defun
 
 
 @node Index