blob: 510a1c7339b7185d0f77a68e558bf4845f1a1517 [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")
@no_protocol_prefix
protocol Handlefuncs {
/// ## Summary
///
/// Close a handle.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_handle_close(zx_handle_t handle);
/// ```
///
/// ## Description
///
/// `zx_handle_close()` closes a *handle*, causing the underlying object to be
/// reclaimed by the kernel if no other handles to it exist.
///
/// If the *handle* was used in a pending [`zx_object_wait_one()`] or a
/// [`zx_object_wait_many()`] call, the wait will be aborted.
///
/// It is not an error to close the special "never a valid handle" **ZX_HANDLE_INVALID**,
/// similar to `free(NULL)` being a valid call.
///
/// Closing the last handle to a peered object using `zx_handle_close()` can affect
/// the state of the object's peer (if any). See also
/// [peered-objects][peered-objects].
///
/// ## Rights
///
/// None.
///
/// ## Return value
///
/// `zx_handle_close()` returns **ZX_OK** on success.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** *handle* isn't a valid handle.
///
/// ## See also
///
/// <!-- Reference links -->
/// [peered-objects]: /docs/reference/kernel_objects/objects.md#peered-objects-and-the-peer-closed-state
///
/// - [`zx_handle_close_many()`]
/// - [`zx_handle_duplicate()`]
/// - [`zx_handle_replace()`]
///
/// [`zx_handle_close_many()`]: handle_close_many.md
/// [`zx_handle_duplicate()`]: handle_duplicate.md
/// [`zx_handle_replace()`]: handle_replace.md
/// [`zx_object_wait_many()`]: object_wait_many.md
/// [`zx_object_wait_one()`]: object_wait_one.md
HandleClose(resource struct {
@release
handle handle;
}) -> () error status;
/// ## Summary
///
/// Close a number of handles.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_handle_close_many(const zx_handle_t* handles,
/// size_t num_handles);
/// ```
///
/// ## Description
///
/// `zx_handle_close_many()` closes a number of handles, causing each
/// underlying object to be reclaimed by the kernel if no other handles to
/// it exist.
///
/// If a handle was used in a pending [`zx_object_wait_one()`] or a
/// [`zx_object_wait_many()`] call, the wait will be aborted.
///
/// This operation closes all handles presented to it, even if one or more
/// of the handles is duplicate or invalid.
///
/// It is not an error to close the special "never a valid handle" **ZX_HANDLE_INVALID**,
/// similar to `free(NULL)` being a valid call.
///
/// Closing the last handle to a peered object using `zx_handle_close_many()` can
/// affect the state of the object's peer (if any). See also
/// [peered-objects][peered-objects].
///
/// ## Rights
///
/// None.
///
/// ## Return value
///
/// `zx_handle_close_many()` returns **ZX_OK** on success.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** One of the *handles* isn't a valid handle, or the same handle is
/// present multiple times.
///
/// ## See also
///
/// <!-- Reference links -->
/// [peered-objects]: /docs/reference/kernel_objects/objects.md#peered-objects-and-the-peer-closed-state
///
/// - [`zx_handle_close()`]
/// - [`zx_handle_duplicate()`]
/// - [`zx_handle_replace()`]
///
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_handle_duplicate()`]: handle_duplicate.md
/// [`zx_handle_replace()`]: handle_replace.md
/// [`zx_object_wait_many()`]: object_wait_many.md
/// [`zx_object_wait_one()`]: object_wait_one.md
HandleCloseMany(resource struct {
@release
handles vector<handle>;
}) -> () error status;
/// ## Summary
///
/// Duplicate a handle.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_handle_duplicate(zx_handle_t handle,
/// zx_rights_t rights,
/// zx_handle_t* out);
/// ```
///
/// ## Description
///
/// `zx_handle_duplicate()` creates a duplicate of *handle*, referring
/// to the same underlying object, with new access rights *rights*.
///
/// To duplicate the handle with the same rights use **ZX_RIGHT_SAME_RIGHTS**. If different
/// rights are desired they must be strictly lesser than of the source handle. It is possible
/// to specify no rights by using **ZX_RIGHT_NONE**. To remove **ZX_RIGHT_DUPLICATE** right when
/// transferring through a channel, use [`zx_channel_write_etc()`].
///
/// ## Rights
///
/// *handle* must have **ZX_RIGHT_DUPLICATE**.
///
/// ## Return value
///
/// `zx_handle_duplicate()` returns **ZX_OK** and the duplicate handle via *out* on success.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** *handle* isn't a valid handle.
///
/// **ZX_ERR_INVALID_ARGS** The *rights* requested are not a subset of *handle* rights or
/// *out* is an invalid pointer.
///
/// **ZX_ERR_ACCESS_DENIED** *handle* does not have **ZX_RIGHT_DUPLICATE** and may not be duplicated.
///
/// **ZX_ERR_NO_MEMORY** Failure due to lack of memory.
/// There is no good way for userspace to handle this (unlikely) error.
/// In a future build this error will no longer occur.
///
/// ## See also
///
/// - [rights]
/// - [`zx_channel_write_etc()`]
/// - [`zx_handle_close()`]
/// - [`zx_handle_close_many()`]
/// - [`zx_handle_replace()`]
///
/// [rights]: /docs/concepts/kernel/rights.md
/// [`zx_channel_write_etc()`]: channel_write_etc.md
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_handle_close_many()`]: handle_close_many.md
/// [`zx_handle_replace()`]: handle_replace.md
HandleDuplicate(resource struct {
handle handle;
rights rights;
}) -> (resource struct {
out handle;
}) error status;
/// ## Summary
///
/// Replace a handle.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_handle_replace(zx_handle_t handle,
/// zx_rights_t rights,
/// zx_handle_t* out);
/// ```
///
/// ## Description
///
/// `zx_handle_replace()` creates a replacement for *handle*, referring to
/// the same underlying object, with new access rights *rights*.
///
/// *handle* is always invalidated.
///
/// If *rights* is **ZX_RIGHT_SAME_RIGHTS**, the replacement handle will
/// have the same rights as the original handle. Otherwise, *rights* must be
/// a subset of original handle's rights.
///
/// ## Rights
///
/// None.
///
/// ## Return value
///
/// `zx_handle_replace()` returns **ZX_OK** and the replacement handle (via *out*)
/// on success.
///
/// ## Errors
///
/// **ZX_ERR_BAD_HANDLE** *handle* isn't a valid handle.
///
/// **ZX_ERR_INVALID_ARGS** The *rights* requested are not a subset of
/// *handle*'s rights or *out* is an invalid pointer.
///
/// **ZX_ERR_NO_MEMORY** Failure due to lack of memory.
/// There is no good way for userspace to handle this (unlikely) error.
/// In a future build this error will no longer occur.
///
/// ## See also
///
/// - [`zx_handle_close()`]
/// - [`zx_handle_close_many()`]
/// - [`zx_handle_duplicate()`]
///
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_handle_close_many()`]: handle_close_many.md
/// [`zx_handle_duplicate()`]: handle_duplicate.md
HandleReplace(resource struct {
@release
handle handle;
rights rights;
}) -> (resource struct {
out handle;
}) error status;
};