Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sysobj_lookup (3SYSOBJ)

Name

sysobj_create, sysobj_destroy, sysobj_find, sysobj_lookup, sysobj_uuid, sysobj_uuidstr, sysobj_classes, sysobj_free - look up, create, and destroy system database objects

Synopsis

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

     int      sysobj_create(uuid_t *uuidp, const char *class, sysobj_t *objp);
     int      sysobj_destroy(sysobj_t obj);
     sysobj_t sysobj_dup(sysobj_t obj);
     void     sysobj_free(sysobj_t obj);

     int  sysobj_classes(sysobj_t obj, char ***classes, size_t *nclasses);

     void sysobj_uuid(sysobj_t obj, uuid_t *uuidp);
     void sysobj_uuidstr(sysobj_t obj, char *uuidstr);

     int  sysobj_find(char *uuidstr, sysobj_t *objp);
     int  sysobj_lookup(const char *search, sysobj_t **results,
         size_t *nresults);

Description

The following sections state the tasks performed by the functions.

Allocation

sysobj_create()

The function adds a new object of the primary class specified in the parameter, class. The uuidp parameter specifies the UUID to use for the new object. If, however, the uuidp parameter is NULL, a new UUID is generated and used for the object. The new object is stored in the handle pointed to by the objp parameter.

sysobj_classes()

The function returns a string array of all the classes that an object belongs to. The primary class is at index 0 in the array.

sysobj_destroy()

The function removes an object that was previously inserted into the sysobj database. The object is described by the handle in the name parameter. The function frees only the object, and not the handle.

sysobj_free()

The function frees an unused handle, but does not destroy the database object described by that handle.

sysobj_dup()

The function duplicates a handle, but does not duplicate or add references to the database object described by that handle.

UUIDs

sysobj_uuid()

The function returns a UUID structure associated with an object.

sysobj_uuidstr()

The function returns a printable UUID string associated with an object.

Lookup

sysobj_find()

The function looks up an object by its UUID string, and stores a new handle in the space pointed to by the objp parameter.

sysobj_lookup()

The function provides a more powerful way of looking up objects than the sysobj_find() function. The sysobj_lookup() function does this by using search expressions, described as follows:

Search Expression

The search expression used by the sysobj_lookup() function is contained as a string in the search parameter. The search expression is a number of sets combined with logical operators. Each set in the search expression is a comma-separated list of comparisons. Each comparison has a keyword describing whole or part of an alias or property as its right hand side, and a value to compare it to as its left hand side. Sets, or their combinations can grouped by enclosing them in parentheses ( and ).

Regular expressions may be used in right hand comparison values.

A search expression has the following format:
     search     := set [logicop set ..]
     logicop    := '&&' | '||' | '--'
     set        := expression [, expression ...]
     expression := keyword operator value
     keyword    := 'aliasclass' | 'aliasspace' | 'aliasval' |
                   'propclass' | 'propname' | 'propval'
     operator   := '==' | '!=' | '>' | '<' | '>=' | '=:' | '=:' | '=@'
     value      := string | regexp | integer | floating point | hex

The components of a search expression are described as follows:

Keywords

Keywords can take the following values:

aliasclass

The class under which an object has a specified alias

aliasspace

The namespace in which the alias resides

aliasval

The value of the alias

propclass

The class of a property

propname

The name of a property

propval

The value of a property

Right hand comparison values

Right hand comparison values can take the following formats:

  • Signed integer

  • Floating point value

  • HEX value starting with 0x

  • String value

    A string value is surrounded by single quotes. If a quote needs to be included in the string, it must be escaped by a backslash character that in turn must be escaped by another backslash character. Any other escape sequence is ignored, and removed from the string.

Comparison operators

Comparison operators can take the following values:

==

Equal to

!=

Not equal to

>

Greater than

<

Smaller than

>=

Greater than or equal to

<=

Smaller than or equal to

=:

Compares FMRI string values

=@

Compares devid string values

Logical operators

Logical operators can take the following values

&&

AND (set intersection)

||

OR (set union)

--

DIFF (set difference)

Parameters

obj

The handle of an existing system database object

objp

The pointer to the system object handle that will contain a new handle

class

The primary class of a new object

uuidp

A pointer to an existing UUID or to a UUID to be returned

uuidstr

A caller-allocated space that contains or will contain a printable UUID string

search

The search expression used to match database objects

results

A pointer to an array of sysobj_t handles

nresults

The number of elements in the results parameter

classes

A pointer to an array that consists of classes in the form of strings, and is allocated and returned to the caller

nclasses

The number of elements in the classes parameter

Return Values

These functions return 0 on success and an error value on failure, except for the sysobj_free(), sysobj_uuid() and sysobj_uuidstr() functions, which have no return value.

Errors

These functions fail if:

EINVAL

An invalid argument is specified.

ENOMEM

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

EEXIST

A UUID is passed to the sysobj_create() function when a UUID already exists in the database.

ENOENT

A look up performed by either the sysobj_find() or the sysobj_lookup() function returned no results.

EACCES

The system object db daemon disallowed the operation.

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

Examples

Example 1 Looking Up Objects and Printing Their UUIDS
     /*
      * Look up all objects that are in class 'cloud', have a property
      * with a name that ends in 'size', with a value greater
      * than 1024', and print their UUIDs.
      */

      #include <malloc.h>
      #include <sysobj.h>
      #include <uuid/uuid.h>
      #include <stdio.h>
      #include <stdlib.h>

      ...

      size_t nresults, i;
      sysobj_t *results;
      int ret;
      char uuidstr[UUID_PRINTABLE_STRING_LENGTH];

      ret = sysobj_lookup(
          "aliasclass == 'cloud',propname == '.*size',propval > 1024",
          &results, &nresults);
      if (ret != 0) {
          fprintf(stderr, "sysobj_lookup: %s\n", strerror(ret));
          exit(1);
      }
      for (i = 0; i < nresults; i++) {
          sysobj_uuidstr(results[i], uuidstr);
          printf("UUID: %s\n", uuidstr);
          sysobj_free(results[i]);
      }

      free(results);

Attributes

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

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

See Also

libsysobj(3LIB), sysobj_add_alias(3SYSOBJ), sysobj_add_property(3SYSOBJ), sysobj_event_register(3SYSOBJ), uuid_clear(3UUID), attributes(7)