1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
/*
Copyright (C) 2008 Andreas Baumann <abaumann@yahoo.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef WOLF_DAEMON_H
#define WOLF_DAEMON_H
/**
* @addtogroup wolf_unix Unix-specific
* @{
*/
/**
* @addtogroup wolf_daemon Unix Daemons
* @{
*/
/**
* @file daemon.h
* @brief helper to write a Unix daemon
* @author Andreas Baumann <abaumann@yahoo.com>
*/
#include "errors.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief ADT representing the state of the daemon
*/
typedef struct wolf_daemon_t *wolf_daemon_p;
/**
* @brief structure to fill out when creating a new daemon.
*/
typedef struct wolf_daemon_params_t {
const char *daemon_name; /**< name of the daemon (used for setproctitle,
default name of the pidfile, logfile) */
const char *pid_filename; /**< name of the pid/lock file */
const char *group_name; /**< group of the effective user */
const char *user_name; /**< name of the effective user */
} wolf_daemon_params_t;
/**
* Creates a new Unix daemon.
*
* @param params steers how the daemon should be created.
* @param error indicates errors creating the daemon
*
* @return the daemon object
*/
wolf_daemon_p wolf_daemon_new( wolf_daemon_params_t params,
wolf_error_t *error );
/**
* Start the daemon
*
* @param demon the daemon object to daemonize
*/
wolf_error_t wolf_daemon_start( wolf_daemon_p demon );
/**
* Terminates the daemon. This must be the last function in
* your main program as the call doesn't return!
*
* @param demon the daemon object to daemonize
*/
void wolf_daemon_exit( wolf_daemon_p demon );
/**
* Free up resources used by the daemon object (before daemonizing).
* After a successful call to daemon_start daemon_exit will take
* care of cleaning up. Use this if you have to bail out in main
* just after daemon_new and before daemon_start.
*
* @param demon the daemon object to free
*/
void wolf_daemon_free( wolf_daemon_p demon );
/**
* Initialize signal handlers of the daemon.
*
* Must only be called if the daemon runs in foreground mode! Otherwise
* signals are initiailized by wolf_daemon_start.
*
* Must be called before wolf_daemon_signals_install_handlers!
*/
wolf_error_t wolf_daemon_signals_initialize( void );
/**
* Installs the default signal handlers of the daemon. After this fatal signals
* lead to a graceful termination with logging, some signals are
* ignored (as terminal signals) and some other signals can be
* retrieved with wolf_daemon_signals_suspend in the main program.
*
* Must only be called if the daemon runs in foreground mode! Otherwise
* signals are initiailized by wolf_daemon_start.
*
* wolf_daemon_signals_initialize must be called before.
*/
wolf_error_t wolf_daemon_signals_install_handlers( void );
/**
* Suspend the current thread till a signal happens. Not all signals
* are delivered this way, only those registered to have notifications
* (see wolf_signal_install_notify). Per default the following signals
* are delivered: SIGTERM, SIGINT, SIGHUP, SIGUSR1, SIGUSR2.
*
* @param timeout wait at most timeout seconds, then return also
* without signal
* @param error WOLF_OK if a signal occured, WOLF_ERR_TIMEOUT if
* no signal happened after timeout seconds
* @return the signal number or undefined on timeout
*/
int wolf_daemon_signals_suspend( int timeout, wolf_error_t *error );
/**
* Frees resources used for signal handling in the foreground mode
* of the daemon.
*
* Must only be called if the daemon runs in foreground mode! Otherwise
* signals are terminated by wolf_daemon_exit resp. wolf_daemon_free.
*/
void wolf_daemon_signals_terminate( void );
#ifdef __cplusplus
}
#endif
/** @} */ /* @addtogroup wolf_daemon */
/** @} */ /* @addtogroup wolf_unix */
#endif /* ifndef WOLF_DAEMON_H */
|
