1# zx_vmo_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmo_create - create 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_create(uint64_t size, uint32_t options, zx_handle_t* out);
17```
18
19## DESCRIPTION
20
21`zx_vmo_create()` creates a new virtual memory object (VMO), which represents
22a container of zero to *size* bytes of memory managed by the operating
23system.
24
25The size of the VMO will be rounded up to the next page size boundary.
26Use [`zx_vmo_get_size()`] to return the current size of the VMO.
27
28One handle is returned on success, representing an object with the requested
29size.
30
31The following rights will be set on the handle by default:
32
33**ZX_RIGHT_DUPLICATE** - The handle may be duplicated.
34
35**ZX_RIGHT_TRANSFER** - The handle may be transferred to another process.
36
37**ZX_RIGHT_READ** - May be read from or mapped with read permissions.
38
39**ZX_RIGHT_WRITE** - May be written to or mapped with write permissions.
40
41**ZX_RIGHT_EXECUTE** - May be mapped with execute permissions.
42
43**ZX_RIGHT_MAP** - May be mapped.
44
45**ZX_RIGHT_GET_PROPERTY** - May get its properties using
46[object_get_property](object_get_property.md).
47
48**ZX_RIGHT_SET_PROPERTY** - May set its properties using
49[object_set_property](object_set_property.md).
50
51The *options* field can be 0 or **ZX_VMO_NON_RESIZABLE** to create a VMO
52that cannot change size. Clones of a non-resizable VMO can be resized.
53
54The **ZX_VMO_ZERO_CHILDREN** signal is active on a newly created VMO. It becomes
55inactive whenever a clone of the VMO is created and becomes active again when
56all clones have been destroyed and no mappings of those clones into address
57spaces exist.
58
59## RIGHTS
60
61<!-- Updated by update-docs-from-abigen, do not edit. -->
62
63TODO(ZX-2399)
64
65## RETURN VALUE
66
67`zx_vmo_create()` returns **ZX_OK** on success. In the event
68of failure, a negative error value is returned.
69
70## ERRORS
71
72**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL or *options* is
73any value other than 0.
74
75**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
76There is no good way for userspace to handle this (unlikely) error.
77In a future build this error will no longer occur.
78
79## SEE ALSO
80
81 - [`zx_vmar_map()`]
82 - [`zx_vmo_clone()`]
83 - [`zx_vmo_get_size()`]
84 - [`zx_vmo_op_range()`]
85 - [`zx_vmo_read()`]
86 - [`zx_vmo_set_size()`]
87 - [`zx_vmo_write()`]
88
89<!-- References updated by update-docs-from-abigen, do not edit. -->
90
91[`zx_vmar_map()`]: vmar_map.md
92[`zx_vmo_clone()`]: vmo_clone.md
93[`zx_vmo_get_size()`]: vmo_get_size.md
94[`zx_vmo_op_range()`]: vmo_op_range.md
95[`zx_vmo_read()`]: vmo_read.md
96[`zx_vmo_set_size()`]: vmo_set_size.md
97[`zx_vmo_write()`]: vmo_write.md
98