1# zx_handle_replace
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7handle_replace - replace a handle
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_handle_replace(zx_handle_t handle,
17                              zx_rights_t rights,
18                              zx_handle_t* out);
19```
20
21## DESCRIPTION
22
23`zx_handle_replace()` creates a replacement for *handle*, referring to
24the same underlying object, with new access rights *rights*.
25
26*handle* is always invalidated.
27
28If *rights* is **ZX_RIGHT_SAME_RIGHTS**, the replacement handle will
29have the same rights as the original handle. Otherwise, *rights* must be
30a subset of original handle's rights.
31
32## RIGHTS
33
34<!-- Updated by update-docs-from-abigen, do not edit. -->
35
36None.
37
38## RETURN VALUE
39
40`zx_handle_replace()` returns **ZX_OK** and the replacement handle (via *out*)
41on success.
42
43## ERRORS
44
45**ZX_ERR_BAD_HANDLE**  *handle* isn't a valid handle.
46
47**ZX_ERR_INVALID_ARGS**  The *rights* requested are not a subset of
48*handle*'s rights or *out* is an invalid pointer.
49
50**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
51There is no good way for userspace to handle this (unlikely) error.
52In a future build this error will no longer occur.
53
54## SEE ALSO
55
56 - [`zx_handle_close()`]
57 - [`zx_handle_close_many()`]
58 - [`zx_handle_duplicate()`]
59
60<!-- References updated by update-docs-from-abigen, do not edit. -->
61
62[`zx_handle_close()`]: handle_close.md
63[`zx_handle_close_many()`]: handle_close_many.md
64[`zx_handle_duplicate()`]: handle_duplicate.md
65