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