Tribblix: manual page: papiAttributeListGetString.3papi

PAPIATTRIBUTELISTADDVALUE(3PAPI) PAPI Library Functions

NAME

papiAttributeListAddValue, papiAttributeListAddBoolean,
papiAttributeListAddCollection, papiAttributeListAddDatetime,
papiAttributeListAddInteger, papiAttributeListAddMetadata,
papiAttributeListAddRange, papiAttributeListAddResolution,
papiAttributeListAddString, papiAttributeListDelete,
papiAttributeListGetValue, papiAttributeListGetNext,
papiAttributeListFind, papiAttributeListGetBoolean,
papiAttributeListGetCollection, papiAttributeListGetDatetime,
papiAttributeListGetInteger, papiAttributeListGetMetadata,
papiAttributeListGetRange, papiAttributeListGetResolution,
papiAttributeListGetString, papiAttributeListFromString,
papiAttributeListToString, papiAttributeListFree - manage PAPI
attribute lists

SYNOPSIS

cc [ flag... ] file... -lpapi [ library... ]
#include <papi.h>

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

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

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 attributes

attributes
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 attributes

datetime
attribute time value specified in time_t representation

delim
delimiter used in construction of a string
representation of an attribute list

dt
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).

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 of multi-value
attributes

list
array of pointers to attributes (attribute list)

lower
lower bound for a range of integer

max
maximum value in a range

metadata
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 value

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

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 resolution

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.

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 <stdio.h>
#include <papi.h>

/*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,
"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");

/* retrieve 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