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
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);
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:
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.
The function deletes the specified property of the object specified in the name argument, from the database.
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.
The function returns an nvlist of <class, nvlist> pairs.
The function returns the list of <propname, value> pairs for a specified class.
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.
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.
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.
The handle of an existing system database object
The class of one or more properties
The name of a property
The data type of a property
An nvlist pointer, returned by the sysobj_properties() function and passed to the sysobj_nvl() convenience functions
A pointer to an nvlist pointer, in which results are returned
A pointer to an nvpair pointer, in which a <name, value> pair property is returned
These functions return 0 on success and an error value on failure.
These functions fail if:
An invalid argument is specified.
Either the library or the system object db daemon cannot allocate the memory required for the operation
The alias added already exists in the database.
The system object db daemon disallowed the operation.
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.
/*
* 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);
}
See attributes(7) for descriptions of the following attributes:
|
libnvpair(3LIB), libsysobj(3LIB), sysobj_create(3SYSOBJ), sysobj_event_register(3SYSOBJ), attributes(7)