Description

The papiAttributeListAdd*() functions add new attributes and/or values to the attribute list
passed in. If necessary, the attribute list passed in is expanded to
contain a new attribute pointer for any new attributes added to the
list. The list is null-terminated. Space for the new attributes and values is
allocated and the name and value are copied into this allocated space.

If PAPI_ATTR_REPLACE is specified in flags, any existing attribute values are freed
and replaced with the supplied value.

If PAPI_ATTR_APPEND is specified, the supplied value is appended to the attribute's
list of values.

If PAPI_ATTR_EXCL is specified, the operation succeeds only if the attribute was
not previously defined.

The papiAttributeListGet*() functions retrieve an attribute value from an attribute list. If
the attribute is a multi-valued attribute, the first call to retrieve a
value should pass in an iterator and attribute name. Subsequent calls to
retrieve additional values should pass in the iterator and a null value for
the attribute name. If a single-valued attribute is to be retrieved,
NULL can be used in place of the iterator.

Upon successful completion of a get operation, the value passed in (string,
integer, boolean, ...) is changed to the value from the attribute list.
If the operation fails for any reason (type mismatch, not found,
...), the value passed in remains untouched.

The resulting value returned from a get operation is returned from the
attribute list's allocated memory. It is not guaranteed to be available after
the attribute list has been freed.

The papiAttributeListDelete() function removes an attribute from a supplied list.

The papiAttributeListFind() function allows an application to retrieve an entire attribute structure
from the passed-in attribute list.

The papiAttributeListGetNext() function allows an application to walk through an attribute list
returning subsequent attributes from the list. With the first call, the
iterator should be initialized to NULL and subsequent calls should use NULL
for the list argument.

The papiAttributeListFree() function deallocates all memory associated with an attribute list, including
values that might have been retrieved previously using papiAttributeListGet*() calls.

The papiAttributeListFromString() function takes in a string representation of a set of
attributes, parses the string and adds the attributes to the passed in
attribute list using the flags to determine how to add them.
String values are specified with “key=value”. Integer values are specified with “key=number”. Boolean
values are specified with either “key=(true|false)” or “[no]key”. Multiple attributes can be
specified in the string by separating them with a whitespace character.

The papiAttributeListToString() function converts an attribute list to a string representation that
can be displayed to a user. The delimiter value is placed
between attributes in the string.

Return Values

These functions return PAPI_OK upon successful completion and one of the following
on failure:

PAPI_BAD_ARGUMENT

The supplied arguments were not valid.

PAPI_CONFLICT

There was an attribute type mismatch.

PAPI_NOT_FOUND

The requested attribute could not be found.

PAPI_NOT_POSSIBLE

The requested operation could not be performed due to buffer overflow.