'\" 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 "Mar 1, 2004" .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 \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\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 .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 Internal tracing is being used. .RE .sp .ne 2 .na \fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR .ad .RS 28n \fBlibtnfprobe.so.1\fR is not loaded 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_check_libs()\fR: .sp .ne 2 .na \fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR .ad .RS 24n A memory allocation failure occurred. .RE .sp .ne 2 .na \fB\fBTNFCTL_ERR_INTERNAL\fR\fR .ad .RS 24n An internal error occurred. .RE .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 \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.