svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
sysobj_event_register(3sysobj)
System Object Database sysobj_event_register(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 informa‐
tion 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 reg‐
istered listener wants to be informed of. The following valid mask val‐
ues 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 argu‐
ment 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:
o SYSOBJ_CREATE
o SYSOBJ_DESTROY
o SYSOBJ_LOOKUP
o SYSOBJ_ADD_ALIAS
o SYSOBJ_DEL_ALIAS
o SYSOBJ_ADD_PROPERTY
o SYSOBJ_DEL_PROPERTY
o 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 mul‐
tiple 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_prop‐
erty(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 descrip‐
tor
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:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityVolatile _ MT-LevelMT-Safe
SEE ALSO
port_get(3C), libnvpair(3LIB), libsysobj(3LIB),
sysobj_add_alias(3SYSOBJ), sysobj_add_property(3SYSOBJ), sysobj_cre‐
ate(3SYSOBJ), attributes(7)
Oracle Solaris 11.4 27 Nov 2017
sysobj_event_register(3SYSOBJ)