Hardware Locality (hwloc)  master-20230831.0905.git364652f8b
Enumerations | Functions
Consulting and Adding Info Attributes

Enumerations

enum  hwloc_modify_infos_op_e { HWLOC_MODIFY_INFOS_OP_ADD, HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE, HWLOC_MODIFY_INFOS_OP_REPLACE, HWLOC_MODIFY_INFOS_OP_REMOVE }
 

Functions

static const char * hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
 
static const char * hwloc_get_info_by_name (struct hwloc_infos_s *infos, const char *name)
 
int hwloc_modify_infos (struct hwloc_infos_s *infos, unsigned long operation, const char *name, const char *value)
 
static int hwloc_obj_add_info (hwloc_obj_t obj, const char *name, const char *value)
 
struct hwloc_infos_shwloc_topology_get_infos (hwloc_topology_t topology)
 

Detailed Description

Enumeration Type Documentation

◆ hwloc_modify_infos_op_e

Operations given to hwloc_modify_infos().

Enumerator
HWLOC_MODIFY_INFOS_OP_ADD 

Add a new info attribute with the given name and value.

Returns
1 if the pair was successfully added.
HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE 

Add a new info attribute with the given name and value only if that pair doesn't exist yet.

Returns
1 if the pair was successfully added.
0 if the pair already existed.
HWLOC_MODIFY_INFOS_OP_REPLACE 

Replace existing info attributes with the given name, with a single attribute with the given name and value. If no existing pair matches, add a new one. If multiple pairs match, only one remains.

Returns
1 if the pair was added.
N+1 if N existing pairs were replaced by one.
HWLOC_MODIFY_INFOS_OP_REMOVE 

Remove existing info attributes that matches the given name and/or value if not NULL.

Returns
N if N existing pairs were removed.
0 if no matching pair was found and removed.

Function Documentation

◆ hwloc_get_info_by_name()

static const char* hwloc_get_info_by_name ( struct hwloc_infos_s infos,
const char *  name 
)
inlinestatic

Search the given name in the array of infos and return the corresponding value.

If multiple info attributes match the given name, only the first one is returned.

Returns
A pointer to the value string if it exists.
NULL if no such info attribute exists.
Note
The string should not be freed by the caller, it belongs to the hwloc library.

◆ hwloc_modify_infos()

int hwloc_modify_infos ( struct hwloc_infos_s infos,
unsigned long  operation,
const char *  name,
const char *  value 
)

Modify an array of info attributes.

operation is a single value among hwloc_modify_infos_op_e.

If adding (HWLOC_MODIFY_INFOS_OP_ADD or HWLOC_MODIFY_INFOS_OP_ADD_UNIQUE) or replacing (HWLOC_MODIFY_INFOS_OP_REPLACE) an info attribute, name and value cannot be NULL. The input strings are copied before being added in the object infos.

If removing existing info pairs (HWLOC_MODIFY_INFOS_OP_REMOVE), name and/or value may be non NULL to specify which pair(s) to remove. If both name and value are NULL, all pairs are removed.

Returns
a positive value if some info attributes were added/modified/removed (see the documentation of each operation).
0 if the request was valid but no change was applied.
-1 on error.
Note
If value contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.

◆ hwloc_obj_add_info()

static int hwloc_obj_add_info ( hwloc_obj_t  obj,
const char *  name,
const char *  value 
)
inlinestatic

Add the given name and value pair to the given object info attributes.

The info pair is appended to the existing info array even if another pair with the same name already exists. See hwloc_modify_infos() for a more flexible variant.

The input strings are copied before being added in the object infos.

name and value must be non NULL.

Returns
0 on success, -1 on error.
Note
This function may be used to enforce object colors in the lstopo graphical output by adding "lstopoStyle" as a name and "Background=#rrggbb" as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
If name or value contain some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.

◆ hwloc_obj_get_info_by_name()

static const char* hwloc_obj_get_info_by_name ( hwloc_obj_t  obj,
const char *  name 
)
inlinestatic

Search the given name in the object array of infos and return the corresponding value.

Identical to hwloc_get_info_by_name() but operates on the infos of the given object.

◆ hwloc_topology_get_infos()

struct hwloc_infos_s* hwloc_topology_get_infos ( hwloc_topology_t  topology)

Get the structure of info attributes attached to the topology.

These attributes contain information about the topology discovery (backends) and about the operating system.

Note
The function cannot return NULL.
The returned pointer belongs to the hwloc library, it should not be freed or modified.