main/syscalls/vmo_transfer_data.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_vmo_transfer_data

## SUMMARY

Moves data into a VMO.

## Declaration

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

zx_status_t zx_vmo_transfer_data(zx_vmo_t dst_vmo,
                                 uint32_t options,
                                 uint64_t offset,
                                 uint64_t length,
                                 zx_vmo_t src_vmo,
                                 uint64_t src_offset);
```

## Description

Moves the pages in `[*src_offset*, *src_offset* + *length*)` from
*src_vmo* to `[*offset*, *offset* + *length*)` in *dst_vmo*. It is
functionally equivalent to a `memmove` from *src_vmo* to *dst_vmo*
followed by a decommit of the associated pages in *src_vmo*. However,
the mechanism by which this is achieved is different; the backing pages
are actually moved between VMOs instead of copying data. This allows for
much better performance. Despite this different mechanism, this syscall
presents the same semantics as `memmove`, in that providing overlapping
source and destination regions is supported.

The *options* field must currently be set to 0.

## Rights

*dst_vmo* must be of type `ZX_OBJ_TYPE_VMO`. This handle must have
`ZX_RIGHT_WRITE`.

*src_vmo* must be of type `ZX_OBJ_TYPE_VMO`. This handle must have
`ZX_RIGHT_READ` and `ZX_RIGHT_WRITE`.

## Return value

`zx_vmo_transfer_data()` returns `ZX_OK` on success. In the event of
failure, a negative error value is returned (as described below). If the
transfer fails, then any number of pages in *src_vmo* may have been
moved to *dst_vmo*. We make no guarantees as to exactly how much data
was moved. However, we can guarantee that the call will succeed if the
following conditions are met:

1. None of the conditions that would result in the errors listed below
   are met.
2. The *src_vmo* and *dst_vmo* are not modified by any other threads
   while this operation is running.

A "modification" in this context refers to a write/resize/pin on either
the VMO directly or on a reference to the VMO (e.g. slices, reference
children, etc.). Modifying a parent, child, or sibling of any kind of
snapshot should not result in any error, although depending on the
snapshot you may get write tearing. Write tearing could occur if you
manipulate the parent of a `SNAPSHOT_AT_LEAST_ON_WRITE` VMO as the
actual transfer has no promised atomicity. Note that in the case of
transferring pages from a `SNAPSHOT` child we may need to perform
copies, i.e. allocate new pages, if that particular page has not yet
been copy-on-written.

## Errors

`ZX_ERR_BAD_HANDLE`  *dst_vmo* or *src_vmo* is not a valid VMO handle.

`ZX_ERR_INVALID_ARGS` *offset*, *length*, or *src_offset* is not page
aligned, or *options* is nonzero.

`ZX_ERR_ACCESS_DENIED` *src_vmo* does not have `ZX_RIGHT_WRITE` or
`ZX_RIGHT_READ`, or *dst_vmo* does not have `ZX_RIGHT_WRITE`.

`ZX_ERR_BAD_STATE` Pages in the specified range in `src_vmo` or
`dst_vmo` are pinned.

`ZX_ERR_NOT_SUPPORTED` Either *src_vmo* or *dst_vmo* is physical,
contiguous, or pager-backed.

`ZX_ERR_OUT_OF_RANGE` The specified range in *dst_vmo* or *src_vmo* is
invalid.

`ZX_ERR_NO_MEMORY` Failure due to lack of memory.

## See also

[`zx_vmo_create()`]: vmo_create.md