PAPI Library Functions papiAttributeListAddValue(3PAPI)
NAME
papiAttributeListAddValue, papiAttributeListAddBoolean,papiAttributeListAddCollection, papiAttributeListAddDate-
time, papiAttributeListAddInteger, papiAttributeListAddMeta-
data, papiAttributeListAddRange, papiAttributeListAddResolu-
tion, papiAttributeListAddString, papiAttributeListDelete,papiAttributeListGetValue, papiAttributeListGetNext, papiAt-
tributeListFind, papiAttributeListGetBoolean, papiAttribu-
teListGetCollection, papiAttributeListGetDatetime, papiAt-
tributeListGetInteger, papiAttributeListGetMetadata, papiAt-
tributeListGetRange, papiAttributeListGetResolution, papiAt-
tributeListGetString, papiAttributeListFromString, papiAt-
tributeListToString, papiAttributeListFree - manage PAPI
attribute listsSYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papi_status_t papiAttributeListAddValue(papi_attribute_t ***attrs,
int flags, char *name, papi_attribute_value_type_t type,
papi_attribute_value_t *value);
papi_status_t papiAttributeListAddString(papi_attribute_t ***attrs,
int flags, char *name, char *string);papi_status_t papiAttributeListAddInteger(papi_attribute_t ***attrs,
int flags, char *name, int integer);papi_status_t papiAttributeListAddBoolean(papi_attribute_t ***attrs,
int flags, char *name, char boolean);papi_status_t papiAttributeListAddRange(papi_attribute_t ***attrs,
int flags, char *name, int lower, int upper);papi_status_t papiAttributeListAddResolution(papi_attribute_t ***attrs,
int flags, char *name, int xres, int yres,papi_resolution_unit_t units);
papi_status_t papiAttributeListAddDatetime(papi_attribute_t ***attrs,
int flags, char *name, time_t datetime);
papi_status_t papiAttributeListAddCollection(papi_attribute_t ***attrs,
int flags, char *name, papi_attribute_t **collection);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiAttributeListAddValue(3PAPI)papi_status_t papiAttributeListAddMetadata(papi_attribute_t ***attrs,
int flags, char *name, papi_metadata_t metadata);
papi_status_t papiAttributeListDelete(papi_attribute_t ***attributes,
char *name);papi_status_t papiAttributeListGetValue(papi_attribute_t **list,
void **iterator, char *name, papi_attribute_value_type_t type,
papi_attribute_value_t **value);
papi_status_t papiAttributeListGetString(papi_attribute_t **list,
void **iterator, char *name, char **vptr);papi_status_t papiAttributeListGetInteger(papi_attribute_t **list,
void **iterator, char *name, int *vptr);papi_status_t papiAttributeListGetBoolean(papi_attribute_t **list,
void **iterator, char *name, char *vptr);papi_status_t papiAttributeListGetRange(papi_attribute_t **list,
void **iterator, char *name, int *min, int *max);papi_status_t papiAttributeListGetResolution(papi_attribute_t **list,
void **iterator, char *name, int *x, int *y,papi_resolution_unit_t *units);
papi_status_t papiAttributeListGetDatetime(papi_attribute_t **list,
void **iterator, char *name, time_t *dt);
papi_status_t papiAttributeListGetCollection(papi_attribute_t **list,
void **iterator, char *name, papi_attribute_t ***collection);
papi_status_t papiAttributeListGetMetadata(papi_attribute_t **list,
void **iterator, char *name, papi_metadata_t *vptr);
papi_attribute_t *papiAttributeListFind(papi_attribute_t **list,
char *name);papi_attribute_t *papiAttributeListGetNext(papi_attribute_t **list,
void **iterator);SunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiAttributeListAddValue(3PAPI)void papiAttributeListFree(papi_attribute_t **attributes);
papi_status_t papiAttributeListFromString(papi_attribute_t ***attrs,
int flags, char *string);papi_status_t papiAttributeListToString(papi_attribute_t **attrs,
char *delim, char *buffer, size_t buflen);
PARAMETERS
attrs address of array of pointers to attributesattributes a list of attributes (of type papi_attribute_t
**) contained in a collection. Lists can be hierarchical.boolean boolean value (PAPI_TRUE or PAPI_FALSE)
buffer buffer to fill buflen length of supplied buffer collection list of attributesdatetime attribute time value specified in time_t
representation delim delimiter used in construction of a string representation of an attribute listdt date and time represented as a time_t
flags Specify bit fields defining how actions will be performed:PAPI_ATTR_REPLACE
Free any existing value(s) and replace it with the supplied value(s).SunOS 5.11 Last change: 17 Jan 2007 3
PAPI Library Functions papiAttributeListAddValue(3PAPI)PAPI_ATTR_APPEND
Add the supplied value to the attribute.PAPI_ATTR_EXCL
Add the supplied value to the attribute, if the attribute was not previously defined. integer integer value iterator iterator for enumerating multiple values ofmulti-value attributes
list array of pointers to attributes (attribute list) lower lower bound for a range of integer max maximum value in a rangemetadata pseudo-values for specialized attributes
PAPI_UNSUPPORTED, PAPI_DEFAULT, PAPI_UNKNOWN,
PAPI_NO_VALUE, PAPI_NOT_SETTABLE, PAPI_DELETE
min minimum value in a range name attribute name string string valuetype attribute type (PAPI_STRING, PAPI_INTEGER,
PAPI_BOOLEAN, PAPI_RANGE, PAPI_RESOLUTION,
PAPI_DATETIME, PAPI_COLLECTION, PAPI_METADATA)
units resolution unit of measure (PAPI_RES_PER_INCH
or PAPI_RES_PER_CM)
SunOS 5.11 Last change: 17 Jan 2007 4
PAPI Library Functions papiAttributeListAddValue(3PAPI) upper upper bound for a range of integer value attribute value vptr pointer to arbitrary data x horizontal (x) resolution xres horizontal (x) component of a resolution y vertical (y) resolution yres vertical (y) component of a resolutionDESCRIPTION
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 attributevalue 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 anull value for the attribute name. If a single-valued
attribute is to be retrieved, NULL can be used in place of the iterator.SunOS 5.11 Last change: 17 Jan 2007 5
PAPI Library Functions papiAttributeListAddValue(3PAPI) 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 applicationto retrieve an entire attribute structure from the passed-in
attribute list.The papiAttributeListGetNext() function allows an applica-
tion 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 thatmight have been retrieved previously using papiAttributeL-
istGet*() 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 attri-
bute list to a string representation that can be displayed to a user. The delimiter value is placed between attributes in the string.SunOS 5.11 Last change: 17 Jan 2007 6
PAPI Library Functions papiAttributeListAddValue(3PAPI)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.PAPI_TEMPORARY_ERROR Memory could not be allocated to add
to the attribute list.EXAMPLES
Example 1 The following example manipulates a PAPI attribute list. /* * program to manipulate a PAPI attribute list */#include
#include
/*ARGSUSED*/ int main(int ac, char *av[]) { char buf[BUFSIZ];papi_status_t status;
papi_attribute_t **list = NULL;
void *iter = NULL; char *string = NULL;int32_t integer = 0;
/* build an attribute list */(void) papiAttributeListAddString(&list, PAPI_ATTR_EXCL,
"job-title", "example");
(void) papiAttributeListAddInteger(&list, PAPI_ATTR_EXCL,
"copies", 1);(void) papiAttributeListFromString(&list, PAPI_ATTR_REPLACE, av[1]);
status = papiAttributeListAddString(&list, PAPI_ATTR_EXCL,
SunOS 5.11 Last change: 17 Jan 2007 7
PAPI Library Functions papiAttributeListAddValue(3PAPI)"document-format", "text/plain");
if (status != PAPI_OK)
printf("failed to set document-format to text/plain: %s\n",
papiStatusString(status)); /* dump the list */ status = papiAttributeListToString(list, "\n\t", buf, sizeof (buf));if (status == PAPI_OK)
printf("Attributes: %s\n", buf);
else printf("Attribute list to big to dump\n"); /* retreive various elements */ integer = 12; (void) papiAttributeListGetInteger(list, NULL, "copies", &integer);printf("copies: %d\n", integer);
string = NULL; for (status = papiAttributeListGetString(list, &oter,"job-files", &string);
status == PAPI_OK;
status = papiAttributeListGetString(list, &iter, NULL, &string))printf("file: %s\n", string);
papiAttributeListFree(list); }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Volatile ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libpapi(3LIB), attributes(5)SunOS 5.11 Last change: 17 Jan 2007 8