Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sysobj_get_aliases (3SYSOBJ)

Name

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

Synopsis

     
     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);

Parameters

obj

The handle of an existing system database object

class

The class under which the object appears in a namespace

namespace

The namespace containing a specified alias

alias

The specified alias

aliases

A pointer to an array of aliases for an object in a specified class and namespace

naliases

A pointer to a size_t value in which the number of aliases is returned

nvl

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

nvlp

A pointer to the nvlist pointer in which results are returned

Description

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:

sysobj_add_alias()

A call to the sysobj_add_alias() function adds an object to a new class, if it doesn't already belong to it.

sysobj_del_alias() and sysobj_add_alias()

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.

sysobj_aliases()

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

sysobj_nvl_alias_classes(), sysobj_nvl_alias_namespaces(), and sysobj_nvl_alias_array()

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.

sysobj_del_alias() and sysobj_aliases()

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 $.

sysobj_get_aliases()

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.

Return Values

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

Errors

These functions will fail if:

EINVAL

An invalid argument is specified.

ENOMEM

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

EEXIST

An alias is added that already existed in the database.

EACCES

The system object db daemon disallowed the operation.

ENOENT

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.

Examples

Example 1 Look Up an Object by UUID and Print its Aliases
     /*
      * 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);

      }

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_add_property(3SYSOBJ), sysobj_create(3SYSOBJ), sysobj_event_register(3SYSOBJ), attributes(7)