# `syslog` --- Unix syslog 库例程

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

可用性: Unix, 非 Emscripten, 非 WASI。

This module wraps the system `syslog` family of routines. A pure Python library that can speak to a syslog server is available in the `logging.handlers` module as `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`.

  在 3.2 版本发生变更: 在之前的版本中，如果 `openlog()` 未在对 `syslog()` 的调用之前被调用则它将不会被自动调用，而是由 syslog 实现来负责调用 `openlog()`。

  在 3.12 版本发生变更: 此函数在子解释器中受到限制。 （该限制只影响在多解释器中运行的代码因而与大多数用户无关。） `openlog()` 必须在子解释器使用 `syslog()` 之前在主解释器中被调用。 否则它将引发 `RuntimeError`。

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 版本发生变更: 在之前的版本中，不允许使用关键字参数，并且要求必须有 ident。

  在 3.12 版本发生变更: 此函数在子解释器中受到限制。 （该限制只影响在多解释器中运行的代码因而与大多数用户无关。） 此函数只能在主解释器中被调用。 如果在子解释器中被调用它将引发 `RuntimeError`。

syslog.closelog()

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

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

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

  在 3.12 版本发生变更: 此函数在子解释器中受到限制。 （该限制只影响在多解释器中运行的代码因而与大多数用户无关。） 此函数只能在主解释器中被调用。 如果在子解释器中被调用它将引发 `RuntimeError`。

syslog.setlogmask(maskpri)

  将优先级掩码设为 maskpri 并返回之前的掩码值。 调用 `syslog()` 并附带未在 maskpri 中设置的优先级将会被忽略。 默认设置为记录所有优先级。 函数 `LOG_MASK(pri)` 可计算单个优先级 pri 的掩码。 函数 `LOG_UPTO(pri)` 可计算包括 pri 在内的所有优先级的掩码。

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

此模块定义了一下常量:

Priority levels (high to low):

  `LOG_EMERG`, `LOG_ALERT`, `LOG_CRIT`, `LOG_ERR`, `LOG_WARNING`, `LOG_NOTICE`, `LOG_INFO`, `LOG_DEBUG`.

Facilities:

  `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`, and, if defined in `<syslog.h>`, `LOG_AUTHPRIV`.

Log options:

  `LOG_PID`, `LOG_CONS`, `LOG_NDELAY`, and, if defined in `<syslog.h>`, `LOG_ODELAY`, `LOG_NOWAIT`, and `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...')