zx_task_create_exception_channel

摘要

為指定工作、程序或執行緒建立例外狀況管道。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_task_create_exception_channel(zx_handle_t handle,
                                             uint32_t options,
                                             zx_handle_t* out);

說明

zx_task_create_exception_channel() 會建立管道，接收來自執行緒、程序或工作的例外狀況。

handle 是要接收例外狀況的執行緒、程序或工作控制代碼。

options 可以是 0 或 ZX_EXCEPTION_CHANNEL_DEBUGGER，用來註冊偵錯例外狀況 (僅限程序或工作)。

成功時，out 會填入新建立的管道端點。這個管道將為唯讀，並具備下列權利：

  • ZX_RIGHT_TRANSFER
  • ZX_RIGHT_WAIT
  • ZX_RIGHT_READ

例外管道數

每項工作最多可有一個一般例外狀況管道和一個偵錯工具例外狀況管道，但工作除外。單一工作最多可有 ZX_EXCEPTION_CHANNEL_JOB_DEBUGGER_MAX_COUNT 個偵錯工具例外狀況管道。

如果嘗試在工作上建立例外狀況管道，但該工作已達特定類型的管道數量上限，系統會傳回 ZX_ERR_ALREADY_BOUND。

例外狀況訊息

發生例外狀況時，管道會收到一則訊息，其中包含一個例外狀況控制代碼和一個 zx_exception_info_t 資料。

在收到例外狀況控制代碼並關閉前，執行緒會持續遭到例外狀況封鎖，之後執行緒會根據所選行為繼續執行或處理例外狀況 (請參閱 zx_object_get_property() 中的 ZX_PROP_EXCEPTION_STATE)。

解除繫結

關閉建立的管道控制代碼會取消註冊例外狀況處理常式。如果管道關閉時，有例外狀況訊息在等待，例外狀況處理程序會繼續搜尋順序中的下一個處理常式。

權限

控制代碼必須有 ZX_RIGHT_INSPECT、ZX_RIGHT_DUPLICATE、ZX_RIGHT_TRANSFER 和 ZX_RIGHT_MANAGE_THREAD。

如果 handle 的型別為 ZX_OBJ_TYPE_JOB 或 ZX_OBJ_TYPE_PROCESS，則必須具有 ZX_RIGHT_ENUMERATE。

傳回值

成功時，zx_task_create_exception_channel() 會傳回 ZX_OK。 如果失敗，系統會傳回負數錯誤值。

錯誤

ZX_ERR_ACCESS_DENIED 撥號者設有工作政策，禁止建立新頻道。

ZX_ERR_ALREADY_BOUND 指定類型的例外狀況管道數量已達上限，且已繫結至 handle。

「ZX_ERR_BAD_HANDLE」handle 不是有效的控制代碼。

ZX_ERR_BAD_STATE 把手快要斷裂或已斷裂。

ZX_ERR_INVALID_ARGS options 中傳遞的值無效。

ZX_ERR_NO_MEMORY 記憶體不足，因此失敗。 使用者空間無法妥善處理這項 (不太可能發生的) 錯誤。 日後的版本將不會再發生這個錯誤。

ZX_ERR_WRONG_TYPE handle 不是工作、程序或執行緒的控制碼。

另請參閱