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 (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(). Use zx_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() with ZX_PROP_VMO_CONTENT_SIZE to read the content size of the VMO. Use zx_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().

  • ZX_RIGHT_SET_PROPERTY - May set its properties using zx_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() 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