---
name: "hwlocality_helper_traversal_basic"
section: "3"
platform: "linux"
package: "libhwloc-doc"
version: "1.4.1-4"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/hwlocality_helper_traversal_basic"
---

# hwlocality\_helper\_traversal\_basic(3)

## NAME

Basic Traversal Helpers -

### Functions

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

## 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 socket has fewer caches than its peers.

## Function Documentation

### static inline hwloc\_obj\_t hwloc\_get\_ancestor\_obj\_by\_depth (hwloc\_topology\_t topology, unsigneddepth, hwloc\_obj\_tobj)` [static]`

Returns the ancestor object of `obj` at depth `depth`.

### static inline hwloc\_obj\_t hwloc\_get\_ancestor\_obj\_by\_type (hwloc\_topology\_t topology, hwloc\_obj\_type\_ttype, hwloc\_obj\_tobj)` [static]`

Returns the ancestor object of `obj` with type `type`.

### static inline hwloc\_obj\_t hwloc\_get\_common\_ancestor\_obj (hwloc\_topology\_t topology, hwloc\_obj\_tobj1, hwloc\_obj\_tobj2)` [static]`

Returns the common parent object to objects lvl1 and lvl2.

### static inline hwloc\_obj\_t hwloc\_get\_next\_child (hwloc\_topology\_t topology, hwloc\_obj\_tparent, hwloc\_obj\_tprev)` [static]`

Return the next child. If `prev` is `NULL`, return the first child.

### static inline hwloc\_obj\_t hwloc\_get\_next\_obj\_by\_depth (hwloc\_topology\_ttopology, unsigneddepth, hwloc\_obj\_tprev)` [static]`

Returns the next object at depth `depth`. If `prev` is `NULL`, return the first object at depth `depth`.

### static inline hwloc\_obj\_t hwloc\_get\_next\_obj\_by\_type (hwloc\_topology\_ttopology, hwloc\_obj\_type\_ttype, hwloc\_obj\_tprev)` [static]`

Returns the next object of type `type`. If `prev` is `NULL`, return the first object at type `type`. If there are multiple or no depth for given type, return `NULL` and let the caller fallback to **hwloc\_get\_next\_obj\_by\_depth()**.

### static inline hwloc\_obj\_t hwloc\_get\_pu\_obj\_by\_os\_index (hwloc\_topology\_ttopology, unsignedos\_index)` [static]`

Returns the object of type **HWLOC\_OBJ\_PU** with `os_index`. **Note:**

The `os_index` field of object should most of the times only be used for pretty-printing purpose. Type **HWLOC\_OBJ\_PU** is the only case where `os_index` could actually be useful, when manually binding to processors. However, using CPU sets to hide this complexity should often be preferred.

### static inline hwloc\_obj\_t hwloc\_get\_root\_obj (hwloc\_topology\_ttopology)` [static]`

Returns the top-object of the topology-tree. Its type is typically **HWLOC\_OBJ\_MACHINE** but it could be different for complex topologies. This function replaces the old deprecated hwloc\_get\_system\_obj().

### static inline int hwloc\_obj\_is\_in\_subtree (hwloc\_topology\_t topology, hwloc\_obj\_tobj, hwloc\_obj\_tsubtree\_root)` [static]`

Returns true if `obj` is inside the subtree beginning with `subtree_root`. **Note:**

This function assumes that both `obj` and `subtree_root` have a `cpuset`.

## Author

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