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
const char *	hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
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)
int	hwloc_obj_add_info (hwloc_obj_t obj, const char *name, const char *value)
struct hwloc_infos_s *	hwloc_topology_get_infos (hwloc_topology_t topology)
int	hwloc_obj_set_subtype (hwloc_topology_t topology, hwloc_obj_t obj, const char *subtype)

Detailed Description

Enumeration Type Documentation

hwloc_modify_infos_op_e

enum 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()

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

inline

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()

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

inline

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()

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

inline

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_obj_set_subtype()

int hwloc_obj_set_subtype	(	hwloc_topology_t	topology,
		hwloc_obj_t	obj,
		const char *	subtype
	)

Set (or replace) the subtype of an object.

The given subtype is copied internally, the caller is responsible for freeing the original subtype if needed.

If another subtype already exists in object, it is replaced. The given subtype may be NULL to remove the existing subtype.

Note

This function is mostly meant to initialize the subtype of user-added objects such as groups with hwloc_topology_alloc_group_object().

Returns

0 on success.

-1 with errno set to ENOMEM on failure to allocate memory.

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.