---
name: "hwloc_get_common_ancestor_obj"
section: "3"
platform: "linux"
package: "hwloc"
version: "2.15.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hwlocality_helper_ancestors"
---

# hwloc\_get\_common\_ancestor\_obj(3)

Looking at Ancestor and Child Objects

Part of [hwlocality\_helper\_ancestors(3)](/hwlocality_helper_ancestors/3.md).

## NAME

hwlocality\_helper\_ancestors - Looking at Ancestor and Child Objects

## SYNOPSIS

### Functions

**hwloc\_obj\_t** **hwloc\_get\_ancestor\_obj\_by\_depth** (**hwloc\_topology\_t** topology, int depth, **hwloc\_obj\_t** obj)\
 **hwloc\_obj\_t** **hwloc\_get\_ancestor\_obj\_by\_type** (**hwloc\_topology\_t** topology, **hwloc\_obj\_type\_t** type, **hwloc\_obj\_t** obj)\
 **hwloc\_obj\_t** **hwloc\_get\_common\_ancestor\_obj** (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** obj1, **hwloc\_obj\_t** obj2)\
 int **hwloc\_obj\_is\_in\_subtree** (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** obj, **hwloc\_obj\_t** subtree\_root)\
 **hwloc\_obj\_t** **hwloc\_get\_next\_child** (**hwloc\_topology\_t** topology, **hwloc\_obj\_t** parent, **hwloc\_obj\_t** prev)\

## Detailed Description

Be sure to see the figure in **Terms and Definitions** that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

## Function Documentation

### hwloc\_obj\_t hwloc\_get\_ancestor\_obj\_by\_depth (hwloc\_topology\_t topology, int depth, hwloc\_obj\_t obj) \[inline\]

Returns the ancestor object of obj at depth depth.

**Returns**

the ancestor if any.

NULL if no such ancestor exists.

**Note**

depth should not be the depth of PU or NUMA objects since they are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate level depth, such as the depth of Packages, Cores, or Caches.

### hwloc\_obj\_t hwloc\_get\_ancestor\_obj\_by\_type (hwloc\_topology\_t topology, hwloc\_obj\_type\_t type, hwloc\_obj\_t obj) \[inline\]

Returns the ancestor object of obj with type type.

**Returns**

the ancestor if any.

NULL if no such ancestor exists.

**Note**

if multiple matching ancestors exist (e.g. multiple levels of **HWLOC\_OBJ\_GROUP**) the lowest one is returned.

type should not be **HWLOC\_OBJ\_PU** or **HWLOC\_OBJ\_NUMANODE** since these objects are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate object type, such as **HWLOC\_OBJ\_PACKAGE**, **HWLOC\_OBJ\_CORE**, etc.

### hwloc\_obj\_t hwloc\_get\_common\_ancestor\_obj (hwloc\_topology\_t topology, hwloc\_obj\_t obj1, hwloc\_obj\_t obj2) \[inline\]

Returns the common parent object to objects obj1 and obj2.

**Returns**

the common ancestor.

**Note**

This function cannot return NULL.

### hwloc\_obj\_t hwloc\_get\_next\_child (hwloc\_topology\_t topology, hwloc\_obj\_t parent, hwloc\_obj\_t prev) \[inline\]

Return the next child. Return the next child among the normal children list, then among the memory children list, then among the I/O children list, then among the Misc children list.

**Returns**

the first child if prev is NULL.

the next child if prev is not NULL.

NULL when there is no next child.

### int hwloc\_obj\_is\_in\_subtree (hwloc\_topology\_t topology, hwloc\_obj\_t obj, hwloc\_obj\_t subtree\_root) \[inline\]

Returns true if obj is inside the subtree beginning with ancestor object subtree\_root.

**Returns**

1 is the object is in the subtree, 0 otherwise.

**Note**

This function cannot work if obj and subtree\_root objects do not have CPU sets (I/O or Misc objects).

## Author

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.