Manual Pages for UNIX Operating System command usage for man pctx_set_events

CPU Performance Counters Library Functions  pctx_set_events(3CPC)



NAME
     pctx_set_events - associate callbacks with process events

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

     typedef   enum {
             PCTX_NULL_EVENT = 0,
             PCTX_SYSC_EXEC_EVENT,
             PCTX_SYSC_FORK_EVENT,
             PCTX_SYSC_EXIT_EVENT,
             PCTX_SYSC_LWP_CREATE_EVENT,
             PCTX_INIT_LWP_EVENT,
             PCTX_FINI_LWP_EVENT,
             PCTX_SYSC_LWP_EXIT_EVENT
     } pctx_event_t;

     typedef int pctx_sysc_execfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          char *cmd, void *arg);


     typedef void pctx_sysc_forkfn_t(pctx_t *pctx,
          pid_t pid, id_t lwpid, pid_t child, void *arg);


     typedef void pctx_sysc_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          void *arg);


     typedef int pctx_sysc_lwp_createfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          void *arg);


     typedef int pctx_init_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          void *arg);


     typedef int pctx_fini_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          void *arg);


     typedef int pctx_sysc_lwp_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
          void *arg);


     int pctx_set_events(pctx_t *pctx...);


DESCRIPTION
     The pctx_set_events() 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  pctx_set_events(3CPC)



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


     The pctx_set_events() function takes a pctx_t  handle,  fol-
     lowed  by  a  variable  length list of pairs of pctx_event_t
     tags and  their  corresponding  handlers,  terminated  by  a
     PCTX_NULL_EVENT tag.


     Most of the events correspond closely to various classes  of
     system  calls, though two additional pseudo-events (init_lwp
     and fini_lwp) are provided to allow callers to perform vari-
     ous  housekeeping  tasks.  The init_lwp handler is called as
     soon as the library identifies a new LWP, while fini_lwp  is
     called  just  before  the  LWP  disappears. Thus the classic
     "hello  world"  program  would  see  an  init_lwp  event,  a
     fini_lwp  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          |   fini_lwp   | Invoked serially on all lwps in the|
    |                               |              | process.                           |
    |                               |     exec     | Only invoked if the  exec()  system|
    |                               |              | call succeeded.                    |
    |                               |   init_lwp   | 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             |   fini_lwp   | 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
     pctx_t  handle,  the  pid,  and lwpid of the process and lwp
     generating the  event.  The  lwp_exit,  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  pctx_set_events(3CPC)



     begin, while the exec, fork, and lwp_create 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 pctx_capture() before handing
     control to the fork handler.  The  process  is  released  on
     return from the handler.

RETURN VALUES
     Upon successful  completion,  pctx_set_events()  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(pctx_t *pctx, pid_t pid, id_t lwpid, char *cmd, void *arg)
       {
            (void) printf("pid %d execed '%s'\n", (int)pid, cmd);
       }
       int
       main()
       {
            ...
            pctx = pctx_capture(pid, NULL, 1, NULL);
            (void) pctx_set_events(pctx,
                  PCTX_SYSC_EXEC_EVENT, HandleExec,
                  ...
                  PCTX_NULL_EVENT);
            (void) pctx_run(pctx, 0, 0, NULL);
            pctx_release(pctx);
       }


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











SunOS 5.11          Last change: 13 May 2003                    3






CPU Performance Counters Library Functions  pctx_set_events(3CPC)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | 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