Unix syslog 库例程
******************

======================================================================

此模块提供一个接口到Unix "syslog" 日常库. 参考 Unix 手册页关于
"syslog" 设施的详细描述.

此模块包装了系统的 "syslog" 例程族。 一个能与 syslog 服务器对话的纯
Python 库则以 "logging.handlers" 模块中 "SysLogHandler" 类的形式提供。

这个模块定义了以下函数：

syslog.syslog(message)
syslog.syslog(priority, message)

   将字符串 *message* 发送到系统日志记录器。 如有必要会添加末尾换行符
   。 每条消息都带有一个由 *facility* 和 *level* 组成的优先级标价签。
   可选的 *priority* 参数默认值为 "LOG_INFO"，它确定消息的优先级。 如
   果未在 *priority* 中使用逻辑或 ("LOG_INFO | LOG_USER") 对 facility
   进行编码，则会使用在 "openlog()" 调用中所给定的值。

   如果 "openlog()" 未在对 "syslog()" 的调用之前被调用，则将不带参数地
   调用 "openlog()"。

   引发 审计事件 "syslog.syslog" 使用参数 "priority", "message".

syslog.openlog([ident[, logoption[, facility]]])

   后续 "syslog()" 调用的日志选项可以通过调用 "openlog()" 来设置。 如
   果日志当前未打开则 "syslog()" 将不带参数地调用 "openlog()"。

   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 "LOG_USER") sets the default facility for messages
   which do not have a facility explicitly encoded.

   引发 审计事件 "syslog.openlog" 使用参数 "ident", "logoption",
   "facility".

   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.

syslog.closelog()

   重置日志模块值并且调用系统库 "closelog()".

   This causes the module to behave as it does when initially
   imported.  For example, "openlog()" will be called on the first
   "syslog()" call (if "openlog()" hasn't already been called), and
   *ident* and other "openlog()" parameters are reset to defaults.

   引发一个 审计事件 "syslog.closelog" 不附带任何参数。

syslog.setlogmask(maskpri)

   Set the priority mask to *maskpri* and return the previous mask
   value.  Calls to "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*.

   引发一个 审计事件 "syslog.setlogmask" 附带参数 "maskpri"。

此模块定义了一下常量:

优先级级别 (高到低):
   "LOG_EMERG", "LOG_ALERT", "LOG_CRIT", "LOG_ERR", "LOG_WARNING",
   "LOG_NOTICE", "LOG_INFO", "LOG_DEBUG".

设施:
   "LOG_KERN", "LOG_USER", "LOG_MAIL", "LOG_DAEMON", "LOG_AUTH",
   "LOG_LPR", "LOG_NEWS", "LOG_UUCP", "LOG_CRON", "LOG_SYSLOG",
   "LOG_LOCAL0" to "LOG_LOCAL7"，如果 "<syslog.h>" 中有定义则还有
   "LOG_AUTHPRIV"。

日志选项:
   "LOG_PID", "LOG_CONS", "LOG_NDELAY"，如果 "<syslog.h>" 中有定义则还
   有 "LOG_ODELAY", "LOG_NOWAIT" 以及 "LOG_PERROR"。


示例
====


简单示例
--------

一个简单的示例集:

   import syslog

   syslog.syslog('Processing started')
   if error:
       syslog.syslog(syslog.LOG_ERR, 'Processing started')

一个设置多种日志选项的示例，其中有在日志消息中包含进程 ID，以及将消息
写入用于邮件日志记录的目标设施等:

   syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
   syslog.syslog('E-mail processing initiated...')
