sysobj_create, sysobj_destroy, sysobj_find, sysobj_lookup, sysobj_uuid, sysobj_uuidstr, sysobj_classes, sysobj_free - look up, create, and destroy system database objects
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);
The following sections state the tasks performed by the functions.
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.
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.
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.
The function frees an unused handle, but does not destroy the database object described by that handle.
The function duplicates a handle, but does not duplicate or add references to the database object described by that handle.
The function returns a UUID structure associated with an object.
The function returns a printable UUID string associated with an object.
The function looks up an object by its UUID string, and stores a new handle in the space pointed to by the objp parameter.
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:
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.
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 can take the following values:
The class under which an object has a specified alias
The namespace in which the alias resides
The value of the alias
The class of a property
The name of a property
The value of a property
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 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 can take the following values
AND (set intersection)
OR (set union)
DIFF (set difference)
The handle of an existing system database object
The pointer to the system object handle that will contain a new handle
The primary class of a new object
A pointer to an existing UUID or to a UUID to be returned
A caller-allocated space that contains or will contain a printable UUID string
The search expression used to match database objects
A pointer to an array of sysobj_t handles
The number of elements in the results parameter
A pointer to an array that consists of classes in the form of strings, and is allocated and returned to the caller
The number of elements in the classes parameter
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.
These functions fail if:
An invalid argument is specified.
Either the library or the system object daemon cannot allocate the memory required for the operation.
A UUID is passed to the sysobj_create() function when a UUID already exists in the database.
A look up performed by either the sysobj_find() or the sysobj_lookup() function returned no results.
The system object db daemon disallowed the operation.
Passing invalid pointers or object handles to any of these functions results in undefined behavior.
/*
* 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);
See attributes(7) for descriptions of the following attributes:
|
libsysobj(3LIB), sysobj_add_alias(3SYSOBJ), sysobj_add_property(3SYSOBJ), sysobj_event_register(3SYSOBJ), uuid_clear(3UUID), attributes(7)