---
name: "pmemobj_first"
section: "3"
platform: "linux"
package: "libpmemobj-dev"
version: "1.13.1-1.1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pmemobj_first"
---

# pmemobj\_first(3)

pmemobj container operations

## NAME

**pmemobj\_first**(), **pmemobj\_next**(), **POBJ\_FIRST**(), **POBJ\_FIRST\_TYPE\_NUM**(), **POBJ\_NEXT**(), **POBJ\_NEXT\_TYPE\_NUM**(), **POBJ\_FOREACH**(), **POBJ\_FOREACH\_SAFE**(), **POBJ\_FOREACH\_TYPE**(), **POBJ\_FOREACH\_SAFE\_TYPE**() - pmemobj container operations

## SYNOPSIS

-

  ```
  #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)
  ```

## DESCRIPTION

The [**libpmemobj**(7)](/libpmemobj/7.md) 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.

The **pmemobj\_first**() function returns the first object from the pool.

The **POBJ\_FIRST**() macro returns the first object from the pool of the type specified by *TYPE*.

The **POBJ\_FIRST\_TYPE\_NUM**() macro returns the first object from the pool of the type specified by *type\_num*.

The **pmemobj\_next**() function returns the next object from the pool.

The **POBJ\_NEXT**() macro returns the next object of the same type as the object referenced by *oid*.

The **POBJ\_NEXT\_TYPE\_NUM**() macro returns the next object of the same type number as the object referenced by *oid*.

The following four macros provide a more convenient way to iterate through the internal collections, performing a specific operation on each object.

The **POBJ\_FOREACH**() macro performs a specific operation on each allocated object stored in the persistent memory pool *pop*. It traverses the internal collection of all the objects, assigning a handle to each element in turn to *varoid*.

The **POBJ\_FOREACH\_TYPE**() macro performs a specific operation on each allocated object stored in the persistent memory pool *pop* that has the same type as *var*. It traverses the internal collection of all the objects of the specified type, assigning a handle to each element in turn to *var*.

The macros **POBJ\_FOREACH\_SAFE**() and **POBJ\_FOREACH\_SAFE\_TYPE**() work in a similar fashion as **POBJ\_FOREACH**() and **POBJ\_FOREACH\_TYPE**(), 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 *nvaroid* or *nvar*, respectively. This allows safe deletion of selected objects while iterating through the collection.

## RETURN VALUE

**pmemobj\_first**() returns the first object from the pool, or, if the pool is empty, **OID\_NULL**.

**pmemobj\_next**() returns the next object from the pool. If the object referenced by *oid* is the last object in the collection, or if *oid* is *OID\_NULL*, **pmemobj\_next**() returns **OID\_NULL**.

## SEE ALSO

[**libpmemobj**(7)](/libpmemobj/7.md) and **\<https://pmem.io\>**