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