path: root/usr/src/man/man3tnf/tnfctl_pid_open.3tnf

'\" te
.\"  Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH TNFCTL_PID_OPEN 3TNF "Mar 1, 2004"
.SH NAME
tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue \- interfaces for direct
probe and process control for another process
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
#include <tnf/tnfctl.h>

\fBtnfctl_errcode_t\fR \fBtnfctl_pid_open\fR(\fBpid_t\fR \fIpid\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_exec_open\fR(\fBconst char *\fR\fIpgm_name\fR,
     \fBchar * const *\fR\fIargv\fR, \fBchar * const *\fR\fIenvp\fR,
     \fBconst char *\fR\fIlibnfprobe_path\fR, \fBconst char *\fR\fIld_preload\fR,
     \fBtnfctl_handle_t **\fR\fIret_val\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_continue\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR,
     \fBtnfctl_event_t *\fR\fIevt\fR, \fBtnfctl_handle_t **\fR\fIchild_hndl\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and
\fBtnfctl_continue()\fR functions create handles to control probes in another
process (direct process probe control). Either \fBtnfctl_pid_open()\fR or
\fBtnfctl_exec_open()\fR will return a handle in \fIret_val\fR that can be used
for probe control. On return of these calls, the process is stopped.
\fBtnfctl_continue()\fR allows the process specified by \fIhndl\fR to continue
execution.
.sp
.LP
The \fBtnfctl_pid_open()\fR function attaches to a running process with process
id of  \fIpid\fR. The process is stopped on return of this call.  The
\fBtnfctl_pid_open()\fR function returns an error message if \fIpid\fR is the
same as the calling process. See \fBtnfctl_internal_open\fR(3TNF) for
information on internal process probe control. A pointer to an opaque handle is
returned in  \fIret_val\fR, which can be used to control the process and the
probes in the process. The target process must have  \fBlibtnfprobe.so.1\fR
(defined in <\fBtnf/tnfctl.h\fR> as macro \fBTNFCTL_LIBTNFPROBE)\fR linked in
for probe control to work.
.sp
.LP
The \fBtnfctl_exec_open()\fR function is used to \fBexec\fR(2) a program and
obtain a probe control handle. For probe control to work, the process image to
be  \fBexec\fR'd must load \fBlibtnfprobe.so.1\fR. The \fBtnfctl_exec_open()\fR
function makes it simple for the library to be loaded at process start up time.
The \fIpgm_name\fR argument is the command to \fBexec\fR. If \fIpgm_name\fR is
not an absolute path, then the  \fB$PATH\fR environment variable is used to
find the \fIpgm_name\fR. \fIargv\fR 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
\fIargv\fR argument must have at least one member, and it should point to a
string that is the same as \fIpgm_name\fR. See \fBexecve\fR(2). The
\fIlibnfprobe_path\fR argument is an optional argument, and if set, it should
be the path to the directory that contains \fBlibtnfprobe.so.1\fR. There is no
need for a trailing "/" in this argument.  This argument is  useful if
\fBlibtnfprobe.so.1\fR is not installed in  \fB/usr/lib\fR. \fIld_preload\fR is
a space-separated list of libraries to preload into the target program. This
string should follow the syntax guidelines of the \fBLD_PRELOAD\fR environment
variable.  See \fBld.so.1\fR(1). The following illustrates how strings are
concatenated to form the \fBLD_PRELOAD\fR environment variable in the new
process image:
.sp
.in +2
.nf
<current value of $LD_PRELOAD> + <space> +
libtnfprobe_path + "/libtnfprobe.so.1" +<space> +
ld_preload
.fi
.in -2

.sp
.LP
This option is useful for preloading interposition libraries that have probes
in them.
.sp
.LP
\fIenvp\fR 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 \fBexecve\fR(2). If \fIenvp\fR is set, it overrides
\fIld_preload\fR. In this case, it is the caller's responsibility to ensure
that  \fBlibtnfprobe.so.1\fR is loaded into the target program.  If \fIenvp\fR
is not set, the new process image inherits the environment of the  calling
process, except for \fBLD_PRELOAD\fR.
.sp
.LP
The \fIret_val\fR 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 \fB\&.init\fR sections, has been executed.
.sp
.LP
The \fBtnfctl_continue()\fR function is a blocking call and lets the target
process referenced by \fIhndl\fR continue running.  It can only be used on
handles returned by \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR
(direct process probe control). It returns when the target stops; the reason
that the  process stopped  is returned in \fIevt\fR. This call is interruptible
by signals.  If it is interrupted, the process is stopped, and
\fBTNFCTL_EVENT_EINTR\fR is returned in \fIevt\fR. 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 \fBtnfctl_continue()\fR, it will return, and
the caller can decide whether or not to call \fBtnfctl_continue()\fR again.
.sp
.LP
\fBtnfctl_continue()\fR returns with an event of \fBTNFCTL_EVENT_DLOPEN\fR,
\fBTNFCTL_EVENT_DLCLOSE\fR, \fBTNFCTL_EVENT_EXEC\fR, \fBTNFCTL_EVENT_FORK\fR,
\fBTNFCTL_EVENT_EXIT\fR, or \fBTNFCTL_EVENT_TARGGONE\fR, respectively, when the
target program calls \fBdlopen\fR(3C), \fBdlclose\fR(3C), any flavor of
\fBexec\fR(2), \fBfork\fR(2) (or \fBfork1\fR(2)), \fBexit\fR(2), or terminates
unexpectedly. If the target program called \fBexec\fR(2), the client then needs
to call \fBtnfctl_close\fR(3TNF) on the current handle leaving the target
resumed, suspended, or killed (second argument to  \fBtnfctl_close\fR(3TNF)).
No other \fBlibtnfctl\fR interface call can be used on the existing handle. If
the client wants to control the \fBexec\fR'ed image, it should leave the old
handle suspended, and use \fBtnfctl_pid_open()\fR to reattach to the same
process.  This new handle can then be used to control the \fBexec\fR'ed image.
See \fBEXAMPLES\fR below for sample code.  If the target process did a
\fBfork\fR(2) or \fBfork1\fR(2), and if control of the child process is not
needed, then \fIchild_hndl\fR should be  \fINULL\fR. If control of the child
process is needed, then \fIchild_hndl\fR should be set.  If it is set, a
pointer to a handle that can be used to control the child process is returned
in \fIchild_hndl\fR. The child process is stopped at the end of the
\fBfork()\fR system call. See \fBEXAMPLES\fR for an example of this event.
.SH RETURN VALUES
.sp
.LP
The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and
\fBtnfctl_continue()\fR functions return \fBTNFCTL_ERR_NONE\fR upon success.
.SH ERRORS
.sp
.LP
The following error codes apply to \fBtnfctl_pid_open()\fR:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BADARG\fR\fR
.ad
.RS 28n
The  \fIpid\fR specified is the same process.  Use
\fBtnfctl_internal_open\fR(3TNF) instead.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ACCES\fR\fR
.ad
.RS 28n
Permission denied. No privilege to connect to a setuid  process.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
.ad
.RS 28n
A memory allocation failure occurred.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BUSY\fR\fR
.ad
.RS 28n
Another client is already using  \fB/proc\fR to control this process or
internal tracing is being used.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
.ad
.RS 28n
The process is not a dynamic executable.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
.ad
.RS 28n
No such target process exists.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
.ad
.RS 28n
\fBlibtnfprobe.so.1\fR is not linked in the target process.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INTERNAL\fR\fR
.ad
.RS 28n
An internal error occurred.
.RE

.sp
.LP
The following error codes apply to  \fBtnfctl_exec_open()\fR:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ACCES\fR\fR
.ad
.RS 28n
Permission denied.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
.ad
.RS 28n
A memory allocation failure occurred.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR
.ad
.RS 28n
The target is not a dynamic executable.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR
.ad
.RS 28n
\fBlibtnfprobe.so.1\fR is not linked in the target process.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR
.ad
.RS 28n
The program is not found.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INTERNAL\fR\fR
.ad
.RS 28n
An internal error occurred.
.RE

.sp
.LP
The following error codes apply to  \fBtnfctl_continue()\fR:
.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_BADARG\fR\fR
.ad
.RS 24n
Bad input argument. \fIhndl\fR is not a direct process probe control handle.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_INTERNAL\fR\fR
.ad
.RS 24n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR
.ad
.RS 24n
No such target process exists.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBtnfctl_pid_open()\fR
.sp
.LP
These examples do not include any error-handling code.  Only the initial
example includes the declaration of the variables that are used in all  of the
examples.

.sp
.LP
The following example shows how to preload  \fBlibtnfprobe.so.1\fR from the
normal location and inherit the parent's environment.

.sp
.in +2
.nf
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);
.fi
.in -2

.sp
.LP
This example shows how to preload two user-supplied libraries
\fBlibc_probe.so.1\fR and \fBlibthread_probe.so.1\fR. They interpose on the
corresponding \fBlibc.so\fR and \fBlibthread.so\fR interfaces and have probes
for function entry and exit. \fBlibtnfprobe.so.1\fR is preloaded from the
normal location and the parent's environment is inherited.

.sp
.in +2
.nf
/* 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);
.fi
.in -2

.sp
.LP
This example preloads an interposition library \fBlibc_probe.so.1\fR, and
specifies a different location from which to preload \fBlibtnfprobe.so.1\fR.

.sp
.in +2
.nf
/* 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);
.fi
.in -2

.sp
.LP
To set up the environment explicitly for probe control to work, the target
process must link  \fBlibtnfprobe.so.1\fR. If using  \fIenvp\fR, it is the
caller's responsibility to do so.

.sp
.in +2
.nf
/* 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);
.fi
.in -2

.sp
.LP
Use this example to resume a process that does an  \fBexec\fR(2) without
controlling it.

.sp
.in +2
.nf
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;
}
.fi
.in -2

.sp
.LP
Alternatively, use the next example to control a process that does an
\fBexec\fR(2).

.sp
.in +2
.nf
/*
 * 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;
}
.fi
.in -2

.sp
.LP
To let  \fBfork\fR'ed children continue without control, use \fINULL\fR as the
last argument to \fBtnfctl_continue(\|).\fR

.sp
.in +2
.nf
err = tnfctl_continue(hndl, &evt, NULL);
.fi
.in -2

.sp
.LP
The next example is how to control child processes that \fBfork\fR(2) or
\fBfork1\fR(2) create.

.sp
.in +2
.nf
err = tnfctl_continue(hndl, &evt, &child_hndl);
switch (evt) {
case TNFCTL_EVENT_FORK:
     /* spawn a new thread or process to control child_hndl */
     ...
     break;
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBld\fR(1), \fBprex\fR(1), \fBproc\fR(1), \fBexec\fR(2), \fBexecve\fR(2),
\fBexit\fR(2), \fBfork\fR(2), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C),
\fBdlopen\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF),
\fBtnfctl_internal_open\fR(3TNF), \fBtracing\fR(3TNF) \fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR
.SH NOTES
.sp
.LP
After a call to \fBtnfctl_continue()\fR returns, a client should use
\fBtnfctl_trace_attrs_get\fR(3TNF) to check the \fBtrace_buf_state\fR member of
the trace attributes and make sure that there is no internal error in the
target.