1:mod:`syslog` --- Unix syslog library routines
2==============================================
3
4.. module:: syslog
5   :platform: Unix
6   :synopsis: An interface to the Unix syslog library routines.
7
8--------------
9
10This module provides an interface to the Unix ``syslog`` library routines.
11Refer to the Unix manual pages for a detailed description of the ``syslog``
12facility.
13
14This module wraps the system ``syslog`` family of routines.  A pure Python
15library that can speak to a syslog server is available in the
16:mod:`logging.handlers` module as :class:`SysLogHandler`.
17
18The module defines the following functions:
19
20
21.. function:: syslog(message)
22              syslog(priority, message)
23
24   Send the string *message* to the system logger.  A trailing newline is added
25   if necessary.  Each message is tagged with a priority composed of a
26   *facility* and a *level*.  The optional *priority* argument, which defaults
27   to :const:`LOG_INFO`, determines the message priority.  If the facility is
28   not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the
29   value given in the :func:`openlog` call is used.
30
31   If :func:`openlog` has not been called prior to the call to :func:`syslog`,
32   ``openlog()`` will be called with no arguments.
33
34   .. audit-event:: syslog.syslog priority,message syslog.syslog
35
36
37.. function:: openlog([ident[, logoption[, facility]]])
38
39   Logging options of subsequent :func:`syslog` calls can be set by calling
40   :func:`openlog`.  :func:`syslog` will call :func:`openlog` with no arguments
41   if the log is not currently open.
42
43   The optional *ident* keyword argument is a string which is prepended to every
44   message, and defaults to ``sys.argv[0]`` with leading path components
45   stripped.  The optional *logoption* keyword argument (default is 0) is a bit
46   field -- see below for possible values to combine.  The optional *facility*
47   keyword argument (default is :const:`LOG_USER`) sets the default facility for
48   messages which do not have a facility explicitly encoded.
49
50   .. audit-event:: syslog.openlog ident,logoption,facility syslog.openlog
51
52   .. versionchanged:: 3.2
53      In previous versions, keyword arguments were not allowed, and *ident* was
54      required.  The default for *ident* was dependent on the system libraries,
55      and often was ``python`` instead of the name of the Python program file.
56
57
58.. function:: closelog()
59
60   Reset the syslog module values and call the system library ``closelog()``.
61
62   This causes the module to behave as it does when initially imported.  For
63   example, :func:`openlog` will be called on the first :func:`syslog` call (if
64   :func:`openlog` hasn't already been called), and *ident* and other
65   :func:`openlog` parameters are reset to defaults.
66
67   .. audit-event:: syslog.closelog "" syslog.closelog
68
69
70.. function:: setlogmask(maskpri)
71
72   Set the priority mask to *maskpri* and return the previous mask value.  Calls
73   to :func:`syslog` with a priority level not set in *maskpri* are ignored.
74   The default is to log all priorities.  The function ``LOG_MASK(pri)``
75   calculates the mask for the individual priority *pri*.  The function
76   ``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
77   *pri*.
78
79   .. audit-event:: syslog.setlogmask maskpri syslog.setlogmask
80
81The module defines the following constants:
82
83Priority levels (high to low):
84   :const:`LOG_EMERG`, :const:`LOG_ALERT`, :const:`LOG_CRIT`, :const:`LOG_ERR`,
85   :const:`LOG_WARNING`, :const:`LOG_NOTICE`, :const:`LOG_INFO`,
86   :const:`LOG_DEBUG`.
87
88Facilities:
89   :const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`,
90   :const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`,
91   :const:`LOG_CRON`, :const:`LOG_SYSLOG`, :const:`LOG_LOCAL0` to
92   :const:`LOG_LOCAL7`, and, if defined in ``<syslog.h>``,
93   :const:`LOG_AUTHPRIV`.
94
95Log options:
96   :const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, and, if defined
97   in ``<syslog.h>``, :const:`LOG_ODELAY`, :const:`LOG_NOWAIT`, and
98   :const:`LOG_PERROR`.
99
100
101Examples
102--------
103
104Simple example
105~~~~~~~~~~~~~~
106
107A simple set of examples::
108
109   import syslog
110
111   syslog.syslog('Processing started')
112   if error:
113       syslog.syslog(syslog.LOG_ERR, 'Processing started')
114
115An example of setting some log options, these would include the process ID in
116logged messages, and write the messages to the destination facility used for
117mail logging::
118
119   syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
120   syslog.syslog('E-mail processing initiated...')
121