1# zx_handle_duplicate
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7handle_duplicate - duplicate 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_duplicate(zx_handle_t handle,
17                                zx_rights_t rights,
18                                zx_handle_t* out);
19```
20
21## DESCRIPTION
22
23`zx_handle_duplicate()` creates a duplicate of *handle*, referring
24to the same underlying object, with new access rights *rights*.
25
26To duplicate the handle with the same rights use **ZX_RIGHT_SAME_RIGHTS**. If different
27rights are desired they must be strictly lesser than of the source handle. It is possible
28to specify no rights by using 0.
29
30## RIGHTS
31
32<!-- Updated by update-docs-from-abigen, do not edit. -->
33
34*handle* must have **ZX_RIGHT_DUPLICATE**.
35
36## RETURN VALUE
37
38`zx_handle_duplicate()` returns **ZX_OK** and the duplicate handle via *out* on success.
39
40## ERRORS
41
42**ZX_ERR_BAD_HANDLE**  *handle* isn't a valid handle.
43
44**ZX_ERR_INVALID_ARGS**  The *rights* requested are not a subset of *handle* rights or
45*out* is an invalid pointer.
46
47**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_DUPLICATE** and may not be duplicated.
48
49**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
50There is no good way for userspace to handle this (unlikely) error.
51In a future build this error will no longer occur.
52
53## SEE ALSO
54
55 - [rights](../rights.md)
56 - [`zx_handle_close()`]
57 - [`zx_handle_close_many()`]
58 - [`zx_handle_replace()`]
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_replace()`]: handle_replace.md
65