sysobj_add_alias, sysobj_del_alias, sysobj_get_aliases, sysobj_aliases, sysobj_nvl_alias_classes, sysobj_nvl_alias_namespaces, sysobj_nvl_alias_array - add, remove, and get aliases for system objects
cc [ flag... ] file... -lsysobj [ library... ]
#include <libnvpair.h>
#include <sysobj.h>
int sysobj_add_alias(sysobj_t obj, const char *class,
const char *namespace, const char *alias);
int sysobj_del_alias(sysobj_t obj, const char *class,
const char *namespace, const char *alias);
int sysobj_get_aliases(sysobj_t obj, const char *class,
const char *namespace, char ***aliases, size_t *nelemp);
int sysobj_aliases(sysobj_t obj, const char *class, const char *namespace,
nvlist_t **nvlp);
int sysobj_nvl_alias_classes(nvlist_t *nvl, nvlist_t **nvlp);
int sysobj_nvl_alias_namespaces(nvlist_t *nvl, const char *class,
nvlist_t **nvlp);
int sysobj_nvl_alias_array(nvlist_t *nvl, const char *class,
const char *namespace, char ***aliases, size_t *naliases);
The handle of an existing system database object
The class under which the object appears in a namespace
The namespace containing a specified alias
The specified alias
A pointer to an array of aliases for an object in a specified class and namespace
A pointer to a size_t value in which the number of aliases is returned
An nvlist pointer, returned by the sysobj_aliases() function and passed to the sysobj_nvl() convenience functions
A pointer to the nvlist pointer in which results are returned
These functions add, remove and retrieve aliases associated with objects in the system object database.
An object can have multiple aliases in a certain namespace. For each class an object belongs to, the object appears under an alias in at least one namespace. The primary class of an object is specified when the object is created and causes the object to appear in the predefined namespace, "global-uuid".
The functions in this man page are used as follows:
A call to the sysobj_add_alias() function adds an object to a new class, if it doesn't already belong to it.
An object can have multiple aliases in a namespace. Additionally, adding an alias to a namespace cannot overwrite any existing alias in that namespace. Thus, aliases cannot be changed by overwriting. Therefore, if an alias needs to be changed, you must explicitly delete it with the sysobj_del_alias() function, and then create a new alias with the sysobj_add_alias() function. However, deleting aliases is not expected to be a common operation. For more information, see the 'Client Recommendations' section of the sysobj(7) man page.
The sysobj_aliases() function allocates and returns a nested nvlist containing alias information for an object. The nvlist is a list of <class, nvlist> pairs. Each of the nvlists in the pair is a list of <namespace, aliasarray> pairs. Only aliases that match the class and namespace parameters are included in the array, aliasarray. If both the class and namespace parameters are NULL, the sysobj_aliases() function returns all possible class and namespace combinations in the nested nvlist
You must use the following convenience functions to access the nvlist pairs returned by the sysobj_aliases() function.
The sysobj_nvl_alias_classes() function returns the nvlist of <class, nvlist> pairs.
The sysobj_nvl_alias_namespaces() function returns the nvlist of <namespace, aliasarray> pairs for a specified class.
The sysobj_nvl_alias_array() function returns the array of aliases, aliasarray for a class and namespace combination.
The sysobj_del_alias() and sysobj_aliases() functions accept extended regular expressions in their class and namespace parameters. The regular expression is considered to be a match if it matches a whole class or namespace name, and not just a substring. In regular expression terms, this means that each regular expression is implicitly enclosed in ^ and $.
The sysobj_get_aliases() function returns the array of aliases for an object in a specified class and namespace. The function also allocates the space for the array and for each individual alias in the form of a string.
These functions return 0 on success and an error value on failure.
These functions will fail if:
An invalid argument is specified.
Either the library or the system object db daemon cannot allocate memory required for the operation.
An alias is added that already existed in the database.
The system object db daemon disallowed the operation.
No aliases matched the parameters passed to the sysobj_aliases() function
Passing invalid pointers or object handles to any of these functions results in undefined behavior.
/*
* Look up an object by its UUID, and print its aliases in
* the device-path namespace.
*/
#include <libnvpair.h>
#include <malloc.h>
#include <sysobj.h>
#include <stdio.h>
#include <stdlib.h>
...
int
print_aliases(const char *uuidstr)
{
int ret;
sysobj_t obj;
nvlist_t *nvl;
char **aliases;
size_t naliases, i;
ret = sysobj_find(uuidstr, &obj);
if (ret != 0)
return (ret);
/*
* Method one: if we're just interested in alias(es) in
* one class/namespace, use sysobj_get_aliases directly.
*/
ret = sysobj_get_aliases(obj, "device", "device-path",
&aliases, &naliases);
if (ret != 0)
return (ret);
printf("aliases 1:\n");
for (i = 0; i < naliases; i++) {
printf("alias %u: %s\n", (uint_t)i, aliases[i]);
}
/*
* Must free all array elements as well as the array itself.
*/
for (i = 0; i < naliases; i++) {
free(aliases[i]);
}
free(aliases);
/*
* Method 2: get all aliases and then extract the ones
* we're interested in from the returned nvlist.
*
* Step 1: get all aliases for this object.
*/
ret = sysobj_aliases(obj, NULL, NULL, &nvl);
if (ret != 0)
return (ret);
/*
* Step 2: Grab the aliases in the 'device-path' namespace where
* this object appears in the class 'device'.
*/
ret = sysobj_nvl_alias_array("device", "device-path", &aliases,
&naliases);
if (ret != 0) {
nvlist_free(nvl);
return (ret);
}
printf("aliases 2:\n");
for (i = 0; i < naliases; i++) {
printf("alias %u: %s\n", (uint_t)i, aliases[i]);
}
nvlist_free(nvl);
return (0);
}
See attributes(7) for descriptions of the following attributes:
|
libnvpair(3LIB), libsysobj(3LIB), sysobj_add_property(3SYSOBJ), sysobj_create(3SYSOBJ), sysobj_event_register(3SYSOBJ), attributes(7)