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()" 调用中所给定的值。

   If "openlog()" has not been called prior to the call to "syslog()",
   "openlog()" will be called with no arguments.

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

   3.2 版更變: In previous versions, "openlog()" would not be called
   automatically if it wasn't called prior to the call to "syslog()",
   deferring to the syslog implementation to call "openlog()".

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

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

   可选的 *ident* 关键字参数是在每条消息前添加的字符串，默认为
   "sys.argv[0]" 去除打头的路径部分。 可选的 *logoption* 关键字参数（
   默认为 0）是一个位字段 -- 请参见下文了解可能的组合值。 可选的
   *facility* 关键字参数 (默认为 "LOG_USER") 为没有显式编码 facility
   的消息设置默认的 facility。

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

   3.2 版更變: In previous versions, keyword arguments were not
   allowed, and *ident* was required.

syslog.closelog()

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

   这使得此模块在初始导入时行为固定。 例如，"openlog()" 将在首次调用
   "syslog()" 时被调用（如果 "openlog()" 还未被调用过），并且 *ident*
   和其他 "openlog()" 形参会被重置为默认值。

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

syslog.setlogmask(maskpri)

   将优先级掩码设为 *maskpri* 并返回之前的掩码值。 调用 "syslog()" 并
   附带未在 *maskpri* 中设置的优先级将会被忽略。 默认设置为记录所有优
   先级。 函数 "LOG_MASK(pri)" 可计算单个优先级 *pri* 的掩码。 函数
   "LOG_UPTO(pri)" 可计算包括 *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...')
