CPU Performance Counters Library Functions  pctxsetevents(3CPC)



NAME
     pctxsetevents - associate callbacks with process events

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

     typedef   enum {
             PCTXNULEVENT = 0,
             PCTXSYSCEXECEVENT,
             PCTXSYSCFORKEVENT,
             PCTXSYSCEXITEVENT,
             PCTXSYSCLWPCREATEVENT,
             PCTXINITLWPEVENT,
             PCTXFINILWPEVENT,
             PCTXSYSCLWPEXITEVENT
     } pctxeventt;

     typedef int pctxsyscexecfnt(pctxt *pctx, pidt pid, idt lwpid,
          char *cmd, void *arg);


     typedef void pctxsyscforkfnt(pctxt *pctx,
          pidt pid, idt lwpid, pidt child, void *arg);


     typedef void pctxsyscexitfnt(pctxt *pctx, pidt pid, idt lwpid,
          void *arg);


     typedef int pctxsysclwpcreatefnt(pctxt *pctx, pidt pid, idt lwpid,
          void *arg);


     typedef int pctxinitlwpfnt(pctxt *pctx, pidt pid, idt lwpid,
          void *arg);


     typedef int pctxfinilwpfnt(pctxt *pctx, pidt pid, idt lwpid,
          void *arg);


     typedef int pctxsysclwpexitfnt(pctxt *pctx, pidt pid, idt lwpid,
          void *arg);


     int pctxsetevents(pctxt *pctx...);


DESCRIPTION
     The pctxsetevents() function allows the caller  (the  con-
     trolling  process)  to express interest in various events in



SunOS 5.11          Last change: 13 May 2003                    1






CPU Performance Counters Library Functions  pctxsetevents(3CPC)



     the controlled process.  See pctxcapture(3CPC) for informa-
     tion  about  how  the controlling process is able to create,
     capture and manipulate the controlled process.


     The pctxsetevents() function takes a pctxt  handle,  fol-
     lowed  by  a  variable  length list of pairs of pctxeventt
     tags and  their  corresponding  handlers,  terminated  by  a
     PCTXNULEVENT tag.


     Most of the events correspond closely to various classes  of
     system  calls, though two additional pseudo-events (initlwp
     and finilwp) are provided to allow callers to perform vari-
     ous  housekeeping  tasks.  The initlwp handler is called as
     soon as the library identifies a new LWP, while finilwp  is
     called  just  before  the  LWP  disappears. Thus the classic
     "hello  world"  program  would  see  an  initlwp  event,  a
     finilwp  event  and  (process)  exit  event, in that order.
     The table below displays the interactions between the states
     of the controlled process and the handlers executed by users
     of the library.



     
     System Calls and pctx Handlers                                                  
    
              System call              Handler                 Comments              
    
              exec,execve             finilwp    Invoked serially on all lwps in the
                                                  process.                           
                                        exec      Only invoked if the  exec()  system
                                                  call succeeded.                    
                                      initlwp    If the exec succeeds, only  invoked
                                                  on   lwp  1.  If  the  exec  fails,
                                                  invoked serially on all lwps in the
                                                  process.                           
    
           fork, vfork, fork1           fork      Only invoked if the  fork()  system
                                                  call succeeded.                    
    
                  exit                finilwp    Invoked on all lwps in the process.
                                        exit          Invoked on the exiting lwp.    
    



     Each of the handlers is passed the caller's opaque handle, a
     pctxt  handle,  the  pid,  and lwpid of the process and lwp
     generating the  event.  The  lwpexit,  and  (process)  exit
     events  are  delivered  before  the  underlying system calls



SunOS 5.11          Last change: 13 May 2003                    2






CPU Performance Counters Library Functions  pctxsetevents(3CPC)



     begin, while the exec, fork, and lwpcreate events are  only
     delivered  after the relevant system calls complete success-
     fully. The exec handler is passed a  string  that  describes
     the  command  being executed. Catching the fork event causes
     the calling process to fork(2), then capture  the  child  of
     the  controlled  process using pctxcapture() before handing
     control to the fork handler.  The  process  is  released  on
     return from the handler.

RETURN VALUES
     Upon successful  completion,  pctxsetevents()  returns  0.
     Otherwise, the function returns -1.

EXAMPLES
     Example 1 HandleExec example.


     This example captures  an  existing  process  whose  process
     identifier  is pid, and arranges to call the HandleExec rou-
     tine when the process performs an exec(2).


       static void
       HandleExec(pctxt *pctx, pidt pid, idt lwpid, char *cmd, void *arg)
       {
            (void) printf("pid %d execed '%s'\n", (int)pid, cmd);
       }
       int
       main()
       {
            ...
            pctx = pctxcapture(pid, NUL, 1, NUL);
            (void) pctxsetevents(pctx,
                  PCTXSYSCEXECEVENT, HandleExec,
                  ...
                  PCTXNULEVENT);
            (void) pctxrun(pctx, 0, 0, NUL);
            pctxrelease(pctx);
       }


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











SunOS 5.11          Last change: 13 May 2003                    3






CPU Performance Counters Library Functions  pctxsetevents(3CPC)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Evolving                    
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     exec(2), exit(2), fork(2),  vfork(2),  fork1(2),  cpc(3CPC),
     libpctx(3LIB), proc(4), attributes(5)











































SunOS 5.11          Last change: 13 May 2003                    4