---
name: "toid_declare"
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/toid_declare"
---

# toid\_declare(3)

libpmemobj type safety mechanism

## NAME

**TOID\_DECLARE**(), **TOID\_DECLARE\_ROOT**(), **TOID**(), **TOID\_TYPE\_NUM**(), **TOID\_TYPE\_NUM\_OF**(), **TOID\_VALID**(), **OID\_INSTANCEOF**(), **TOID\_ASSIGN**(), **TOID\_IS\_NULL**(), **TOID\_EQUALS**(), **TOID\_TYPEOF**(), **TOID\_OFFSETOF**(), **DIRECT\_RW**(), **D\_RW**(), **DIRECT\_RO**(), **D\_RO**() - libpmemobj type safety mechanism

## SYNOPSIS

-

  ```
  #include <libpmemobj.h>
  TOID_DECLARE(TYPE, uint64_t type_num)
  TOID_DECLARE_ROOT(ROOT_TYPE)
  TOID(TYPE)
  TOID_TYPE_NUM(TYPE)
  TOID_TYPE_NUM_OF(TOID oid)
  TOID_VALID(TOID oid)
  OID_INSTANCEOF(PMEMoid oid, TYPE)
  TOID_ASSIGN(TOID o, VALUE)
  TOID_IS_NULL(TOID o)
  TOID_EQUALS(TOID lhs, TOID rhs)
  TOID_TYPEOF(TOID o)
  TOID_OFFSETOF(TOID o, FILED)
  DIRECT_RW(TOID oid)
  D_RW(TOID oid)
  DIRECT_RO(TOID oid)
  D_RO(TOID oid)
  ```

## DESCRIPTION

Operating on untyped object handles, as well as on direct untyped object pointers (*void\**), may be confusing and error-prone. To facilitate type safety, [**libpmemobj**(7)](/libpmemobj/7.md) defines a set of macros that provide static type enforcement, catching potential errors at compile time. For example, a compile-time error is generated when an attempt is made to assign a handle to an object of one type to the object handle variable of another type of object.

The **TOID\_DECLARE**() macro declares a typed *OID* of user-defined type *TYPE* and type number *type\_num*.

The **TOID\_DECLARE\_ROOT**() macro declares a typed *OID* of user-defined type *ROOT\_TYPE* and root object type number **POBJ\_ROOT\_TYPE\_NUM**.

The **TOID**() macro declares a handle to an object of type *TYPE*, where *TYPE* is the name of a user-defined structure. The typed *OID* must be declared first using the **TOID\_DECLARE**(), **TOID\_DECLARE\_ROOT**(), **POBJ\_LAYOUT\_TOID**(3) or **POBJ\_LAYOUT\_ROOT**(3) macros.

The **TOID\_TYPE\_NUM**() macro returns the type number of the type specified by *TYPE*.

The **TOID\_TYPE\_NUM\_OF**() macro returns the type number of the object specified by *oid*. The type number is read from the typed *OID*.

The **TOID\_VALID**() macro validates whether the type number stored in the object’s metadata is equal to the type number read from the typed *OID*.

The **OID\_INSTANCEOF**() macro checks whether the *oid* is of type *TYPE*.

The **TOID\_ASSIGN**() macro assigns the object handle *VALUE* to typed *OID* *o*.

The **TOID\_IS\_NULL**() macro evaluates to true if the object handle represented by *o* is **OID\_NULL**.

The **TOID\_EQUALS**() macro evaluates to true if both the *lhs* and *rhs* object handles reference the same persistent object.

The **TOID\_TYPEOF**() macro returns the type of the object handle represented by typed *OID* *o*.

The **TOID\_OFFSETOF**() macro returns the offset of the *FIELD* member from the start of the object represented by *o*.

The **DIRECT\_RW**() macro and its shortened form **D\_RW**() return a typed write pointer (*TYPE\**) to an object represented by *oid*. If *oid* is **OID\_NULL**, the macro evaluates to NULL.

The **DIRECT\_RO**() macro and its shortened form **D\_RO**() return a typed read-only (const) pointer (*TYPE\**) to an object represented by *oid*. If *oid* is **OID\_NULL**, the macro evaluates to NULL.

## SEE ALSO

**OID\_IS\_NULL**(3), **POBJ\_LAYOUT\_ROOT**(3), **POBJ\_LAYOUT\_TOID**(3), [**libpmemobj**(7)](/libpmemobj/7.md) and **\<https://pmem.io\>**