Some cleanup and documentation

diff --git a/doc/README b/doc/README
new file mode 100644 (file)
index 0000000..6656215
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,16 @@
+python-daemon is a pretty simple object named Daemon used to daemonize a process.
+
+To do so subclass the Daemon object and override its run method with the code
+you want to turn into a unix daemon.
+
+You can override the shutdown method which is called on Daemon stop (either via
+the stop method or on SIGTERM).
+
+Cf. examples for code snippet.
+
+
+FEATURES:
+       * redirects stderr|stdout to file
+       * writes a pid file
+       * transparently deletes the pid file at stop
+       * catch SIGTERM and handles a clean stop via shutdown method

diff --git a/src/daemon.py b/src/daemon.py
index c364efdad53eb7b21928b4ac74c03bdde5c0c5ac..96cde84e9ec3a043dd49f3b557a28e56b5c438b8 100644 (file)
--- a/src/daemon.py
+++ b/src/daemon.py
@@ -3,7 +3,7 @@
 # Public Domain
 #
 # Copyright 2007, 2009 Sander Marechal <s.marechal@jejik.com>
-# Copyright 2010, 2011 Jack Kaliko <efrim@azylum.org>
+# Copyright 2010, 2011, 2012 Jack Kaliko <efrim@azylum.org>
 #
 # http://www.jejik.com/articles/2007/02/a_simple_unix_linux_daemon_in_python/
 
@@ -34,9 +34,15 @@ class Daemon(object):
 
     def daemonize(self):
         """
-        do the UNIX double-fork magic, see Stevens' "Advanced
-        Programming in the UNIX Environment" for details (ISBN 0201563177)
-        http://www.erlenstar.demon.co.uk/unix/faq_2.html#SEC16
+        Do the UNIX double-fork magic.
+        see W. Richard Stevens, "Advanced Programming in the Unix Environment"
+        for details (ISBN 0201563177)
+
+        Short explanation:
+            Unix processes belong to "process group" which in turn lies within a "session".
+            A session can have a controlling tty.
+            Forking twice allows to detach the session from a possible tty.
+            The process lives then within the init process.
         """
         try:
             pid = os.fork()
@@ -44,11 +50,11 @@ class Daemon(object):
                 # exit first parent
                 sys.exit(0)
         except OSError, e:
-            sys.stderr.write("fork #1 failed: %d (%s)\n" % (e.errno, e.strerror))
+            sys.stderr.write('fork #1 failed: %d (%s)\n' % (e.errno, e.strerror))
             sys.exit(1)
 
         # Decouple from parent environment
-        os.chdir("/")
+        os.chdir('/')
         os.setsid()
         self.umask = os.umask(0)
 
@@ -59,7 +65,7 @@ class Daemon(object):
                 # exit from second parent
                 sys.exit(0)
         except OSError, e:
-            sys.stderr.write("fork #2 failed: %d (%s)\n" % (e.errno, e.strerror))
+            sys.stderr.write('fork #2 failed: %d (%s)\n' % (e.errno, e.strerror))
             sys.exit(1)
 
         self.write_pid()
@@ -117,7 +123,7 @@ class Daemon(object):
             pid = None
 
         if pid:
-            message = "pidfile %s already exist. Daemon already running?\n"
+            message = 'pidfile %s already exist. Daemon already running?\n'
             sys.stderr.write(message % self.pidfile)
             sys.exit(1)
 
@@ -146,7 +152,7 @@ class Daemon(object):
             pid = None
 
         if not pid:
-            message = "pidfile %s does not exist. Is the Daemon running?\n"
+            message = 'pidfile %s does not exist. Is the Daemon running?\n'
             sys.stderr.write(message % self.pidfile)
             return  # not an error in a restart
 
@@ -188,13 +194,5 @@ class Daemon(object):
         called after the process has been daemonized by start() or restart().
         """
 
-
-def main():
-    pass
-
-# Script starts here
-if __name__ == '__main__':
-    main()
-
 # VIM MODLINE
 # vim: ai ts=4 sw=4 sts=4 expandtab