TNF Library Functions tnfctlindirectopen(3TNF)
NAME
tnfctlindirectopen, tnfctlchecklibs - control probes of
another process where caller provides /proc functionality
SYNOPSIS
cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include
tnfctlerrcodet tnfctlindirectopen(void *prochandle,
tnfctlindconfigt *config, tnfctlhandlet **retval);
tnfctlerrcodet tnfctlchecklibs(tnfctlhandlet *hndl);
DESCRIPTION
The interfaces tnfctlindirectopen() and
tnfctlchecklibs() are used to control probes in another
process where the libtnfctl(3TNF) client has already opened
proc(4) on the target process. An example of this is when
the client is a debugger. Since these clients already use
/proc on the target, libtnfctl(3TNF) cannot use /proc
directly. Therefore, these clients must provide callback
functions that can be used to inspect and to update the tar-
get process. The target process must load libtnfprobe.so.1
(defined in as macro TNFCTLIBTNFPROBE).
The first argument prochandle 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
/proc on the target process (the /proc file descriptor).
The second argument, config, is a pointer to
typedef
struct tnfctlindconfig {
int (*pread)(void *prochandle, paddrt addr, char *buf,
sizet size);
int (*pwrite)(void *prochandle, paddrt addr, char *buf,
sizet size);
pidt (*pgetpid)(void *prochandle);
int (*pobjiter)(void *prochandle, tnfctlindobjf *func,
void *clientdata);
} tnfctlindconfigt;
The first field pread is the address of a function that
can read size bytes at address addr in the target image
into the buffer buf. The function should return 0 upon suc-
cess.. The second field pwrite is the address of a function
SunOS 5.11 Last change: 1 Mar 2004 1
TNF Library Functions tnfctlindirectopen(3TNF)
that can write size bytes at address addr in the target
image from the buffer buf. The function should return 0 upon
success. The third field pgetpid is the address of a func-
tion that should return the process id of the target process
(prochandle). The fourth field pobjiter is the address of
a function that iterates over all load objects and the exe-
cutable by calling the callback function func with
clientdata. If func returns 0, pobjiter should continue
processing link objects. If func returns any other value,
pobjiter should stop calling the callback function and
return that value. pobjiter should return 0 if it
iterates over all load objects.
If a failure is returned by any of the functions in config,
the error is propagated back as PREXERINTERNAL by the
libtnfctl interface that called it.
The definition of tnfctlindobjf is:
typedef int
tnfctlindobjf(void *prochandle,
const struct tnfctlindobjinfo *obj
void *clientdata);
typedef struct tnfctlindobjinfo {
int objfd; /* -1 indicates fd not available */
paddrt textbase; /* virtual addr of text segment */
paddrt database; /* virtual addr of data segment */
const char *objname; /* null-term. pathname to loadobj */
} tnfctlindobjinfot;
objfd should be the file descriptor of the load object or
executable. If it is -1, then objname should be an absolute
pathname to the load object or executable. If objfd is not
closed by libtnfctl, it should be closed by the load object
iterator function. textbase and database are the addresses
where the text and data segments of the load object are
mapped in the target process.
Whenever the target process opens or closes a dynamic
object, the set of available probes may change. See
dlopen(3C) and dlclose(3C). In indirect mode, call
tnfctlchecklibs() when such events occur to make libtnfctl
aware of any changes. In other modes this is unnecessary
but harmless. It is also harmless to call
tnfctlchecklibs() when no such events have occurred.
SunOS 5.11 Last change: 1 Mar 2004 2
TNF Library Functions tnfctlindirectopen(3TNF)
RETURN VALUES
tnfctlindirectopen() and tnfctlchecklibs() return
TNFCTLERNONE upon success.
ERORS
The following error codes apply to tnfctlindirectopen():
TNFCTLERALOCFAIL A memory allocation failure
occurred.
TNFCTLERBUSY Internal tracing is being used.
TNFCTLERNOLIBTNFPROBE libtnfprobe.so.1 is not loaded
in the target process.
TNFCTLERINTERNAL An internal error occurred.
The following error codes apply to tnfctlchecklibs():
TNFCTLERALOCFAIL A memory allocation failure
occurred.
TNFCTLERINTERNAL An internal error occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWtnfc
MT Level MT-Safe
SEE ALSO
prex(1), TNFPROBE(3TNF), dlclose(3C), dlopen(3C),
libtnfctl(3TNF), tnfctlprobeenable(3TNF),
tnfctlprobetrace(3TNF), tracing(3TNF), proc(4), attri-
butes(5)
SunOS 5.11 Last change: 1 Mar 2004 3
TNF Library Functions tnfctlindirectopen(3TNF)
Linker and Libraries Guide
NOTES
tnfctlindirectopen() 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 libtnfctl interface is used on it. For
example, when used for indirect process probe control,
tnfctlprobeenable(3TNF) and tnfctlprobetrace(3TNF)
should be called only for a process that is stopped.
SunOS 5.11 Last change: 1 Mar 2004 4
|
