usr/src/lib/libtnfctl/tnfctl.h

   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 */