4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief Daemon public header */
30 #include <boost/utility.hpp>
32 //#include "Daemon.mpp"
33 ///////////////////////////////hh.p////////////////////////////////////////
37 /** \brief %Daemon process
39 %senf::Daemon provides simple management for daemon processes. Specifically, the %Daemon class
41 \li <i>Safe startup.</i> If the startup fails, the foreground process which launches the
42 daemon will terminate with an appropriate error exit code.
43 \li <i>Straight forward application initialization.</i> The daemon process is forked before
44 even initializing the application. The initialization procedure must not cater for a
46 \li <i>Automatic pid file management.</i> The daemon will not be started, if a valid pid file is
47 found. Stale pid files are automatically removed.
48 \li <i>Console log management.</i> It is possible, to redirect standard output and error to
49 one or two log files. Messages pertaining to application initialization will be written
50 to both the console and the log file whereas later messages will be directed to the log
52 \li <i>Optional foreground execution.</i> The daemon may be started in the foreground for
53 debugging purposes. In this case, the console log file(s) is/are automatically
56 Starting the daemon process proceeds along the following steps:
57 \li The daemon is started by calling the daemon class instances start() member. This
58 normally happens from the \c main() function generated by \ref SENF_DAEMON_MAIN().
59 \li configure() is called. This (virtual) member configures the daemon manager by calling
60 the Daemon class parameter members.
61 \li The log files are opened, \c fork() is called and the pid file is checked and
62 created. The parent (foreground) process keeps running overseeing the daemon process.
63 \li main() is called. This virtual member may optionally be overridden in the derived
64 class. Here we assume, main() is not overridden so the default implementation is used.
65 \li main() calls init().
66 \li after init() returns, main() calls detach().
67 \li detach() signals successful startup to the parent process. The parent process terminates
68 leaving the daemon process running in the background.
69 \li main() calls run()
70 \li If run() ever returns, the daemon process terminates.
71 \li Whenever the process terminates normally (not necessarily successfully), the pid file is
72 automatically removed.
74 The parameter members are used from configure() to configure the daemon manager. See below
75 for details. The \e default configure() implementation will scan the command line arguments
76 to check for the following parameters:
80 <tr><td><tt>--no-daemon</tt></td><td>Run in foreground</td></tr>
82 <tr><td><tt>--console-log=</tt><i>stdout</i>[<tt>,</tt><i>stderr</i>]</td><td>Set the
83 console log file(s). If only \a stdout is specified (with no comma), the same log file
84 configuration will be applied to the standard output and error stream. Otherwise each stream
85 is assigned it's own log file. If either log file name is empty, the command will not change
86 the log file of that stream, the default log file will be used. If the log file name is set
87 to 'none', the log file will be disabled.</td></tr>
89 <tr><td><tt>--pid-file=</tt><i>pidfile</i></td><td>Set pid file path</td></tr>
93 The default configure() implementation will use whatever parameters have been set beforehand
94 as default values. These default values should be set in a derived class configure()
95 implementation. After setting the default values, the configure() implementation may choose
96 to call this default configure() implementation to scan for command line parmeters. The
97 default configure() implementation does \e not completely parse the command line
98 arguments. It just checks, if any of above arguments are present and precesses them. Other
99 arguments are completely ignored. The command line parameters should be completely processed
103 class Daemon : boost::noncopyable
106 ///////////////////////////////////////////////////////////////////////////
109 /// Select standard stream to redirect
111 StdOut /** Standard output stream */
112 , StdErr /** Standard error stream */
113 , Both /** Both, standard output and error stream */
116 ///////////////////////////////////////////////////////////////////////////
117 ///\name Structors and default members
126 void daemonize(bool); ///< Configure whether to run in fore- or background
127 bool daemon(); ///< \c true, if running as daemon
129 void consoleLog(std::string const &, StdStream which = Both);
130 ///< Configure console log file
131 /**< May be called multiple times to set the log file
132 for stdout and stderr seperately. Any standard stream
133 not assigned to a log file will be redirected to
136 When running in the foreground, the log files will be
139 void pidFile(std::string const &); ///< Configure pid file
140 /**< If a pid file is configured it will be checked on
141 daemon startup. If another running instance of the
142 daemon is detected, starting the daemon will fail. */
145 ///\name Auxiliary helpers
148 void detach(); ///< Detach into background now
149 /**< This is \e not the same as forking. The process will
150 already have forked into the background but until
151 detach() is called (either automatically after init()
152 returns or manually), the front end (foreground)
153 process will wait for the background process to ensure
154 successful startup. */
156 int argc(); ///< Access command line parameter count
157 char ** argv(); ///< Access command line parameters
159 static void exit(unsigned code=0); ///< Terminate daemon with failure
163 int start(int argc, char ** argv); ///< Called from main() to launch daemon.
164 /**< Normally not called directly but from the
165 \ref SENF_DAEMON_MAIN macro. */
170 virtual void configure(); ///< Called before forking to configure the daemon class
171 /**< This default implementation will parser some command
172 line parameters. See the class documentation above. */
180 virtual void main(); ///< Called after forking to execute the main application
181 /**< The default implementation will call init(), detach()
182 and then run(). It is preferred to override init() and
183 run() if possible. */
184 virtual void init(); ///< Called to initialize the main application
185 /**< While init() is running, the application still is
186 connected to the controlling terminal. Error messages
187 will be shown to the user.
189 This member is only called, if the default main()
190 implementation is not overridden. */
191 virtual void run(); ///< Called to execute main application
192 /**< Called after detaching from the controlling
195 This member is only called, if the default main()
196 implementation is not overridden. */
201 bool pidfileCreate();
207 std::string stdoutLog_;
208 std::string stderrLog_;
211 std::string pidfile_;
212 bool pidfileCreated_;
217 /** \brief Provide \c main() function
219 This macro will provide a \c main() function to launch the daemon process defined in \a
220 klass. \a klass must be a class derived from senf::Daemon.
224 # define SENF_DAEMON_MAIN(klass) \
225 int main(int argc, char ** argv) \
228 return instance.start(argc, argv); \
233 ///////////////////////////////hh.e////////////////////////////////////////
234 //#include "Daemon.cci"
235 //#include "Daemon.ct"
236 //#include "Daemon.cti"
243 // comment-column: 40
244 // c-file-style: "senf"
245 // indent-tabs-mode: nil
246 // ispell-local-dictionary: "american"
247 // compile-command: "scons -u test"