摘要
詢問各種核心物件的各種屬性。
宣告
#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。
這會以軟體替代 rdfsbase、wrfsbase 和 rdgsbase，以及較新 x86 至 64 CPU 支援的 wrgsbase 指令配對，而且行為應與直接使用 CPU 操作說明相同 (除非您嘗試設定非標準位址，而只會傳回錯誤，而不是產生機器例外狀況)。使用支援這些指令的 CPU 時 (如 cpuid 指令所回報)，直接使用機器操作說明會比較有效率。
僅適用於 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
判斷動態載入器是否會在共用程式庫的每次載入時發出偵錯追蹤。如果設定在程序的第一個執行緒執行前設定，也會為初始載入觸發偵錯追蹤。
動態載入器會先設定 ZX_PROP_PROCESS_DEBUG_ADDR 的預期值，再觸發這個偵錯追蹤。例外狀況處理常式可以使用這個屬性查詢動態載入器的狀態。
動態載入器發生問題時，系統也會將 ZX_PROP_PROCESS_BREAK_ON_LOAD 的值設為偵錯追蹤的位址，這樣一來，偵錯工具便可將該值與例外狀況位址進行比較，以判斷動態載入器是否觸發了偵錯追蹤。
系統會將任何非零的值視為可啟用這項功能。將此屬性設為 0 將停用。偵錯工具也能使用這項屬性，偵測是否已有其他附加至同一程序的偵錯工具。
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，且必須是屬性支援的 ZX_OBJ_TYPE_，詳情請參閱上述個別屬性的說明。
傳回值
zx_object_get_property() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負值的錯誤值。
錯誤
個別屬性值的具體錯誤已列於上述說明中。 以下列出常見的錯誤：
ZX_ERR_BAD_HANDLE：帳號代碼不是有效的控制代碼。
ZX_ERR_WRONG_TYPE：handle 不是屬性的適當類型。
ZX_ERR_ACCESS_DENIED：帳號代碼沒有這項作業的必要權限。
ZX_ERR_INVALID_ARGS：value 是無效指標。
ZX_ERR_NO_MEMORY 因記憶體不足而失敗。使用者空間無法以任何方式處理這個錯誤 (極可能) 錯誤。日後的建構作業不會再發生這個錯誤。
ZX_ERR_BUFFER_TOO_SMALL：屬性的 value_size 太小。
ZX_ERR_NOT_SUPPORTED：property 不存在。