---
name: "hwlocality_distances_add"
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_distances_add"
---

# hwlocality\_distances\_add(3)

Add distances between objects

## NAME

hwlocality\_distances\_add - Add distances between objects

## SYNOPSIS

### Typedefs

typedef void \* **hwloc\_distances\_add\_handle\_t**\

### Enumerations

enum **hwloc\_distances\_add\_flag\_e** { **HWLOC\_DISTANCES\_ADD\_FLAG\_GROUP**, **HWLOC\_DISTANCES\_ADD\_FLAG\_GROUP\_INACCURATE** }\

### Functions

**hwloc\_distances\_add\_handle\_t** **hwloc\_distances\_add\_create** (**hwloc\_topology\_t** topology, const char \*name, unsigned long kind, unsigned long flags)\
 int **hwloc\_distances\_add\_values** (**hwloc\_topology\_t** topology, **hwloc\_distances\_add\_handle\_t** handle, unsigned nbobjs, **hwloc\_obj\_t** \*objs, hwloc\_uint64\_t \*values, unsigned long flags)\
 int **hwloc\_distances\_add\_commit** (**hwloc\_topology\_t** topology, **hwloc\_distances\_add\_handle\_t** handle, unsigned long flags)\

## Detailed Description

The usual way to add distances is:

```
hwloc_distances_add_handle_t handle;
int err = -1;
handle = hwloc_distances_add_create(topology, "name", kind, 0);
if (handle) {
  err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
  if (!err)
    err = hwloc_distances_add_commit(topology, handle, flags);
}
```

 If err is 0 at the end, then addition was successful.

## Typedef Documentation

### typedef void\* hwloc\_distances\_add\_handle\_t

Handle to a new distances structure during its addition to the topology.

## Enumeration Type Documentation

### enum hwloc\_distances\_add\_flag\_e

Flags for adding a new distances to a topology.

**Enumerator**

- ***HWLOC\_DISTANCES\_ADD\_FLAG\_GROUP***

  Try to group objects based on the newly provided distance information. Grouping is only performed when the distances structure contains latencies, and when all objects are of the same type.

- ***HWLOC\_DISTANCES\_ADD\_FLAG\_GROUP\_INACCURATE***

  If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC\_GROUPING\_ACCURACY environment variable (see **Environment variables for tweaking hwloc heuristics**).

## Function Documentation

### int hwloc\_distances\_add\_commit (hwloc\_topology\_t topology, hwloc\_distances\_add\_handle\_t handle, unsigned long flags)

Commit a new distances structure. This function finalizes the distances structure and inserts in it the topology.

Parameter handle was previously returned by **hwloc\_distances\_add\_create()**. Then objects and values were specified with **hwloc\_distances\_add\_values()**.

flags configures the behavior of the function using an optional OR'ed set of **hwloc\_distances\_add\_flag\_e**. It may be used to request the grouping of existing objects based on distances.

On error, the temporary distances structure and its content are destroyed.

**Returns**

0 on success.

\-1 on error.

### hwloc\_distances\_add\_handle\_t hwloc\_distances\_add\_create (hwloc\_topology\_t topology, const char \* name, unsigned long kind, unsigned long flags)

Create a new empty distances structure. Create an empty distances structure to be filled with **hwloc\_distances\_add\_values()** and then committed with **hwloc\_distances\_add\_commit()**.

Parameter name is optional, it may be NULL. Otherwise, it will be copied internally and may later be freed by the caller.

kind specifies the kind of distance as a OR'ed set of **hwloc\_distances\_kind\_e**. Only one kind of meaning and one kind of provenance may be given if appropriate (e.g. **HWLOC\_DISTANCES\_KIND\_MEANS\_BANDWIDTH** and **HWLOC\_DISTANCES\_KIND\_FROM\_USER**). Kind **HWLOC\_DISTANCES\_KIND\_HETEROGENEOUS\_TYPES** will be automatically set according to objects having different types in **hwloc\_distances\_add\_values()**.

flags must be 0 for now.

**Returns**

A **hwloc\_distances\_add\_handle\_t** that should then be passed to **hwloc\_distances\_add\_values()** and **hwloc\_distances\_add\_commit()**.

NULL on error.

### int hwloc\_distances\_add\_values (hwloc\_topology\_t topology, hwloc\_distances\_add\_handle\_t handle, unsigned nbobjs, hwloc\_obj\_t \* objs, hwloc\_uint64\_t \* values, unsigned long flags)

Specify the objects and values in a new empty distances structure. Specify the objects and values for a new distances structure that was returned as a handle by **hwloc\_distances\_add\_create()**. The structure must then be committed with **hwloc\_distances\_add\_commit()**.

The number of objects is nbobjs and the array of objects is objs. Distance values are stored as a one-dimension array in values. The distance from object i to object j is in slot i\*nbobjs+j.

nbobjs must be at least 2.

Arrays objs and values will be copied internally, they may later be freed by the caller.

On error, the temporary distances structure and its content are destroyed.

flags must be 0 for now.

**Returns**

0 on success.

\-1 on error.

## Author

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