sysobj_event_register, sysobj_event_unregister, sysobj_event_watch, sysobj_event_get - managing system object database events
cc [ flag... ] file... -lsysobj [ library... ]
#include <libnvpair.h>
#include <sysobj.h>
int sysobj_event_register(uint64_t flags, int *portfdp);
int sysobj_event_unregister(void);
int sysobj_event_watch(const char *class, uint64_t mask);
int sysobj_event_user(const char *class, const char *evname,
uint64_t id, nvlist_t *userdata);
int sysobj_event_get(nvlist_t **evnvlp);
int sysobj_nvl__op(nvlist_t *nvl, sysobj_op_t *opp);
int sysobj_nvl_class(nvlist_t *nvl, char **class);
int sysobj_nvl_destroy_args(nvlist_t *nvl, char **uuidp);
int sysobj_nvl_create_args(nvlist_t *nvl, char **uuidp, char **classp);
int sysobj_nvl_add_alias_args(nvlist_t *nvl, char **uuidp, char **classp,
char **namespacep, char **aliasp);
int sysobj_nvl_del_alias_args(nvlist_t *nvl, char **uuidp, char **classp,
char **namespacep, char **aliasp);
int sysobj_nvl_add_property_args(nvlist_t *nvl, char **uuidp,
char **classp, char **propp, nvpair_t **nvpp);
int sysobj_nvl_del_property_args(nvlist_t *nvl, char **uuidp,
char **classp, char **propp);
int sysobj_nvl_event_user_args(nvlist_t *nvl, char **classp,
char **evnamep, uint64_t *idp, nvlist_t **usernvl);
These sysobj_event() family of functions deal with events associated with the system object database that are triggered by a change in the database, or specified by users. These functions produce event information is produced in the form of nvlists. The sysobj_nvl() family of functions can then be used to extract relevant information from those nvlists. Event information is managed by the sysobjd(8) function, and is deleted after a configurable amount of time to prevent excessive memory use. By default, this amount of time is 5 minutes. The sysobj_event() and the sysobj_nvl() families of functions perform the following tasks:
The sysobj_event_register() function registers a process as an event listener. If the flags argument contains the value, SYSOBJ_EVREG_NOWAIT, and if there is no event information to be retrieved, then the sysobj_event_get() function will not block. If the flags argument contains the value, SYSOBJ_EVREG_PORT, then a port file descriptor will be stored in the integer pointed to by the portfdp parameter. For more information on port file descriptors, see the port_create(3C) man page. The stored file descriptor can then be used as an argument to the poll(2) function or the port_get(3C) function or to both functions to wait for events.
The port_get() function returns an event of type, PORTEV_USER. The fields in the port_event_t structure have no meaning, and you need to retrieve information about the event by using the sysobj_event_get() function.
The sysobj_event_unregister() function unregisters a process as an event listener. When a process exits, it is automatically unregistered by the sysobjd(8) function, and any state associated with the process, cleaned up.
The sysobj_event_watch() function sets a mask of events that belong to the class of object specified in the class parameter and that the registered listener wants to be informed of. The following valid mask values can be ORed together:
Objects in the class are added or removed
Aliases for an object in the class are added or removed
Properties for an object in the class are added, changed or removed
User events sent by processes
Changing the event mask does not delete events that are queued.
The sysobj_event_user() function sends a user event for a class of objects. This can be used to inform listeners of events such as the completion of a series of operations, or to coordinate between sysobj database clients. The id parameter specifies a 64bit id value, which is passed as opaque by the sysobjd(8) function. The interpretation is left to clients. Additionally, user-specified data can be passed along as an nvlist.
The sysobj_event_get() function retrieves the head of the event queue for a listener. It blocks waiting for an event, unless the flags argument of the sysobj_event_register() function specifies the value, SYSOBJ_EVREG_NOWAIT. The nvlist describing the event is allocated and returned in the evnvlpp parameter.
The sysobj_nvl() functions can be used to extract information from event nvlists. An event nvlist contains the arguments of the operation that triggered the event. Usually, the first step in extracting nvlist event information is to use the sysobj_nvl_op() function to extract the operation. The operation is specified in the sysobj_op_t enum type, and can have one of these values:
SYSOBJ_CREATE
SYSOBJ_DESTROY
SYSOBJ_LOOKUP
SYSOBJ_ADD_ALIAS
SYSOBJ_DEL_ALIAS
SYSOBJ_ADD_PROPERTY
SYSOBJ_DEL_PROPERTY
SYSOBJ_EVENT_USER
The object class in which the event happened can be retrieved using the sysobj_nvl_class() function. This class will match one of the classes specified as a class to watch. Since an object can be a member of multiple classes, the object class retrieved might not match the class in the operation that actually caused the event.
The arguments to the operation that was extracted in the first step can then be extracted by the applicable sysobj_nvl() function. See the sysobj_create(3SYSOBJ), sysobj_add_alias(3SYSOBJ), and sysobj_add_property(3SYSOBJ) man pages for the arguments passed to these operations.
When the sysobj_nvl() functions return arrays or strings, they remain valid as long as the nvlist passed in remains allocated.
For the sysobj_event() functions:
The options for registration
A pointer to an integer that contains a port file descriptor
The class of events to watch
The mask of the types of events to watch
The name of a user event
The ID of a user event
The nvlist with data for a user event
The nvlist with arguments for the operation that triggered an event
For the sysobj_nvl() functions:
The nvlist returned by the sysobj_event_get() function
The pointer to a UUID string
The pointer to a string that contains a class name
The pointer to a string that contains a namespace name
The pointer to a string that contains a property name
The pointer to a string that will contain a user event name
The pointer to a 64-bit integer that contains a user event id
The pointer to an nvlist that contains a user data nvlist
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.
The system object db daemon disallowed the operation.
The userdata nvlist specified in the sysobj_event_user() function is too big.
The sysobj_event_get() function found no events in the queue, and SYSOBJ_EVREG_NOWAIT was specified when registering as an event listener.
Passing invalid pointers to any of these functions results in undefined behavior.
#include <sysobj.h>
#include <libnvpair.h>
#include <port.h>
#include <stdio.h>
/*
* Error handling omitted for simplicity.
*/
void
handle_device_events(void)
{
int port;
nvlist_t *nvl;
port_event_t pe;
char *uuid, *class, *watchedclass;
sysobj_op_t op;
/*
* Register for events for the device class of object.
*/
sysobj_event_register(SYSOBJ_EVREG_PORT, &port);
/*
* Watch for add/remove events.
*/
sysobj_event_watch("device", SYSOBJ_EV_ADDREMOVE);
sysobj_event_watch("device-minor", SYSOBJ_EV_ADDREMOVE);
for (;;) {
port_get(port, &pe, NULL);
sysobj_event_get(&nvl);
sysobj_nvl_op(nvl, &op);
sysobj_nvl_class(nvl, &watchedclass);
printf("event in class %s:\n", watchedclass);
switch (op) {
case SYSOBJ_CREATE:
sysobj_nvl_create_args(nvl, &uuid, &class);
printf("UUID %s created\n", uuid);
break;
case SYSOBJ_DESTROY:
sysobj_nvl_destroy_args(nvl, &uuid);
printf("UUID %s destroyed\n", uuid);
break;
}
}
See attributes(7) for descriptions of the following attributes:
|
port_get(3C), libnvpair(3LIB), libsysobj(3LIB), sysobj_add_alias(3SYSOBJ), sysobj_add_property(3SYSOBJ), sysobj_create(3SYSOBJ), attributes(7)