# zx_vmo_create

## Summary

Create a VM object.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_vmo_create(uint64_t size, uint32_t options, zx_handle_t* out);

## Description

`zx_vmo_create()` creates a new, zero-filled, [virtual memory
object](https://fuchsia.dev/docs/reference/kernel_objects/vm_object) (VMO), which represents a container of zero to
*size* bytes of memory managed by the operating system.

The size of the VMO will be rounded up to the next system page size boundary,
as reported by [`zx_system_get_page_size()`](https://fuchsia.dev/reference/syscalls/system_get_page_size). Use [`zx_vmo_get_size()`](https://fuchsia.dev/reference/syscalls/vmo_get_size) to
return the current size of the VMO.

The content size of the VMO will be initialized to the given (unrounded) size.
Use [`zx_object_get_property()`](https://fuchsia.dev/reference/syscalls/object_get_property) with `ZX_PROP_VMO_CONTENT_SIZE` to read the
content size of the VMO. Use [`zx_object_set_property()`](https://fuchsia.dev/reference/syscalls/object_set_property) with
`ZX_PROP_VMO_CONTENT_SIZE` to set the content size of the VMO without
actually resizing the VMO.

One handle is returned on success, representing an object with the requested
size.

The following rights will be set on the handle by default:

- `ZX_RIGHT_DUPLICATE` - The handle may be duplicated.

- `ZX_RIGHT_TRANSFER` - The handle may be transferred to another process.

- `ZX_RIGHT_READ` - May be read from or mapped with read permissions.

- `ZX_RIGHT_WRITE` - May be written to or mapped with write permissions.

- `ZX_RIGHT_MAP` - May be mapped.

- `ZX_RIGHT_GET_PROPERTY` - May get its properties using [`zx_object_get_property()`](https://fuchsia.dev/reference/syscalls/object_get_property).

- `ZX_RIGHT_SET_PROPERTY` - May set its properties using [`zx_object_set_property()`](https://fuchsia.dev/reference/syscalls/object_set_property).

- `ZX_RIGHT_RESIZE` - May be resized. Only set if the `ZX_VMO_RESIZABLE` option was specified.

The *options* field can be 0 or a combination of:

- `ZX_VMO_RESIZABLE` to create a VMO that can change size. Children of a non-resizable VMO can
  be resized.

- `ZX_VMO_DISCARDABLE` to create a VMO that the kernel can discard pages from under memory
  pressure. Use [`zx_vmo_op_range()`](https://fuchsia.dev/reference/syscalls/vmo_op_range) with `ZX_VMO_OP_LOCK` to lock discardable VMOs when in
  use, and unlock them when done with `ZX_VMO_OP_UNLOCK` making them eligible for reclamation by
  the kernel. A newly created discardable VMO is initially unlocked.

- `ZX_VMO_UNBOUNDED` to create a VMO that is initialized to the largest possible size. Cannot be
  used in conjunction with `ZX_VMO_RESIZABLE`. Size argument sets the stream size only.

The `ZX_VMO_ZERO_CHILDREN` signal is active on a newly created VMO. It becomes
inactive whenever a child of the VMO is created and becomes active again when
all children have been destroyed and no mappings of those children into address
spaces exist.

## Rights

Caller job policy must allow `ZX_POL_NEW_VMO`.

## Return value

`zx_vmo_create()` returns `ZX_OK` on success. In the event
of failure, a negative error value is returned.

## Errors

`ZX_ERR_INVALID_ARGS` *out* is an invalid pointer or NULL, *options* contains an unsupported
combination of flags.

`ZX_ERR_NO_MEMORY` Failure due to lack of memory.
There is no good way for userspace to handle this (unlikely) error.
In a future build this error will no longer occur.

`ZX_ERR_OUT_OF_RANGE` Requested size is too large.

## See also

- [`zx_system_get_page_size()`](https://fuchsia.dev/reference/syscalls/system_get_page_size)
- [`zx_vmar_map()`](https://fuchsia.dev/reference/syscalls/vmar_map)
- [`zx_vmo_create_child()`](https://fuchsia.dev/reference/syscalls/vmo_create_child)
- [`zx_vmo_get_size()`](https://fuchsia.dev/reference/syscalls/vmo_get_size)
- [`zx_vmo_op_range()`](https://fuchsia.dev/reference/syscalls/vmo_op_range)
- [`zx_vmo_read()`](https://fuchsia.dev/reference/syscalls/vmo_read)
- [`zx_vmo_replace_as_executable()`](https://fuchsia.dev/reference/syscalls/vmo_replace_as_executable)
- [`zx_vmo_set_size()`](https://fuchsia.dev/reference/syscalls/vmo_set_size)
- [`zx_vmo_write()`](https://fuchsia.dev/reference/syscalls/vmo_write)