1pctx_set_events(3CPCCP)U Performance Counters Library Functiopncstx_set_events(3CPC)
2
3
4

NAME

6       pctx_set_events - associate callbacks with process events
7

SYNOPSIS

9       cc [ flag... ] file... −lpctx [ library... ]
10       #include <libpctx.h>
11
12       typedef   enum {
13               PCTX_NULL_EVENT = 0,
14               PCTX_SYSC_EXEC_EVENT,
15               PCTX_SYSC_FORK_EVENT,
16               PCTX_SYSC_EXIT_EVENT,
17               PCTX_SYSC_LWP_CREATE_EVENT,
18               PCTX_INIT_LWP_EVENT,
19               PCTX_FINI_LWP_EVENT,
20               PCTX_SYSC_LWP_EXIT_EVENT
21       } pctx_event_t;
22
23       typedef int pctx_sysc_execfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
24            char *cmd, void *arg);
25
26
27       typedef void pctx_sysc_forkfn_t(pctx_t *pctx,
28            pid_t pid, id_t lwpid, pid_t child, void *arg);
29
30
31       typedef void pctx_sysc_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
32            void *arg);
33
34
35       typedef int pctx_sysc_lwp_createfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
36            void *arg);
37
38
39       typedef int pctx_init_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
40            void *arg);
41
42
43       typedef int pctx_fini_lwpfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
44            void *arg);
45
46
47       typedef int pctx_sysc_lwp_exitfn_t(pctx_t *pctx, pid_t pid, id_t lwpid,
48            void *arg);
49
50
51       int pctx_set_events(pctx_t *pctx...);
52
53

DESCRIPTION

55       The  pctx_set_events()  function  allows  the  caller  (the controlling
56       process) to express  interest  in  various  events  in  the  controlled
57       process.  See pctx_capture(3CPC) for information about how the control‐
58       ling process is able to create, capture and manipulate  the  controlled
59       process.
60
61
62       The  pctx_set_events()  function  takes  a pctx_t handle, followed by a
63       variable length list of pairs of pctx_event_t  tags  and  their  corre‐
64       sponding handlers, terminated by a PCTX_NULL_EVENT tag.
65
66
67       Most  of  the  events  correspond  closely to various classes of system
68       calls, though two additional pseudo-events (init_lwp and fini_lwp)  are
69       provided  to  allow callers to perform various housekeeping tasks.  The
70       init_lwp handler is called as soon as the library identifies a new LWP,
71       while fini_lwp is called just before the LWP disappears. Thus the clas‐
72       sic "hello world" program would see  an  init_lwp  event,  a   fini_lwp
73       event  and  (process) exit event, in that order.   The table below dis‐
74       plays the interactions between the states of the controlled process and
75       the handlers executed by users of the library.
76
77
78
79
80       ┌───────────────────────────────┬──────────────┬────────────────────────────────────┐
81       │System Calls and pctx Handlers │              │                                    │
82       ├───────────────────────────────┼──────────────┼────────────────────────────────────┤
83       │         System call           │   Handler    │             Comments               │
84       ├───────────────────────────────┼──────────────┼────────────────────────────────────┤
85exec,execve           fini_lwp    │Invoked serially on all lwps in the │
86       │                               │              │process.                            │
87       │                               │    exec      │Only invoked if the  exec()  system │
88       │                               │              │call succeeded.                     │
89       │                               │  init_lwp    │If  the exec succeeds, only invoked │
90       │                               │              │on  lwp  1.  If  the  exec   fails, │
91       │                               │              │invoked serially on all lwps in the │
92       │                               │              │process.                            │
93       ├───────────────────────────────┼──────────────┼────────────────────────────────────┤
94fork, vfork, fork1       fork      │Only invoked if the  fork()  system │
95       │                               │              │call succeeded.                     │
96       ├───────────────────────────────┼──────────────┼────────────────────────────────────┤
97exit              fini_lwp    │Invoked on all lwps in the process. │
98       │                               │    exit      │    Invoked on the exiting lwp.     │
99       └───────────────────────────────┴──────────────┴────────────────────────────────────┘
100
101
102       Each  of  the  handlers  is passed the caller's opaque handle, a pctx_t
103       handle, the pid, and lwpid of the process and lwp generating the event.
104       The lwp_exit, and (process) exit events are delivered before the under‐
105       lying system calls begin, while the exec, fork, and  lwp_create  events
106       are  only  delivered  after the relevant system calls complete success‐
107       fully. The exec handler is passed a string that describes  the  command
108       being  executed.  Catching the fork event causes the calling process to
109       fork(2), then  capture  the  child  of  the  controlled  process  using
110       pctx_capture() before handing control to the fork handler.  The process
111       is released on return from the handler.
112

RETURN VALUES

114       Upon successful completion, pctx_set_events()  returns  0.   Otherwise,
115       the function returns -1.
116

EXAMPLES

118       Example 1 HandleExec example.
119
120
121       This  example  captures an existing process whose process identifier is
122       pid, and arranges to call the HandleExec routine when the process  per‐
123       forms an exec(2).
124
125
126         static void
127         HandleExec(pctx_t *pctx, pid_t pid, id_t lwpid, char *cmd, void *arg)
128         {
129              (void) printf("pid %d execed '%s'\n", (int)pid, cmd);
130         }
131         int
132         main()
133         {
134              ...
135              pctx = pctx_capture(pid, NULL, 1, NULL);
136              (void) pctx_set_events(pctx,
137                    PCTX_SYSC_EXEC_EVENT, HandleExec,
138                    ...
139                    PCTX_NULL_EVENT);
140              (void) pctx_run(pctx, 0, 0, NULL);
141              pctx_release(pctx);
142         }
143
144

ATTRIBUTES

146       See attributes(5) for descriptions of the following attributes:
147
148
149
150
151       ┌─────────────────────────────┬─────────────────────────────┐
152       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
153       ├─────────────────────────────┼─────────────────────────────┤
154       │Interface Stability          │Evolving                     │
155       ├─────────────────────────────┼─────────────────────────────┤
156       │MT-Level                     │Unsafe                       │
157       └─────────────────────────────┴─────────────────────────────┘
158

SEE ALSO

160       exec(2),    exit(2),    fork(2),    vfork(2),    fork1(2),   cpc(3CPC),
161       libpctx(3LIB), proc(4), attributes(5)
162
163
164
165SunOS 5.11                        13 May 2003            pctx_set_events(3CPC)
Impressum