SYSEVENT_BIND_HANDLE(3SYSEVENT) System Event Library Functions

NAME

sysevent_bind_handle, sysevent_unbind_handle - bind or unbind
subscriber handle

SYNOPSIS

cc [flag...] file ... -lsysevent [library ...]
#include <libsysevent.h>

sysevent_handle_t *sysevent_bind_handle(void (*event_handler)
(sysevent_t *ev));


void sysevent_unbind_handle(sysevent_handle_t *sysevent_hdl);

PARAMETERS

ev
pointer to sysevent buffer handle


event_handler
pointer to an event handling function


sysevent_hdl
pointer to a sysevent subscriber handle

DESCRIPTION

The sysevent_bind_handle() function allocates memory associated with
a subscription handle and binds it to the caller's event_handler.
The event_handler is invoked during subsequent system event
notifications once a subscription has been made with
sysevent_subscribe_event(3SYSEVENT).


The system event is represented by the argument ev and is passed as
an argument to the invoked event delivery function, event_handler.


Additional threads are created to service communication between
syseventd(8) and the calling process and to run the event handler
routine, event_handler.


The sysevent_unbind_handle() function deallocates memory and other
resources associated with a subscription handle and deactivates all
system event notifications for the calling process. All event
notifications are guaranteed to stop upon return from
sysevent_unbind_handle().

RETURN VALUES

The sysevent_bind_handle() function returns a valid sysevent
subscriber handle if the handle is successfully allocated.
Otherwise, NULL is returned and errno is set to indicate the error.


The sysevent_unbind_handle() function returns no value.

ERRORS

The sysevent_bind_handle() function will fail if:

EACCES
The calling process has an ID other than the privileged
user.


EBUSY
There are no resources available.


EINVAL
The pointer to the function event_handler is NULL.


EMFILE
The process has too many open descriptors.


ENOMEM
There are insufficient resources to allocate the handle.

ATTRIBUTES

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


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO

sysevent_subscribe_event(3SYSEVENT), attributes(7), syseventd(8)

NOTES

Event notifications are revoked by syseventd when the bound process
dies. Event notification is suspended if a signal is caught and
handled by the event_handler thread. Event notification is also
suspended when the calling process attempts to use fork(2) or
fork1(2). Event notifications might be lost during suspension
periods.


The libsysevent interfaces do not work at all in non-global zones.

July 24, 2009
SYSEVENT_BIND_HANDLE(3SYSEVENT)