.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2021-2022, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_vm_reservation_map_find\f[R](),
\f[B]pmem2_vm_reservation_map_find_prev\f[R](),
\f[B]pmem2_vm_reservation_map_find_next\f[R](),
\f[B]pmem2_vm_reservation_map_find_first\f[R]() and
\f[B]pmem2_vm_reservation_map_find_last\f[R]() - search for the mapping
located at the desirable location
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_map;
struct pmem2_vm_reservation;
int pmem2_vm_reservation_map_find(struct pmem2_vm_reservation *rsv,
        size_t reserv_offset, size_t len, struct pmem2_map **map_ptr);
int pmem2_vm_reservation_map_find_prev(struct pmem2_vm_reservation *rsv,
        struct pmem2_map *map, struct pmem2_map **prev_map);
int pmem2_vm_reservation_map_find_next(struct pmem2_vm_reservation *rsv,
        struct pmem2_map *map, struct pmem2_map **next_map);
int pmem2_vm_reservation_map_find_first(struct pmem2_vm_reservation *rsv,
        struct pmem2_map **first_map);
int pmem2_vm_reservation_map_find_last(struct pmem2_vm_reservation *rsv,
        struct pmem2_map **last_map);
\f[R]
.fi
.SH DESCRIPTION
.PP
Mappings are inserted to the virtual memory reservation in the order of
their virtual address space location.
First mapping represents the earliest mapping in the virtual address
space contained in a reservation, whereas the last mapping represents
the last one.
.PP
The \f[B]pmem2_vm_reservation_map_find\f[R]() function searches for the
earliest mapping, stored in the virtual memory reservation, intersecting
with the interval defined by \f[I]reserv_offset\f[R] and \f[I]len\f[R]
variables and returns it via \f[I]map_ptr\f[R] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_prev\f[R]() function searches for the
map previous to the provided \f[I]map\f[R] and returns it via provided
\f[I]prev_map\f[R] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_next\f[R]() function searches for the
map next after the provided \f[I]map\f[R] and returns it via
\f[I]next_map\f[R] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_first\f[R]() function searches for
the first map in the reservation and returns it via provided
\f[I]first_map\f[R] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_last\f[R]() function searches for the
last map in the reservation and returns it via provided
\f[I]last_map\f[R] variable.
# RETURN VALUE #
.PP
The \f[B]pmem2_vm_reservation_map_find\f[R](),
\f[B]pmem2_vm_reservation_map_find_prev\f[R](),
\f[B]pmem2_vm_reservation_map_find_next\f[R](),
\f[B]pmem2_vm_reservation_map_find_first\f[R]() and
\f[B]pmem2_vm_reservation_map_find_last\f[R]() return 0 on success or a
negative error on failure.
.PP
It passes an address to the found mapping via user provided
\f[I]map\f[R] pointer variable on success, otherwise it passes
\f[I]NULL\f[R] value when no mapping was found.
.SH ERRORS
.PP
The \f[B]pmem2_vm_reservation_map_find\f[R](),
\f[B]pmem2_vm_reservation_map_find_prev\f[R](),
\f[B]pmem2_vm_reservation_map_find_next\f[R](),
\f[B]pmem2_vm_reservation_map_find_first\f[R]() and
\f[B]pmem2_vm_reservation_map_find_last\f[R]() can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_NOT_FOUND\f[R] - no mapping found at the desirable
location of the reservation
.SH SEE ALSO
.PP
\f[B]libpmem2\f[R](7), and \f[B]<https://pmem.io>\f[R]