sd-daemon: add gcc format string attribute to sd_notifyf

[elogind.git] / src / sd-daemon.h

diff --git a/src/sd-daemon.h b/src/sd-daemon.h
index e209af64896d12d6c027db6480502b5e579915e5..20c260c40dd764c19a8f36fed05d079520930a8c 100644 (file)
--- a/src/sd-daemon.h
+++ b/src/sd-daemon.h
@@ -27,13 +27,25 @@
   SOFTWARE.
 ***/
 
+#include <sys/types.h>
 #include <inttypes.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /* 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. */
+
+#ifdef __GNUC__
+#define _sd_printf_attr_(a,b) __attribute__ ((format (printf, a, b)))
+#else
+#define _sd_printf_attr_(a,b)
+#endif
 
 /*
   Log levels for usage on stderr:
@@ -56,12 +68,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 +102,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
@@ -106,4 +122,64 @@ int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port
  * errno style error code on failure. */
 int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length);
 
+/* Informs systemd about changed daemon state. This takes a numeber of
+ * newline seperated environment-style variable assignments in a
+ * string. The following strings are known:
+ *
+ *    READY=1      Tells systemd that daemon startup is finished (only
+ *                 relevant for services of Type=notify). The passed
+ *                 argument is a boolean "1" or "0". Since there is
+ *                 little value in signalling non-readiness the only
+ *                 value daemons should send is "READY=1".
+ *
+ *    STATUS=...   Passes a single-line status string back to systemd
+ *                 that describes the daemon state. This is free-from
+ *                 and can be used for various purposes: general state
+ *                 feedback, fsck-like programs could pass completion
+ *                 percentages and failing programs could pass a human
+ *                 readable error message. Example: "STATUS=Completed
+ *                 66% of file system check..."
+ *
+ *    ERRNO=...    If a daemon fails, the errno-style error code,
+ *                 formatted as string. Example: "ERRNO=2" for ENOENT.
+ *
+ *    BUSERROR=... If a daemon fails, the D-Bus error-style error
+ *                 code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
+ *
+ *    MAINPID=...  The main pid of a daemon, in case systemd did not
+ *                 fork off the process itself. Example: "MAINPID=4711"
+ *
+ * Daemons can choose to send additional variables.
+ *
+ * Returns a negative errno-style error code on failure. Returns > 0
+ * if systemd could be notified, 0 if it couldn't possibly because
+ * systemd is not running.
+ *
+ * See sd_notifyf() for more complete examples.
+ */
+int sd_notify(int unset_environment, const char *state);
+
+/* Similar to sd_send_state() but takes a format string.
+ *
+ * Example 1: A daemon could send the following after initialization:
+ *
+ * sd_notifyf(0, "READY=1\n"
+ *               "STATUS=Processing requests...\n"
+ *               "MAINPID=%lu",
+ *               (unsigned long) getpid());
+ *
+ * Example 2: A daemon could send the following shortly before
+ * exiting, on failure:
+ *
+ * sd_notifyf(0, "STATUS=Failed to start up: %s\n"
+ *               "ERRNO=%i",
+ *               strerror(errno),
+ *               errno);
+ */
+int sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_attr_(2,3);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif