XML: Brief documentation of LibUCW-XML

[libucw.git] / ucw / daemon.h

diff --git a/ucw/daemon.h b/ucw/daemon.h
index 561a401577e9bbecc5614a932be298c71475ea7b..25a34f8033f3b43690b036892da17a82a4415a30 100644 (file)
--- a/ucw/daemon.h
+++ b/ucw/daemon.h
@@ -1,7 +1,7 @@
 /*
  *     UCW Library -- Daemonization
  *
- *     (c) 2012 Martin Mares <mj@ucw.cz>
+ *     (c) 2012--2014 Martin Mares <mj@ucw.cz>
  *
  *     This software may be freely distributed and used according to the terms
  *     of the GNU Lesser General Public License.
@@ -12,9 +12,18 @@
 
 #include <sys/types.h>
 
+#ifdef CONFIG_UCW_CLEAN_ABI
+#define daemon_control ucw_daemon_control
+#define daemon_exit ucw_daemon_exit
+#define daemon_init ucw_daemon_init
+#define daemon_resolve_ugid ucw_daemon_resolve_ugid
+#define daemon_run ucw_daemon_run
+#define daemon_switch_ugid ucw_daemon_switch_ugid
+#endif
+
 /** Parameters passed to the daemon helper. **/
 struct daemon_params {
-  uns flags;                           // DAEMON_FLAG_xxx
+  uint flags;                          // DAEMON_FLAG_xxx
   const char *pid_file;                        // A path to PID file (optional)
   const char *run_as_user;             // User name or "#uid" (optional)
   const char *run_as_group;            // Group name or "#gid" (optional)
@@ -30,6 +39,7 @@ struct daemon_params {
 /** Flags passed to the daemon helper. **/
 enum daemon_flags {
   DAEMON_FLAG_PRESERVE_CWD = 1,                // Skip chdir("/")
+  DAEMON_FLAG_SIMULATE = 2,            // Simulate daemonization (avoid fork etc.)
 };
 
 /**
@@ -44,6 +54,9 @@ void daemon_init(struct daemon_params *dp);
  * a new process and does all necessary setup. Inside the new process, it calls
  * @body (and when it returns, it exits the process). In the original process, it writes
  * the PID file and returns.
+ *
+ * When `DAEMON_FLAG_SIMULATE` is set, it justs calls @body. This is useful
+ * for running of daemons in a debugger.
  **/
 void daemon_run(struct daemon_params *dp, void (*body)(struct daemon_params *dp));
 
@@ -52,9 +65,24 @@ void daemon_run(struct daemon_params *dp, void (*body)(struct daemon_params *dp)
  **/
 void daemon_exit(struct daemon_params *dp);
 
+/**
+ * Parse `run_as_user` and `run_as_group` and remember the results in internal fields.
+ * This is called automatically by daemon_init(), but also provided as a separate
+ * function in case you want to use daemon_switch_ugid(). Upon parse error, it calls die().
+ **/
+void daemon_resolve_ugid(struct daemon_params *dp);
+
+/**
+ * Switch user and group as specified by the `run_as_user` and `run_as_group`.
+ * This is performed automatically by daemon_run(), but sometimes you might want to
+ * switch the user and group separately. In this case, you have to call daemon_resolve_ugid()
+ * beforehand.
+ **/
+void daemon_switch_ugid(struct daemon_params *dp);
+
 #define DAEMON_ERR_LEN 256
 
-/** Parameters passed to daemon_control() **/
+/** Parameters passed to @daemon_control() **/
 struct daemon_control_params {
   const char *pid_file;                // A path to PID file
   const char *guard_file;      // A path to guard file
@@ -65,7 +93,7 @@ struct daemon_control_params {
 };
 
 enum daemon_control_action {
-  DAEMON_CONTROL_CHECK,
+  DAEMON_CONTROL_CHECK = 1,
   DAEMON_CONTROL_START,
   DAEMON_CONTROL_STOP,
   DAEMON_CONTROL_SIGNAL,
@@ -77,7 +105,7 @@ enum daemon_control_action {
  * * `DAEMON_CONTROL_START` to start the daemon
  * * `DAEMON_CONTROL_STOP` to stop the daemon (send `SIGTERM` or `dc->signal` if non-zero)
  * * `DAEMON_CONTROL_CHECK` to check that the daemon is running
- * * `DAEMON_CONTROL_SIGNAL` to send a signal to the daemon
+ * * `DAEMON_CONTROL_SIGNAL` to send a signal to the daemon (send `SIGHUP` or `dc->signal` if non-zero)
  *
  * The function returns a status code:
  *
@@ -85,15 +113,19 @@ enum daemon_control_action {
  * * `DAEMON_STATUS_ALREADY_DONE` if the daemon is already in the requested state
  * * `DAEMON_STATUS_NOT_RUNNING` if the action failed, because the daemon is not running
  * * `DAEMON_STATUS_ERROR` if the action failed for some other reason (in this case,
- *   the error_msg field contains a full error message)
+ *   `dc->error_msg` contains a full error message)
+ * * `DAEMON_STATUS_STALE` if the daemon was in an undefined state (e.g., a stale PID file);
+ *   for `DAEMON_CONTROL_START`, it means success
  **/
 enum daemon_control_status daemon_control(struct daemon_control_params *dc);
 
+// XXX: Also used as exit codes of the ucw-daemon-control utility.
 enum daemon_control_status {
   DAEMON_STATUS_OK = 0,
   DAEMON_STATUS_ALREADY_DONE = 100,
   DAEMON_STATUS_NOT_RUNNING = 101,
   DAEMON_STATUS_ERROR = 102,
+  DAEMON_STATUS_STALE = 103,
 };
 
 #endif