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


-- | FFI interface to syslog(3) from POSIX.1-2001
--   
--   This library provides FFI bindings to syslog(3) from POSIX.1-2001. See
--   <a>http://www.opengroup.org/onlinepubs/009695399/basedefs/syslog.h.html</a>
--   for further details.
@package hsyslog
@version 2.0


-- | FFI bindings to syslog(3) from <a>POSIX.1-2001</a>.
module System.Posix.Syslog

-- | Log messages are prioritized.
--   
--   Note that the <a>Enum</a> instance for this class is incomplete. We
--   abuse <a>toEnum</a> and <a>fromEnum</a> to map these constructors to
--   their corresponding bit-mask value in C, but not all uses cases
--   provided by of enumerating that class are fully supported (<a>issue
--   #5</a>).
data Priority

-- | system is unusable
Emergency :: Priority

-- | action must be taken immediately
Alert :: Priority

-- | critical conditions
Critical :: Priority

-- | error conditions
Error :: Priority

-- | warning conditions
Warning :: Priority

-- | normal but significant condition
Notice :: Priority

-- | informational
Info :: Priority

-- | debug-level messages
Debug :: Priority

-- | Syslog distinguishes various system facilities. Most applications
--   should log in <a>USER</a>.
data Facility

-- | kernel messages
KERN :: Facility

-- | user-level messages (default unless set otherwise)
USER :: Facility

-- | mail system
MAIL :: Facility

-- | system daemons
DAEMON :: Facility

-- | security/authorization messages
AUTH :: Facility

-- | messages generated internally by syslogd
SYSLOG :: Facility

-- | line printer subsystem
LPR :: Facility

-- | network news subsystem
NEWS :: Facility

-- | UUCP subsystem
UUCP :: Facility

-- | clock daemon
CRON :: Facility

-- | security/authorization messages (effectively equals <a>AUTH</a> on
--   some systems)
AUTHPRIV :: Facility

-- | ftp daemon (effectively equals <a>DAEMON</a> on some systems)
FTP :: Facility

-- | reserved for local use
LOCAL0 :: Facility

-- | reserved for local use
LOCAL1 :: Facility

-- | reserved for local use
LOCAL2 :: Facility

-- | reserved for local use
LOCAL3 :: Facility

-- | reserved for local use
LOCAL4 :: Facility

-- | reserved for local use
LOCAL5 :: Facility

-- | reserved for local use
LOCAL6 :: Facility

-- | reserved for local use
LOCAL7 :: Facility

-- | Options for the syslog service. Set with <a>withSyslog</a>.
data Option

-- | log the pid with each message
PID :: Option

-- | log on the console if errors in sending
CONS :: Option

-- | delay open until first <tt>syslog()</tt> (default)
ODELAY :: Option

-- | don't delay open
NDELAY :: Option

-- | don't wait for console forks: DEPRECATED
NOWAIT :: Option

-- | log to <tt>stderr</tt> as well (might be a no-op on some systems)
PERROR :: Option

-- | Bracket an <a>IO</a> computation between calls to <a>_openlog</a>,
--   <a>_setlogmask</a>, and <a>_closelog</a>. The function can be used as
--   follows:
--   
--   <pre>
--   main = withSyslog "my-ident" [PID, PERROR] USER (logUpTo Debug) $ do
--            putStrLn "huhu"
--            syslog Debug "huhu"
--   </pre>
--   
--   Note that these are <i>process-wide</i> settings, so multiple calls to
--   this function will interfere with each other in unpredictable ways.
withSyslog :: String -> [Option] -> Facility -> [Priority] -> IO a -> IO a

-- | Log a message with the given priority.
--   
--   Note that the API of this function is somewhat unsatisfactory and is
--   likely to change in the future:
--   
--   <ol>
--   <li>The function should accept a <tt>[<a>Facility</a>]</tt> argument
--   so that messages can be logged to certain facilities without depending
--   on the process-wide global default value set by <tt>openlog</tt>
--   (<a>issue #6</a>).</li>
--   <li>The <a>Priority</a> argument should be
--   <tt>[<a>Priority</a>]</tt>.</li>
--   <li>Accepting a <tt>ByteString</tt> instead of <a>String</a> would be
--   preferrable because we can log those more efficiently, i.e. without
--   marshaling. On top of that, we can provide a wrapper for this function
--   that accepts anything that can be marshaled into a <tt>ByteString</tt>
--   (<a>issue #7</a>).</li>
--   </ol>
syslog :: Priority -> String -> IO ()

-- | Returns the list of priorities up to and including the argument. Note
--   that the syslog priority <a>Debug</a> is considered the highest one in
--   this context, which may counter-intuitive for some.
--   
--   <pre>
--   &gt;&gt;&gt; logUpTo(Debug)
--   [Emergency,Alert,Critical,Error,Warning,Notice,Info,Debug]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; logUpTo(Emergency)
--   [Emergency]
--   </pre>
logUpTo :: Priority -> [Priority]

-- | Escape any occurances of '<tt>%</tt>' in a string, so that it is safe
--   to pass it to <a>_syslog</a>. The <a>syslog</a> wrapper does this
--   automatically.
--   
--   Unfortunately, the application of this function to every single syslog
--   message is a performence nightmare. Instead, we should call syslog the
--   existence of this function is a kludge, in a way that doesn't require
--   any escaping (<a>issue #8</a>).
safeMsg :: String -> String

-- | Open a connection to the system logger for a program. The string
--   identifier passed as the first argument is prepended to every message,
--   and is typically set to the program name. The behavior is unspecified
--   by POSIX.1-2008 if that identifier is <tt>nullPtr</tt>.
_openlog :: CString -> CInt -> CInt -> IO ()

-- | Close the descriptor being used to write to the system logger.
_closelog :: IO ()

-- | A process has a log priority mask that determines which calls to
--   <a>syslog</a> may be logged. All other calls will be ignored. Logging
--   is enabled for the priorities that have the corresponding bit set in
--   mask. The initial mask is such that logging is enabled for all
--   priorities. This function sets this logmask for the calling process,
--   and returns the previous mask. If the mask argument is 0, the current
--   logmask is not modified.
_setlogmask :: CInt -> IO CInt

-- | Generate a log message, which will be distributed by
--   <tt>syslogd(8)</tt>. The priority argument is formed by ORing the
--   facility and the level values (explained below). The remaining
--   arguments are a format, as in printf(3) and any arguments required by
--   the format, except that the two character sequence %m will be replaced
--   by the error message string strerror(errno). A trailing newline may be
--   added if needed.
_syslog :: CInt -> CString -> IO ()
instance Eq Priority
instance Bounded Priority
instance Show Priority
instance Read Priority
instance Generic Priority
instance Eq Facility
instance Bounded Facility
instance Show Facility
instance Read Facility
instance Eq Option
instance Bounded Option
instance Show Option
instance Datatype D1Priority
instance Constructor C1_0Priority
instance Constructor C1_1Priority
instance Constructor C1_2Priority
instance Constructor C1_3Priority
instance Constructor C1_4Priority
instance Constructor C1_5Priority
instance Constructor C1_6Priority
instance Constructor C1_7Priority
instance Enum Option
instance Enum Facility
instance Enum Priority