Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sysobj_event_unregister (3SYSOBJ)

Name

sysobj_event_register, sysobj_event_unregister, sysobj_event_watch, sysobj_event_get - managing system object database events

Synopsis

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

Description

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:

SYSOBJ_EV_ADDREMOVE

Objects in the class are added or removed

SYSOBJ_EV_ALIASES

Aliases for an object in the class are added or removed

SYSOBJ_EV_PROPERTIES

Properties for an object in the class are added, changed or removed

SYSOBJ_EV_USER

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.

Parameters

For the sysobj_event() functions:

flags

The options for registration

portfdp

A pointer to an integer that contains a port file descriptor

class

The class of events to watch

mask

The mask of the types of events to watch

evname

The name of a user event

id

The ID of a user event

userdata

The nvlist with data for a user event

evnvlp

The nvlist with arguments for the operation that triggered an event

For the sysobj_nvl() functions:

nvl

The nvlist returned by the sysobj_event_get() function

uuidp

The pointer to a UUID string

classp

The pointer to a string that contains a class name

namespacep

The pointer to a string that contains a namespace name

propp

The pointer to a string that contains a property name

evnamep

The pointer to a string that will contain a user event name

idp

The pointer to a 64-bit integer that contains a user event id

usernvl

The pointer to an nvlist that contains a user data nvlist

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.

EACCES

The system object db daemon disallowed the operation.

E2BIG

The userdata nvlist specified in the sysobj_event_user() function is too big.

EAGAIN

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.

Examples

Example 1 Registering and Watching for Events
#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;
                     }
             }

Attributes

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

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

See Also

port_get(3C), libnvpair(3LIB), libsysobj(3LIB), sysobj_add_alias(3SYSOBJ), sysobj_add_property(3SYSOBJ), sysobj_create(3SYSOBJ), attributes(7)