System Event Library Functions
                              syseventsubscribeevent(3SYSEVENT)



NAME
     syseventsubscribeevent,    syseventunsubscribeevent    -
     register or unregister interest in event receipt

SYNOPSIS
     cc  [ flag... ] file... -lsysevent [ library... ]
     #include 

     int syseventsubscribeevent(syseventhandlet *syseventhdl,
          char *eventclass, char **eventsubclasslist,
          int numsubclasses);


     void syseventunsubscribeevent(syseventhandlet *syseventhdl,
          char *eventclass);


PARAMETERS
     eventclass            system event class string


     eventsubclasslist    array of subclass strings


     numsubclasses         number of subclass strings


     syseventhdl           sysevent subscriber handle


DESCRIPTION
     The  syseventsubscribeevent()   function   registers   the
     caller's  interest  in  event notifications belonging to the
     class  eventclass   and   the   subclasses   contained   in
     eventsubclasslist.   The subscriber handle syseventhdl is
     updated with the new subscription and  the  calling  process
     receives  event  notifications from the event handler speci-
     fied in syseventbindhandle.


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


     The numsubclasses argument provides the number of  subclass
     string elements in eventsubclasslist.



SunOS 5.11          Last change: 12 May 2008                    1






System Event Library Functions
                              syseventsubscribeevent(3SYSEVENT)



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


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


     The syseventunsubscribeevent() function removes  the  sub-
     scription  described by eventclass for syseventhdl.  Event
     notifications matching eventclass will not be delivered  to
     the calling process upon return.


     A caller can use the event class ECAL to remove  all  sub-
     scriptions for syseventhdl.


     The library manages all subscription resources.

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


     The syseventunsubscribeevent() function returns no value.

ERORS
     The syseventsubscribeevent() function will fail if:

     EACES    The calling process  has  an  ID  other  than  the
               privileged user.


     EINVAL    The syseventhdl argument is an  invalid  sysevent
               handle.


     ENOMEM    There is insufficient memory available to allocate
               subscription resources.


EXAMPLES
     Example 1 Subscribing for environmental events

       #include 



SunOS 5.11          Last change: 12 May 2008                    2






System Event Library Functions
                              syseventsubscribeevent(3SYSEVENT)



       #include 

       static int32t attrint32;

       #define    CLAS1        "class1"
       #define    CLAS2        "class2"
       #define    SUBCLAS1    "subclass1"
       #define    SUBCLAS2    "subclass2"
       #define    SUBCLAS3    "subclass3"
       #define    MAXSUBCLAS  3

       static void
       eventhandler(syseventt *ev)
       {
           nvlistt *nvlist;

           /*
            * Special processing  for events (CLAS1, SUBCLAS1) and
            * (CLAS2, SUBCLAS3)
            */
           if ((strcmp(CLAS1, syseventgetclassname(ev)) == 0 &&
               strcmp(SUBCLAS1, syseventgetsubclassname(ev)) == 0) 
               (strcmp(CLAS2, syseventgetsubclassname(ev) == 0) &&
               strcmp(SUBCLAS3, syseventgetsubclass(ev)) == 0)) {
               if (syseventgetattrlist(ev, &nvlist) != 0)
                   return;
               if (nvlistlookupint32(nvlist, "myint32attr", &attrint32)
                   != 0)
                   return;

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

       }


       int
       main(int argc, char **argv)
       {
           syseventhandlet *shp;
           const char *subclasslist[MAXSUBCLAS];

           /* Bind event handler and create subscriber handle */
           shp = syseventbindhandle(eventhandler);
           if (shp == NUL)
               exit(1);

           /* Subscribe to all CLAS1 event notifications */
           subclasslist[0] = ECSUBAL;



SunOS 5.11          Last change: 12 May 2008                    3






System Event Library Functions
                              syseventsubscribeevent(3SYSEVENT)



           if (syseventsubscribeevent(shp, CLAS1, subclasslist, 1) != 0) {
               syseventunbindhandle(shp);
               exit(1);
           }

           /* Subscribe to CLAS2 events for subclasses: SUBCLAS1,
            * SUBCLAS2 and SUBCLAS3
            */
           subclasslist[0] = SUBCLAS1;
           subclasslist[1] = SUBCLAS2;
           subclasslist[2] = SUBCLAS3;
           if (syseventsubscribeevent(shp, CLAS2, subclasslist,
               MAXSUBCLAS) != 0) {
               syseventunbindhandle(shp);
               exit(1);
           }

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


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     syseventd(1M),              syseventbindhandle(3SYSEVENT),
     syseventgetattrlist(3SYSEVENT),
     syseventgetclassname(3SYSEVENT),
     syseventgetvendorname(3SYSEVENT), attributes(5)











SunOS 5.11          Last change: 12 May 2008                    4






System Event Library Functions
                              syseventsubscribeevent(3SYSEVENT)






















































SunOS 5.11          Last change: 12 May 2008                    5