TNF Library Functions tnfctl_pid_open(3TNF)
NAME
tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue - inter-
faces for direct probe and process control for another pro-
cessSYNOPSIS
cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include
tnfctl_errcode_t tnfctl_pid_open(pid_t pid, tnfctl_handle_t **ret_val);
tnfctl_errcode_t tnfctl_exec_open(const char *pgm_name,
char * const *argv, char * const *envp,const char *libnfprobe_path, const char *ld_preload,
tnfctl_handle_t **ret_val);
tnfctl_errcode_t tnfctl_continue(tnfctl_handle_t *hndl,
tnfctl_event_t *evt, tnfctl_handle_t **child_hndl);
DESCRIPTION
The tnfctl_pid_open(), tnfctl_exec_open(), and
tnfctl_continue() functions create handles to control probes
in another process (direct process probe control). Eithertnfctl_pid_open() or tnfctl_exec_open() will return a handle
in ret_val that can be used for probe control. On return of
these calls, the process is stopped. tnfctl_continue()
allows the process specified by hndl to continue execution.The tnfctl_pid_open() function attaches to a running process
with process id of pid. The process is stopped on return ofthis call. The tnfctl_pid_open() function returns an error
message if pid is the same as the calling process. Seetnfctl_internal_open(3TNF) for information on internal pro-
cess probe control. A pointer to an opaque handle isreturned in ret_val, which can be used to control the pro-
cess and the probes in the process. The target process must have libtnfprobe.so.1 (defined inas macro TNFCTL_LIBTNFPROBE) linked in for probe control to work.
The tnfctl_exec_open() function is used to exec(2) a program
and obtain a probe control handle. For probe control to work, the process image to be exec'd must loadlibtnfprobe.so.1. The tnfctl_exec_open() function makes it
simple for the library to be loaded at process start uptime. The pgm_name argument is the command to exec. If
pgm_name is not an absolute path, then the $PATH environ-
ment variable is used to find the pgm_name. argv is a null-
SunOS 5.11 Last change: 1 Mar 2004 1
TNF Library Functions tnfctl_pid_open(3TNF)
terminated argument pointer, that is, it is a null-
terminated array of pointers to null-terminated strings.
These strings constitute the argument list available to the new process image. The argv argument must have at least one member, and it should point to a string that is the same aspgm_name. See execve(2). The libnfprobe_path argument is an
optional argument, and if set, it should be the path to the directory that contains libtnfprobe.so.1. There is no needfor a trailing "/" in this argument. This argument is use-
ful if libtnfprobe.so.1 is not installed in /usr/lib.ld_preload is a space-separated list of libraries to preload
into the target program. This string should follow the syn-
tax guidelines of the LD_PRELOAD environment variable. See
ld.so.1(1). The following illustrates how strings are con-
catenated to form the LD_PRELOAD environment variable in the
new process image:
+ + libtnfprobe_path + "/libtnfprobe.so.1" +
+ ld_preload
This option is useful for preloading interposition libraries that have probes in them. envp is an optional argument, and if set, it is used for theenvironment of the target program. It is a null-terminated
array of pointers to null-terminated strings. These strings
constitute the environment of the new process image. Seeexecve(2). If envp is set, it overrides ld_preload. In this
case, it is the caller's responsibility to ensure that libtnfprobe.so.1 is loaded into the target program. If envp is not set, the new process image inherits the environmentof the calling process, except for LD_PRELOAD.
The ret_val argument is the handle that can be used to con-
trol the process and the probes within the process. Uponreturn, the process is stopped before any user code, includ-
ing .init sections, has been executed.The tnfctl_continue() function is a blocking call and lets
the target process referenced by hndl continue running. Itcan only be used on handles returned by tnfctl_pid_open()
and tnfctl_exec_open() (direct process probe control). It
returns when the target stops; the reason that the process stopped is returned in evt. This call is interruptible by signals. If it is interrupted, the process is stopped, andTNFCTL_EVENT_EINTR is returned in evt. The client of this
SunOS 5.11 Last change: 1 Mar 2004 2
TNF Library Functions tnfctl_pid_open(3TNF)
library will have to decide which signal implies a stop to the target and catch that signal. Since a signal interruptstnfctl_continue(), it will return, and the caller can decide
whether or not to call tnfctl_continue() again.
tnfctl_continue() returns with an event of
TNFCTL_EVENT_DLOPEN, TNFCTL_EVENT_DLCLOSE,
TNFCTL_EVENT_EXEC, TNFCTL_EVENT_FORK, TNFCTL_EVENT_EXIT, or
TNFCTL_EVENT_TARGGONE, respectively, when the target program
calls dlopen(3C), dlclose(3C), any flavor of exec(2), fork(2) (or fork1(2)), exit(2), or terminates unexpectedly. If the target program called exec(2), the client then needsto call tnfctl_close(3TNF) on the current handle leaving the
target resumed, suspended, or killed (second argument totnfctl_close(3TNF)). No other libtnfctl interface call can
be used on the existing handle. If the client wants to con-
trol the exec'ed image, it should leave the old handlesuspended, and use tnfctl_pid_open() to reattach to the same
process. This new handle can then be used to control theexec'ed image. See EXAMPLES below for sample code. If the
target process did a fork(2) or fork1(2), and if control ofthe child process is not needed, then child_hndl should be
NULL. If control of the child process is needed, thenchild_hndl should be set. If it is set, a pointer to a han-
dle that can be used to control the child process isreturned in child_hndl. The child process is stopped at the
end of the fork() system call. See EXAMPLES for an example
of this event.RETURN VALUES
The tnfctl_pid_open(), tnfctl_exec_open(), and
tnfctl_continue() functions return TNFCTL_ERR_NONE upon suc-
cess.ERRORS
The following error codes apply to tnfctl_pid_open():
TNFCTL_ERR_BADARG The pid specified is the same
process. Usetnfctl_internal_open(3TNF)
instead.TNFCTL_ERR_ACCES Permission denied. No privilege
to connect to a setuid process.TNFCTL_ERR_ALLOCFAIL A memory allocation failure
occurred.SunOS 5.11 Last change: 1 Mar 2004 3
TNF Library Functions tnfctl_pid_open(3TNF)
TNFCTL_ERR_BUSY Another client is already using
/proc to control this process or internal tracing is being used.TNFCTL_ERR_NOTDYNAMIC The process is not a dynamic
executable.TNFCTL_ERR_NOPROCESS No such target process exists.
TNFCTL_ERR_NOLIBTNFPROBE libtnfprobe.so.1 is not linked
in the target process.TNFCTL_ERR_INTERNAL An internal error occurred.
The following error codes apply to tnfctl_exec_open():
TNFCTL_ERR_ACCES Permission denied.
TNFCTL_ERR_ALLOCFAIL A memory allocation failure
occurred.TNFCTL_ERR_NOTDYNAMIC The target is not a dynamic exe-
cutable.TNFCTL_ERR_NOLIBTNFPROBE libtnfprobe.so.1 is not linked
in the target process.TNFCTL_ERR_FILENOTFOUND The program is not found.
TNFCTL_ERR_INTERNAL An internal error occurred.
The following error codes apply to tnfctl_continue():
TNFCTL_ERR_BADARG Bad input argument. hndl is not a
direct process probe control handle.TNFCTL_ERR_INTERNAL An internal error occurred.
SunOS 5.11 Last change: 1 Mar 2004 4
TNF Library Functions tnfctl_pid_open(3TNF)
TNFCTL_ERR_NOPROCESS No such target process exists.
EXAMPLES
Example 1 Using tnfctl_pid_open()
These examples do not include any error-handling code. Only
the initial example includes the declaration of the vari-
ables that are used in all of the examples. The following example shows how to preload libtnfprobe.so.1from the normal location and inherit the parent's environ-
ment. const char *pgm; char * const *argv;tnfctl_handle_t *hndl, *new_hndl, *child_hndl;
tnfctl_errcode_t err;
char * const *envptr; extern char **environ;tnfctl_event_t evt;
int pid; /* assuming argv has been allocated */ argv[0] = pgm; /* set up rest of argument vector here */err = tnfctl_exec_open(pgm, argv, NULL, NULL, NULL, &hndl);
This example shows how to preload two user-supplied
libraries libc_probe.so.1 and libthread_probe.so.1. They
interpose on the corresponding libc.so and libthread.so interfaces and have probes for function entry and exit. libtnfprobe.so.1 is preloaded from the normal location and the parent's environment is inherited. /* assuming argv has been allocated */ argv[0] = pgm; /* set up rest of argument vector here */err = tnfctl_exec_open(pgm, argv, NULL, NULL,
"libc_probe.so.1 libthread_probe.so.1", &hndl);
This example preloads an interposition librarylibc_probe.so.1, and specifies a different location from
SunOS 5.11 Last change: 1 Mar 2004 5
TNF Library Functions tnfctl_pid_open(3TNF)
which to preload libtnfprobe.so.1. /* assuming argv has been allocated */ argv[0] = pgm; /* set up rest of argument vector here */err = tnfctl_exec_open(pgm, argv, NULL, "/opt/SUNWXXX/lib",
"libc_probe.so.1", &hndl);
To set up the environment explicitly for probe control to work, the target process must link libtnfprobe.so.1. If using envp, it is the caller's responsibility to do so. /* assuming argv has been allocated */ argv[0] = pgm; /* set up rest of argument vector here */ /* envptr set up to caller's needs */err = tnfctl_exec_open(pgm, argv, envptr, NULL, NULL, &hndl);
Use this example to resume a process that does an exec(2) without controlling it.err = tnfctl_continue(hndl, &evt, NULL);
switch (evt) {case TNFCTL_EVENT_EXEC:
/* let target process continue without control */err = tnfctl_close(hndl, TNFCTL_TARG_RESUME);
... break; } Alternatively, use the next example to control a process that does an exec(2). /* * assume the pid variable has been set by calling* tnfctl_trace_attrs_get()
*/err = tnfctl_continue(hndl, &evt, NULL);
switch (evt) {case TNFCTL_EVENT_EXEC:
/* suspend the target process */err = tnfctl_close(hndl, TNFCTL_TARG_SUSPEND);
SunOS 5.11 Last change: 1 Mar 2004 6
TNF Library Functions tnfctl_pid_open(3TNF)
/* re-open the exec'ed image */
err = tnfctl_pid_open(pid, &new_hndl);
/* new_hndl now controls the exec'ed image */
... break; } To let fork'ed children continue without control, use NULLas the last argument to tnfctl_continue().
err = tnfctl_continue(hndl, &evt, NULL);
The next example is how to control child processes that fork(2) or fork1(2) create.err = tnfctl_continue(hndl, &evt, &child_hndl);
switch (evt) {case TNFCTL_EVENT_FORK:
/* spawn a new thread or process to control child_hndl */
... break; }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | system/tnf ||_____________________________|_____________________________|
| MT Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ld(1), prex(1), proc(1), exec(2), execve(2), exit(2),fork(2), TNF_PROBE(3TNF), dlclose(3C), dlopen(3C),
libtnfctl(3TNF), tnfctl_close(3TNF),
tnfctl_internal_open(3TNF), tracing(3TNF) attributes(5)
SunOS 5.11 Last change: 1 Mar 2004 7
TNF Library Functions tnfctl_pid_open(3TNF)
Linker and Libraries Guide NOTESAfter a call to tnfctl_continue() returns, a client should
use tnfctl_trace_attrs_get(3TNF) to check the
trace_buf_state member of the trace attributes and make sure
that there is no internal error in the target.SunOS 5.11 Last change: 1 Mar 2004 8