1# zx_object_get_cookie
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7object_get_cookie - Get an object's cookie.
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_object_get_cookie(zx_handle_t handle,
17                                 zx_handle_t scope,
18                                 uint64_t* cookie);
19```
20
21## DESCRIPTION
22
23Some objects (Events, Event pairs, Resources, VMOs) may have a cookie attached,
24which is a 64bit opaque value.  Initially the cookie is undefined and not readable.
25
26If the cookie has been set on an object, `zx_object_get_cookie()` may be
27called, using the same object as *scope* to obtain the cookie.
28
29Event pairs are special.  If one side of the pair is closed, the other side's
30cookie is invalidated. An invalidated cookie is not get-able or set-able with any scope.
31
32Cookies are useful for objects that will be passed to another process and
33later returned.  By setting the cookie with [`zx_object_set_cookie()`],
34using a *scope* that is not accessible by other processes, `zx_object_get_cookie()`
35may later be used to verify that a handle is referring to an object that was
36"created" by the calling process and simultaneously return an ID or pointer
37to local state for that object.
38
39When the object referenced by *scope* is destroyed or if a handle to that object
40is no longer available, the cookie may no longer be modified or obtained.
41
42
43## RIGHTS
44
45<!-- Updated by update-docs-from-abigen, do not edit. -->
46
47TODO(ZX-2399)
48
49## RETURN VALUE
50
51`zx_object_get_cookie()` returns **ZX_OK** and the *cookie* value on success.
52In the event of failure, a negative error value is returned.
53
54
55## ERRORS
56
57**ZX_ERR_BAD_HANDLE**  *handle* or *scope* are not valid handles.
58
59**ZX_ERR_NOT_SUPPORTED**  *handle* is not a handle to an object that may have a cookie set.
60
61**ZX_ERR_ACCESS_DENIED**  The cookie has not been set, or *scope* is not the correct scope
62to obtain the set cookie.
63
64**ZX_ERR_INVALID_ARGS**  *cookie* is an invalid pointer.
65
66## SEE ALSO
67
68 - [`zx_object_set_cookie()`]
69
70<!-- References updated by update-docs-from-abigen, do not edit. -->
71
72[`zx_object_set_cookie()`]: object_set_cookie.md
73