Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sysobj_properties (3SYSOBJ)

Name

sysobj_add_property, sysobj_del_property, sysobj_properties, sysobj_nvl_prop_classes, sysobj_nvl_prop_list, sysobj_nvl_prop_nvpair, sysobj_nvl_prop_value - add, delete, and query properties of system object database objects

Synopsis

     cc [ flag... ] file... -lsysobj [ library... ]
     #include <libnvpair.h>
     #include <sysobj.h>

     int  sysobj_add_property(sysobj_t obj, const char *class,
         const char *pname, data_type_t type, ...);
     int  sysobj_del_property(sysobj_t obj, const char *class,
         const char *pname);
     int  sysobj_get_property(sysobj_t obj, const char *class,
         const char *pname, data_type_t type, ...);

     int sysobj_properties(sysobj_t obj, const char *class, const char *pname,
         nvlist_t **nvlp);

     int sysobj_nvl_prop_classes(nvlist_t *nvl, nvlist_t **nvlp);
     int sysobj_nvl_prop_list(nvlist_t *nvl, const char *class,
         nvlist_t **nvlp);
     int sysobj_nvl_prop_value(nvlist_t *nvl, const char *class,
         const char *pname, data_type_t type, ...);
     int sysobj_nvl_prop_nvpair(nvlist_t *nvl, const char *class,
         const char *pname, nvpair_t **nvp);

Description

These functions add, remove and retrieve properties of objects in the system object database.

Properties are <propname, value> pairs, in which propname is a string, and value is of the type, data_type_t. For a list of possible values for data_type_t, see the nvpair_type(3NVPAIR) man page. Properties are divided into classes. A class is identified by a string.

The functions are described as follows:

sysobj_add_property()

The function adds a property of a specified class to an object in the database. If the property already exists, the function overwrites it. Depending on the data type specified, the value passed to the sysobj_add_property() function consists of either one, or two parameters described as follows:

  • For array types, a pointer to the array and the length of the array, size_t are used.

  • For integer, boolean and double types, the value is passed.

  • For an nvlist type, a pointer to an nvlist is passed.

sysobj_del_property()

The function deletes the specified property of the object specified in the name argument, from the database.

sysobj_properties()

The function returns a nested nvlist of properties. The nvlist further consists of <class, nvlist> pairs for each class of properties. The nvlist in each such <class, nvlist> pair is itself an nvlist of <propname, value> pairs.

Convenience functions are provided to access the nvlist returned by the sysobj_properties() function. For array types and strings, the convenience functions return pointers to data contained in the nvlist. This means that the data is valid as long as the nvlist is not freed.

sysobj_nvl_prop_classes()

The function returns an nvlist of <class, nvlist> pairs.

sysobj_nvl_prop_list()

The function returns the list of <propname, value> pairs for a specified class.

sysobj_nvl_prop_value()

The function retrieves the value of a property from the nvlist returned by the sysobj_properties() function. The type is specified in the type parameter. For non-array types, the parameter after the type parameter is a pointer to variable of that type. For array types, there are two additional parameters: a pointer to an array and a pointer to a size_t.

sysobj_get_property()

The function retrieves just one property. The output parameters are specified in the same way for the sysobj_nvl_prop_value() function. Unlike the sysobj_nvl_prop_value() function, the sysobj_get_property() allocates space if needed for the type of property, whether strings or arrays. Additionally, for string arrays and nvlist arrays, each individual array element that is returned is allocated separately.

sysobj_del_property() and sysobj_property()

The functions accept extended regular expressions in their class and pname parameters. The regular expression is considered to be a match if it matches the whole class or property name, and not just a substring.

Parameters

obj

The handle of an existing system database object

class

The class of one or more properties

pname

The name of a property

type

The data type of a property

nvl

An nvlist pointer, returned by the sysobj_properties() function and passed to the sysobj_nvl() convenience functions

nvlp

A pointer to an nvlist pointer, in which results are returned

nvp

A pointer to an nvpair pointer, in which a <name, value> pair property is returned

Return Values

These functions return 0 on success and an error value on failure.

Errors

These functions fail if:

EINVAL

An invalid argument is specified.

ENOMEM

Either the library or the system object db daemon cannot allocate the memory required for the operation

EEXIST

The alias added already exists in the database.

EACCES

The system object db daemon disallowed the operation.

ENOENT

No aliases match the parameters passed to the sysobj_aliases() function

Passing invalid pointers or object handles to any of these functions results in undefined behavior.

Examples

Example 1 Adding and Printing Object Properties
     /*
      * Add properties to an object.
      * Print some properties associated with an object.
      */

      #include <libnvpair.h>
      #include <malloc.h>
      #include <sysobj.h>
      #include <stdio.h>
      #include <stdlib.h>

      ...

      /*
       * Assume an object has a set of properties, amongst which are:
       * class "object data" name "intprop"
       * class "random stuff" name "bytes"
       * class "random stuff" name "double"
       * class "other" name "strings"
       */
      int
      add_properties(sysobj_t obj, int64_t int64val, uint8_t *bytes,
          size_t nbytes, double dval, char **strings, size_t nstrings)
      {
          int ret;

          ret = sysobj_add_property(name, "object data", "intprop",
              DATA_TYPE_INT64, int64val);
          if (ret != 0)
              return (ret);

          ret = sysobj_add_property(name, "random stuff", "bytes",
              DATA_TYPE_UINT8_ARRAY, bytes, nbytes);
          if (ret != 0)
              return (ret);

          ret = sysobj_add_property(name, "random stuff", "double",
              DATA_TYPE_DOUBLE, dval);
          if (ret != 0)
              return (ret);

          ret = sysobj_add_property(name, "other", "strings",
              DATA_TYPE_STRING_ARRAY, strings, nstrings);
          if (ret != 0)
              return (ret);
      }

      int
      print_some_properties(sysobj_t obj)
      {
          int ret;
          nvlist_t *nvl;
          size_t nbytes, nstrings, i;
          int64_t int64val;
          double dval;
          uint8_t *bytes;
          char **strings;

          /*
           * If the caller is just interested in one property,
           * this is the easiest way to do it.
           */
           ret = sysobj_get_property(obj, "object data", "intprop",
               DATA_TYPE_INT64, &int64val);
          if (ret == 0)
              printf("int64val 1: %lld\n", (long long)int64val);

          /*
           * Do the same as above, but retrieve the entire list
           * of properties, extracting the one we want. The list
           * could be used to look up other properties too.
           */
          ret = sysobj_properties(obj, NULL, NULL, &nvl);
          if (ret != 0)
              return (ret);

          /*
           * Retrieve the 'intprop' property.
           */
          ret = sysobj_nvl_prop_value(nvl, "object data", "intprop",
              DATA_TYPE_INT64, &int64val);
          if (ret == 0)
              printf("int64val 2: %lld\n", (long long)int64val);

          nvlist_free(nvl);

          /*
           * Alternatively, here's how to retrieve some properties
           * that are in the same class by retrieving the list
           * for one class first, and then extracting the properties
           * that we want.
           */

          ret = sysobj_properties(obj, "random stuff", NULL, &nvl);
          if (ret != 0)
              return (ret);

          ret = sysobj_nvl_prop_value(nvl, "random stuff", "bytes",
              DATA_TYPE_UINT8_ARRAY, &bytes, &nbytes);
          if (ret == 0) {
              printf("bytes:\n");
              for (i = 0; i < nbytes; i++) {
                  printf("%02x ", bytes[i]);
              }
              printf("\n");
          }

          ret = sysobj_nvl_prop_value(nvl, "random stuff", "bytes",
              DATA_TYPE_DOUBLE, &dval);
          if (ret == 0)
              printf("dval: %lf\n", dval);

          nvlist_free(nvl);

          return (0);

      }

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe

See Also

libnvpair(3LIB), libsysobj(3LIB), sysobj_create(3SYSOBJ), sysobj_event_register(3SYSOBJ), attributes(7)