-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Systemd facilities (Socket activation, Notify)
--   
--   A module for Systemd facilities.
@package systemd
@version 2.3.0


-- | This module implements all functions from <a>System.Systemd.Daemon</a>
--   that require or return <a>Socket</a>s purely using <a>Fd</a>s. This is
--   especially useful if you have to do low level IO using file
--   descriptors or use a different socket library than <tt>network</tt>.
--   
--   The API is exactly the same as <a>System.Systemd.Daemon</a> except
--   that <a>Socket</a>s have been replaced by <a>Fd</a>s (actually
--   <a>System.Systemd.Daemon</a> uses this module internally). This also
--   means that <a>System.Systemd.Daemon.Fd</a> and
--   <a>System.Systemd.Daemon</a> expose conflicting functions. You either
--   have to import <a>System.Systemd.Daemon.Fd</a> <tt>qualified</tt> or
--   like so:
--   
--   <pre>
--   import System.Systemd.Daemon hiding ( notifyWithFD, storeFd
--                                       , storeFdWithName
--                                       , getActivatedSockets
--                                       , getActivatedSocketsWithNames )
--   import System.Systemd.Daemon.Fd
--   </pre>
--   
--   The functions in <a>System.Systemd.Daemon</a> that are not implemented
--   in this module are 100% compatible with
--   <a>System.Systemd.Daemon.Fd</a>.
module System.Systemd.Daemon.Fd

-- | Same as <a>notify</a>, but send along a <a>Fd</a>. Note that the
--   caller must set the message, i. e. send <tt>FDSTORE=1</tt> to actually
--   store the file descriptor. In most cases it is probably best to use
--   <a>storeFd</a> or the notify-functions from
--   <a>System.Systemd.Daemon</a>.
--   
--   Equivalent to standard <a>notifyWithFD</a>.
notifyWithFD :: Bool -> String -> Fd -> IO (Maybe ())

-- | Notify Systemd to store a file descriptor for us. This together with
--   <a>getActivatedSockets</a> allows for zero downtime restarts and
--   socket activation.
--   
--   Equivalent to standard <a>storeFd</a>
storeFd :: Fd -> IO (Maybe ())

-- | Like <a>storeFd</a>, but associate the file descriptor with a name.
--   Best used along with <a>getActivatedSocketsWithNames</a>.
--   
--   Equivalent to standard <a>storeFdWithName</a>
storeFdWithName :: Fd -> String -> IO (Maybe ())

-- | Return <a>Just</a> a list of file descriptors if the current process
--   has been activated with one or more socket by systemd, <a>Nothing</a>
--   otherwise.
--   
--   The file descriptors are in the same order as the sockets in the
--   associated <tt>.socket</tt> file. The sockets will have their family,
--   type, and status set according to the <tt>.socket</tt> file.
--   
--   Equivalent to standard <a>getActivatedSockets</a>
getActivatedSockets :: IO (Maybe [Fd])

-- | Like <a>getActivatedSockets</a>, but also return the associated names.
--   If a file descriptor has no associated name, it will be a generic one
--   set by systemd.
--   
--   Equivalent to standard <a>getActivatedSocketsWithNames</a>
getActivatedSocketsWithNames :: IO (Maybe [(Fd, String)])


-- | Implementation of Systemd facilities to create and manage daemons.
--   
--   All socket-related actions in this module, work with the
--   <a>Network.Socket</a> module from <tt>network</tt>. If you want to use
--   a different socket library or work directly with file descriptors, see
--   <a>System.Systemd.Daemon.Fd</a>.
--   
--   This module contains socket activation and notify tools. See
--   
--   <ul>
--   
--   <li><a>http://0pointer.de/blog/projects/socket-activation.html</a></li>
--   
--   <li><a>http://www.freedesktop.org/software/systemd/man/systemd.socket.html</a></li>
--   
--   <li><a>http://www.freedesktop.org/software/systemd/man/systemd.service.html</a></li>
--   </ul>
--   
--   Example:
--   
--   <pre>
--   import Control.Monad(forever)
--   import System.Systemd.Daemon(notifyWatchdog)
--   
--   main :: IO ()
--   main = forever $ do
--           functionThatMayHang
--           notifyWatchdog
--   </pre>
--   
--   If you use the service described as below, Systemd will restart your
--   program each time the watchdog fail to notify itself under 60 sec.
--   
--   <pre>
--   [Unit]
--   Description=MyDaemon
--   
--   [Service]
--   Type=simple
--   TimeoutStartSec=0
--   ExecStart=AbsolutePathToMyExecutable
--   WatchdogSec=60
--   Restart=on-failure
--   
--   [Install]
--   WantedBy=multi-user.target
--   </pre>
module System.Systemd.Daemon

-- | Notify systemd about an event
--   
--   After notifying systemd the <a>Bool</a> parameter specify if the
--   environnement shall be unset (Further call to notify will fail)
--   
--   The <a>String</a> is the event to pass
--   
--   Returns <a>Nothing</a> if the program was not started with systemd or
--   that the environnement was previously unset
notify :: Bool -> String -> IO (Maybe ())

-- | Same as <a>notify</a> but send along a socket to be stored
--   
--   It is up to the caller to properly set the message (i.e: do not forget
--   to set FDSTORE=1)
notifyWithFD :: Bool -> String -> Socket -> IO (Maybe ())

-- | Notify systemd to store a socket for us.
--   
--   To be used along <a>getActivatedSockets</a> during a restart
--   
--   Usefull for zero downtime restart
storeFd :: Socket -> IO (Maybe ())

-- | Notify systemd to store a socket for us and specify a name.
--   
--   To be used along <a>getActivatedSocketsWithNames</a> during a restart
--   
--   Usefull for zero downtime restart
storeFdWithName :: Socket -> String -> IO (Maybe ())

-- | Notify the watchdog that the program is still alive
notifyWatchdog :: IO (Maybe ())

-- | Notify the systemd that the program is ready
notifyReady :: IO (Maybe ())

-- | Notify systemd of the PID of the program (for after a fork)
notifyPID :: CPid -> IO (Maybe ())

-- | Notify systemd of an <a>Errno</a> error
notifyErrno :: Errno -> IO (Maybe ())

-- | Notify systemd of the status of the program.
--   
--   An arbitrary <a>String</a> can be passed
notifyStatus :: String -> IO (Maybe ())

-- | Notify systemd of a DBUS error like.
--   
--   Correct formatting of the <a>String</a> is left to the caller
notifyBusError :: String -> IO (Maybe ())

-- | Notify systemd that the service is reloading its configuration
notifyReloading :: IO (Maybe ())

-- | Notify systemd that the service is beginning its shutdown
notifyStopping :: IO (Maybe ())

-- | Return a list of activated sockets, if the program was started with
--   socket activation.
--   
--   The sockets are in the same order as in the associated
--   <tt>.socket</tt> file. The sockets will have their family, type, and
--   status set appropriately.
--   
--   Returns <a>Nothing</a> in systems without socket activation (or when
--   the program was not socket activated).
getActivatedSockets :: IO (Maybe [Socket])

-- | Same as <a>getActivatedSockets</a> but return also the names
--   associated with those sockets if <a>storeFdWithName</a> was used or
--   specified in the <tt>.socket</tt> file.
--   
--   IF <a>storeFd</a> was used to transmit the socket to systemd, the name
--   will be a generic one (i.e: usally "stored")
getActivatedSocketsWithNames :: IO (Maybe [(Socket, String)])

-- | Unset all environnement variable related to Systemd.
--   
--   Calls to functions like <a>notify</a> and <a>getActivatedSockets</a>
--   will return <a>Nothing</a> after that.
unsetEnvironnement :: IO ()