z_job_set_policy

总结

设置作业安全政策和资源政策。

声明

#include <zircon/syscalls.h>

zx_status_t zx_job_set_policy(zx_handle_t handle,
                              uint32_t options,
                              uint32_t topic,
                              const void* policy,
                              uint32_t policy_size);

说明

将一项或多项安全和/或资源政策设置为空作业。作业的有效政策是父级的有效政策与 policy 中指定的政策的组合。现有政策与新政策之间发生冲突时的影响由 options 值控制：

  • ZX_JOB_POL_RELATIVE：政策将应用于未明确被父政策覆盖的条件。
  • ZX_JOB_POL_ABSOLUTE：将政策应用于 policy 中的所有条件，否则系统调用失败。

此调用成功后，任何新的子进程或子作业都将应用新的有效政策。

topic 表示 policy 格式。支持的值包括 ZX_JOB_POL_BASIC_V1、ZX_JOB_POL_BASIC_V2 和 ZX_JOB_POL_TIMER_SLACK。

ZX_JOB_POL_BASIC_V2 and V1

主题为 ZX_JOB_POL_BASIC_V2 表示政策是以下条目的数组：

typedef struct zx_policy_basic {
    uint32_t condition;
    uint32_t action;
    uint32_t flags;
} zx_policy_basic_v2_t;

主题为 ZX_JOB_POL_BASIC_V1 表示政策是以下条目的数组：

// Deprecated. Use zx_policy_basic_v2_t.
typedef struct zx_policy_basic {
    uint32_t condition;
    uint32_t policy;
} zx_policy_basic_v1_t;

其中，condition 是下列其中一项：

  • ZX_POL_BAD_HANDLE：此作业下的进程正在尝试发出具有无效句柄的系统调用。在这种情况下，ZX_POL_ACTION_ALLOW 和 ZX_POL_ACTION_DENY 是等效的：如果系统调用返回，它将始终返回错误 ZX_ERR_BAD_HANDLE。
  • ZX_POL_WRONG_OBJECT：此作业下的进程正在尝试发出包含不支持此操作的句柄的系统调用。
  • ZX_POL_VMAR_WX 此作业下的进程正在尝试映射具有写入/执行权限的地址区域。
  • ZX_POL_NEW_VMO：此作业下的进程正在尝试创建新的虚拟机对象。
  • ZX_POL_NEW_CHANNEL 此作业下的进程正在尝试创建新渠道。
  • ZX_POL_NEW_EVENT 此作业下的进程正在尝试创建新事件。
  • ZX_POL_NEW_EVENTPAIR：此作业下的进程正在尝试创建新的事件对。
  • ZX_POL_NEW_PORT 此作业下的进程正在尝试创建新端口。
  • ZX_POL_NEW_SOCKET：此作业下的进程正在尝试创建新套接字。
  • ZX_POL_NEW_FIFO 此作业下的进程正在尝试创建新的 fifo。
  • ZX_POL_NEW_TIMER 此作业下的进程正在尝试创建新计时器。
  • ZX_POL_NEW_PROCESS：此作业下的进程正在尝试创建新进程。
  • ZX_POL_NEW_PROFILE 此作业下的进程正在尝试创建新的配置文件。
  • ZX_POL_NEW_PAGER 此作业下的进程正在尝试创建新的 VMO 分页器。
  • ZX_POL_AMBIENT_MARK_VMO_EXEC，此作业下的进程正在尝试使用 zx_vmo_replace_as_executable() 并将 ZX_HANDLE_INVALID 作为第二个参数，而不是以 ZX_RSRC_SYSTEM_VMEX_BASE 为基数的有效 ZX_RSRC_KIND_SYSTEM 资源。
  • ZX_POL_NEW_ANY 是一个特殊条件，代表上述所有 ZX_NEW 条件（例如 ZX_POL_NEW_VMO、ZX_POL_NEW_CHANNEL、ZX_POL_NEW_EVENT、ZX_POL_NEW_EVENTPAIR、ZX_POL_NEW_PORT、ZX_POL_NEW_SOCKET、ZX_POL_NEW_FIFO）以及未来的所有 ZX_NEW 政策。这包括创建不需要父对象的所有新内核对象。
  • ZX_POL_NEW_IOB：此作业下的进程正在尝试创建新的 IOBuffer。

其中，ZX_JOB_POL_BASIC_V1 的 policy 或 ZX_JOB_POL_BASIC_V2 的 action 为以下之一：

  • ZX_POL_ACTION_ALLOW 允许条件。
  • ZX_POL_ACTION_DENY 可防止出现条件。
  • ZX_POL_ACTION_ALLOW_EXCEPTION 通过调试端口生成异常。以这种方式生成的异常充当断点。该线程可在发生异常后恢复。恢复后，系统将允许触发异常的条件完成，就像未发生违反政策的情况一样。
  • ZX_POL_ACTION_DENY_EXCEPTION就像ZX_POL_ACTION_ALLOW_EXCEPTION一样，但在恢复后，条件会被拒绝，通常会导致 ZX_ERR_ACCESS_DENIED。
  • ZX_POL_ACTION_KILL 可终止进程。

其中，flags 是以下之一：

  • ZX_POL_OVERRIDE_ALLOW允许为子作业更改此政策。
  • ZX_POL_OVERRIDE_DENY 不允许更改有关子作业的此政策。

无论替换模式如何，只要 Job 具有任何子项，其政策就无法更改。

ZX_JOB_POL_TIMER_SLACK

topic 为 ZX_JOB_POL_TIMER_SLACK 表示 policy 为：

typedef struct zx_policy_timer_slack {
    zx_duration_t min_slack;
    uint32_t default_mode;
} zx_policy_timer_slack_t;

min_slack 指定应用于由作业创建的计时器和基于截止时间的事件的最小 slack 量。

如果父作业的 min_slack 大于指定的 min_slack，则改用父作业的值。换句话说，作业的 min_slack 是指定值及其父作业的 min_slack 的最大值。

default_mode 指定在系统调用参数未以其他方式指示的情况下，如何应用 slack。无论父级作业的 default_mode 为何，都可以设置作业的 default_mode。default_mode 可能的值包括：

  • ZX_TIMER_SLACK_CENTER
  • ZX_TIMER_SLACK_EARLY
  • ZX_TIMER_SLACK_LATE

如需了解详情，请参阅计时器延迟。

设置计时器 Slack 政策时，options 必须为 ZX_JOB_POL_RELATIVE，count 必须为 1。

权限

handle 必须为 ZX_OBJ_TYPE_JOB 类型，且具有 ZX_RIGHT_SET_POLICY。

返回值

zx_job_set_policy() 会在成功时返回 ZX_OK。如果失败，则返回负的错误值。

备注

使用主题 ZX_INFO_HANDLE_VALID 调用 zx_object_get_info() 时，ZX_POL_BAD_HANDLE 政策绝不会应用。所有其他主题和接受句柄的所有其他系统调用（如果处于活动状态）都受此政策的限制。

错误

ZX_ERR_INVALID_ARGS policy 不是有效的指针，count 为 0，policy 不是 ZX_JOB_POL_RELATIVE 或 ZX_JOB_POL_ABSOLUTE，或 topic 不是 ZX_JOB_POL_BASIC。

ZX_ERR_BAD_HANDLE 句柄不是有效的句柄。

ZX_ERR_WRONG_TYPE 句柄不是作业句柄。

ZX_ERR_ACCESS_DENIED 标识名没有 ZX_POL_RIGHT_SET 权限。

ZX_ERR_BAD_STATE：表示作业存在活跃的现有作业或进程。

ZX_ERR_OUT_OF_RANGE count 大于 ZX_POL_MAX 或 condition 大于 ZX_POL_MAX。

ZX_ERR_ALREADY_EXISTS 项现有政策与新政策冲突。

ZX_ERR_NOT_SUPPORTED policy 中的条目包含无效值。

ZX_ERR_NO_MEMORY 由于内存不足而失败。 用户空间没有什么方法来处理此（不太可能）错误。在以后的 build 中，此错误不会再发生。

另请参阅