blob: 8e1782d86755a42dff748d7a0a66d3e5136f502c [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library zx;
@transport("Syscall")
protocol Exception {
/// ## Summary
///
/// Create a handle for the exception's thread.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_exception_get_thread(zx_handle_t handle, zx_handle_t* out);
/// ```
///
/// ## Description
///
/// *handle* is the exception handle.
///
/// *out* will be filled with a new handle to the exception thread. This handle
/// will have the same rights as the task given to
/// [`zx_task_create_exception_channel()`].
///
/// ## Rights
///
/// *handle* must be of type **ZX_OBJ_TYPE_EXCEPTION**.
///
/// ## Return value
///
/// `zx_exception_get_thread()` returns **ZX_OK** on success.
/// In the event of failure, a negative error value is returned.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
///
/// **ZX_ERR_NO_MEMORY** Failed to allocate memory for a new handle.
///
/// **ZX_ERR_WRONG_TYPE** *handle* is not an exception.
///
/// ## See also
///
/// - [exceptions]
/// - [`zx_exception_get_process()`]
///
/// [exceptions]: /docs/concepts/kernel/exceptions.md
/// [`zx_exception_get_process()`]: exception_get_process.md
/// [`zx_task_create_exception_channel()`]: task_create_exception_channel.md
GetThread(resource struct {
handle handle:EXCEPTION;
}) -> (resource struct {
out handle:THREAD;
}) error status;
/// ## Summary
///
/// Create a handle for the exception's process.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_exception_get_process(zx_handle_t handle, zx_handle_t* out);
/// ```
///
/// ## Description
///
/// The exception process is only available for job and process exception channels,
/// thread exceptions cannot access their parent process handles.
///
/// *handle* is the exception handle.
///
/// *out* will be filled with a new handle to the exception process. This handle
/// will have the same rights as the task given to
/// [`zx_task_create_exception_channel()`].
///
/// ## Rights
///
/// *handle* must be of type **ZX_OBJ_TYPE_EXCEPTION**.
///
/// ## Return value
///
/// `zx_exception_get_process()` returns **ZX_OK** on success.
/// In the event of failure, a negative error value is returned.
///
/// ## Errors
///
/// **ZX_ERR_ACCESS_DENIED** *handle* was received via a thread exception channel.
///
/// **ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
///
/// **ZX_ERR_NO_MEMORY** Failed to allocate memory for a new handle.
///
/// **ZX_ERR_WRONG_TYPE** *handle* is not an exception.
///
/// ## See also
///
/// - [exceptions]
/// - [`zx_exception_get_thread()`]
///
/// [exceptions]: /docs/concepts/kernel/exceptions.md
/// [`zx_exception_get_thread()`]: exception_get_thread.md
/// [`zx_task_create_exception_channel()`]: task_create_exception_channel.md
GetProcess(resource struct {
handle handle:EXCEPTION;
}) -> (resource struct {
out handle:PROCESS;
}) error status;
};