---
name: "pmemobj_tx_zalloc"
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_tx_alloc"
---

# pmemobj\_tx\_zalloc(3)

transactional object manipulation

Part of [pmemobj\_tx\_alloc(3)](/pmemobj_tx_alloc/3.md).

## NAME

**pmemobj\_tx\_alloc**(), **pmemobj\_tx\_zalloc**(), **pmemobj\_tx\_xalloc**(), **pmemobj\_tx\_realloc**(), **pmemobj\_tx\_zrealloc**(), **pmemobj\_tx\_strdup**(), **pmemobj\_tx\_xstrdup**(), **pmemobj\_tx\_wcsdup**(), **pmemobj\_tx\_xwcsdup**(), **pmemobj\_tx\_free**(), **pmemobj\_tx\_xfree**()

**TX\_NEW**(), **TX\_ALLOC**(), **TX\_ZNEW**(), **TX\_ZALLOC**(), **TX\_XALLOC**(), **TX\_REALLOC**(), **TX\_ZREALLOC**(), **TX\_STRDUP**(), **TX\_XSTRDUP**(), **TX\_WCSDUP**(), **TX\_XWCSDUP**(), **TX\_FREE**(), **TX\_XFREE**() - transactional object manipulation

## SYNOPSIS

-

  ```
  #include <libpmemobj.h>
  PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num);
  PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num);
  PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags);
  PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num);
  PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num);
  PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num);
  PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num);
  int pmemobj_tx_free(PMEMoid oid);
  int pmemobj_tx_xfree(PMEMoid oid, uint64_t flags);
  TX_NEW(TYPE)
  TX_ALLOC(TYPE, size_t size)
  TX_ZNEW(TYPE)
  TX_ZALLOC(TYPE, size_t size)
  TX_XALLOC(TYPE, size_t size, uint64_t flags)
  TX_REALLOC(TOID o, size_t size)
  TX_ZREALLOC(TOID o, size_t size)
  TX_STRDUP(const char *s, uint64_t type_num)
  TX_WCSDUP(const wchar_t *s, uint64_t type_num)
  TX_FREE(TOID o)
  TX_XFREE(TOID o, uint64_t flags)
  ```

## DESCRIPTION

The **pmemobj\_tx\_alloc**() function transactionally allocates a new object of given *size* and *type\_num*. In contrast to the non-transactional allocations, the objects are added to the internal object containers of given *type\_num* only after the transaction is committed, making the objects visible to the **POBJ\_FOREACH\_\***() macros. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_zalloc**() function transactionally allocates a new zeroed object of given *size* and *type\_num*. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_xalloc**() function transactionally allocates a new object of given *size* and *type\_num*. The *flags* argument is a bitmask of the following values:

- •

  **POBJ\_XALLOC\_ZERO** - zero the allocated object (equivalent of pmemobj\_tx\_zalloc)

- •

  **POBJ\_XALLOC\_NO\_FLUSH** - skip flush on commit (when application deals with flushing or uses pmemobj\_memcpy\_persist)

- •

  **POBJ\_CLASS\_ID(class\_id)** - allocate an object from the allocation class with id equal to *class\_id*

- •

  **POBJ\_ARENA\_ID(arena\_id)** - allocate an object from the arena specified by *arena\_id*. The arena must exist, otherwise, the behavior is undefined. If *arena\_id* is equal 0, then arena assigned to the current thread will be used.

- •

  **POBJ\_XALLOC\_NO\_ABORT** - if the function does not end successfully, do not abort the transaction.

This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_realloc**() function transactionally resizes an existing object to the given *size* and changes its type to *type\_num*. If *oid* is **OID\_NULL**, then the call is equivalent to *pmemobj\_tx\_alloc(pop, size, type\_num)*. If *size* is equal to zero and *oid* is not **OID\_NULL**, then the call is equivalent to *pmemobj\_tx\_free(oid)*. If the new size is larger than the old size, the added memory will *not* be initialized. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_zrealloc**() function transactionally resizes an existing object to the given *size* and changes its type to *type\_num*. If the new size is larger than the old size, the extended new space is zeroed. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_strdup**() function transactionally allocates a new object containing a duplicate of the string *s* and assigns it a type *type\_num*. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_xstrdup**() function behaves exactly the same as **pmemobj\_tx\_strdup**() when *flags* equals zero. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xalloc** section.

The **pmemobj\_tx\_wcsdup**() function transactionally allocates a new object containing a duplicate of the wide character string *s* and assigns it a type *type\_num*. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_xwcsdup**() function behaves exactly the same as **pmemobj\_tx\_wcsdup**() when *flags* equals zero. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xalloc** section.

The **pmemobj\_tx\_free**() function transactionally frees an existing object referenced by *oid*. This function must be called during **TX\_STAGE\_WORK**.

The **pmemobj\_tx\_xfree**() function behaves exactly the same as **pmemobj\_tx\_free**() when *flags* equals zero. *flags* is a bitmask of the following value:

- •

  **POBJ\_XFREE\_NO\_ABORT** - if the function does not end successfully, do not abort the transaction.

This function must be called during **TX\_STAGE\_WORK**.

The **TX\_NEW**() macro transactionally allocates a new object of given *TYPE* and assigns it a type number read from the typed *OID*. The allocation size is determined from the size of the user-defined structure *TYPE*. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_ALLOC**() macro transactionally allocates a new object of given *TYPE* and assigns it a type number read from the typed *OID*. The allocation size is passed by *size* parameter. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the stage is set to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_ZNEW**() macro transactionally allocates a new zeroed object of given *TYPE* and assigns it a type number read from the typed *OID*. The allocation size is determined from the size of the user-defined structure *TYPE*. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, stage changes to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_ZALLOC**() macro transactionally allocates a new zeroed object of given *TYPE* and assigns it a type number read from the typed *OID*. The allocation size is passed by *size* argument. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_XALLOC**() macro transactionally allocates a new object of given *TYPE* and assigns it a type number read from the typed *OID*. The allocation size is passed by *size* argument. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xalloc** section. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the **OID\_NULL** is returned, **errno** is set and when flags do not contain **POBJ\_XALLOC\_NO\_ABORT**, the transaction is aborted.

The **TX\_REALLOC**() macro transactionally resizes an existing object referenced by a handle *o* to the given *size*. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the reallocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_ZREALLOC**() macro transactionally resizes an existing object referenced by a handle *o* to the given *size*. If the new size is larger than the old size, the extended new space is zeroed. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the reallocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_STRDUP**() macro transactionally allocates a new object containing a duplicate of the string *s* and assigns it type *type\_num*. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_XSTRDUP**() macro transactionally allocates a new object containing a duplicate of the string *s* and assigns it type *type\_num*. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xalloc** section. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the **OID\_NULL** is returned, **errno** is set and when flags do not contain **POBJ\_XALLOC\_NO\_ABORT**, the transaction is aborted.

The **TX\_WCSDUP**() macro transactionally allocates a new object containing a duplicate of the wide character string *s* and assigns it a type *type\_num*. If successful and called during **TX\_STAGE\_WORK**, it returns a handle to the newly allocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately.

The **TX\_XWCSDUP**() macro transactionally allocates a new object containing a duplicate of the wide character string *s* and assigns it a type *type\_num*. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xalloc** section. If successful and called during **TX\_STAGE\_WORK** it returns a handle to the newly allocated object. Otherwise, the **OID\_NULL** is returned, **errno** is set and when flags do not contain **POBJ\_XALLOC\_NO\_ABORT**, the transaction is aborted.

The **TX\_FREE**() macro transactionally frees the memory space represented by an object handle *o*. If *o* is **OID\_NULL**, no operation is performed. If successful and called during **TX\_STAGE\_WORK**, **TX\_FREE**() returns 0. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT** and *errno* is set appropriately.

The **TX\_XFREE**() macro transactionally frees the memory space represented by an object handle *o*. If *o* is **OID\_NULL**, no operation is performed. The *flags* argument is a bitmask of values described in **pmemobj\_tx\_xfree** section. If successful and called during **TX\_STAGE\_WORK**, **TX\_FREE**() returns 0. Otherwise, the error number is returned, **errno** is set and when flags do not contain **POBJ\_XFREE\_NO\_ABORT**, the transaction is aborted.

## RETURN VALUE

On success, the **pmemobj\_tx\_alloc**(), **pmemobj\_tx\_zalloc**(), **pmemobj\_tx\_strdup**() and **pmemobj\_tx\_wcsdup**() functions return a handle to the newly allocated object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately. If *size* equals 0, **OID\_NULL** is returned and *errno* is set appropriately.

On success, the **pmemobj\_tx\_xalloc**(), **pmemobj\_tx\_xstrdup**() and **pmemobj\_tx\_xwcsdup**() functions return a handle to the newly allocated object. Otherwise, the **OID\_NULL** is returned, **errno** is set and when flags do not contain **POBJ\_XALLOC\_NO\_ABORT**, the transaction is aborted.

On success, **pmemobj\_tx\_realloc**() and **pmemobj\_tx\_zrealloc**() return a handle to the resized object. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **OID\_NULL** is returned, and *errno* is set appropriately. Note that the object handle value may change as a result of reallocation.

On success, **pmemobj\_tx\_free**() returns 0. Otherwise, the stage is changed to **TX\_STAGE\_ONABORT**, **errno** is set appropriately and transaction is aborted

On success **pmemobj\_tx\_xfree**() returns 0. Otherwise, the error number is returned, **errno** is set and when flags do not contain **POBJ\_XFREE\_NO\_ABORT**, the transaction is aborted.

## SEE ALSO

[**pmemobj\_tx\_add\_range**(3)](/pmemobj_tx_add_range/3.md), [**pmemobj\_tx\_begin**(3)](/pmemobj_tx_begin/3.md), [**libpmemobj**(7)](/libpmemobj/7.md) and **\<https://pmem.io\>**