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 lists
SYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papistatust papiAttributeListAddValue(papiattributet ***attrs,
int flags, char *name, papiattributevaluetypet type,
papiattributevaluet *value);
papistatust papiAttributeListAddString(papiattributet ***attrs,
int flags, char *name, char *string);
papistatust papiAttributeListAddInteger(papiattributet ***attrs,
int flags, char *name, int integer);
papistatust papiAttributeListAddBoolean(papiattributet ***attrs,
int flags, char *name, char boolean);
papistatust papiAttributeListAddRange(papiattributet ***attrs,
int flags, char *name, int lower, int upper);
papistatust papiAttributeListAddResolution(papiattributet ***attrs,
int flags, char *name, int xres, int yres,
papiresolutionunitt units);
papistatust papiAttributeListAddDatetime(papiattributet ***attrs,
int flags, char *name, timet datetime);
papistatust papiAttributeListAddCollection(papiattributet ***attrs,
int flags, char *name, papiattributet **collection);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiAttributeListAddValue(3PAPI)
papistatust papiAttributeListAddMetadata(papiattributet ***attrs,
int flags, char *name, papimetadatat metadata);
papistatust papiAttributeListDelete(papiattributet ***attributes,
char *name);
papistatust papiAttributeListGetValue(papiattributet **list,
void **iterator, char *name, papiattributevaluetypet type,
papiattributevaluet **value);
papistatust papiAttributeListGetString(papiattributet **list,
void **iterator, char *name, char **vptr);
papistatust papiAttributeListGetInteger(papiattributet **list,
void **iterator, char *name, int *vptr);
papistatust papiAttributeListGetBoolean(papiattributet **list,
void **iterator, char *name, char *vptr);
papistatust papiAttributeListGetRange(papiattributet **list,
void **iterator, char *name, int *min, int *max);
papistatust papiAttributeListGetResolution(papiattributet **list,
void **iterator, char *name, int *x, int *y,
papiresolutionunitt *units);
papistatust papiAttributeListGetDatetime(papiattributet **list,
void **iterator, char *name, timet *dt);
papistatust papiAttributeListGetCollection(papiattributet **list,
void **iterator, char *name, papiattributet ***collection);
papistatust papiAttributeListGetMetadata(papiattributet **list,
void **iterator, char *name, papimetadatat *vptr);
papiattributet *papiAttributeListFind(papiattributet **list,
char *name);
papiattributet *papiAttributeListGetNext(papiattributet **list,
void **iterator);
SunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiAttributeListAddValue(3PAPI)
void papiAttributeListFree(papiattributet **attributes);
papistatust papiAttributeListFromString(papiattributet ***attrs,
int flags, char *string);
papistatust papiAttributeListToString(papiattributet **attrs,
char *delim, char *buffer, sizet buflen);
PARAMETERS
attrs address of array of pointers to attributes
attributes a list of attributes (of type papiattributet
**) contained in a collection. Lists can be
hierarchical.
boolean boolean value (PAPITRUE or PAPIFALSE)
buffer buffer to fill
buflen length of supplied buffer
collection list of attributes
datetime attribute time value specified in timet
representation
delim delimiter used in construction of a string
representation of an attribute list
dt date and time represented as a timet
flags Specify bit fields defining how actions will
be performed:
PAPIATREPLACE
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)
PAPIATRAPEND
Add the supplied value to the attribute.
PAPIATREXCL
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
PAPIUNSUPORTED, PAPIDEFAULT, PAPIUNKNOWN,
PAPINOVALUE, PAPINOTSETABLE, PAPIDELETE
min minimum value in a range
name attribute name
string string value
type attribute type (PAPISTRING, PAPINTEGER,
PAPIBOLEAN, PAPIRANGE, PAPIRESOLUTION,
PAPIDATETIME, PAPICOLECTION, PAPIMETADATA)
units resolution unit of measure (PAPIRESPERINCH
or PAPIRESPERCM)
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 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 PAPIATREPLACE is specified in flags, any existing
attribute values are freed and replaced with the supplied
value.
If PAPIATRAPEND is specified, the supplied value is
appended to the attribute's list of values.
If PAPIATREXCL 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, NUL 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 application
to 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 NUL and subsequent calls should
use NUL for the list argument.
The papiAttributeListFree() function deallocates all memory
associated with an attribute list, including values that
might 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=(truefalse)" 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 PAPIOK upon successful completion
and one of the following on failure:
PAPIBADARGUMENT The supplied arguments were not
valid.
PAPICONFLICT There was an attribute type
mismatch.
PAPINOTFOUND The requested attribute could not be
found.
PAPINOTPOSIBLE The requested operation could not be
performed due to buffer overflow.
PAPITEMPORARYEROR 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];
papistatust status;
papiattributet **list = NUL;
void *iter = NUL;
char *string = NUL;
int32t integer = 0;
/* build an attribute list */
(void) papiAttributeListAddString(&list, PAPIATREXCL,
"job-title", "example");
(void) papiAttributeListAddInteger(&list, PAPIATREXCL,
"copies", 1);
(void) papiAttributeListFromString(&list, PAPIATREPLACE, av[1]);
status = papiAttributeListAddString(&list, PAPIATREXCL,
SunOS 5.11 Last change: 17 Jan 2007 7
PAPI Library Functions papiAttributeListAddValue(3PAPI)
"document-format", "text/plain");
if (status != PAPIOK)
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 == PAPIOK)
printf("Attributes: %s\n", buf);
else
printf("Attribute list to big to dump\n");
/* retreive various elements */
integer = 12;
(void) papiAttributeListGetInteger(list, NUL, "copies", &integer);
printf("copies: %d\n", integer);
string = NUL;
for (status = papiAttributeListGetString(list, &oter,
"job-files", &string);
status == PAPIOK;
status = papiAttributeListGetString(list, &iter, NUL, &string))
printf("file: %s\n", string);
papiAttributeListFree(list);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Volatile
MT-Level Safe
SEE ALSO
libpapi(3LIB), attributes(5)
SunOS 5.11 Last change: 17 Jan 2007 8
|
