| blob | 0526dafb30f37b6202fbc36c1d451e41044eca31 |
1 '\" te
2 .\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH TNFCTL_PID_OPEN 3TNF "Mar 1, 2004"
7 .SH NAME
8 tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue \- interfaces for direct
9 probe and process control for another process
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
14 #include <tnf/tnfctl.h>
16 \fBtnfctl_errcode_t\fR \fBtnfctl_pid_open\fR(\fBpid_t\fR \fIpid\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR);
17 .fi
19 .LP
20 .nf
21 \fBtnfctl_errcode_t\fR \fBtnfctl_exec_open\fR(\fBconst char *\fR\fIpgm_name\fR,
22 \fBchar * const *\fR\fIargv\fR, \fBchar * const *\fR\fIenvp\fR,
23 \fBconst char *\fR\fIlibnfprobe_path\fR, \fBconst char *\fR\fIld_preload\fR,
24 \fBtnfctl_handle_t **\fR\fIret_val\fR);
25 .fi
27 .LP
28 .nf
29 \fBtnfctl_errcode_t\fR \fBtnfctl_continue\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
30 \fBtnfctl_event_t *\fR\fIevt\fR, \fBtnfctl_handle_t **\fR\fIchild_hndl\fR);
31 .fi
33 .SH DESCRIPTION
34 .sp
35 .LP
36 The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and
37 \fBtnfctl_continue()\fR functions create handles to control probes in another
38 process (direct process probe control). Either \fBtnfctl_pid_open()\fR or
39 \fBtnfctl_exec_open()\fR will return a handle in \fIret_val\fR that can be used
40 for probe control. On return of these calls, the process is stopped.
41 \fBtnfctl_continue()\fR allows the process specified by \fIhndl\fR to continue
42 execution.
43 .sp
44 .LP
45 The \fBtnfctl_pid_open()\fR function attaches to a running process with process
46 id of \fIpid\fR. The process is stopped on return of this call. The
47 \fBtnfctl_pid_open()\fR function returns an error message if \fIpid\fR is the
48 same as the calling process. See \fBtnfctl_internal_open\fR(3TNF) for
49 information on internal process probe control. A pointer to an opaque handle is
50 returned in \fIret_val\fR, which can be used to control the process and the
51 probes in the process. The target process must have \fBlibtnfprobe.so.1\fR
52 (defined in <\fBtnf/tnfctl.h\fR> as macro \fBTNFCTL_LIBTNFPROBE)\fR linked in
53 for probe control to work.
54 .sp
55 .LP
56 The \fBtnfctl_exec_open()\fR function is used to \fBexec\fR(2) a program and
57 obtain a probe control handle. For probe control to work, the process image to
58 be \fBexec\fR'd must load \fBlibtnfprobe.so.1\fR. The \fBtnfctl_exec_open()\fR
59 function makes it simple for the library to be loaded at process start up time.
60 The \fIpgm_name\fR argument is the command to \fBexec\fR. If \fIpgm_name\fR is
61 not an absolute path, then the \fB$PATH\fR environment variable is used to
62 find the \fIpgm_name\fR. \fIargv\fR is a null-terminated argument pointer, that
63 is, it is a null-terminated array of pointers to null-terminated strings. These
64 strings constitute the argument list available to the new process image. The
65 \fIargv\fR argument must have at least one member, and it should point to a
66 string that is the same as \fIpgm_name\fR. See \fBexecve\fR(2). The
67 \fIlibnfprobe_path\fR argument is an optional argument, and if set, it should
68 be the path to the directory that contains \fBlibtnfprobe.so.1\fR. There is no
69 need for a trailing "/" in this argument. This argument is useful if
70 \fBlibtnfprobe.so.1\fR is not installed in \fB/usr/lib\fR. \fIld_preload\fR is
71 a space-separated list of libraries to preload into the target program. This
72 string should follow the syntax guidelines of the \fBLD_PRELOAD\fR environment
73 variable. See \fBld.so.1\fR(1). The following illustrates how strings are
74 concatenated to form the \fBLD_PRELOAD\fR environment variable in the new
75 process image:
76 .sp
77 .in +2
78 .nf
79 <current value of $LD_PRELOAD> + <space> +
80 libtnfprobe_path + "/libtnfprobe.so.1" +<space> +
81 ld_preload
82 .fi
83 .in -2
85 .sp
86 .LP
87 This option is useful for preloading interposition libraries that have probes
88 in them.
89 .sp
90 .LP
91 \fIenvp\fR is an optional argument, and if set, it is used for the environment
92 of the target program. It is a null-terminated array of pointers to
93 null-terminated strings. These strings constitute the environment of the new
94 process image. See \fBexecve\fR(2). If \fIenvp\fR is set, it overrides
95 \fIld_preload\fR. In this case, it is the caller's responsibility to ensure
96 that \fBlibtnfprobe.so.1\fR is loaded into the target program. If \fIenvp\fR
97 is not set, the new process image inherits the environment of the calling
98 process, except for \fBLD_PRELOAD\fR.
99 .sp
100 .LP
101 The \fIret_val\fR argument is the handle that can be used to control the
102 process and the probes within the process. Upon return, the process is stopped
103 before any user code, including \fB\&.init\fR sections, has been executed.
104 .sp
105 .LP
106 The \fBtnfctl_continue()\fR function is a blocking call and lets the target
107 process referenced by \fIhndl\fR continue running. It can only be used on
108 handles returned by \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR
109 (direct process probe control). It returns when the target stops; the reason
110 that the process stopped is returned in \fIevt\fR. This call is interruptible
111 by signals. If it is interrupted, the process is stopped, and
112 \fBTNFCTL_EVENT_EINTR\fR is returned in \fIevt\fR. The client of this library
113 will have to decide which signal implies a stop to the target and catch that
114 signal. Since a signal interrupts \fBtnfctl_continue()\fR, it will return, and
115 the caller can decide whether or not to call \fBtnfctl_continue()\fR again.
116 .sp
117 .LP
118 \fBtnfctl_continue()\fR returns with an event of \fBTNFCTL_EVENT_DLOPEN\fR,
119 \fBTNFCTL_EVENT_DLCLOSE\fR, \fBTNFCTL_EVENT_EXEC\fR, \fBTNFCTL_EVENT_FORK\fR,
120 \fBTNFCTL_EVENT_EXIT\fR, or \fBTNFCTL_EVENT_TARGGONE\fR, respectively, when the
121 target program calls \fBdlopen\fR(3C), \fBdlclose\fR(3C), any flavor of
122 \fBexec\fR(2), \fBfork\fR(2) (or \fBfork1\fR(2)), \fBexit\fR(2), or terminates
123 unexpectedly. If the target program called \fBexec\fR(2), the client then needs
124 to call \fBtnfctl_close\fR(3TNF) on the current handle leaving the target
125 resumed, suspended, or killed (second argument to \fBtnfctl_close\fR(3TNF)).
126 No other \fBlibtnfctl\fR interface call can be used on the existing handle. If
127 the client wants to control the \fBexec\fR'ed image, it should leave the old
128 handle suspended, and use \fBtnfctl_pid_open()\fR to reattach to the same
129 process. This new handle can then be used to control the \fBexec\fR'ed image.
130 See \fBEXAMPLES\fR below for sample code. If the target process did a
131 \fBfork\fR(2) or \fBfork1\fR(2), and if control of the child process is not
132 needed, then \fIchild_hndl\fR should be \fINULL\fR. If control of the child
133 process is needed, then \fIchild_hndl\fR should be set. If it is set, a
134 pointer to a handle that can be used to control the child process is returned
135 in \fIchild_hndl\fR. The child process is stopped at the end of the
136 \fBfork()\fR system call. See \fBEXAMPLES\fR for an example of this event.
137 .SH RETURN VALUES
138 .sp
139 .LP
140 The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and
141 \fBtnfctl_continue()\fR functions return \fBTNFCTL_ERR_NONE\fR upon success.
142 .SH ERRORS
143 .sp
144 .LP
145 The following error codes apply to \fBtnfctl_pid_open()\fR:
146 .sp
147 .ne 2
148 .na
149 \fB\fBTNFCTL_ERR_BADARG\fR\fR
150 .ad
151 .RS 28n
152 The \fIpid\fR specified is the same process. Use
153 \fBtnfctl_internal_open\fR(3TNF) instead.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBTNFCTL_ERR_ACCES\fR\fR
160 .ad
161 .RS 28n
162 Permission denied. No privilege to connect to a setuid process.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
169 .ad
170 .RS 28n
171 A memory allocation failure occurred.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBTNFCTL_ERR_BUSY\fR\fR
178 .ad
179 .RS 28n
180 Another client is already using \fB/proc\fR to control this process or
181 internal tracing is being used.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
188 .ad
189 .RS 28n
190 The process is not a dynamic executable.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
197 .ad
198 .RS 28n
199 No such target process exists.
200 .RE
202 .sp
203 .ne 2
204 .na
205 \fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
206 .ad
207 .RS 28n
208 \fBlibtnfprobe.so.1\fR is not linked in the target process.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
215 .ad
216 .RS 28n
217 An internal error occurred.
218 .RE
220 .sp
221 .LP
222 The following error codes apply to \fBtnfctl_exec_open()\fR:
223 .sp
224 .ne 2
225 .na
226 \fB\fBTNFCTL_ERR_ACCES\fR\fR
227 .ad
228 .RS 28n
229 Permission denied.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
236 .ad
237 .RS 28n
238 A memory allocation failure occurred.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
245 .ad
246 .RS 28n
247 The target is not a dynamic executable.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
254 .ad
255 .RS 28n
256 \fBlibtnfprobe.so.1\fR is not linked in the target process.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR
263 .ad
264 .RS 28n
265 The program is not found.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
272 .ad
273 .RS 28n
274 An internal error occurred.
275 .RE
277 .sp
278 .LP
279 The following error codes apply to \fBtnfctl_continue()\fR:
280 .sp
281 .ne 2
282 .na
283 \fB\fBTNFCTL_ERR_BADARG\fR\fR
284 .ad
285 .RS 24n
286 Bad input argument. \fIhndl\fR is not a direct process probe control handle.
287 .RE
289 .sp
290 .ne 2
291 .na
292 \fB\fBTNFCTL_ERR_INTERNAL\fR\fR
293 .ad
294 .RS 24n
295 An internal error occurred.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
302 .ad
303 .RS 24n
304 No such target process exists.
305 .RE
307 .SH EXAMPLES
308 .LP
309 \fBExample 1 \fRUsing \fBtnfctl_pid_open()\fR
310 .sp
311 .LP
312 These examples do not include any error-handling code. Only the initial
313 example includes the declaration of the variables that are used in all of the
314 examples.
316 .sp
317 .LP
318 The following example shows how to preload \fBlibtnfprobe.so.1\fR from the
319 normal location and inherit the parent's environment.
321 .sp
322 .in +2
323 .nf
324 const char *pgm;
325 char * const *argv;
326 tnfctl_handle_t *hndl, *new_hndl, *child_hndl;
327 tnfctl_errcode_t err;
328 char * const *envptr;
329 extern char **environ;
330 tnfctl_event_t evt;
331 int pid;
333 /* assuming argv has been allocated */
334 argv[0] = pgm;
335 /* set up rest of argument vector here */
336 err = tnfctl_exec_open(pgm, argv, NULL, NULL, NULL, &hndl);
337 .fi
338 .in -2
340 .sp
341 .LP
342 This example shows how to preload two user-supplied libraries
343 \fBlibc_probe.so.1\fR and \fBlibthread_probe.so.1\fR. They interpose on the
344 corresponding \fBlibc.so\fR and \fBlibthread.so\fR interfaces and have probes
345 for function entry and exit. \fBlibtnfprobe.so.1\fR is preloaded from the
346 normal location and the parent's environment is inherited.
348 .sp
349 .in +2
350 .nf
351 /* assuming argv has been allocated */
352 argv[0] = pgm;
353 /* set up rest of argument vector here */
354 err = tnfctl_exec_open(pgm, argv, NULL, NULL,
355 "libc_probe.so.1 libthread_probe.so.1", &hndl);
356 .fi
357 .in -2
359 .sp
360 .LP
361 This example preloads an interposition library \fBlibc_probe.so.1\fR, and
362 specifies a different location from which to preload \fBlibtnfprobe.so.1\fR.
364 .sp
365 .in +2
366 .nf
367 /* assuming argv has been allocated */
368 argv[0] = pgm;
369 /* set up rest of argument vector here */
370 err = tnfctl_exec_open(pgm, argv, NULL, "/opt/SUNWXXX/lib",
371 "libc_probe.so.1", &hndl);
372 .fi
373 .in -2
375 .sp
376 .LP
377 To set up the environment explicitly for probe control to work, the target
378 process must link \fBlibtnfprobe.so.1\fR. If using \fIenvp\fR, it is the
379 caller's responsibility to do so.
381 .sp
382 .in +2
383 .nf
384 /* assuming argv has been allocated */
385 argv[0] = pgm;
386 /* set up rest of argument vector here */
387 /* envptr set up to caller's needs */
388 err = tnfctl_exec_open(pgm, argv, envptr, NULL, NULL, &hndl);
389 .fi
390 .in -2
392 .sp
393 .LP
394 Use this example to resume a process that does an \fBexec\fR(2) without
395 controlling it.
397 .sp
398 .in +2
399 .nf
400 err = tnfctl_continue(hndl, &evt, NULL);
401 switch (evt) {
402 case TNFCTL_EVENT_EXEC:
403 /* let target process continue without control */
404 err = tnfctl_close(hndl, TNFCTL_TARG_RESUME);
405 ...
406 break;
407 }
408 .fi
409 .in -2
411 .sp
412 .LP
413 Alternatively, use the next example to control a process that does an
414 \fBexec\fR(2).
416 .sp
417 .in +2
418 .nf
419 /*
420 * assume the pid variable has been set by calling
421 * tnfctl_trace_attrs_get()
422 */
423 err = tnfctl_continue(hndl, &evt, NULL);
424 switch (evt) {
425 case TNFCTL_EVENT_EXEC:
426 /* suspend the target process */
427 err = tnfctl_close(hndl, TNFCTL_TARG_SUSPEND);
428 /* re-open the exec'ed image */
429 err = tnfctl_pid_open(pid, &new_hndl);
430 /* new_hndl now controls the exec'ed image */
431 ...
432 break;
433 }
434 .fi
435 .in -2
437 .sp
438 .LP
439 To let \fBfork\fR'ed children continue without control, use \fINULL\fR as the
440 last argument to \fBtnfctl_continue(\|).\fR
442 .sp
443 .in +2
444 .nf
445 err = tnfctl_continue(hndl, &evt, NULL);
446 .fi
447 .in -2
449 .sp
450 .LP
451 The next example is how to control child processes that \fBfork\fR(2) or
452 \fBfork1\fR(2) create.
454 .sp
455 .in +2
456 .nf
457 err = tnfctl_continue(hndl, &evt, &child_hndl);
458 switch (evt) {
459 case TNFCTL_EVENT_FORK:
460 /* spawn a new thread or process to control child_hndl */
461 ...
462 break;
463 }
464 .fi
465 .in -2
467 .SH ATTRIBUTES
468 .sp
469 .LP
470 See \fBattributes\fR(5) for descriptions of the following attributes:
471 .sp
473 .sp
474 .TS
475 box;
476 c | c
477 l | l .
478 ATTRIBUTE TYPE ATTRIBUTE VALUE
479 _
480 MT Level MT-Safe
481 .TE
483 .SH SEE ALSO
484 .sp
485 .LP
486 \fBld\fR(1), \fBprex\fR(1), \fBproc\fR(1), \fBexec\fR(2), \fBexecve\fR(2),
487 \fBexit\fR(2), \fBfork\fR(2), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C),
488 \fBdlopen\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF),
489 \fBtnfctl_internal_open\fR(3TNF), \fBtracing\fR(3TNF) \fBattributes\fR(5)
490 .sp
491 .LP
492 \fILinker and Libraries Guide\fR
493 .SH NOTES
494 .sp
495 .LP
496 After a call to \fBtnfctl_continue()\fR returns, a client should use
497 \fBtnfctl_trace_attrs_get\fR(3TNF) to check the \fBtrace_buf_state\fR member of
498 the trace attributes and make sure that there is no internal error in the
499 target.