papiAttributeListAddCollection(3papi)

1papiAttributeListAddValue(3PAPPAIP)I Library FunctipoanpsiAttributeListAddValue(3PAPI)
2
3
4

NAME

6       papiAttributeListAddValue,     papiAttributeListAddBoolean,     papiAt‐
7       tributeListAddCollection,     papiAttributeListAddDatetime,     papiAt‐
8       tributeListAddInteger,  papiAttributeListAddMetadata, papiAttributeLis‐
9       tAddRange, papiAttributeListAddResolution,  papiAttributeListAddString,
10       papiAttributeListDelete,  papiAttributeListGetValue, papiAttributeList‐
11       GetNext,  papiAttributeListFind,  papiAttributeListGetBoolean,  papiAt‐
12       tributeListGetCollection,     papiAttributeListGetDatetime,     papiAt‐
13       tributeListGetInteger, papiAttributeListGetMetadata, papiAttributeList‐
14       GetRange,  papiAttributeListGetResolution,  papiAttributeListGetString,
15       papiAttributeListFromString,     papiAttributeListToString,     papiAt‐
16       tributeListFree - manage PAPI attribute lists
17

SYNOPSIS

19       cc [ flag... ] file... -lpapi [ library... ]
20       #include <papi.h>
21
22       papi_status_t papiAttributeListAddValue(papi_attribute_t ***attrs,
23            int flags, char *name, papi_attribute_value_type_t type,
24            papi_attribute_value_t *value);
25
26
27       papi_status_t papiAttributeListAddString(papi_attribute_t ***attrs,
28            int flags, char *name, char *string);
29
30
31       papi_status_t papiAttributeListAddInteger(papi_attribute_t ***attrs,
32            int flags, char *name, int integer);
33
34
35       papi_status_t papiAttributeListAddBoolean(papi_attribute_t ***attrs,
36            int flags, char *name, char boolean);
37
38
39       papi_status_t papiAttributeListAddRange(papi_attribute_t ***attrs,
40            int flags, char *name, int lower, int upper);
41
42
43       papi_status_t papiAttributeListAddResolution(papi_attribute_t ***attrs,
44            int flags, char *name, int xres, int yres,
45            papi_resolution_unit_t units);
46
47
48       papi_status_t papiAttributeListAddDatetime(papi_attribute_t ***attrs,
49            int flags, char *name, time_t datetime);
50
51
52       papi_status_t papiAttributeListAddCollection(papi_attribute_t ***attrs,
53            int flags, char *name, papi_attribute_t **collection);
54
55
56       papi_status_t papiAttributeListAddMetadata(papi_attribute_t ***attrs,
57            int flags, char *name, papi_metadata_t metadata);
58
59
60       papi_status_t papiAttributeListDelete(papi_attribute_t ***attributes,
61            char *name);
62
63
64       papi_status_t papiAttributeListGetValue(papi_attribute_t **list,
65            void **iterator, char *name, papi_attribute_value_type_t type,
66            papi_attribute_value_t **value);
67
68
69       papi_status_t papiAttributeListGetString(papi_attribute_t **list,
70            void **iterator, char *name, char **vptr);
71
72
73       papi_status_t papiAttributeListGetInteger(papi_attribute_t **list,
74            void **iterator, char *name, int *vptr);
75
76
77       papi_status_t papiAttributeListGetBoolean(papi_attribute_t **list,
78            void **iterator, char *name, char *vptr);
79
80
81       papi_status_t papiAttributeListGetRange(papi_attribute_t **list,
82            void **iterator, char *name, int *min, int *max);
83
84
85       papi_status_t papiAttributeListGetResolution(papi_attribute_t **list,
86            void **iterator, char *name, int *x, int *y,
87            papi_resolution_unit_t *units);
88
89
90       papi_status_t papiAttributeListGetDatetime(papi_attribute_t **list,
91            void **iterator, char *name, time_t *dt);
92
93
94       papi_status_t papiAttributeListGetCollection(papi_attribute_t **list,
95            void **iterator, char *name, papi_attribute_t ***collection);
96
97
98       papi_status_t papiAttributeListGetMetadata(papi_attribute_t **list,
99            void **iterator, char *name, papi_metadata_t *vptr);
100
101
102       papi_attribute_t *papiAttributeListFind(papi_attribute_t **list,
103            char *name);
104
105
106       papi_attribute_t *papiAttributeListGetNext(papi_attribute_t **list,
107            void **iterator);
108
109
110       void papiAttributeListFree(papi_attribute_t **attributes);
111
112
113       papi_status_t papiAttributeListFromString(papi_attribute_t ***attrs,
114            int flags, char *string);
115
116
117       papi_status_t papiAttributeListToString(papi_attribute_t **attrs,
118            char *delim, char *buffer, size_t buflen);
119
120

PARAMETERS

122       attrs         address of array of pointers to attributes
123
124
125       attributes    a  list  of attributes (of type papi_attribute_t **) con‐
126                     tained in a collection. Lists can be hierarchical.
127
128
129       boolean       boolean value (PAPI_TRUE or PAPI_FALSE)
130
131
132       buffer        buffer to fill
133
134
135       buflen        length of supplied buffer
136
137
138       collection    list of attributes
139
140
141       datetime      attribute time value specified in time_t representation
142
143
144       delim         delimiter used in construction of a string representation
145                     of an attribute list
146
147
148       dt            date and time represented as a time_t
149
150
151       flags         Specify  bit  fields  defining  how  actions will be per‐
152                     formed:
153
154                     PAPI_ATTR_REPLACE
155
156                         Free any existing value(s) and replace  it  with  the
157                         supplied value(s).
158
159
160                     PAPI_ATTR_APPEND
161
162                         Add the supplied value to the attribute.
163
164
165                     PAPI_ATTR_EXCL
166
167                         Add  the  supplied  value  to  the  attribute, if the
168                         attribute was not previously defined.
169
170
171
172       integer       integer value
173
174
175       iterator      iterator for enumerating multiple values  of  multi-value
176                     attributes
177
178
179       list          array of pointers to attributes (attribute list)
180
181
182       lower         lower bound for a range of integer
183
184
185       max           maximum value in a range
186
187
188       metadata      pseudo-values   for  specialized  attributes  PAPI_UNSUP‐
189                     PORTED,   PAPI_DEFAULT,   PAPI_UNKNOWN,    PAPI_NO_VALUE,
190                     PAPI_NOT_SETTABLE, PAPI_DELETE
191
192
193       min           minimum value in a range
194
195
196       name          attribute name
197
198
199       string        string value
200
201
202       type          attribute  type (PAPI_STRING, PAPI_INTEGER, PAPI_BOOLEAN,
203                     PAPI_RANGE, PAPI_RESOLUTION, PAPI_DATETIME,  PAPI_COLLEC‐
204                     TION, PAPI_METADATA)
205
206
207       units         resolution   unit   of   measure   (PAPI_RES_PER_INCH  or
208                     PAPI_RES_PER_CM)
209
210
211       upper         upper bound for a range of integer
212
213
214       value         attribute value
215
216
217       vptr          pointer to arbitrary data
218
219
220       x             horizontal (x) resolution
221
222
223       xres          horizontal (x) component of a resolution
224
225
226       y             vertical (y) resolution
227
228
229       yres          vertical (y) component of a resolution
230
231

DESCRIPTION

233       The papiAttributeListAdd*() functions add new attributes and/or  values
234       to  the  attribute  list  passed  in.  If necessary, the attribute list
235       passed in is expanded to contain a new attribute pointer  for  any  new
236       attributes  added  to  the list. The list is null-terminated. Space for
237       the new attributes and values is allocated and the name and  value  are
238       copied into this allocated space.
239
240
241       If PAPI_ATTR_REPLACE is specified in flags, any existing attribute val‐
242       ues are freed and replaced with the supplied value.
243
244
245       If PAPI_ATTR_APPEND is specified, the supplied value is appended to the
246       attribute's list of values.
247
248
249       If  PAPI_ATTR_EXCL  is  specified,  the  operation succeeds only if the
250       attribute was not previously defined.
251
252
253       The papiAttributeListGet*() functions retrieve an attribute value  from
254       an  attribute  list.  If the attribute is a multi-valued attribute, the
255       first call to retrieve a value should pass in an iterator and attribute
256       name. Subsequent calls to retrieve additional values should pass in the
257       iterator and a null value for the attribute name.  If  a  single-valued
258       attribute  is  to be retrieved, NULL can be used in place of the itera‐
259       tor.
260
261
262       Upon successful completion of a get  operation,  the  value  passed  in
263       (string,  integer,  boolean,  ...)  is  changed  to  the value from the
264       attribute list.  If the operation fails for any reason (type  mismatch,
265       not found, ...), the value passed in remains untouched.
266
267
268       The  resulting value returned from a get operation is returned from the
269       attribute list's allocated memory. It is not guaranteed to be available
270       after the attribute list has been freed.
271
272
273       The papiAttributeListDelete() function removes an attribute from a sup‐
274       plied list.
275
276
277       The papiAttributeListFind() function allows an application to  retrieve
278       an entire attribute structure from the passed-in attribute list.
279
280
281       The  papiAttributeListGetNext()  function allows an application to walk
282       through an attribute list  returning  subsequent  attributes  from  the
283       list.   With the first call, the iterator should be initialized to NULL
284       and subsequent calls should use NULL for the list argument.
285
286
287       The papiAttributeListFree() function deallocates all memory  associated
288       with an attribute list, including values that might have been retrieved
289       previously using papiAttributeListGet*() calls.
290
291
292       The papiAttributeListFromString() function takes in a string  represen‐
293       tation  of  a  set  of  attributes,  parses  the  string  and  adds the
294       attributes to the passed in attribute list using the flags to determine
295       how to add them.  String values are specified with "key=value". Integer
296       values are specified with "key=number". Boolean  values  are  specified
297       with either "key=(true|false)" or "[no]key". Multiple attributes can be
298       specified in the string by separating them with a whitespace character.
299
300
301       The papiAttributeListToString() function converts an attribute list  to
302       a string representation that can be displayed to a user.  The delimiter
303       value is placed between attributes in the string.
304

RETURN VALUES

306       These functions return PAPI_OK upon successful completion  and  one  of
307       the following on failure:
308
309       PAPI_BAD_ARGUMENT       The supplied arguments were not valid.
310
311
312       PAPI_CONFLICT           There was an attribute type mismatch.
313
314
315       PAPI_NOT_FOUND          The requested attribute could not be found.
316
317
318       PAPI_NOT_POSSIBLE       The  requested operation could not be performed
319                               due to buffer overflow.
320
321
322       PAPI_TEMPORARY_ERROR    Memory could not be allocated  to  add  to  the
323                               attribute list.
324
325

EXAMPLES

327       Example 1 The following example manipulates a PAPI attribute list.
328
329         /*
330          * program to manipulate a PAPI attribute list
331          */
332         #include <stdio.h>
333         #include <papi.h>
334
335         /*ARGSUSED*/
336         int
337         main(int ac, char *av[])
338         {
339             char buf[BUFSIZ];
340             papi_status_t status;
341             papi_attribute_t **list = NULL;
342             void *iter = NULL;
343             char *string = NULL;
344             int32_t integer = 0;
345
346             /* build an attribute list */
347             (void) papiAttributeListAddString(&list, PAPI_ATTR_EXCL,
348                                         "job-title", "example");
349             (void) papiAttributeListAddInteger(&list, PAPI_ATTR_EXCL,
350                                         "copies", 1);
351             (void) papiAttributeListFromString(&list, PAPI_ATTR_REPLACE, av[1]);
352             status = papiAttributeListAddString(&list, PAPI_ATTR_EXCL,
353                                         "document-format", "text/plain");
354             if (status != PAPI_OK)
355                 printf("failed to set document-format to text/plain: %s\n",
356                        papiStatusString(status));
357
358             /* dump the list */
359             status = papiAttributeListToString(list, "\n\t", buf, sizeof (buf));
360             if (status == PAPI_OK)
361                 printf("Attributes: %s\n", buf);
362             else
363                 printf("Attribute list to big to dump\n");
364
365
366             /* retreive various elements */
367             integer = 12;
368             (void) papiAttributeListGetInteger(list, NULL, "copies", &integer);
369             printf("copies: %d\n", integer);
370
371             string = NULL;
372             for (status = papiAttributeListGetString(list, &oter,
373                                                     "job-files", &string);
374                  status == PAPI_OK;
375                  status = papiAttributeListGetString(list, &iter, NULL, &string))
376                 printf("file: %s\n", string);
377
378             papiAttributeListFree(list);
379         }
380
381

ATTRIBUTES

383       See attributes(5) for descriptions of the following attributes:
384
385
386
387
388       ┌─────────────────────────────┬─────────────────────────────┐
389       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
390       ├─────────────────────────────┼─────────────────────────────┤
391       │Interface Stability          │Volatile                     │
392       ├─────────────────────────────┼─────────────────────────────┤
393       │MT-Level                     │Safe                         │
394       └─────────────────────────────┴─────────────────────────────┘
395