总结
请求各种内核对象的各种属性。
声明
#include <zircon/syscalls.h>
zx_status_t zx_object_get_property(zx_handle_t handle,
uint32_t property,
void* value,
size_t value_size);
说明
zx_object_get_property()
请求内核对象的属性值。获取资源需要拥有相应标识名的 ZX_RIGHT_GET_PROPERTY
权限。
handle 参数表示目标内核对象。不同的属性仅适用于特定类型的内核对象,如下所述。
property 参数会指示要获取/设置的属性。属性值的前缀为 ZX_PROP_
,如下所述。
value 参数用于保存属性值,并且必须是指向 value_size 字节的缓冲区的指针。不同的属性需要不同的值类型/大小,如下所述。
属性
属性值带有前缀 ZX_PROP_
,并在
#include <zircon/syscalls/object.h>
ZX_PROP_NAME
handle 类型:Any of the following
- 作业
- 进程
- 线程
- 资源
- 虚拟内存对象 (VMO)
- 总线事务发起程序 (BTI)
value 类型:char[ZX_MAX_NAME_LEN]
允许的操作:get
、set
对象的名称,采用以 NUL 结尾的字符串。
如果尝试获取或设置已退出线程的名称,则会失败并显示 ZX_ERR_BAD_STATE
。
ZX_PROP_REGISTER_FS 和 ZX_PROP_REGISTER_GS
handle 类型:Thread
value 类型:uintptr_t
允许的操作:get
、set
分别表示 x86 FS.BASE 或 GS.BASE 寄存器的值。value
必须是规范地址。尝试设置非规范地址将失败并显示 ZX_ERR_INVALID_ARGS
。
这是较新 x86-64 CPU 上支持的 rdfsbase
、wrfsbase
、rdgsbase
、wrgsbase
指令对的软件替代项,其行为应与直接使用 CPU 指令完全相同(不过,尝试设置非规范地址作为值只会得到错误返回,而不会生成机器异常)。使用支持这些指令(由 cpuid
指令报告)的 CPU 时,直接使用机器指令会更高效、更简单。
仅针对 x86-64 进行了定义。对于其他架构,返回 ZX_ERR_NOT_SUPPORTED
。如果未从当前线程调用,则返回 ZX_ERR_ACCESS_DENIED
。
ZX_PROP_PROCESS_DEBUG_ADDR
handle 类型:Process
value 类型:uintptr_t
允许的操作:get
、set
ld.so 的 _dl_debug_addr
的值。调试程序可以使用它来查询动态加载器的状态。
ZX_PROP_PROCESS_BREAK_ON_LOAD
handle 类型:Process
value 类型:uintptr_t
允许的操作:get
、set
确定动态加载程序是否会在每次加载共享库时发出调试 trap。如果在进程的第一个线程运行之前设置,则还会针对初始加载触发调试陷阱。
动态加载器会在触发此调试陷阱之前设置 ZX_PROP_PROCESS_DEBUG_ADDR
的预期值。异常处理程序可以使用此属性查询动态加载器的状态。
当动态加载器发出调试 trap 时,它还会将 ZX_PROP_PROCESS_BREAK_ON_LOAD
的值设置为调试 trap 的地址,以便调试程序可以将该值与异常的地址进行比较,以确定动态加载器是否触发了调试 trap。
任何非零值都会被视为启用此功能。将此属性设置为零会停用它。调试程序还可以使用此属性来检测同一进程是否已连接其他调试程序。
ZX_PROP_PROCESS_VDSO_BASE_ADDRESS
handle 类型:Process
value 类型:uintptr_t
允许的操作:get
vDSO 映射的基础地址,或零。
ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID
handle 类型:Process
value 类型:uintptr_t
允许的操作:get
上下文 ID 用于区分硬件指令跟踪中的不同进程。在 Intel X86-64 上,这是寄存器 CR3 的值。
如需获取 ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID
,您必须在内核命令行中指定 kernel.enable-debugging-syscalls=true
。否则,该函数会返回 ZX_ERR_NOT_SUPPORTED
。
目前仅为 X86 定义。
ZX_PROP_SOCKET_RX_THRESHOLD
handle 类型:Socket
value 类型:size_t
允许的操作:get
、set
套接字的读取阈值的大小(以字节为单位)。设置此值后,如果可读取的数据量大于或等于阈值,则会断言 ZX_SOCKET_READ_THRESHOLD
。将此属性设置为零会导致 ZX_SOCKET_READ_THRESHOLD
的断言被取消。
如果设置的值大于套接字支持的大小上限,则会失败并显示 ZX_ERR_INVALID_ARGS
。
ZX_PROP_SOCKET_TX_THRESHOLD
handle 类型:Socket
value 类型:size_t
允许的操作:get
、set
套接字的写入阈值的大小(以字节为单位)。设置此值后,如果可供写入的空间量大于或等于阈值,则将断言 ZX_SOCKET_WRITE_THRESHOLD
。将此属性设置为零会导致 ZX_SOCKET_WRITE_THRESHOLD
的断言被取消。在对等体关闭后设置写入阈值是一种错误,会导致返回 ZX_ERR_PEER_CLOSED
错误。
如果设置的值大于套接字支持的大小上限,则会失败并显示 ZX_ERR_INVALID_ARGS
。
ZX_PROP_JOB_KILL_ON_OOM
handle 类型:Job
value 类型:size_t
允许的操作:set
值为 1 时,如果系统发现自己处于系统级内存不足的情况,则会终止 Job 及其子项。如果使用 0(默认值)进行调用,则在这种情况下不会终止作业。设置为任何其他值都将失败并显示 ZX_ERR_INVALID_ARGS
。
ZX_PROP_EXCEPTION_STATE
handle 类型:Exception
value 类型:uint32_t
允许的操作:get
、set
设置为 ZX_EXCEPTION_STATE_HANDLED
时,关闭异常句柄将完成异常处理并恢复底层线程。设置为 ZX_EXCEPTION_STATE_TRY_NEXT
时,关闭异常句柄会通过按顺序尝试下一个处理程序,继续处理异常。设置为 ZX_EXCEPTION_STATE_THREAD_EXIT
时,关闭异常句柄会导致生成异常的线程退出。
设置为任何其他值都将失败并显示 ZX_ERR_INVALID_ARGS
。
ZX_PROP_EXCEPTION_STRATEGY
handle 类型:Exception
value 类型:uint32_t
允许的操作:get
、set
如果设置了 ZX_EXCEPTION_STRATEGY_SECOND_CHANCE
,那么在进程级处理程序未能处理异常时,调试程序将获得“第二次机会”。如果设置了 ZX_EXCEPTION_STRATEGY_FIRST_CHANCE
,调试程序没有第二次机会处理异常。
设置为任何其他值都将失败并显示 ZX_ERR_INVALID_ARGS
。
仅当句柄对应于调试程序进程异常通道时,才能设置此属性。当异常渠道是任何其他类型时尝试设置此属性将导致 ZX_ERR_BAD_STATE
。
ZX_PROP_STREAM_MODE_APPEND
handle 类型:Stream
value 类型:uint8_t
允许的操作:get
、set
当数据流处于附加模式时,此属性的值为 1
;当数据流不处于附加模式时,此属性的值为 0
。在附加模式下,数据流会以原子方式将数据流的还原偏移量设置为在 zx_stream_writev()
中写入数据之前数据流的内容大小。
权限
handle 必须具有 ZX_RIGHT_GET_PROPERTY
,并且必须是 property 支持的 ZX_OBJ_TYPE_
(如上文各个属性的说明中所述)。
返回值
zx_object_get_property()
会在成功时返回 ZX_OK
。如果失败,将返回负的错误值。
错误
如需了解各个属性值的具体错误,请参阅上文的说明。 常见错误如下:
ZX_ERR_BAD_HANDLE
:handle 不是有效的句柄。
ZX_ERR_WRONG_TYPE
:handle 不是 property 的合适类型。
ZX_ERR_ACCESS_DENIED
:handle 没有执行操作所需的权限。
ZX_ERR_INVALID_ARGS
:value 是无效的指针。
ZX_ERR_NO_MEMORY
由于内存不足而失败。
用户空间没有什么方法来处理此(不太可能)错误。在以后的 build 中,此错误不会再发生。
ZX_ERR_BUFFER_TOO_SMALL
:对于 property 而言,value_size 过小。
ZX_ERR_NOT_SUPPORTED
:属性不存在。