hwlocality_diff(3)

📦

version 2.15.0 · 13 versions

💅 hwlocality_diff(3) — Topology differences 💅

okay bestie, welcome to hwlocality_diff(3) from the Library Functions Manual 🫶. this page is literally all about topology differences, and we're gonna keep every flag, every enum, every return code, and every little caveat. the vibes are cute; the facts are sacred. periodt. ✨

🎀 NAME 🎀

hwlocality_diff — Topology differences. that's the whole name section, short and iconic. 💅

✨ SYNOPSIS ✨

lowkey the synopsis is a whole lil ecosystem. here's the exact cast, no cap, fr fr — and not me triple-checking every token, okay maybe me 😭:

🧸 Data Structures

union hwloc_topology_diff_obj_attr_u
union hwloc_topology_diff_u

🧚 Typedefs

typedef enum hwloc_topology_diff_obj_attr_type_e
    hwloc_topology_diff_obj_attr_type_t
typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
typedef union hwloc_topology_diff_u * hwloc_topology_diff_t

🌈 Enumerations

enum hwloc_topology_diff_obj_attr_type_e {
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE,
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    }
enum hwloc_topology_diff_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,
    HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX }
enum hwloc_topology_diff_apply_flags_e {
    HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE }

🛠️ Functions

int hwloc_topology_diff_build (hwloc_topology_t topology,
    hwloc_topology_t newtopology, unsigned long flags,
    hwloc_topology_diff_t *diff)
int hwloc_topology_diff_apply (hwloc_topology_t topology,
    hwloc_topology_diff_t diff, unsigned long flags)
int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
int hwloc_topology_diff_load_xml (const char *xmlpath,
    hwloc_topology_diff_t *diff, char **refname)
int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const
    char *refname, const char *xmlpath)
int hwloc_topology_diff_load_xmlbuffer (const char *xmlbuffer, int
    buflen, hwloc_topology_diff_t *diff, char **refname)
int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff,
    const char *refname, char **xmlbuffer, int *buflen)

🔥 DETAILED DESCRIPTION 🔥

so picture this: your app is out here manipulating a bunch of super similar topologies—maybe one for each node of a homogeneous cluster—and you're like "bestie, this is a lot of memory footprint". same. that's why you might want to compress those topologies. 💖

this file gives you a way to manipulate the difference between topologies and export/import it to/from XML. so the compression glow-up works like this: you store one topology entirely, and the others are only described by their differences with that former topology. when you actually need the real topology, you reconstruct it by applying the precomputed difference to the reference topology. main character reconstruction energy. ✨

highkey important vibe check: this interface targets very similar nodes. only very simple differences between topologies are actually supported—like a change in the memory size, the name of the object, or some info attribute. more complex differences, such as adding or removing objects, cannot be represented in the difference structures and therefore return errors. differences between object sets or topology-wide allowed sets cannot be represented either. so if you were hoping for chaos, not today. 💀

what that means practically: there is no need to apply the difference when you're looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects. however, the difference must be applied when you're looking at object attributes such as the name, the memory size or info attributes. iykyk. 🫶

🎀 TYPEDEF DOCUMENTATION 🎀

`hwloc_topology_diff_obj_attr_type_t`

typedef enum hwloc_topology_diff_obj_attr_type_e
    hwloc_topology_diff_obj_attr_type_t

type of one object attribute difference. serving type-realness. obsessed. 💅

`hwloc_topology_diff_t`

typedef union hwloc_topology_diff_u * hwloc_topology_diff_t

one element of a difference list between two topologies. iconic pointer moment.

`hwloc_topology_diff_type_t`

typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t

type of one element of a difference list. periodt.

🌈 ENUMERATION TYPE DOCUMENTATION 🌈

`enum hwloc_topology_diff_apply_flags_e`

flags to be given to hwloc_topology_diff_apply(). yes bestie, these are the apply flags.

Enumerator

HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE — apply topology diff in reverse direction. backwards slay. 🔄

`enum hwloc_topology_diff_obj_attr_type_e`

type of one object attribute difference.

Enumerators

HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE — the object local memory is modified. the union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s (and the index field is ignored).
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME — the object name is modified. the union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s (and the name field is ignored).
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO — the value of an info attribute is modified. the union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s.

`enum hwloc_topology_diff_type_e`

type of one element of a difference list.

Enumerators

HWLOC_TOPOLOGY_DIFF_OBJ_ATTR — an object attribute was changed. the union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.
HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX — the difference is too complex, it cannot be represented. the difference below this object has not been checked. hwloc_topology_diff_build() will return 1. the union is a hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s.

🛠️ FUNCTION DOCUMENTATION 🛠️

`hwloc_topology_diff_apply`

int hwloc_topology_diff_apply (hwloc_topology_t topology,
    hwloc_topology_diff_t diff, unsigned long flags)

apply a topology diff to an existing topology. flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

the new topology is modified in place. hwloc_topology_dup() may be used to duplicate it before patching. so if you need the original untouched, duplicate first, bestie.

if the difference cannot be applied entirely, all previous applied elements are unapplied before returning. it's giving cleanup on aisle diff.

Returns

0 on success.
-N if applying the difference failed while trying to apply the N-th part of the difference. for instance -1 is returned if the very first difference element could not be applied.

`hwloc_topology_diff_build`

int hwloc_topology_diff_build (hwloc_topology_t topology, hwloc_topology_t
    newtopology, unsigned long flags, hwloc_topology_diff_t * diff)

compute the difference between 2 topologies. the difference is stored as a list of hwloc_topology_diff_t entries starting at diff. it is computed by doing a depth-first traversal of both topology trees simultaneously. two trees, one vibe check. 🌳🌳

if the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. the computation of the diff does not continue below these objects. so each such diff entry means that the difference between two subtrees could not be computed.

Returns

0 if the difference can be represented properly.
0 with diff pointing to NULL if there is no difference between the topologies.
1 if the difference is too complex (see above). some entries in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
-1 on any other error.

Note

flags is currently not used. it should be 0.
the output diff has to be freed with hwloc_topology_diff_destroy().
the output diff can only be exported to XML or passed to hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
the output diff may be modified by removing some entries from the list. the removed entries should be freed by passing them to hwloc_topology_diff_destroy() (possible as another list).

`hwloc_topology_diff_destroy`

int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)

destroy a list of topology differences. that's it. that's the function. clean, simple, ate. 💅

Returns

0.

`hwloc_topology_diff_export_xml`

int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const char *
    refname, const char * xmlpath)

export a list of topology differences to a XML file. if not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. this identifier is usually the name of the other XML file that contains the reference topology. this attribute is given back when reading the diff from XML. cute lil round trip. 🔁

Returns

0 on success, -1 on error.

`hwloc_topology_diff_export_xmlbuffer`

int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff, const
    char * refname, char ** xmlbuffer, int * buflen)

export a list of topology differences to a XML buffer. if not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. this identifier is usually the name of the other XML file that contains the reference topology. this attribute is given back when reading the diff from XML.

the returned buffer ends with a \0 that is included in the returned length. so yes, the null terminator counts, no cap. 🫶

Returns

0 on success, -1 on error.

Note

the XML buffer should later be freed with hwloc_free_xmlbuffer().

`hwloc_topology_diff_load_xml`

int hwloc_topology_diff_load_xml (const char * xmlpath,
    hwloc_topology_diff_t * diff, char ** refname)

load a list of topology differences from a XML file. if not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. this identifier is usually the name of the other XML file that contains the reference topology.

Returns

0 on success, -1 on error.

Note

the pointer returned in refname should later be freed by the caller.

`hwloc_topology_diff_load_xmlbuffer`

int hwloc_topology_diff_load_xmlbuffer (const char * xmlbuffer, int buflen,
    hwloc_topology_diff_t * diff, char ** refname)

load a list of topology differences from a XML buffer. build a list of differences from the XML memory buffer given at xmlbuffer and of length buflen (including an ending \0). this buffer may have been filled earlier with hwloc_topology_diff_export_xmlbuffer().

if not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. this identifier is usually the name of the other XML file that contains the reference topology.

Returns

0 on success, -1 on error.

Note

the pointer returned in refname should later be freed by the caller.

🌸 AUTHOR 🌸

generated automatically by Doxygen for Hardware Locality (hwloc) from the source code. yes, the docs wrote themselves (not really, but that's the vibe). 💖

source/version sign-off, bestie: Hardware Locality (hwloc), Version 2.15.0, and the page name hwlocality_diff(3). the original footer doesn't list a date, so i'm not inventing one—mystery-era footer, periodt. 💅✨

📦 where this page comes from

arch rolling: hwloc 2.15.0-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms