sysevent_subscribe_event.3sysevent revision c10c16dec587a0662068f6e2991c29ed3a9db943
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_subscribe_event 3SYSEVENT "24 Jul 2009" "SunOS 5.11" "System Event Library Functions"
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();
 }
}
ATTRIBUTES

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

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityCommitted
MT-LevelMT-Safe
SEE ALSO

syseventd(1M), sysevent_bind_handle(3SYSEVENT), sysevent_get_attr_list(3SYSEVENT), sysevent_get_class_name(3SYSEVENT), sysevent_get_vendor_name(3SYSEVENT), attributes(5)

NOTES

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