Проект OpenNet: MAN sysevent_subscribe_event (3) Библиотечные вызовы (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

sysevent_subscribe_event (3)

>> sysevent_subscribe_event (3) ( Solaris man: Библиотечные вызовы )

NAME

sysevent_subscribe_event, sysevent_unsubscribe_event - register or unregister interest in event receipt

SYNOPSIS

cc  [ flag... ] file... -lsysevent [ 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

DESCRIPTION

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 EC_ALL to subscribe to all event classes and subclasses. The event class EC_SUB_ALL 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 EC_ALL 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:

EACCES

: 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 environmental events

#include <libsysevent.h>
#include <sys/nvpair.h>

static int32_t attr_int32;

#define    CLASS1        "class1"
#define    CLASS2        "class2"
#define    SUBCLASS_1    "subclass_1"
#define    SUBCLASS_2    "subclass_2"
#define    SUBCLASS_3    "subclass_3"
#define    MAX_SUBCLASS  3

static void
event_handler(sysevent_t *ev)
{
   nvlist_t *nvlist;

   /*
    * Special processing  for events (CLASS1, SUBCLASS_1) and
    * (CLASS2, SUBCLASS_3)
    */  
   if ((strcmp(CLASS1, sysevent_get_class_name(ev)) == 0 &&
       strcmp(SUBCLASS_1, sysevent_get_subclass_name(ev)) == 0) ||
       (strcmp(CLASS2, sysevent_get_subclass_name(ev) == 0) &&
       strcmp(SUBCLASS_3, sysevent_get_subclass(ev)) == 0)) {
       if (sysevent_get_attr_list(ev, &nvlist) != 0)
           return;
       if (nvlist_lookup_int32(nvlist, "my_int32_attr", &attr_int32)
           != 0)
           return;

       /* Event Processing */
   } else {
       /* Event Processing */
   }

}


int
main(int argc, char **argv)
{
   sysevent_handle_t *shp;
   const 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 CLASS1 event notifications */
   subclass_list[0] = EC_SUB_ALL;
   if (sysevent_subscribe_event(shp, CLASS1, subclass_list, 1) != 0) {
       sysevent_unbind_handle(shp);
       exit(1);
   }

   /* Subscribe to CLASS2 events for subclasses: SUBCLASS_1,
    * SUBCLASS_2 and SUBCLASS_3
    */  
   subclass_list[0] = SUBCLASS_1;
   subclass_list[1] = SUBCLASS_2;
   subclass_list[2] = SUBCLASS_3;
   if (sysevent_subscribe_event(shp, CLASS2, subclass_list,
       MAX_SUBCLASS) != 0) {
       sysevent_unbind_handle(shp);
       exit(1);
   }

   for (;;) {
       (void) pause();
   }
}