papiAttributeListAddValue man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

PAPIATTRIBUTELISTADDVALUE(3PAPI)	      PAPIATTRIBUTELISTADDVALUE(3PAPI)

NAME
       papiAttributeListAddValue,     papiAttributeListAddBoolean,     papiAt‐
       tributeListAddCollection,     papiAttributeListAddDatetime,     papiAt‐
       tributeListAddInteger,  papiAttributeListAddMetadata, papiAttributeLis‐
       tAddRange, papiAttributeListAddResolution,  papiAttributeListAddString,
       papiAttributeListDelete,	 papiAttributeListGetValue, papiAttributeList‐
       GetNext,	 papiAttributeListFind,	 papiAttributeListGetBoolean,  papiAt‐
       tributeListGetCollection,     papiAttributeListGetDatetime,     papiAt‐
       tributeListGetInteger, papiAttributeListGetMetadata, papiAttributeList‐
       GetRange,  papiAttributeListGetResolution,  papiAttributeListGetString,
       papiAttributeListFromString,	papiAttributeListToString,     papiAt‐
       tributeListFree - 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 **) con‐
		     tained 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 per‐
		     formed:

		     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_UNSUP‐
		     PORTED,   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_COLLEC‐
		     TION, 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 val‐
       ues 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 itera‐
       tor.

       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 sup‐
       plied 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  represen‐
       tation  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");

	     /* 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 attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Volatile	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       libpapi(3LIB), attributes(5)

				 Jan 17, 2007 PAPIATTRIBUTELISTADDVALUE(3PAPI)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net