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