# zx_pager_query_vmo_stats

## NAME

Query pager related statistics on a pager owned VMO.

## SYNOPSIS

    #include <zircon/syscalls.h>

    zx_status_t zx_pager_query_vmo_stats(zx_handle_t pager,
                                         zx_handle_t pager_vmo,
                                         uint32_t options,
                                         void* buffer,
                                         size_t buffer_size);

## Description

Queries *pager_vmo* for any pager related statistics, e.g. whether *pager_vmo* has been modified.
The *pager_vmo* must have previously been created from the *pager* by [`zx_pager_create_vmo()`](https://fuchsia.dev/reference/syscalls/pager_create_vmo).

*options* can be `ZX_PAGER_RESET_VMO_STATS` if the caller also wishes to reset the queried stats.
An *options* value of 0 does not reset any state, and performs a pure query.

*buffer* should be a pointer to a `zx_pager_vmo_stats_t` struct that will hold the result of the
query, and *buffer_size* should be large enough to accommodate the struct.

    typedef struct zx_pager_vmo_stats {
      // Will be set to ZX_PAGER_VMO_STATS_MODIFIED if the VMO was modified, or 0 otherwise.
      // Note that this can be set to 0 if a previous zx_pager_query_vmo_stats() call specified the
      // ZX_PAGER_RESET_VMO_STATS option, which resets the modified state.
      uint32_t modified;
    } zx_pager_vmo_stats_t;

Note that this call can have an effect on future `zx_pager_query_vmo_stats()` calls by consuming
queryable state if the `ZX_PAGER_RESET_VMO_STATS` option is specified. For example, if a
`zx_vmo_write()` is followed by two consecutive `zx_pager_query_vmo_stats()` with the
`ZX_PAGER_RESET_VMO_STATS` option, only the first of those will see `modified` set to
`ZX_PAGER_VMO_STATS_MODIFIED`. Since no further modifications took place after the first
`zx_pager_query_vmo_stats()`, the second `zx_pager_query_vmo_stats()` will return `modified` as 0.

## Rights

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

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

## Return value

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

## 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_MANAGE_VMO` or *pager_vmo* does not have
`ZX_RIGHT_READ`.

`ZX_ERR_INVALID_ARGS` *pager_vmo* is not a VMO created from *pager* , or *options* is neither 0 or
`ZX_PAGER_RESET_VMO_STATS`, or *buffer* is an invalid pointer.

`ZX_ERR_BUFFER_TOO_SMALL` *buffer_size* is not large enough to accommodate `zx_pager_vmo_stats_t`.

## See also

- [`zx_pager_create_vmo()`](https://fuchsia.dev/reference/syscalls/pager_create_vmo)
- [`zx_pager_detach_vmo()`](https://fuchsia.dev/reference/syscalls/pager_detach_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)
- [`zx_pager_supply_pages()`](https://fuchsia.dev/reference/syscalls/pager_supply_pages)