// 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
closed 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
    strict 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
    strict HandleCloseMany(resource struct {
        @release
        handles vector<Handle>:MAX;
    }) -> () 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
    strict 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
    strict HandleReplace(resource struct {
        @release
        handle Handle;
        rights Rights;
    }) -> (resource struct {
        out Handle;
    }) error Status;
};