Port of issue8451 to python3: Syslog use sys.argv[0] for ident.
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index 89dd38f..c25ed41 100644
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -10,42 +10,66 @@
Refer to the Unix manual pages for a detailed description of the ``syslog``
facility.
+This module wraps the system ``syslog`` module. A pure Python
+library that can speak to a syslog server is available in
+the :mod:`logging.handlers` module as :class:`SysLogHandler`.
+
The module defines the following functions:
.. function:: syslog([priority,] message)
- Send the string *message* to the system logger. A trailing newline is added if
- necessary. Each message is tagged with a priority composed of a *facility* and
- a *level*. The optional *priority* argument, which defaults to
- :const:`LOG_INFO`, determines the message priority. If the facility is not
- encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the value
- given in the :func:`openlog` call is used.
+ Send the string *message* to the system logger. A trailing newline is
+ added if necessary. Each message is tagged with a priority composed
+ of a *facility* and a *level*. The optional *priority* argument, which
+ defaults to :const:`LOG_INFO`, determines the message priority. If the
+ facility is not encoded in *priority* using logical-or (``LOG_INFO |
+ LOG_USER``), the value given in the :func:`openlog` call is used.
+
+ If :func:`openlog` has not been called prior to the call to
+ :func:'syslog', ``openlog()`` will be called with no arguments.
-.. function:: openlog(ident[, logopt[, facility]])
+.. function:: openlog([ident[, logopt[, facility]]])
- Logging options other than the defaults can be set by explicitly opening the log
- file with :func:`openlog` prior to calling :func:`syslog`. The defaults are
- (usually) *ident* = ``'syslog'``, *logopt* = ``0``, *facility* =
- :const:`LOG_USER`. The *ident* argument is a string which is prepended to every
- message. The optional *logopt* argument is a bit field - see below for possible
- values to combine. The optional *facility* argument sets the default facility
- for messages which do not have a facility explicitly encoded.
+ Logging options of subsequent :func:`syslog` calls can be set by
+ calling :func:`openlog`. :func:`syslog` will call :func:`openlog`
+ with no arguments if the log is not currently open.
+
+ The optional *ident* keyword argument is a string which is prepended
+ to every message, and defaults to ''sys.argv[0]'' with leading
+ path components stripped. The optional *logopt* keyword argument
+ (default=0) is a bit field - see below for possible values to combine.
+ The optional *facility* keyword argument (default=:const:`LOG_USER`)
+ sets the default facility for messages which do not have a facility
+ explicitly encoded.
+
+ .. versionchanged::3.2
+ In previous versions, keyword arguments were not allowed, and *ident*
+ was required. The default for *ident* was dependent on the system
+ libraries, and often was ''python'' instead of the name of the
+ python program file.
.. function:: closelog()
- Close the log file.
+ Reset the syslog module values and call the system library
+ ''closelog()''.
+
+ This causes the module to behave as it does when initially imported.
+ For example, :func:'openlog' will be called on the first :func:'syslog'
+ call (if :func:'openlog' hasn't already been called), and *ident*
+ and other :func:'openlog' parameters are reset to defaults.
.. function:: setlogmask(maskpri)
- Set the priority mask to *maskpri* and return the previous mask value. Calls to
- :func:`syslog` with a priority level not set in *maskpri* are ignored. The
- default is to log all priorities. The function ``LOG_MASK(pri)`` calculates the
- mask for the individual priority *pri*. The function ``LOG_UPTO(pri)``
- calculates the mask for all priorities up to and including *pri*.
+ Set the priority mask to *maskpri* and return the previous mask value.
+ Calls to :func:`syslog` with a priority level not set in *maskpri*
+ are ignored. The default is to log all priorities. The function
+ ``LOG_MASK(pri)`` calculates the mask for the individual priority
+ *pri*. The function ``LOG_UPTO(pri)`` calculates the mask for all
+ priorities up to and including *pri*.
The module defines the following constants:
@@ -63,3 +87,24 @@
:const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, :const:`LOG_NOWAIT`
and :const:`LOG_PERROR` if defined in ``<syslog.h>``.
+
+Examples
+--------
+
+Simple example
+~~~~~~~~~~~~~~
+
+A simple set of examples::
+
+ import syslog
+
+ syslog.syslog('Processing started')
+ if error:
+ syslog.syslog(syslog.LOG_ERR, 'Processing started')
+
+An example of setting some log options, these would include the process ID
+in logged messages, and write the messages to the destination facility
+used for mail logging::
+
+ syslog.openlog(logopt=syslog.LOG_PID, facility=syslog.LOG_MAIL)
+ syslog.syslog('E-mail processing initiated...')