TNFCTL_PID_OPEN(3TNF)TNFCTL_PID_OPEN(3TNF)NAME
tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue - interfaces for
direct probe and process control for another process
SYNOPSIS
cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include <tnf/tnfctl.h>
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() func‐
tions create handles to control probes in another process (direct
process probe control). Either tnfctl_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 of this call. The
tnfctl_pid_open() function returns an error message if pid is the same
as the calling process. See tnfctl_internal_open(3TNF) for information
on internal process probe control. A pointer to an opaque handle is
returned in ret_val, which can be used to control the process and the
probes in the process. The target process must have libtnfprobe.so.1
(defined in <tnf/tnfctl.h> as 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 load libtnfprobe.so.1. The tnfctl_exec_open() function
makes it simple for the library to be loaded at process start up time.
The pgm_name argument is the command to exec. If pgm_name is not an
absolute path, then the $PATH environment variable is used to find the
pgm_name. argv is a null-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 as pgm_name. See execve(2). The lib‐
nfprobe_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
need for a trailing "/" in this argument. This argument is useful 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 syntax guidelines of the LD_PRELOAD environ‐
ment variable. See ld.so.1(1). The following illustrates how strings
are concatenated to form the LD_PRELOAD environment variable in the new
process image:
<current value of $LD_PRELOAD> + <space> +
libtnfprobe_path + "/libtnfprobe.so.1" +<space> +
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 the environ‐
ment 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. See execve(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 environment of the calling
process, except for LD_PRELOAD.
The ret_val argument is the handle that can be used to control the
process and the probes within the process. Upon return, the process is
stopped before any user code, including .init sections, has been exe‐
cuted.
The tnfctl_continue() function is a blocking call and lets the target
process referenced by hndl continue running. It can 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 interrupt‐
ible by signals. If it is interrupted, the process is stopped, and
TNFCTL_EVENT_EINTR is returned in evt. The client of this library will
have to decide which signal implies a stop to the target and catch
that signal. Since a signal interrupts tnfctl_continue(), it will
return, and the caller can decide whether or not to call tnfctl_con‐
tinue() 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 tar‐
get program called exec(2), the client then needs to call
tnfctl_close(3TNF) on the current handle leaving the target resumed,
suspended, or killed (second argument to tnfctl_close(3TNF)). No
other libtnfctl interface call can be used on the existing handle. If
the client wants to control the exec'ed image, it should leave the old
handle suspended, and use tnfctl_pid_open() to reattach to the same
process. This new handle can then be used to control the exec'ed
image. See EXAMPLES below for sample code. If the target process did
a fork(2) or fork1(2), and if control of the child process is not
needed, then child_hndl should be NULL. If control of the child
process is needed, then child_hndl should be set. If it is set, a
pointer to a handle that can be used to control the child process is
returned 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() func‐
tions return TNFCTL_ERR_NONE upon success.
ERRORS
The following error codes apply to tnfctl_pid_open():
TNFCTL_ERR_BADARG
The pid specified is the same process.
Use tnfctl_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.
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 tar‐
get 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 executable.
TNFCTL_ERR_NOLIBTNFPROBE
libtnfprobe.so.1 is not linked in the tar‐
get 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.
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 ini‐
tial example includes the declaration of the variables that are used in
all of the examples.
The following example shows how to preload libtnfprobe.so.1 from the
normal location and inherit the parent's environment.
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 corre‐
sponding libc.so and libthread.so interfaces and have probes for func‐
tion 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 library libc_probe.so.1, and
specifies a different location from 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 con‐
trolling 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);
/* 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 NULL as 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 attributes:
┌───────────────┬─────────────────┐
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├───────────────┼─────────────────┤
│MT Level │ MT-Safe │
└───────────────┴─────────────────┘
SEE ALSOld(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)
Linker and Libraries Guide
NOTES
After 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.
Mar 1, 2004 TNFCTL_PID_OPEN(3TNF)
