# zx_handle_close

## Summary

Close a handle.

## Declaration

    #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()`](https://fuchsia.dev/reference/syscalls/object_wait_one) or a
[`zx_object_wait_many()`](https://fuchsia.dev/reference/syscalls/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](https://fuchsia.dev/docs/reference/kernel_objects/objects#peered-objects-and-the-peer-closed-state).

## 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

- [`zx_handle_close_many()`](https://fuchsia.dev/reference/syscalls/handle_close_many)
- [`zx_handle_duplicate()`](https://fuchsia.dev/reference/syscalls/handle_duplicate)
- [`zx_handle_replace()`](https://fuchsia.dev/reference/syscalls/handle_replace)