1pctx_capture(3CPC)CPU Performance Counters Library Functionspctx_capture(3CPC)
2
3
4

NAME

6       pctx_capture,  pctx_create,  pctx_run,  pctx_release  - process context
7       library
8

SYNOPSIS

10       cc [ flag... ] file... −lpctx [ library... ]
11       #include <libpctx.h>
12
13       typedef void (pctx_errfn_t)(const char *fn, const char *fmt, va_list ap);
14
15
16       pctx_t *pctx_create(const char *filename, char *const *argv, void *arg,
17            int verbose, pctx_errfn_t *errfn);
18
19
20       pctx_t *pctx_capture(pid_t pid, void *arg, int verbose,
21            pctx_errfn_t *errfn);
22
23
24       int pctx_run(pctx_t *pctx, uint_t sample, uint_t nsamples,
25            int (*tick)(pctx *, pid_t, id_t, void *));
26
27
28       void pctx_release(pctx_t *pctx);
29
30

DESCRIPTION

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
38   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
45
46       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
52
53       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
59   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
67
68       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
72   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

RETURN VALUES

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
84
85       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

USAGE

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
102
103       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

ATTRIBUTES

111       See attributes(5) for descriptions of the following attributes:
112
113
114
115
116       ┌─────────────────────────────┬─────────────────────────────┐
117       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
118       ├─────────────────────────────┼─────────────────────────────┤
119       │Interface Stability          │Evolving                     │
120       ├─────────────────────────────┼─────────────────────────────┤
121       │MT-Level                     │Unsafe                       │
122       └─────────────────────────────┴─────────────────────────────┘
123

SEE ALSO

125       fork(2),  cpc(3CPC),  pctx_set_events(3CPC),  libpctx(3LIB),   proc(4),
126       attributes(5)
127
128
129
130SunOS 5.11                        13 May 2003               pctx_capture(3CPC)
Impressum