man/man3sysevent/sysevent_bind_handle.3sysevent

         te
 Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
 See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 SYSEVENT_BIND_HANDLE 3SYSEVENT "Jul 24, 2009"
 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.