1# zx_vmo_clone
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmo_clone - create a clone of a VM Object
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_vmo_clone(zx_handle_t handle,
17                         uint32_t options,
18                         uint64_t offset,
19                         uint64_t size,
20                         zx_handle_t* out);
21```
22
23## DESCRIPTION
24
25`zx_vmo_clone()` creates a new virtual memory object (VMO) that clones a range
26of an existing vmo.
27
28One handle is returned on success, representing an object with the requested
29size.
30
31*options* must contain **ZX_VMO_CLONE_COPY_ON_WRITE** and zero or more flags to control
32clone creation.
33
34Valid flags:
35
36- **ZX_VMO_CLONE_COPY_ON_WRITE** - Create a copy-on-write clone. The cloned vmo will
37behave the same way the parent does, except that any write operation on the clone
38will bring in a copy of the page at the offset the write occurred. The new page in
39the cloned vmo is now a copy and may diverge from the parent. Any reads from
40ranges outside of the parent vmo's size will contain zeros, and writes will
41allocate new zero filled pages.  See the NOTES section below for details on
42VMO syscall interactions with clones.
43
44- **ZX_VMO_CLONE_NON_RESIZEABLE** - Create a non-resizeable clone VMO.
45
46*offset* must be page aligned.
47
48*offset* + *size* may not exceed the range of a 64bit unsigned value.
49
50Both offset and size may start or extend beyond the original VMO's size.
51
52The size of the VMO will be rounded up to the next page size boundary.
53
54By default the rights of the cloned handled will be the same as the
55original with a few exceptions. See [`zx_vmo_create()`] for a
56discussion of the details of each right.
57
58If *options* is **ZX_VMO_CLONE_COPY_ON_WRITE** the following rights are added:
59
60- **ZX_RIGHT_WRITE**
61
62## NOTES
63
64Cloning a VMO causes the existing (source) VMO **ZX_VMO_ZERO_CHILDREN** signal
65to become inactive. Only when the last clone is destroyed and no mappings
66of those clones into address spaces exist, will **ZX_VMO_ZERO_CHILDREN** become
67active again.
68
69### ZX_VMO_CLONE_COPY_ON_WRITE
70
71VMOs produced by this mode will interact with the VMO syscalls in the following
72ways:
73
74- The DECOMMIT and COMMIT modes of [`zx_vmo_op_range()`] on a clone will only affect pages
75  allocated to the clone, never its parent.
76- If a page in a clone is decommitted (e.g. with [`zx_vmo_op_range()`]), the parent's page will
77  become visible once again, still with copy-on-write semantics.
78- If a page is committed to a clone using the [`zx_vmo_op_range()`] COMMIT mode, a
79  the new page will have the same contents as the parent's corresponding page
80  (or zero-filled if no such page exists).
81- If the [`zx_vmo_op_range()`] LOOKUP mode is used, the parent's pages will be visible
82  where the clone has not modified them.
83
84## RIGHTS
85
86<!-- Updated by update-docs-from-abigen, do not edit. -->
87
88*handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_DUPLICATE** and have **ZX_RIGHT_READ**.
89
90## RETURN VALUE
91
92`zx_vmo_clone()` returns **ZX_OK** on success. In the event
93of failure, a negative error value is returned.
94
95## ERRORS
96
97**ERR_BAD_TYPE**  Input handle is not a VMO.
98
99**ZX_ERR_ACCESS_DENIED**  Input handle does not have sufficient rights.
100
101**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL
102or the offset is not page aligned.
103
104**ZX_ERR_OUT_OF_RANGE**  *offset* + *size* is too large.
105
106**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
107There is no good way for userspace to handle this (unlikely) error.
108In a future build this error will no longer occur.
109
110## SEE ALSO
111
112 - [`zx_vmar_map()`]
113 - [`zx_vmo_create()`]
114 - [`zx_vmo_get_size()`]
115 - [`zx_vmo_op_range()`]
116 - [`zx_vmo_read()`]
117 - [`zx_vmo_set_size()`]
118 - [`zx_vmo_write()`]
119
120<!-- References updated by update-docs-from-abigen, do not edit. -->
121
122[`zx_vmar_map()`]: vmar_map.md
123[`zx_vmo_create()`]: vmo_create.md
124[`zx_vmo_get_size()`]: vmo_get_size.md
125[`zx_vmo_op_range()`]: vmo_op_range.md
126[`zx_vmo_read()`]: vmo_read.md
127[`zx_vmo_set_size()`]: vmo_set_size.md
128[`zx_vmo_write()`]: vmo_write.md
129