Changeset 391 for python/trunk/Doc/library/syslog.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/syslog.rst (modified) (4 diffs)

python/trunk/Doc/library/syslog.rst

@@ -1 @@
-
 :mod:`syslog` --- Unix syslog library routines
 ==============================================
@@ -12 +11 @@
 facility.
 
+This module wraps the system ``syslog`` family of routines.  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)
+.. function:: syslog(message)
+              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[, logoption[, 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 *logoption* keyword argument (default is 0) is a bit
+   field -- see below for possible values to combine.  The optional *facility*
+   keyword argument (default is :const:`LOG_USER`) sets the default facility for
+   messages which do not have a facility explicitly encoded.
 
 
 .. 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:
@@ -59 +75 @@
    :const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`,
    :const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`,
-   :const:`LOG_CRON` and :const:`LOG_LOCAL0` to :const:`LOG_LOCAL7`.
+   :const:`LOG_CRON`, :const:`LOG_SYSLOG` and :const:`LOG_LOCAL0` to
+   :const:`LOG_LOCAL7`.
 
 Log options:
@@ -65 +82 @@
    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(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
+   syslog.syslog('E-mail processing initiated...')