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