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