1# zx_handle_duplicate
2
3## NAME
4
5handle_duplicate - duplicate a handle
6
7## SYNOPSIS
8
9```
10#include <zircon/syscalls.h>
11
12zx_status_t zx_handle_duplicate(zx_handle_t handle, zx_rights_t rights, zx_handle_t* out);
13```
14
15## DESCRIPTION
16
17**handle_duplicate**() creates a duplicate of *handle*, referring
18to the same underlying object, with new access rights *rights*.
19
20To duplicate the handle with the same rights use **ZX_RIGHT_SAME_RIGHTS**. If different
21rights are desired they must be strictly lesser than of the source handle. It is possible
22to specify no rights by using 0.
23
24## RIGHTS
25
26*handle* must have **ZX_RIGHT_DUPLICATE**.
27
28## RETURN VALUE
29
30**handle_duplicate**() returns ZX_OK and the duplicate handle via *out* on success.
31
32## ERRORS
33
34**ZX_ERR_BAD_HANDLE**  *handle* isn't a valid handle.
35
36**ZX_ERR_INVALID_ARGS**  The *rights* requested are not a subset of *handle* rights or
37*out* is an invalid pointer.
38
39**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_DUPLICATE** and may not be duplicated.
40
41**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
42There is no good way for userspace to handle this (unlikely) error.
43In a future build this error will no longer occur.
44
45## SEE ALSO
46
47[handle_close](handle_close.md),
48[handle_close_many](handle_close_many.md),
49[handle_replace](handle_replace.md),
50[rights](../rights.md).
51