ucw/daemon.h

   1 /*
   2  *      UCW Library -- Daemonization
   3  *
   4  *      (c) 2012--2014 Martin Mares <mj@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_DAEMON_H
  11 #define _UCW_DAEMON_H
  12
  13 #include <sys/types.h>
  14
  15 #ifdef CONFIG_UCW_CLEAN_ABI
  16 #define daemon_control ucw_daemon_control
  17 #define daemon_exit ucw_daemon_exit
  18 #define daemon_init ucw_daemon_init
  19 #define daemon_run ucw_daemon_run
  20 #endif
  21
  22 /** Parameters passed to the daemon helper. **/
  23 struct daemon_params {
  24   uns flags;                            // DAEMON_FLAG_xxx
  25   const char *pid_file;                 // A path to PID file (optional)
  26   const char *run_as_user;              // User name or "#uid" (optional)
  27   const char *run_as_group;             // Group name or "#gid" (optional)
  28
  29   // Internal
  30   uid_t run_as_uid;
  31   uid_t run_as_gid;
  32   int want_setuid;
  33   int want_setgid;
  34   int pid_fd;
  35 };
  36
  37 /** Flags passed to the daemon helper. **/
  38 enum daemon_flags {
  39   DAEMON_FLAG_PRESERVE_CWD = 1,         // Skip chdir("/")
  40   DAEMON_FLAG_SIMULATE = 2,             // Simulate daemonization (avoid fork etc.)
  41 };
  42
  43 /**
  44  * Daemon initialization. Should be run after parsing of options.
  45  * It resolves the UID and GID to run with and locks the PID file.
  46  * Upon error, it calls @die().
  47  **/
  48 void daemon_init(struct daemon_params *dp);
  49
  50 /**
  51  * Run the daemon. Should be run when everything is initialized. It forks off
  52  * a new process and does all necessary setup. Inside the new process, it calls
  53  * @body (and when it returns, it exits the process). In the original process, it writes
  54  * the PID file and returns.
  55  *
  56  * When `DAEMON_FLAG_SIMULATE` is set, it justs calls @body. This is useful
  57  * for running of daemons in a debugger.
  58  **/
  59 void daemon_run(struct daemon_params *dp, void (*body)(struct daemon_params *dp));
  60
  61 /**
  62  * Clean up when the daemon is about to exit. It removes the PID file.
  63  **/
  64 void daemon_exit(struct daemon_params *dp);
  65
  66 /**
  67  * Parse `run_as_user` and `run_as_group` and remember the results in internal fields.
  68  * This is called automatically by daemon_init(), but also provided as a separate
  69  * function in case you want to use daemon_switch_ugid(). Upon parse error, it calls die().
  70  **/
  71 void daemon_resolve_ugid(struct daemon_params *dp);
  72
  73 /**
  74  * Switch user and group as specified by the `run_as_user` and `run_as_group`.
  75  * This is performed automatically by daemon_run(), but sometimes you might want to
  76  * switch the user and group separately. In this case, you have to call daemon_resolve_ugid()
  77  * beforehand.
  78  **/
  79 void daemon_switch_ugid(struct daemon_params *dp);
  80
  81 #define DAEMON_ERR_LEN 256
  82
  83 /** Parameters passed to @daemon_control() **/
  84 struct daemon_control_params {
  85   const char *pid_file;         // A path to PID file
  86   const char *guard_file;       // A path to guard file
  87   int action;                   // Action to perform (DAEMON_CONTROL_xxx)
  88   char * const *argv;           // Daemon's arguments, NULL-terminated (for DAEMON_CONTROL_START)
  89   int signal;                   // Signal to send (for DAEMON_CONTROL_SIGNAL)
  90   char error_msg[DAEMON_ERR_LEN];       // A detailed error message returned (for DAEMON_STATUS_ERROR)
  91 };
  92
  93 enum daemon_control_action {
  94   DAEMON_CONTROL_CHECK = 1,
  95   DAEMON_CONTROL_START,
  96   DAEMON_CONTROL_STOP,
  97   DAEMON_CONTROL_SIGNAL,
  98 };
  99
 100 /**
 101  * Perform an action on a daemon:
 102  *
 103  * * `DAEMON_CONTROL_START` to start the daemon
 104  * * `DAEMON_CONTROL_STOP` to stop the daemon (send `SIGTERM` or `dc->signal` if non-zero)
 105  * * `DAEMON_CONTROL_CHECK` to check that the daemon is running
 106  * * `DAEMON_CONTROL_SIGNAL` to send a signal to the daemon (send `SIGHUP` or `dc->signal` if non-zero)
 107  *
 108  * The function returns a status code:
 109  *
 110  * * `DAEMON_STATUS_OK` if the action has been performed successfully
 111  * * `DAEMON_STATUS_ALREADY_DONE` if the daemon is already in the requested state
 112  * * `DAEMON_STATUS_NOT_RUNNING` if the action failed, because the daemon is not running
 113  * * `DAEMON_STATUS_ERROR` if the action failed for some other reason (in this case,
 114  *   `dc->error_msg` contains a full error message)
 115  * * `DAEMON_STATUS_STALE` if the daemon was in an undefined state (e.g., a stale PID file);
 116  *   for `DAEMON_CONTROL_START`, it means success
 117  **/
 118 enum daemon_control_status daemon_control(struct daemon_control_params *dc);
 119
 120 // XXX: Also used as exit codes of the ucw-daemon-control utility.
 121 enum daemon_control_status {
 122   DAEMON_STATUS_OK = 0,
 123   DAEMON_STATUS_ALREADY_DONE = 100,
 124   DAEMON_STATUS_NOT_RUNNING = 101,
 125   DAEMON_STATUS_ERROR = 102,
 126   DAEMON_STATUS_STALE = 103,
 127 };
 128
 129 #endif