## Summary

Detaches a VMO from a pager.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_pager_detach_vmo(zx_handle_t pager, zx_handle_t pager_vmo);

## Description

Detaching *pager_vmo* from *pager* causes the kernel to stop queuing page requests for the VMO.
Subsequent accesses that would have generated page requests will instead fail.

No new `ZX_PAGER_VMO_READ` and `ZX_PAGER_VMO_DIRTY` requests will be generated after detaching,
but some requests may still be in flight. The pager service is free to ignore these requests, as the
kernel will resume and fault the threads that generated these requests. The final request the pager
service will receive is a `ZX_PAGER_VMO_COMPLETE` request.

The following pager syscalls will fail on a detached VMO:

- [`zx_pager_supply_pages()`](https://fuchsia.dev/reference/syscalls/pager_supply_pages)
- [`zx_pager_op_range()`](https://fuchsia.dev/reference/syscalls/pager_op_range) with `ZX_PAGER_OP_DIRTY` and `ZX_PAGER_OP_FAIL`

And the following will continue working as before the detach:

- [`zx_pager_query_dirty_ranges()`](https://fuchsia.dev/reference/syscalls/pager_query_dirty_ranges)
- [`zx_pager_query_vmo_stats()`](https://fuchsia.dev/reference/syscalls/pager_query_vmo_stats)
- [`zx_pager_op_range()`](https://fuchsia.dev/reference/syscalls/pager_op_range) with `ZX_PAGER_OP_WRITEBACK_BEGIN` and `ZX_PAGER_OP_WRITEBACK_END`

The kernel is free to evict clean pages from detached VMOs, but will retain any dirty pages. Upon
receiving the `ZX_PAGER_VMO_COMPLETE` request, the pager service is expected to query these ranges
with [`zx_pager_query_dirty_ranges()`](https://fuchsia.dev/reference/syscalls/pager_query_dirty_ranges) and write them back with [`zx_pager_op_range()`](https://fuchsia.dev/reference/syscalls/pager_op_range)
`ZX_PAGER_OP_WRITEBACK_BEGIN` and `ZX_PAGER_OP_WRITEBACK_END`. Once they have been written back,
these pages will become clean again, so the kernel is free to evict them.

## Rights

*pager* must be of type `ZX_OBJ_TYPE_PAGER` and have `ZX_RIGHT_ATTACH_VMO` and
`ZX_RIGHT_MANAGE_VMO`.

*pager_vmo* must be of type `ZX_OBJ_TYPE_VMO` and have `ZX_RIGHT_WRITE`.

## Return value

`zx_pager_detach_vmo()` returns ZX_OK on success, or one of the following error codes on failure.

## Errors

`ZX_ERR_BAD_HANDLE` *pager* or *pager_vmo* is not a valid handle.

`ZX_ERR_WRONG_TYPE` *pager* is not a pager handle or *pager_vmo* is not a VMO handle.

`ZX_ERR_ACCESS_DENIED` *pager* does not have `ZX_RIGHT_ATTACH_VMO` or `ZX_RIGHT_MANAGE_VMO`,
or *pager_vmo* does not have `ZX_RIGHT_WRITE`.

`ZX_ERR_INVALID_ARGS` *pager_vmo* is not a VMO created from *pager*.

## See also

- [`zx_pager_create_vmo()`](https://fuchsia.dev/reference/syscalls/pager_create_vmo)
- [`zx_pager_op_range()`](https://fuchsia.dev/reference/syscalls/pager_op_range)
- [`zx_pager_query_dirty_ranges()`](https://fuchsia.dev/reference/syscalls/pager_query_dirty_ranges)