agent: Implement --supervised command (for systemd, etc).

* agent/gpg-agent.c (get_socket_path): New function for POSIX systems
to return the path for a provided unix-domain socket.
(map_supervised_sockets): New function to inspect $LISTEN_FDS and
$LISTEN_FDNAMES and map them to the specific functionality offered by
the agent.
(main): Add --supervised command.  When used, listen on already-open
file descriptors instead of opening our own.
* doc/gpg-agent.texi: Document --supervised option.

--

"gpg-agent --supervised" is a way to invoke gpg-agent such that a
system supervisor like systemd can provide socket-activated startup,
log management, and scheduled shutdown.

When running in this mode, gpg-agent:

 * Does not open its own listening socket; rather, it expects to be
   given a listening socket on incoming file descriptors.

 * Does not detach from the invoking process, staying in the
   foreground instead.  Unless otherwise specified, logs are sent to
   stderr.

Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>

doc/gpg-agent.texi

@@ -158,6 +158,18 @@ As an alternative you may create a new process as a child of
 gpg-agent: @code{gpg-agent --daemon /bin/sh}.  This way you get a new
 shell with the environment setup properly; after you exit from this
 shell, gpg-agent terminates within a few seconds.
+
+@item --supervised
+@opindex supervised
+Run in the foreground, sending logs by default to stderr, and
+listening on provided file descriptors, which must already be bound to
+listening sockets.  This command is useful when running under systemd
+or other similar process supervision schemes.
+
+In --supervised mode, different file descriptors can be provided for
+use as different socket types (e.g. ssh, extra) as long as they are
+identified in the environment variable $LISTEN_FDNAMES (see
+sd_listen_fds(3) for more information on this convention).
 @end table
 
 @mansect options