TNF Library Functions tnfctlpidopen(3TNF)
NAME
tnfctlpidopen, tnfctlexecopen, tnfctlcontinue - inter-
faces for direct probe and process control for another pro-
cess
SYNOPSIS
cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include
tnfctlerrcodet tnfctlpidopen(pidt pid, tnfctlhandlet **retval);
tnfctlerrcodet tnfctlexecopen(const char *pgmname,
char * const *argv, char * const *envp,
const char *libnfprobepath, const char *ldpreload,
tnfctlhandlet **retval);
tnfctlerrcodet tnfctlcontinue(tnfctlhandlet *hndl,
tnfctleventt *evt, tnfctlhandlet **childhndl);
DESCRIPTION
The tnfctlpidopen(), tnfctlexecopen(), and
tnfctlcontinue() functions create handles to control probes
in another process (direct process probe control). Either
tnfctlpidopen() or tnfctlexecopen() will return a handle
in retval that can be used for probe control. On return of
these calls, the process is stopped. tnfctlcontinue()
allows the process specified by hndl to continue execution.
The tnfctlpidopen() function attaches to a running process
with process id of pid. The process is stopped on return of
this call. The tnfctlpidopen() function returns an error
message if pid is the same as the calling process. See
tnfctlinternalopen(3TNF) for information on internal pro-
cess probe control. A pointer to an opaque handle is
returned in retval, which can be used to control the pro-
cess and the probes in the process. The target process must
have libtnfprobe.so.1 (defined in as macro
TNFCTLIBTNFPROBE) linked in for probe control to work.
The tnfctlexecopen() 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 tnfctlexecopen() function makes it
simple for the library to be loaded at process start up
time. The pgmname argument is the command to exec. If
pgmname is not an absolute path, then the $PATH environ-
ment variable is used to find the pgmname. argv is a null-
SunOS 5.11 Last change: 1 Mar 2004 1
TNF Library Functions tnfctlpidopen(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 as
pgmname. See execve(2). The libnfprobepath 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 use-
ful if libtnfprobe.so.1 is not installed in /usr/lib.
ldpreload is a space-separated list of libraries to preload
into the target program. This string should follow the syn-
tax guidelines of the LDPRELOAD environment variable. See
ld.so.1(1). The following illustrates how strings are con-
catenated to form the LDPRELOAD environment variable in the
new process image:
] ]
libtnfprobepath ] "/libtnfprobe.so.1" ] ]
ldpreload
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
environment 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 ldpreload. 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 LDPRELOAD.
The retval argument is the handle that can be used to con-
trol the process and the probes within the process. Upon
return, the process is stopped before any user code, includ-
ing .init sections, has been executed.
The tnfctlcontinue() function is a blocking call and lets
the target process referenced by hndl continue running. It
can only be used on handles returned by tnfctlpidopen()
and tnfctlexecopen() (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, and
TNFCTLEVENTEINTR is returned in evt. The client of this
SunOS 5.11 Last change: 1 Mar 2004 2
TNF Library Functions tnfctlpidopen(3TNF)
library will have to decide which signal implies a stop to
the target and catch that signal. Since a signal interrupts
tnfctlcontinue(), it will return, and the caller can decide
whether or not to call tnfctlcontinue() again.
tnfctlcontinue() returns with an event of
TNFCTLEVENTDLOPEN, TNFCTLEVENTDLCLOSE,
TNFCTLEVENTEXEC, TNFCTLEVENTFORK, TNFCTLEVENTEXIT, or
TNFCTLEVENTARGONE, 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 needs
to call tnfctlclose(3TNF) on the current handle leaving the
target resumed, suspended, or killed (second argument to
tnfctlclose(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 handle
suspended, and use tnfctlpidopen() 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 childhndl should be
NUL. If control of the child process is needed, then
childhndl should be set. If it is set, a pointer to a han-
dle that can be used to control the child process is
returned in childhndl. The child process is stopped at the
end of the fork() system call. See EXAMPLES for an example
of this event.
RETURN VALUES
The tnfctlpidopen(), tnfctlexecopen(), and
tnfctlcontinue() functions return TNFCTLERNONE upon suc-
cess.
ERORS
The following error codes apply to tnfctlpidopen():
TNFCTLERBADARG The pid specified is the same
process. Use
tnfctlinternalopen(3TNF)
instead.
TNFCTLERACES Permission denied. No privilege
to connect to a setuid process.
TNFCTLERALOCFAIL A memory allocation failure
occurred.
SunOS 5.11 Last change: 1 Mar 2004 3
TNF Library Functions tnfctlpidopen(3TNF)
TNFCTLERBUSY Another client is already using
/proc to control this process or
internal tracing is being used.
TNFCTLERNOTDYNAMIC The process is not a dynamic
executable.
TNFCTLERNOPROCES No such target process exists.
TNFCTLERNOLIBTNFPROBE libtnfprobe.so.1 is not linked
in the target process.
TNFCTLERINTERNAL An internal error occurred.
The following error codes apply to tnfctlexecopen():
TNFCTLERACES Permission denied.
TNFCTLERALOCFAIL A memory allocation failure
occurred.
TNFCTLERNOTDYNAMIC The target is not a dynamic exe-
cutable.
TNFCTLERNOLIBTNFPROBE libtnfprobe.so.1 is not linked
in the target process.
TNFCTLERFILENOTFOUND The program is not found.
TNFCTLERINTERNAL An internal error occurred.
The following error codes apply to tnfctlcontinue():
TNFCTLERBADARG Bad input argument. hndl is not a
direct process probe control handle.
TNFCTLERINTERNAL An internal error occurred.
SunOS 5.11 Last change: 1 Mar 2004 4
TNF Library Functions tnfctlpidopen(3TNF)
TNFCTLERNOPROCES No such target process exists.
EXAMPLES
Example 1 Using tnfctlpidopen()
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.1
from the normal location and inherit the parent's environ-
ment.
const char *pgm;
char * const *argv;
tnfctlhandlet *hndl, *newhndl, *childhndl;
tnfctlerrcodet err;
char * const *envptr;
extern char **environ;
tnfctleventt evt;
int pid;
/* assuming argv has been allocated */
argv[0] = pgm;
/* set up rest of argument vector here */
err = tnfctlexecopen(pgm, argv, NUL, NUL, NUL, &hndl);
This example shows how to preload two user-supplied
libraries libcprobe.so.1 and libthreadprobe.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 = tnfctlexecopen(pgm, argv, NUL, NUL,
"libcprobe.so.1 libthreadprobe.so.1", &hndl);
This example preloads an interposition library
libcprobe.so.1, and specifies a different location from
SunOS 5.11 Last change: 1 Mar 2004 5
TNF Library Functions tnfctlpidopen(3TNF)
which to preload libtnfprobe.so.1.
/* assuming argv has been allocated */
argv[0] = pgm;
/* set up rest of argument vector here */
err = tnfctlexecopen(pgm, argv, NUL, "/opt/SUNWX/lib",
"libcprobe.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 = tnfctlexecopen(pgm, argv, envptr, NUL, NUL, &hndl);
Use this example to resume a process that does an exec(2)
without controlling it.
err = tnfctlcontinue(hndl, &evt, NUL);
switch (evt) {
case TNFCTLEVENTEXEC:
/* let target process continue without control */
err = tnfctlclose(hndl, TNFCTLTARGRESUME);
...
break;
}
Alternatively, use the next example to control a process
that does an exec(2).
/*
* assume the pid variable has been set by calling
* tnfctltraceattrsget()
*/
err = tnfctlcontinue(hndl, &evt, NUL);
switch (evt) {
case TNFCTLEVENTEXEC:
/* suspend the target process */
err = tnfctlclose(hndl, TNFCTLTARGSUSPEND);
SunOS 5.11 Last change: 1 Mar 2004 6
TNF Library Functions tnfctlpidopen(3TNF)
/* re-open the exec'ed image */
err = tnfctlpidopen(pid, &newhndl);
/* newhndl now controls the exec'ed image */
...
break;
}
To let fork'ed children continue without control, use NUL
as the last argument to tnfctlcontinue().
err = tnfctlcontinue(hndl, &evt, NUL);
The next example is how to control child processes that
fork(2) or fork1(2) create.
err = tnfctlcontinue(hndl, &evt, &childhndl);
switch (evt) {
case TNFCTLEVENTFORK:
/* spawn a new thread or process to control childhndl */
...
break;
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWtnfc
MT Level MT-Safe
SEE ALSO
ld(1), prex(1), proc(1), exec(2), execve(2), exit(2),
fork(2), TNFPROBE(3TNF), dlclose(3C), dlopen(3C),
libtnfctl(3TNF), tnfctlclose(3TNF),
tnfctlinternalopen(3TNF), tracing(3TNF) attributes(5)
SunOS 5.11 Last change: 1 Mar 2004 7
TNF Library Functions tnfctlpidopen(3TNF)
Linker and Libraries Guide
NOTES
After a call to tnfctlcontinue() returns, a client should
use tnfctltraceattrsget(3TNF) to check the
tracebufstate 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
|
