lib/libproc/libproc.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3  *
   4  * Copyright (c) 2010 The FreeBSD Foundation
   5  * Copyright (c) 2008 John Birrell (jb@freebsd.org)
   6  * All rights reserved.
   7  *
   8  * Portions of this software were developed by Rui Paulo under sponsorship
   9  * from the FreeBSD Foundation.
  10  *
  11  * Redistribution and use in source and binary forms, with or without
  12  * modification, are permitted provided that the following conditions
  13  * are met:
  14  * 1. Redistributions of source code must retain the above copyright
  15  *    notice, this list of conditions and the following disclaimer.
  16  * 2. Redistributions in binary form must reproduce the above copyright
  17  *    notice, this list of conditions and the following disclaimer in the
  18  *    documentation and/or other materials provided with the distribution.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  *
  32  * $FreeBSD$
  33  */
  34
  35 #ifndef _LIBPROC_H_
  36 #define _LIBPROC_H_
  37
  38 #include <gelf.h>
  39 #include <rtld_db.h>
  40 #include <limits.h>
  41
  42 struct ctf_file;
  43 struct proc_handle;
  44
  45 typedef void (*proc_child_func)(void *);
  46
  47 /* Values returned by proc_state(). */
  48 #define PS_IDLE         1
  49 #define PS_STOP         2
  50 #define PS_RUN          3
  51 #define PS_UNDEAD       4
  52 #define PS_DEAD         5
  53 #define PS_LOST         6
  54
  55 /* Flags for proc_attach(). */
  56 #define PATTACH_FORCE   0x01
  57 #define PATTACH_RDONLY  0x02
  58 #define PATTACH_NOSTOP  0x04
  59
  60 /* Reason values for proc_detach(). */
  61 #define PRELEASE_HANG   1
  62 #define PRELEASE_KILL   2
  63
  64 typedef struct prmap {
  65         uintptr_t       pr_vaddr;       /* Virtual address. */
  66         size_t          pr_size;        /* Mapping size in bytes */
  67         size_t          pr_offset;      /* Mapping offset in object */
  68         char            pr_mapname[PATH_MAX];   /* Mapping filename */
  69         uint8_t         pr_mflags;      /* Protection flags */
  70 #define MA_READ         0x01
  71 #define MA_WRITE        0x02
  72 #define MA_EXEC         0x04
  73 #define MA_COW          0x08
  74 #define MA_NEEDS_COPY   0x10
  75 #define MA_NOCOREDUMP   0x20
  76 } prmap_t;
  77
  78 typedef struct prsyminfo {
  79         u_int           prs_lmid;       /* Map id. */
  80         u_int           prs_id;         /* Symbol id. */
  81 } prsyminfo_t;
  82
  83 typedef int proc_map_f(void *, const prmap_t *, const char *);
  84 typedef int proc_sym_f(void *, const GElf_Sym *, const char *);
  85
  86 /* Values for ELF sections */
  87 #define PR_SYMTAB       1
  88 #define PR_DYNSYM       2
  89
  90 /* Values for the 'mask' parameter in the iteration functions */
  91 #define BIND_LOCAL      0x0001
  92 #define BIND_GLOBAL     0x0002
  93 #define BIND_WEAK       0x0004
  94 #define BIND_ANY        (BIND_LOCAL|BIND_GLOBAL|BIND_WEAK)
  95 #define TYPE_NOTYPE     0x0100
  96 #define TYPE_OBJECT     0x0200
  97 #define TYPE_FUNC       0x0400
  98 #define TYPE_SECTION    0x0800
  99 #define TYPE_FILE       0x1000
 100 #define TYPE_ANY        (TYPE_NOTYPE|TYPE_OBJECT|TYPE_FUNC|TYPE_SECTION|\
 101                          TYPE_FILE)
 102
 103 typedef enum {
 104         REG_PC,
 105         REG_SP,
 106         REG_RVAL1,
 107         REG_RVAL2
 108 } proc_reg_t;
 109
 110 #define SIG2STR_MAX     8
 111
 112 typedef struct lwpstatus {
 113         int pr_why;
 114 #define PR_REQUESTED    1
 115 #define PR_FAULTED      2
 116 #define PR_SYSENTRY     3
 117 #define PR_SYSEXIT      4
 118 #define PR_SIGNALLED    5
 119         int pr_what;
 120 #define FLTBPT          -1
 121 } lwpstatus_t;
 122
 123 #define PR_MODEL_ILP32  1
 124 #define PR_MODEL_LP64   2
 125
 126 struct proc_handle_public {
 127         pid_t           pid;
 128 };
 129
 130 #define proc_getpid(phdl)       (((struct proc_handle_public *)(phdl))->pid)
 131
 132 /* Function prototype definitions. */
 133 __BEGIN_DECLS
 134
 135 prmap_t *proc_addr2map(struct proc_handle *, uintptr_t);
 136 prmap_t *proc_name2map(struct proc_handle *, const char *);
 137 char    *proc_objname(struct proc_handle *, uintptr_t, char *, size_t);
 138 int     proc_iter_objs(struct proc_handle *, proc_map_f *, void *);
 139 int     proc_iter_symbyaddr(struct proc_handle *, const char *, int,
 140             int, proc_sym_f *, void *);
 141 int     proc_addr2sym(struct proc_handle *, uintptr_t, char *, size_t, GElf_Sym *);
 142 int     proc_attach(pid_t pid, int flags, struct proc_handle **pphdl);
 143 int     proc_continue(struct proc_handle *);
 144 int     proc_clearflags(struct proc_handle *, int);
 145 int     proc_create(const char *, char * const *, char * const *,
 146             proc_child_func *, void *, struct proc_handle **);
 147 int     proc_detach(struct proc_handle *, int);
 148 int     proc_getflags(struct proc_handle *);
 149 int     proc_name2sym(struct proc_handle *, const char *, const char *,
 150             GElf_Sym *, prsyminfo_t *);
 151 struct ctf_file *proc_name2ctf(struct proc_handle *, const char *);
 152 int     proc_setflags(struct proc_handle *, int);
 153 int     proc_state(struct proc_handle *);
 154 int     proc_getmodel(struct proc_handle *);
 155 int     proc_wstatus(struct proc_handle *);
 156 int     proc_getwstat(struct proc_handle *);
 157 char *  proc_signame(int, char *, size_t);
 158 int     proc_read(struct proc_handle *, void *, size_t, size_t);
 159 const lwpstatus_t *proc_getlwpstatus(struct proc_handle *);
 160 void    proc_free(struct proc_handle *);
 161 rd_agent_t *proc_rdagent(struct proc_handle *);
 162 void    proc_updatesyms(struct proc_handle *);
 163 int     proc_bkptset(struct proc_handle *, uintptr_t, unsigned long *);
 164 int     proc_bkptdel(struct proc_handle *, uintptr_t, unsigned long);
 165 void    proc_bkptregadj(unsigned long *);
 166 int     proc_bkptexec(struct proc_handle *, unsigned long);
 167 int     proc_regget(struct proc_handle *, proc_reg_t, unsigned long *);
 168 int     proc_regset(struct proc_handle *, proc_reg_t, unsigned long);
 169
 170 __END_DECLS
 171
 172 #endif /* _LIBPROC_H_ */