From 695d1ef183a2200cf5f32998f9bd7eb0d8b56ac2 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 2 Jun 2010 04:24:33 +0200
Subject: [PATCH] sd-daemon: rework documentation a little

---
 src/sd-daemon.c |  1 -
 src/sd-daemon.h | 27 ++++++++++++++++-----------
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/src/sd-daemon.c b/src/sd-daemon.c
index 2e1bf321..29bd2046 100644
--- a/src/sd-daemon.c
+++ b/src/sd-daemon.c
@@ -89,7 +89,6 @@ int sd_listen_fds(int unset_environment) {
                 goto finish;
         }
 
-
         for (fd = SD_LISTEN_FDS_START; fd < SD_LISTEN_FDS_START + (int) l; fd ++) {
                 int flags;
 
diff --git a/src/sd-daemon.h b/src/sd-daemon.h
index e209af64..0d8de45b 100644
--- a/src/sd-daemon.h
+++ b/src/sd-daemon.h
@@ -30,10 +30,11 @@
 #include <inttypes.h>
 
 /* Reference implementation of a few systemd related interfaces for
- * writing daemons. These interfaces are trivial to implement, however
- * to simplify porting we provide this reference
- * implementation. Applications are free to reimplement the algorithms
- * described here. */
+ * writing daemons. These interfaces are trivial to implement. To
+ * simplify porting we provide this reference
+ * implementation. Applications are welcome to reimplement the
+ * algorithms described here, if they do not want to include these two
+ * source files. */
 
 /*
   Log levels for usage on stderr:
@@ -56,12 +57,16 @@
 #define SD_LISTEN_FDS_START 3
 
 /* Returns how many file descriptors have been passed, or a negative
- * errno code on failure. Optionally removes the $LISTEN_FDS and
- * $LISTEN_PID file descriptors from the environment
- * (recommended). You'll find the file descriptors passed as fds
- * SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1 if r is the return
- * value of this functioin. Returns a negative errno style error code
- * on failure. */
+ * errno code on failure. Optionally, removes the $LISTEN_FDS and
+ * $LISTEN_PID file descriptors from the environment (recommended, but
+ * problematic in threaded environments). If r is the return value of
+ * this function you'll find the file descriptors passed as fds
+ * SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative
+ * errno style error code on failure. This function call ensures that
+ * the FD_CLOEXEC flag is set for the passed file descriptors, to make
+ * sure they are not passed on to child processes. If FD_CLOEXEC shall
+ * not be set, the caller needs to unset it after this call for all file
+ * descriptors that are used.*/
 int sd_listen_fds(int unset_environment);
 
 /* Helper call for identifying a passed file descriptor. Returns 1 if
@@ -86,7 +91,7 @@ int sd_is_socket(int fd, int family, int type, int listening);
 
 /* Helper call for identifying a passed file descriptor. Returns 1 if
  * the file descriptor is an Internet socket, of the specified family
- * (either AF_INET or AF_INET6) of the specified type (SOCK_DGRAM,
+ * (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM,
  * SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version
  * check is not done. If type is 0 a socket type check will not be
  * done. If port is 0 a socket port check will not be done. The
-- 
2.39.5