1tnfctl_indirect_open(3TNF) TNF Library Functions tnfctl_indirect_open(3TNF)
2
6 tnfctl_indirect_open, tnfctl_check_libs - control probes of another
7 process where caller provides /proc functionality
8
10 cc [ flag ... ] file ... -ltnfctl [ library ... ]
11 #include <tnf/tnfctl.h>
12 tnfctl_errcode_t tnfctl_indirect_open(void *prochandle,
14 tnfctl_ind_config_t *config, tnfctl_handle_t **ret_val);
15 tnfctl_errcode_t tnfctl_check_libs(tnfctl_handle_t *hndl);
18
21 The interfaces tnfctl_indirect_open() and tnfctl_check_libs() are used
22 to control probes in another process where the libtnfctl(3TNF) client
23 has already opened proc(4) on the target process. An example of this
24 is when the client is a debugger. Since these clients already use /proc
25 on the target, libtnfctl(3TNF) cannot use /proc directly. Therefore,
26 these clients must provide callback functions that can be used to
27 inspect and to update the target process. The target process must
28 load libtnfprobe.so.1 (defined in <tnf/tnfctl.h> as macro TNFCTL_LIBT‐
29 NFPROBE).
30 The first argument prochandle is a pointer to an opaque structure that
33 is used in the callback functions that inspect and update the target
34 process. This structure should encapsulate the state that the caller
35 needs to use /proc on the target process (the /proc file descriptor).
36 The second argument, config, is a pointer to
37 typedef
39 struct tnfctl_ind_config {
40 int (*p_read)(void *prochandle, paddr_t addr, char *buf,
41 size_t size);
42 int (*p_write)(void *prochandle, paddr_t addr, char *buf,
43 size_t size);
44 pid_t (*p_getpid)(void *prochandle);
45 int (*p_obj_iter)(void *prochandle, tnfctl_ind_obj_f *func,
46 void *client_data);
47 } tnfctl_ind_config_t;
48 The first field p_read is the address of a function that can read
52 size bytes at address addr in the target image into the buffer buf. The
53 function should return 0 upon success.. The second field p_write is
54 the address of a function that can write size bytes at address addr in
55 the target image from the buffer buf. The function should return 0 upon
56 success. The third field p_getpid is the address of a function that
57 should return the process id of the target process (prochandle). The
58 fourth field p_obj_iter is the address of a function that iterates
59 over all load objects and the executable by calling the callback func‐
60 tion func with client_data. If func returns 0, p_obj_iter should con‐
61 tinue processing link objects. If func returns any other value,
62 p_obj_iter should stop calling the callback function and return that
63 value. p_obj_iter should return 0 if it iterates over all load
64 objects.
65 If a failure is returned by any of the functions in config, the error
68 is propagated back as PREX_ERR_INTERNAL by the libtnfctl interface that
69 called it.
70 The definition of tnfctl_ind_obj_f is:
73 typedef int
75 tnfctl_ind_obj_f(void *prochandle,
76 const struct tnfctl_ind_obj_info *obj
77 void *client_data);
78 typedef struct tnfctl_ind_obj_info {
79 int objfd; /* -1 indicates fd not available */
80 paddr_t text_base; /* virtual addr of text segment */
81 paddr_t data_base; /* virtual addr of data segment */
82 const char *objname; /* null-term. pathname to loadobj */
83 } tnfctl_ind_obj_info_t;
84 objfd should be the file descriptor of the load object or executable.
88 If it is −1, then objname should be an absolute pathname to the load
89 object or executable. If objfd is not closed by libtnfctl, it should
90 be closed by the load object iterator function. text_base and data_base
91 are the addresses where the text and data segments of the load object
92 are mapped in the target process.
93 Whenever the target process opens or closes a dynamic object, the set
96 of available probes may change. See dlopen(3C) and dlclose(3C). In
97 indirect mode, call tnfctl_check_libs() when such events occur to make
98 libtnfctl aware of any changes. In other modes this is unnecessary but
99 harmless. It is also harmless to call tnfctl_check_libs() when no such
100 events have occurred.
101
103 tnfctl_indirect_open() and tnfctl_check_libs() return TNFCTL_ERR_NONE
104 upon success.
105
107 The following error codes apply to tnfctl_indirect_open():
108 TNFCTL_ERR_ALLOCFAIL A memory allocation failure occurred.
110 TNFCTL_ERR_BUSY Internal tracing is being used.
113 TNFCTL_ERR_NOLIBTNFPROBE libtnfprobe.so.1 is not loaded in the tar‐
116 get process.
117 TNFCTL_ERR_INTERNAL An internal error occurred.
120 The following error codes apply to tnfctl_check_libs():
124 TNFCTL_ERR_ALLOCFAIL A memory allocation failure occurred.
126 TNFCTL_ERR_INTERNAL An internal error occurred.
129
132 See attributes(5) for descriptions of the following attributes:
133 ┌─────────────────────────────┬─────────────────────────────┐
138 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
139 ├─────────────────────────────┼─────────────────────────────┤
140 │Availability │SUNWtnfc │
141 ├─────────────────────────────┼─────────────────────────────┤
142 │MT Level │MT-Safe │
143 └─────────────────────────────┴─────────────────────────────┘
144
146 prex(1), TNF_PROBE(3TNF), dlclose(3C), dlopen(3C), libtnfctl(3TNF),
147 tnfctl_probe_enable(3TNF), tnfctl_probe_trace(3TNF), tracing(3TNF),
148 proc(4), attributes(5)
149 Linker and Libraries Guide
152
154 tnfctl_indirect_open() should only be called after the dynamic linker
155 has mapped in all the libraries (rtld sync point) and called only after
156 the process is stopped. Indirect process probe control assumes the tar‐
157 get process is stopped whenever any libtnfctl interface is used on it.
158 For example, when used for indirect process probe control,
159 tnfctl_probe_enable(3TNF) and tnfctl_probe_trace(3TNF) should be called
160 only for a process that is stopped.
161SunOS 5.11 1 Mar 2004 tnfctl_indirect_open(3TNF)