SunOS man pages


	www.sun.com	docs.sun.com \| \| \|

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Introduction to Library Functions

sysevent_subscribe_event(3SYSEVENT)

PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
EXAMPLES
ATTRIBUTES
SEE ALSO

NAME

sysevent_subscribe_event, sysevent_unsubscribe_event - register or unregister interest in event receipt

SYNOPSIS

cc [flag ...] file ... -l [library ...] #include <libsysevent.h> int sysevent_subscribe_event(sysevent_handle_t *sysevent_hdl, char *event_class, char **event_subclass_list, int num_subclasses);

void sysevent_unsubscribe_event(sysevent_handle_t *sysevent_hdl, char *event_class);

PARAMETERS

event_class: system event class string
event_subclass_list: array of subclass strings
num_subclasses: number of subclass strings
sysevent_hdl: sysevent subscriber handle

The sysevent_subscribe_event() function registers the caller's interest in event notifications belonging to the class event_class and the subclasses contained in event_subclass_list. The subscriber handle sysevent_hdl is updated with the new subscription and the calling process receives event notifications from the event handler specified in sysevent_bind_handle.

System events matching event_class and a subclass contained in event_subclass_list published after the caller returns from sysevent_subscribe_event() are guaranteed to be delivered to the calling process. Matching system events published and queued prior to a call to sysevent_subscribe_event() may be delivered to the process's event handler.

The num_subclasses argument provides the number of subclass string elements in event_subclass_list.

A caller can use the event class SE_ALL_CLASSES to subscribe to all event classes and subclasses. The event class SE_ALL_SUBCLASSES can be used to subscribe to all subclasses within a given event class.

Subsequent calls to sysevent_subscribe_event() are allowed to add additional classes or subclasses. To remove an existing subscription, sysevent_unsubscribe_event() must be used to remove the subscription.

The sysevent_unsubscribe_event() function removes the subscription described by event_class for sysevent_hdl. Event notifications matching event_class will not be delivered to the calling process upon return.

A caller can use the event class SE_ALL_CLASSES to remove all subscriptions for sysevent_hdl.

The library manages all subscription resources.

RETURN VALUES

The sysevent_subscribe_event() function returns 0 if the subscription is successful. Otherwise, -1 is returned and errno is set to indicate the error.

The sysevent_unsubscribe_event() function returns no value.

ERRORS

The sysevent_subscribe_event() function will fail if:

EACCESS: The calling process has an ID other than the privileged user.
EINVAL: The sysevent_hdl argument is an invalid sysevent handle.
ENOMEM: There is insufficient memory available to allocate subscription resources.

EXAMPLES

Example 1. Subscribing for DR and environmental events

/* ARGSUSED */
void
event_handler(sysevent_t *ev)
{
        int32_t state;
        nvlist_t *nv_list;

        if (strcmp(EC_DR, sysevent_get_class_name(ev)) == 0 &&
            strcmp(ESC_AP_STATE_CHANGE,
            sysevent_get_subclass_name(ev)) == 0) {

                /* Initiate DR activity */

                return;

        }

        if (strcmp(EC_ENV, sysevent_get_class_name(ev)) == 0) {
                if (sysevent_get_attr_list(ev, &nvlist) != 0) {
                        return;
                }

                if (nvlist_lookup_int32(nvlist, ENV_FRU_STATE,
                    &state) != 0) {
                        nvlist_free(nvlist);
                        return;
                }

                if (state == ENV_FAILED) {

                        /* Initiate FRU shutdown */

                }
                nvlist_free(nvlist);
        }        
}
 
#define        MAX_SUBCLASS        3
 
void
main(int argc, char **argv)
{
        sysevent_handle_t *shp;
        char *subclass_list[MAX_SUBCLASS];
 
        /* Bind event handler and create subscriber handle */
        shp = sysevent_bind_handle(event_handler);
        if (shp == NULL)
                exit(1);
 
        /* Subscribe to all DR event notifications */
        subclass_list[0] = SE_ALL_SUBCLASSES;
        if (sysevent_subscribe_event(shp, EC_DR, &subclass_list,
            1) != 0) {
                sysevent_unbind_handle(shp);
                exit(1);
        }
 
        /* Subscribe to power, fan, and temp environmental alerts */
        subclass_list[0] = ESC_ENV_POWER;
        subclass_list[1] = ESC_ENV_FAN;
        subclass_list[1] = ESC_ENV_TEMP;
        if (sysevent_subscribe_event(shp, EC_ENV, &subclass_list,
            MAX_SUBCLASS) != 0) {
                sysevent_unbind_handle(shp);
                exit(1);
        }
 
        for (;;) {
                (void) pause();
        }         
}

ATTRIBUTES

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

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