.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEMOBJ_FIRST" "3" "2022-08-25" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2018, Intel Corporation
.SH NAME
.PP
\f[B]pmemobj_first\f[](), \f[B]pmemobj_next\f[](),
\f[B]POBJ_FIRST\f[](), \f[B]POBJ_FIRST_TYPE_NUM\f[](),
\f[B]POBJ_NEXT\f[](), \f[B]POBJ_NEXT_TYPE_NUM\f[](),
\f[B]POBJ_FOREACH\f[](), \f[B]POBJ_FOREACH_SAFE\f[](),
\f[B]POBJ_FOREACH_TYPE\f[](), \f[B]POBJ_FOREACH_SAFE_TYPE\f[]() \-
pmemobj container operations
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmemobj.h>

PMEMoid\ pmemobj_first(PMEMobjpool\ *pop);
PMEMoid\ pmemobj_next(PMEMoid\ oid);

POBJ_FIRST(PMEMobjpool\ *pop,\ TYPE)
POBJ_FIRST_TYPE_NUM(PMEMobjpool\ *pop,\ uint64_t\ type_num)
POBJ_NEXT(TOID\ oid)
POBJ_NEXT_TYPE_NUM(PMEMoid\ oid)

POBJ_FOREACH(PMEMobjpool\ *pop,\ PMEMoid\ varoid)
POBJ_FOREACH_SAFE(PMEMobjpool\ *pop,\ PMEMoid\ varoid,\ PMEMoid\ nvaroid)
POBJ_FOREACH_TYPE(PMEMobjpool\ *pop,\ TOID\ var)
POBJ_FOREACH_SAFE_TYPE(PMEMobjpool\ *pop,\ TOID\ var,\ TOID\ nvar)
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]libpmemobj\f[](7) container operations provide a mechanism that
allows iteration through the internal object collection, either looking
for a specific object, or performing a specific operation on each object
of a given type.
Software should not make any assumptions about the order of the objects
in the internal object containers.
.PP
The \f[B]pmemobj_first\f[]() function returns the first object from the
pool.
.PP
The \f[B]POBJ_FIRST\f[]() macro returns the first object from the pool
of the type specified by \f[I]TYPE\f[].
.PP
The \f[B]POBJ_FIRST_TYPE_NUM\f[]() macro returns the first object from
the pool of the type specified by \f[I]type_num\f[].
.PP
The \f[B]pmemobj_next\f[]() function returns the next object from the
pool.
.PP
The \f[B]POBJ_NEXT\f[]() macro returns the next object of the same type
as the object referenced by \f[I]oid\f[].
.PP
The \f[B]POBJ_NEXT_TYPE_NUM\f[]() macro returns the next object of the
same type number as the object referenced by \f[I]oid\f[].
.PP
The following four macros provide a more convenient way to iterate
through the internal collections, performing a specific operation on
each object.
.PP
The \f[B]POBJ_FOREACH\f[]() macro performs a specific operation on each
allocated object stored in the persistent memory pool \f[I]pop\f[].
It traverses the internal collection of all the objects, assigning a
handle to each element in turn to \f[I]varoid\f[].
.PP
The \f[B]POBJ_FOREACH_TYPE\f[]() macro performs a specific operation on
each allocated object stored in the persistent memory pool \f[I]pop\f[]
that has the same type as \f[I]var\f[].
It traverses the internal collection of all the objects of the specified
type, assigning a handle to each element in turn to \f[I]var\f[].
.PP
The macros \f[B]POBJ_FOREACH_SAFE\f[]() and
\f[B]POBJ_FOREACH_SAFE_TYPE\f[]() work in a similar fashion as
\f[B]POBJ_FOREACH\f[]() and \f[B]POBJ_FOREACH_TYPE\f[](), except that
prior to performing the operation on the object, they preserve a handle
to the next object in the collection by assigning it to \f[I]nvaroid\f[]
or \f[I]nvar\f[], respectively.
This allows safe deletion of selected objects while iterating through
the collection.
.SH RETURN VALUE
.PP
\f[B]pmemobj_first\f[]() returns the first object from the pool, or, if
the pool is empty, \f[B]OID_NULL\f[].
.PP
\f[B]pmemobj_next\f[]() returns the next object from the pool.
If the object referenced by \f[I]oid\f[] is the last object in the
collection, or if \f[I]oid\f[] is \f[I]OID_NULL\f[],
\f[B]pmemobj_next\f[]() returns \f[B]OID_NULL\f[].
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[](7) and \f[B]<https://pmem.io>\f[]