'\" 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_indirect_open 3TNF "1 Mar 2004" "SunOS 5.11" "TNF Library Functions"
.SH NAME
tnfctl_indirect_open, tnfctl_check_libs \- control probes of another process
where caller provides /proc functionality
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ]
#include <tnf/tnfctl.h>

\fBtnfctl_errcode_t\fR \fBtnfctl_indirect_open\fR(\fBvoid *\fR\fIprochandle\fR,
     \fBtnfctl_ind_config_t *\fR\fIconfig\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR);
.fi

.LP
.nf
\fBtnfctl_errcode_t\fR \fBtnfctl_check_libs\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The interfaces  \fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR are
used to control probes in another process where the \fBlibtnfctl\fR(3TNF)
client has already opened  \fBproc\fR(4) on the target process. An example of
this is when the client is a debugger. Since these clients already use
\fB/proc\fR on the target, \fBlibtnfctl\fR(3TNF) cannot use \fB/proc\fR
directly.  Therefore, these clients must provide callback functions that can be
used to inspect and to update the target process.   The target process must
load \fBlibtnfprobe.so.1\fR (defined in \fB<tnf/tnfctl.h>\fR as macro
\fBTNFCTL_LIBTNFPROBE).\fR
.sp
.LP
The first argument \fIprochandle\fR is a pointer to an opaque structure that is
used in the callback functions that inspect and update the target process.
This structure should encapsulate the state that the caller needs to use
\fB/proc\fR on the target process (the  \fB/proc\fR file descriptor). The
second argument, \fIconfig\fR, is a pointer to
.sp
.in +2
.nf
typedef
struct tnfctl_ind_config {
	int (*p_read)(void *prochandle, paddr_t addr, char *buf,
					size_t size);
	int (*p_write)(void *prochandle, paddr_t addr, char *buf,
					size_t size);
	pid_t (*p_getpid)(void *prochandle);
	int (*p_obj_iter)(void *prochandle, tnfctl_ind_obj_f *func,
					void *client_data);
} tnfctl_ind_config_t;
.fi
.in -2

.sp
.LP
The first field  \fIp_read\fR is the address of a function that can read
\fBsize\fR bytes at address \fIaddr\fR in the target image into the buffer
\fIbuf\fR. The function should return  \fB0\fR upon success.. The second field
\fIp_write\fR is the address of a function that can write  \fBsize\fR bytes at
address \fIaddr\fR in the target image from the buffer \fIbuf\fR. The function
should return \fB0\fR upon success. The third field \fIp_getpid\fR is the
address of a function that should return the process id of the target process
(\fIprochandle\fR). The fourth field  \fIp_obj_iter\fR is the address of a
function that iterates over all load objects  and the executable by calling the
callback function  \fIfunc\fR with  \fIclient_data\fR. If \fIfunc\fR returns
\fB0\fR, \fIp_obj_iter\fR should continue processing link objects.  If
\fIfunc\fR returns any other value, \fIp_obj_iter\fR should stop calling the
callback function and return that value. \fIp_obj_iter\fR should return
\fB0\fR if it iterates over all load objects.
.sp
.LP
If a failure is returned by any of the functions in \fIconfig\fR, the error is
propagated back as \fBPREX_ERR_INTERNAL\fR by the \fBlibtnfctl\fR interface
that called it.
.sp
.LP
The definition of  \fBtnfctl_ind_obj_f\fR is:
.sp
.in +2
.nf
typedef int
tnfctl_ind_obj_f(void *prochandle,
	const struct tnfctl_ind_obj_info *obj
	void *client_data);
typedef struct tnfctl_ind_obj_info {
	int     objfd;			/* -1 indicates fd not available */
	paddr_t text_base;		/* virtual addr of text segment */
	paddr_t data_base;		/* virtual addr of data segment */
	const char *objname;    	/* null-term. pathname to loadobj */
} tnfctl_ind_obj_info_t;
.fi
.in -2

.sp
.LP
\fIobjfd\fR should be the file descriptor of the load object or executable.  If
it is \fB\(mi1\fR, then \fIobjname\fR should be an absolute pathname to the
load object or executable. If \fIobjfd\fR is not closed by  \fBlibtnfctl\fR, it
should be closed by the load object iterator function. \fItext_base\fR and
\fIdata_base\fR are the addresses where the text and data segments of the load
object are mapped in the target process.
.sp
.LP
Whenever the target process opens  or closes  a dynamic object, the set of
available probes may change.   See \fBdlopen\fR(3C) and \fBdlclose\fR(3C). In
indirect mode, call \fBtnfctl_check_libs()\fR when such events occur to make
\fBlibtnfctl\fR aware of any changes.  In other modes this is unnecessary but
harmless. It is also harmless to call \fBtnfctl_check_libs()\fR when no such
events have occurred.
.SH RETURN VALUES
.sp
.LP
\fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR return
\fBTNFCTL_ERR_NONE\fR upon success.
.SH ERRORS
.sp
.LP
The following error codes apply to  \fBtnfctl_indirect_open()\fR:
.sp
.ne 2
.mk
.na
\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
.ad
.RS 28n
.rt  
A memory allocation failure occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTNFCTL_ERR_BUSY\fR\fR
.ad
.RS 28n
.rt  
Internal tracing is being used.
.RE

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

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

.sp
.LP
The following error codes apply to  \fBtnfctl_check_libs()\fR:
.sp
.ne 2
.mk
.na
\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR
.ad
.RS 24n
.rt  
A memory allocation failure occurred.
.RE

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBprex\fR(1), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
\fBlibtnfctl\fR(3TNF), \fBtnfctl_probe_enable\fR(3TNF),
\fBtnfctl_probe_trace\fR(3TNF), \fBtracing\fR(3TNF), \fBproc\fR(4),
\fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR
.SH NOTES
.sp
.LP
\fBtnfctl_indirect_open()\fR should only be called after the dynamic linker has
mapped in all the libraries (rtld sync point) and called only after the process
is stopped. Indirect process probe control assumes the target process is
stopped whenever any \fBlibtnfctl\fR interface is used on it.  For example,
when used for indirect process probe control,  \fBtnfctl_probe_enable\fR(3TNF)
and \fBtnfctl_probe_trace\fR(3TNF) should be called only for a process that is
stopped.