1sysevent_subscribe_event(S3ySsYtSeEmVEENvTe)nt LibrarysyFsuenvcetnito_nssubscribe_event(3SYSEVENT)
2
3
4

NAME

6       sysevent_subscribe_event,   sysevent_unsubscribe_event  -  register  or
7       unregister interest in event receipt
8

SYNOPSIS

10       cc  [ flag... ] file... -lsysevent [ library... ]
11       #include <libsysevent.h>
12
13       int sysevent_subscribe_event(sysevent_handle_t *sysevent_hdl,
14            char *event_class, char **event_subclass_list,
15            int num_subclasses);
16
17
18       void sysevent_unsubscribe_event(sysevent_handle_t *sysevent_hdl,
19            char *event_class);
20
21

PARAMETERS

23       event_class            system event class string
24
25
26       event_subclass_list    array of subclass strings
27
28
29       num_subclasses         number of subclass strings
30
31
32       sysevent_hdl           sysevent subscriber handle
33
34

DESCRIPTION

36       The sysevent_subscribe_event() function registers the caller's interest
37       in  event notifications belonging to the class event_class and the sub‐
38       classes contained in event_subclass_list.  The subscriber handle sysev‐
39       ent_hdl  is  updated  with the new subscription and the calling process
40       receives event notifications from the event handler specified in sysev‐
41       ent_bind_handle.
42
43
44       System   events  matching  event_class  and  a  subclass  contained  in
45       event_subclass_list published after  the  caller  returns  from  sysev‐
46       ent_subscribe_event()  are  guaranteed  to  be delivered to the calling
47       process.  Matching system events published and queued prior to  a  call
48       to  sysevent_subscribe_event()  may be delivered to the process's event
49       handler.
50
51
52       The num_subclasses argument provides the number of subclass string ele‐
53       ments in event_subclass_list.
54
55
56       A  caller  can  use  the  event  class EC_ALL to subscribe to all event
57       classes and subclasses. The event class EC_SUB_ALL can be used to  sub‐
58       scribe to all subclasses within a given event class.
59
60
61       Subsequent calls to sysevent_subscribe_event() are allowed to add addi‐
62       tional classes or subclasses.   To  remove  an  existing  subscription,
63       sysevent_unsubscribe_event() must be used to remove the subscription.
64
65
66       The  sysevent_unsubscribe_event()  function  removes  the  subscription
67       described by event_class for sysevent_hdl.  Event notifications  match‐
68       ing  event_class  will  not  be  delivered  to the calling process upon
69       return.
70
71
72       A caller can use the event class EC_ALL to remove all subscriptions for
73       sysevent_hdl.
74
75
76       The library manages all subscription resources.
77

RETURN VALUES

79       The  sysevent_subscribe_event()  function returns 0 if the subscription
80       is successful. Otherwise, −1 is returned and errno is set  to  indicate
81       the error.
82
83
84       The sysevent_unsubscribe_event() function returns no value.
85

ERRORS

87       The sysevent_subscribe_event() function will fail if:
88
89       EACCES    The calling process has an ID other than the privileged user.
90
91
92       EINVAL    The sysevent_hdl argument is an invalid sysevent handle.
93
94
95       ENOMEM    There  is insufficient memory available to allocate subscrip‐
96                 tion resources.
97
98

EXAMPLES

100       Example 1 Subscribing for environmental events
101
102         #include <libsysevent.h>
103         #include <sys/nvpair.h>
104
105         static int32_t attr_int32;
106
107         #define    CLASS1        "class1"
108         #define    CLASS2        "class2"
109         #define    SUBCLASS_1    "subclass_1"
110         #define    SUBCLASS_2    "subclass_2"
111         #define    SUBCLASS_3    "subclass_3"
112         #define    MAX_SUBCLASS  3
113
114         static void
115         event_handler(sysevent_t *ev)
116         {
117             nvlist_t *nvlist;
118
119             /*
120              * Special processing  for events (CLASS1, SUBCLASS_1) and
121              * (CLASS2, SUBCLASS_3)
122              */
123             if ((strcmp(CLASS1, sysevent_get_class_name(ev)) == 0 &&
124                 strcmp(SUBCLASS_1, sysevent_get_subclass_name(ev)) == 0) ||
125                 (strcmp(CLASS2, sysevent_get_subclass_name(ev) == 0) &&
126                 strcmp(SUBCLASS_3, sysevent_get_subclass(ev)) == 0)) {
127                 if (sysevent_get_attr_list(ev, &nvlist) != 0)
128                     return;
129                 if (nvlist_lookup_int32(nvlist, "my_int32_attr", &attr_int32)
130                     != 0)
131                     return;
132
133                 /* Event Processing */
134             } else {
135                 /* Event Processing */
136             }
137
138         }
139
140
141         int
142         main(int argc, char **argv)
143         {
144             sysevent_handle_t *shp;
145             const char *subclass_list[MAX_SUBCLASS];
146
147             /* Bind event handler and create subscriber handle */
148             shp = sysevent_bind_handle(event_handler);
149             if (shp == NULL)
150                 exit(1);
151
152             /* Subscribe to all CLASS1 event notifications */
153             subclass_list[0] = EC_SUB_ALL;
154             if (sysevent_subscribe_event(shp, CLASS1, subclass_list, 1) != 0) {
155                 sysevent_unbind_handle(shp);
156                 exit(1);
157             }
158
159             /* Subscribe to CLASS2 events for subclasses: SUBCLASS_1,
160              * SUBCLASS_2 and SUBCLASS_3
161              */
162             subclass_list[0] = SUBCLASS_1;
163             subclass_list[1] = SUBCLASS_2;
164             subclass_list[2] = SUBCLASS_3;
165             if (sysevent_subscribe_event(shp, CLASS2, subclass_list,
166                 MAX_SUBCLASS) != 0) {
167                 sysevent_unbind_handle(shp);
168                 exit(1);
169             }
170
171             for (;;) {
172                 (void) pause();
173             }
174         }
175
176

ATTRIBUTES

178       See attributes(5) for descriptions of the following attributes:
179
180
181
182
183       ┌─────────────────────────────┬─────────────────────────────┐
184       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
185       ├─────────────────────────────┼─────────────────────────────┤
186       │Interface Stability          │Committed                    │
187       ├─────────────────────────────┼─────────────────────────────┤
188       │MT-Level                     │MT-Safe                      │
189       └─────────────────────────────┴─────────────────────────────┘
190

SEE ALSO

192       syseventd(1M),         sysevent_bind_handle(3SYSEVENT),          sysev‐
193       ent_get_attr_list(3SYSEVENT),       sysevent_get_class_name(3SYSEVENT),
194       sysevent_get_vendor_name(3SYSEVENT), attributes(5)
195

NOTES

197       The libsysevent interfaces do not work at all in non-global zones.
198
199
200
201SunOS 5.11                        24 Jul 200s9ysevent_subscribe_event(3SYSEVENT)
Impressum