1pctx_capture(3CPC)CPU Performance Counters Library Functionspctx_capture(3CPC)
2
6 pctx_capture, pctx_create, pctx_run, pctx_release - process context
7 library
8
10 cc [ flag... ] file... −lpctx [ library... ]
11 #include <libpctx.h>
12 typedef void (pctx_errfn_t)(const char *fn, const char *fmt, va_list ap);
14 pctx_t *pctx_create(const char *filename, char *const *argv, void *arg,
17 int verbose, pctx_errfn_t *errfn);
18 pctx_t *pctx_capture(pid_t pid, void *arg, int verbose,
21 pctx_errfn_t *errfn);
22 int pctx_run(pctx_t *pctx, uint_t sample, uint_t nsamples,
25 int (*tick)(pctx *, pid_t, id_t, void *));
26 void pctx_release(pctx_t *pctx);
29
32 This family of functions allows a controlling process (the process that
33 invokes them) to create or capture controlled processes. The functions
34 allow the occurrence of various events of interest in the controlled
35 process to cause the controlled process to be stopped, and to cause
36 callback routines to be invoked in the controlling process.
37 pctx_create() and pctx_capture()
39 There are two ways a process can be acquired by the process context
40 functions. First, a named application can be invoked with the usual
41 argv[] array using pctx_create(), which forks the caller and execs the
42 application in the child. Alternatively, an existing process can be
43 captured by its process ID using pctx_capture().
44 Both functions accept a pointer to an opaque handle, arg; this is saved
47 and treated as a caller-private handle that is passed to the other
48 functions in the library. Both functions accept a pointer to a
49 printf(3C)-like error routine errfn; a default version is provided if
50 NULL is specified.
51 A freshly-created process is created stopped; similarly, a process that
54 has been successfully captured is stopped by the act of capturing it,
55 thereby allowing the caller to specify the handlers that should be
56 called when various events occur in the controlled process. The set of
57 handlers is listed on the pctx_set_events(3CPC) manual page.
58 pctx_run()
60 Once the callback handlers have been set with pctx_set_events(), the
61 application can be set running using pctx_run(). This function starts
62 the event handling loop; it returns only when either the process has
63 exited, the number of time samples has expired, or an error has
64 occurred (for example, if the controlling process is not privileged,
65 and the controlled process has exec-ed a setuid program).
66 Every sample milliseconds the process is stopped and the tick() routine
69 is called so that, for example, the performance counters can be sampled
70 by the caller. No periodic sampling is performed if sample is 0.
71 pctx_release()
73 Once pctx_run() has returned, the process can be released and the
74 underlying storage freed using pctx_release(). Releasing the process
75 will either allow the controlled process to continue (in the case of an
76 existing captured process and its children) or kill the process (if it
77 and its children were created using pctx_create()).
78
80 Upon successful completion, pctx_capture() and pctx_create() return a
81 valid handle. Otherwise, the functions print a diagnostic message and
82 return NULL.
83 Upon successful completion, pctx_run() returns 0 with the controlled
86 process either stopped or exited (if the controlled process has invoked
87 exit(2).) If an error has occurred (for example, if the controlled
88 process has exec-ed a set-ID executable, if certain callbacks have
89 returned error indications, or if the process was unable to respond to
90 proc(4) requests) an error message is printed and the function returns
91 −1.
92
94 Within an event handler in the controlling process, the controlled
95 process can be made to perform various system calls on its behalf. No
96 system calls are directly supported in this version of the API, though
97 system calls are executed by the cpc_pctx family of interfaces in
98 libcpc such as cpc_pctx_bind_event(3CPC). A specially created agent LWP
99 is used to execute these system calls in the controlled process. See
100 proc(4) for more details.
101 While executing the event handler functions, the library arranges for
104 the signals SIGTERM, SIGQUIT, SIGABRT, and SIGINT to be blocked to
105 reduce the likelihood of a keyboard signal killing the controlling
106 process prematurely, thereby leaving the controlled process permanently
107 stopped while the agent LWP is still alive inside the controlled
108 process.
109
111 See attributes(5) for descriptions of the following attributes:
112 ┌─────────────────────────────┬─────────────────────────────┐
117 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
118 ├─────────────────────────────┼─────────────────────────────┤
119 │Interface Stability │Evolving │
120 ├─────────────────────────────┼─────────────────────────────┤
121 │MT-Level │Unsafe │
122 └─────────────────────────────┴─────────────────────────────┘
123
125 fork(2), cpc(3CPC), pctx_set_events(3CPC), libpctx(3LIB), proc(4),
126 attributes(5)
127SunOS 5.11 13 May 2003 pctx_capture(3CPC)