xref: /illumos-gate/usr/src/lib/libtnfctl/tnfctl.h (revision 7c478bd9)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  *      Copyright (c) 1994, by Sun Microsytems, Inc.
24  */
25 
26 #ifndef _TNFCTL_H
27 #define	_TNFCTL_H
28 
29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
30 
31 #include <sys/types.h>
32 #include <gelf.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 #define	TNFCTL_LIBTNFPROBE	"libtnfprobe.so.1"
39 
40 /*
41  * data model dependent defs
42  */
43 #if defined(_LP64)
44 #define	ELF3264_R_SYM	GELF_R_SYM
45 typedef	GElf_Shdr	Elf3264_Shdr;
46 typedef GElf_Dyn	Elf3264_Dyn;
47 typedef GElf_Sword	Elf3264_Sword;
48 typedef GElf_Sym	Elf3264_Sym;
49 typedef GElf_Word	Elf3264_Word;
50 typedef GElf_Addr	Elf3264_Addr;
51 typedef GElf_Rela	Elf3264_Rela;
52 typedef GElf_Rel	Elf3264_Rel;
53 #else
54 #define	ELF3264_R_SYM	ELF32_R_SYM
55 typedef	Elf32_Shdr	Elf3264_Shdr;
56 typedef Elf32_Dyn	Elf3264_Dyn;
57 typedef Elf32_Sword	Elf3264_Sword;
58 typedef Elf32_Sym	Elf3264_Sym;
59 typedef Elf32_Word	Elf3264_Word;
60 typedef Elf32_Addr	Elf3264_Addr;
61 typedef Elf32_Rela	Elf3264_Rela;
62 typedef Elf32_Rel	Elf3264_Rel;
63 #endif
64 /*
65  * Opaque tnfctl handle
66  */
67 typedef	struct tnfctl_handle tnfctl_handle_t;
68 
69 /*
70  * Opaque probe handle
71  */
72 typedef struct tnfctl_probe_handle tnfctl_probe_t;
73 
74 /*
75  * Trace attributes and probe state
76  */
77 typedef enum {
78 	TNFCTL_BUF_OK,
79 	TNFCTL_BUF_NONE,
80 	TNFCTL_BUF_BROKEN
81 } tnfctl_bufstate_t;
82 
83 typedef struct tnfctl_trace_attrs {
84 	pid_t		targ_pid;		/* user process only */
85 	const char	*trace_file_name;	/* user process only */
86 	size_t		trace_buf_size;
87 	size_t		trace_min_size;
88 	tnfctl_bufstate_t trace_buf_state;
89 	boolean_t	trace_state;
90 	boolean_t	filter_state;		/* kernel mode only */
91 	long		pad;
92 } tnfctl_trace_attrs_t;
93 
94 typedef struct tnfctl_probe_state {
95 	ulong_t		id;
96 	const char	*attr_string;
97 	boolean_t	enabled;
98 	boolean_t	traced;
99 	boolean_t	new_probe;
100 	const char	*obj_name;		/* user process only */
101 	const char * const *func_names;		/* array of func names ptrs */
102 	const uintptr_t	*func_addrs;		/* array of func addresses */
103 	void		*client_registered_data;
104 	long		pad;
105 } tnfctl_probe_state_t;
106 
107 /*
108  * error codes
109  */
110 typedef enum {
111 	TNFCTL_ERR_NONE = 0,	/* success */
112 	TNFCTL_ERR_ACCES,	/* permission denied */
113 	TNFCTL_ERR_NOTARGET,	/* target process finished */
114 	TNFCTL_ERR_ALLOCFAIL,	/* memory allocation failure */
115 	TNFCTL_ERR_INTERNAL,	/* internal error */
116 	TNFCTL_ERR_SIZETOOSMALL, /* requested trace size is too small */
117 	TNFCTL_ERR_SIZETOOBIG,	/* requested trace size is too big */
118 	TNFCTL_ERR_BADARG,	/* Bad Input Argument */
119 	TNFCTL_ERR_NOTDYNAMIC,	/* Target is not a dynamic executable */
120 	TNFCTL_ERR_NOLIBTNFPROBE, /* libtnfprobe not linked in target */
121 	TNFCTL_ERR_BUFBROKEN,	/* tracing broken */
122 	TNFCTL_ERR_BUFEXISTS,	/* buffer already exists */
123 	TNFCTL_ERR_NOBUF,	/* no buffer */
124 	TNFCTL_ERR_BADDEALLOC,	/* can't deallocate buffer */
125 	TNFCTL_ERR_NOPROCESS,	/* no such target process */
126 	TNFCTL_ERR_FILENOTFOUND, /* file not found */
127 	TNFCTL_ERR_BUSY,	/* kernel/process already tracing */
128 	TNFCTL_ERR_INVALIDPROBE, /* probe no longer valid (dlclos'ed) */
129 	TNFCTL_ERR_USR1,	/* error extensions - semantics */
130 	TNFCTL_ERR_USR2,	/* 	set by user */
131 	TNFCTL_ERR_USR3,
132 	TNFCTL_ERR_USR4,
133 	TNFCTL_ERR_USR5
134 } tnfctl_errcode_t;
135 
136 /*
137  * event codes
138  */
139 typedef enum {
140 	TNFCTL_EVENT_EINTR,	/* target was interrupted by a signal */
141 	TNFCTL_EVENT_TARGGONE,	/* target finished - did not call exit */
142 	TNFCTL_EVENT_DLOPEN,	/* target did a dlopen */
143 	TNFCTL_EVENT_DLCLOSE,	/* target did a dlclose */
144 	TNFCTL_EVENT_EXEC,	/* target did an exec */
145 	TNFCTL_EVENT_FORK,	/* target did a fork */
146 	TNFCTL_EVENT_EXIT	/* target called exit */
147 } tnfctl_event_t;
148 
149 /*
150  * action to perform on target process
151  */
152 
153 typedef enum {
154 	TNFCTL_TARG_DEFAULT,	/* kills target if it was started with */
155 				/* 	tnfctl_exec_open() */
156 	TNFCTL_TARG_KILL,	/* kills target */
157 	TNFCTL_TARG_RESUME,	/* target is let free */
158 	TNFCTL_TARG_SUSPEND	/* target is suspended */
159 } tnfctl_targ_op_t;
160 
161 /*
162  * data structures needed when using tnfctl_indirect_open() interface i.e. for
163  * clients that will supply callback functions for inspecting target image.
164  */
165 typedef struct tnfctl_ind_obj_info {
166 	int	objfd;		/* -1 indicates fd not available */
167 	uintptr_t text_base;	/* address where text of loadobj was mapped */
168 	uintptr_t data_base;	/* address where data of loadobj was mapped */
169 	const char *objname;	/* null terminated full pathname to loadobj */
170 } tnfctl_ind_obj_info_t;
171 
172 typedef int tnfctl_ind_obj_f(
173 	void *,					/* opaque prochandle */
174 	const struct tnfctl_ind_obj_info *, 	/* info about this object */
175 	void *);				/* client supplied data */
176 
177 typedef struct tnfctl_ind_config {
178 	int (*p_read)(void *, uintptr_t, void *, size_t);
179 	int (*p_write)(void *, uintptr_t, void *, size_t);
180 	pid_t (*p_getpid)(void *);
181 	int (*p_obj_iter)(void *, tnfctl_ind_obj_f *, void * /* client_data */);
182 } tnfctl_ind_config_t;
183 
184 /*
185  * maps an errcode to a string
186  */
187 const char *tnfctl_strerror(tnfctl_errcode_t);
188 
189 /*
190  * interfaces to open a tnfctl handle
191  */
192 tnfctl_errcode_t tnfctl_pid_open(
193 	pid_t, 			/* pid */
194 	tnfctl_handle_t **);	/* return value */
195 
196 tnfctl_errcode_t tnfctl_indirect_open(
197 	void *,			/* prochandle */
198 	tnfctl_ind_config_t *,	/* config */
199 	tnfctl_handle_t **);	/* return value */
200 
201 tnfctl_errcode_t tnfctl_exec_open(
202 	const char *,		/* pgm name */
203 	char * const *,		/* argv */
204 	char * const *,		/* envp */
205 	const char *,		/* ld_preload */
206 	const char *,		/* libtnfprobe_path */
207 	tnfctl_handle_t **);	/* return value */
208 
209 tnfctl_errcode_t tnfctl_internal_open(tnfctl_handle_t **);
210 
211 tnfctl_errcode_t tnfctl_kernel_open(tnfctl_handle_t **);
212 
213 /*
214  * direct mode - to continue process
215  */
216 tnfctl_errcode_t tnfctl_continue(
217 	tnfctl_handle_t *,
218 	tnfctl_event_t *,	/* return value - why did process stop ? */
219 	tnfctl_handle_t **);	/* return value - if fork, handle on child */
220 
221 /*
222  * informs libtnfctl that libraries may have changed
223  */
224 tnfctl_errcode_t tnfctl_check_libs(tnfctl_handle_t *);
225 
226 /*
227  *
228  */
229 tnfctl_errcode_t tnfctl_close(tnfctl_handle_t *, tnfctl_targ_op_t);
230 tnfctl_errcode_t tnfctl_trace_attrs_get(
231 	tnfctl_handle_t *,
232 	tnfctl_trace_attrs_t *);
233 tnfctl_errcode_t tnfctl_buffer_alloc(
234 	tnfctl_handle_t *,
235 	const char *,		/* filename - ignored if kernel handle */
236 	uint_t);		/* buffer size */
237 
238 /*
239  * kernel tracing only
240  */
241 tnfctl_errcode_t tnfctl_buffer_dealloc(tnfctl_handle_t *);
242 tnfctl_errcode_t tnfctl_trace_state_set(tnfctl_handle_t *, boolean_t);
243 tnfctl_errcode_t tnfctl_filter_state_set(tnfctl_handle_t *, boolean_t);
244 tnfctl_errcode_t tnfctl_filter_list_get(tnfctl_handle_t *, pid_t **, int *);
245 tnfctl_errcode_t tnfctl_filter_list_add(tnfctl_handle_t *, pid_t);
246 tnfctl_errcode_t tnfctl_filter_list_delete(tnfctl_handle_t *, pid_t);
247 
248 /*
249  * probe operation interface
250  */
251 typedef tnfctl_errcode_t (*tnfctl_probe_op_t)(
252 	tnfctl_handle_t *,
253 	tnfctl_probe_t *,		/* opaque probe handle */
254 	void *);			/* client supplied data */
255 
256 tnfctl_errcode_t tnfctl_probe_apply(
257 	tnfctl_handle_t *,
258 	tnfctl_probe_op_t,	/* func to apply to each of the probes */
259 	void *);		/* client data - arg to pass to func */
260 
261 tnfctl_errcode_t tnfctl_probe_apply_ids(
262 	tnfctl_handle_t *,
263 	ulong_t,		/* # of probe id's in array */
264 	ulong_t *,		/* array of probe id's */
265 	tnfctl_probe_op_t,	/* func to apply to each those probes */
266 	void *);		/* client data - arg to pass to func */
267 
268 tnfctl_errcode_t tnfctl_register_funcs(
269 	tnfctl_handle_t *,
270 	void *(*)(tnfctl_handle_t *, tnfctl_probe_t *),	/* create_func */
271 	void (*)(void *));				/* destroy_func */
272 
273 tnfctl_errcode_t tnfctl_probe_state_get(tnfctl_handle_t *, tnfctl_probe_t *,
274 		tnfctl_probe_state_t *);
275 
276 /*
277  * supplied probe functions that can be used with tnfctl_probe_apply()
278  * and tnfctl_probe_apply_ids(). last argument is ignored when it is "void *"
279  */
280 tnfctl_errcode_t tnfctl_probe_enable(tnfctl_handle_t *, tnfctl_probe_t *,
281 					void *);
282 tnfctl_errcode_t tnfctl_probe_disable(tnfctl_handle_t *, tnfctl_probe_t *,
283 					void *);
284 tnfctl_errcode_t tnfctl_probe_trace(tnfctl_handle_t *, tnfctl_probe_t *,
285 					void *);
286 tnfctl_errcode_t tnfctl_probe_untrace(tnfctl_handle_t *, tnfctl_probe_t *,
287 					void *);
288 tnfctl_errcode_t tnfctl_probe_disconnect_all(tnfctl_handle_t *,
289 					tnfctl_probe_t *, void *);
290 tnfctl_errcode_t tnfctl_probe_connect(
291 	tnfctl_handle_t *,
292 	tnfctl_probe_t *,
293 	const char *,		/* library base name */
294 	const char *);		/* function name */
295 
296 #ifdef __cplusplus
297 }
298 #endif
299 
300 #endif /* _TNFCTL_H */
301