# zx_vmo_create_child

## NAME

<!-- Updated by update-docs-from-fidl, do not edit. -->

Create a child of a VM Object.

## SYNOPSIS

<!-- Updated by update-docs-from-fidl, do not edit. -->

```c
#include <zircon/syscalls.h>

zx_status_t zx_vmo_create_child(zx_handle_t handle,
                                uint32_t options,
                                uint64_t offset,
                                uint64_t size,
                                zx_handle_t* out);
```

## DESCRIPTION

`zx_vmo_create_child()` creates a new virtual memory object (VMO) a child of
an existing vmo. The behavior of the semantics depends on the type of the child.

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

*options* must contain exactly one of the following flags to specify the
child type:

- **ZX_VMO_CHILD_SNAPSHOT** -  Create a child that behaves as if an eager copy is performed. When a
write occurs, both the parent and child perform a lazy copy. Lazy copying allows both the child and
the parent to diverge from each other. Any reads from ranges outside of the parent VMO's size
contain zeros, and writes allocate new zero filled pages.
This flag is not supported on:
 - VMOs with pinned regions.
 - VMOs created with or descended from [`zx_vmo_create_physical()`] or
   [`zx_vmo_create_contiguous()`]
 - VMOs backed by a user pager.
For information on VMO syscall interactions with children, see [NOTES](#notes).

- **ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE** -  Create a child that behaves with at least copy on
write semantics. Any write operation on the child brings in a copy of the page from the parent,
after which its contents may diverge from the parent. Until a page is written to, and copied, reads
are permitted, although not guaranteed, to return changing values if the parent performs writes.
This flag may not be used for VMOs created with [`zx_vmo_create_physical()`],
[`zx_vmo_create_contiguous()`] or descendants of such VMOs.
For information on VMO syscall interactions with children, see [NOTES](#notes).

- **ZX_VMO_CHILD_SLICE** - Create a slice that has direct read/write access into
a section of the parent. All operations on the slice vmo behave as if they were
done on the parent. A slice differs from a duplicate handle to the parent by allowing
access to only a subrange of the parent vmo, and allowing for the
**ZX_VMO_ZERO_CHILDREN** signal to be used. This flag may be used with vmos created with
[`zx_vmo_create_physical()`] or [`zx_vmo_create_contiguous()`] and their descendants.

An alias child type of **ZX_VMO_CHILD_COPY_ON_WRITE** is also defined and is equivalent to
**ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE**. This alias is intended to be used when
**ZX_VMO_CHILD_SNAPSHOT** is desired, but the VMO may be backed by a user pager. In all other cases,
you should use one of the precise child types as this alias may change or become deprecated.

In addition, *options* can contain zero or more of the following flags to
further specify the child's behavior:

- **ZX_VMO_CHILD_RESIZABLE** - Create a resizable child VMO.

- **ZX_VMO_CHILD_NO_WRITE** - Create a child that cannot be written to.

*offset* must be page aligned.

*offset* + *size* may not exceed the range of a 64bit unsigned value.

Both offset and size may start or extend beyond the original VMO's size.

The size of the VMO will be rounded up to the next page size boundary.

By default the rights of the child handled will be the same as the
original with a few exceptions. See [`zx_vmo_create()`] for a
discussion of the details of each right.

In all cases if **ZX_VMO_NO_WRITE** is set then **ZX_RIGHT_WRITE** will be removed.

If *options* is **ZX_VMO_CHILD_COPY_ON_WRITE** or **ZX_VMO_CHILD_PRIVATE_PAGER_COPY** and
**ZX_VMO_CHILD_NO_WRITE** is not set then **ZX_RIGHT_WRITE** will be added and **ZX_RIGHT_EXECUTE**
will be removed.

## NOTES

Creating a child VMO causes the existing (source) VMO **ZX_VMO_ZERO_CHILDREN** signal
to become inactive. Only when the last child is destroyed and no mappings
of those child into address spaces exist, will **ZX_VMO_ZERO_CHILDREN** become
active again.

Non-slice child vmos will interact with the VMO syscalls in the following ways:

- The COMMIT mode of [`zx_vmo_op_range()`] on a child will commit pages into the child that
  have the same content as its parent's corresponding pages. If those pages are supplied by a
  pager, this operation will also commit those pages in the parent. Otherwise, if those pages
  are not comitted in the parent, zero-filled pages will be comitted directly into
  child, without affecting the parent.
- The DECOMMIT mode of [`zx_vmo_op_range()`] is not supported.

## RIGHTS

<!-- Updated by update-docs-from-fidl, do not edit. -->

*handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_DUPLICATE** and have **ZX_RIGHT_READ**.

## RETURN VALUE

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

## ERRORS

**ERR_BAD_TYPE**  Input handle is not a VMO.

**ZX_ERR_ACCESS_DENIED**  Input handle does not have sufficient rights.

**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL
or the offset is not page aligned.

**ZX_ERR_OUT_OF_RANGE**  *offset* + *size* is too large.

**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.

**ERR_BAD_STATE**  A COW child could not be created because the vmo has some
pinned pages.

## SEE ALSO

 - [`zx_vmar_map()`]
 - [`zx_vmo_create()`]
 - [`zx_vmo_get_size()`]
 - [`zx_vmo_op_range()`]
 - [`zx_vmo_read()`]
 - [`zx_vmo_set_size()`]
 - [`zx_vmo_write()`]

<!-- References updated by update-docs-from-fidl, do not edit. -->

[`zx_pager_create_vmo()`]: pager_create_vmo.md
[`zx_vmar_map()`]: vmar_map.md
[`zx_vmo_create()`]: vmo_create.md
[`zx_vmo_create_physical()`]: vmo_create_physical.md
[`zx_vmo_get_size()`]: vmo_get_size.md
[`zx_vmo_op_range()`]: vmo_op_range.md
[`zx_vmo_read()`]: vmo_read.md
[`zx_vmo_set_size()`]: vmo_set_size.md
[`zx_vmo_write()`]: vmo_write.md