.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_VM_RESERVATION_MAP_FIND" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[](),
\f[B]pmem2_vm_reservation_map_find_prev\f[](),
\f[B]pmem2_vm_reservation_map_find_next\f[](),
\f[B]pmem2_vm_reservation_map_find_first\f[]() and
\f[B]pmem2_vm_reservation_map_find_last\f[]() \- 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[]
.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[]() function searches for the
earliest mapping, stored in the virtual memory reservation, intersecting
with the interval defined by \f[I]reserv_offset\f[] and \f[I]len\f[]
variables and returns it via \f[I]map_ptr\f[] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_prev\f[]() function searches for the
map previous to the provided \f[I]map\f[] and returns it via provided
\f[I]prev_map\f[] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_next\f[]() function searches for the
map next after the provided \f[I]map\f[] and returns it via
\f[I]next_map\f[] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_first\f[]() function searches for the
first map in the reservation and returns it via provided
\f[I]first_map\f[] variable.
.PP
\f[B]pmem2_vm_reservation_map_find_last\f[]() function searches for the
last map in the reservation and returns it via provided
\f[I]last_map\f[] variable.
# RETURN VALUE #
.PP
The \f[B]pmem2_vm_reservation_map_find\f[](),
\f[B]pmem2_vm_reservation_map_find_prev\f[](),
\f[B]pmem2_vm_reservation_map_find_next\f[](),
\f[B]pmem2_vm_reservation_map_find_first\f[]() and
\f[B]pmem2_vm_reservation_map_find_last\f[]() 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[]
pointer variable on success, otherwise it passes \f[I]NULL\f[] value
when no mapping was found.
.SH ERRORS
.PP
The \f[B]pmem2_vm_reservation_map_find\f[](),
\f[B]pmem2_vm_reservation_map_find_prev\f[](),
\f[B]pmem2_vm_reservation_map_find_next\f[](),
\f[B]pmem2_vm_reservation_map_find_first\f[]() and
\f[B]pmem2_vm_reservation_map_find_last\f[]() can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_NOT_FOUND\f[] \- no mapping found at the desirable
location of the reservation
.SH SEE ALSO
.PP
\f[B]libpmem2\f[](7), and \f[B]<https://pmem.io>\f[]