usr/src/man/man3proc/Plookup_by_addr.3proc

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PLOOKUP_BY_ADDR 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plookup_by_addr ,
  19 .Nm Pxlookup_by_addr ,
  20 .Nm Pxlookup_by_addr_resolved ,
  21 .Nm Plookup_by_name ,
  22 .Nm Pxlookup_by_name
  23 .Nd lookup symbols in a process
  24 .Sh SYNOPSIS
  25 .Lb libproc
  26 .In libproc.h
  27 .Ft int
  28 .Fo Plookup_by_addr
  29 .Fa "struct ps_prochandle *P"
  30 .Fa "uintptr_t addr"
  31 .Fa "char *buf"
  32 .Fa "size_t size"
  33 .Fa "Gelf_Sym *symp"
  34 .Fc
  35 .Ft int
  36 .Fo Pxlookup_by_addr
  37 .Fa "struct ps_prochandle *P"
  38 .Fa "uintptr_t addr"
  39 .Fa "char *buf"
  40 .Fa "size_t size"
  41 .Fa "Gelf_Sym *symp"
  42 .Fa "prsyminfo_t *sip"
  43 .Fc
  44 .Ft int
  45 .Fo Pxlookup_by_addr_resolved
  46 .Fa "struct ps_prochandle *P"
  47 .Fa "uintptr_t addr"
  48 .Fa "char *buf"
  49 .Fa "size_t size"
  50 .Fa "Gelf_Sym *symp"
  51 .Fa "prsyminfo_t *sip"
  52 .Fc
  53 .Ft int
  54 .Fo Plookup_by_name
  55 .Fa "struct ps_prochandle *P"
  56 .Fa "const char *object"
  57 .Fa "const char *symbol"
  58 .Fa "GElf_Sym *symp"
  59 .Fc
  60 .Ft int
  61 .Fo Pxlookup_by_name
  62 .Fa "struct ps_prochandle *P"
  63 .Fa "Lmid_t lmid"
  64 .Fa "const char *object"
  65 .Fa "const char *symbol"
  66 .Fa "GElf_Sym *symp"
  67 .Fa "prsyminfo_t *sip"
  68 .Fc
  69 .Sh DESCRIPTION
  70 The
  71 .Fn Plookup_by_addr ,
  72 .Fn Pxlookup_by_addr ,
  73 .Fn Pxlookup_by_addr_resolved ,
  74 .Fn Plookup_by_name ,
  75 and
  76 .Fn Pxlookup_by_name
  77 functions look up symbol information in the process handle
  78 .Fa P
  79 and fill in the ELF symbol information in
  80 .Fa symp
  81 with the found symbol.
  82 Symbols may be looked up both by address and name.
  83 .Pp
  84 The
  85 .Fn Plookup_by_addr
  86 function looks up symbol information corresponding to the address
  87 .Fa addr .
  88 If found, up to
  89 .Fa size
  90 bytes of the symbol's name, including the null terminator will be filled
  91 in to the buffer
  92 .Fa buf .
  93 .Pp
  94 The
  95 .Fn Pxlookup_by_addr
  96 function is identical to the
  97 .Fn Plookup_by_addr
  98 function, except that it also fills in the structure
  99 .Fa sip
 100 with additional information.
 101 The definition of the
 102 .Sy prsyminfo_t
 103 is found in
 104 .Xr libproc 3PROC .
 105 .Pp
 106 The
 107 .Fn Pxlookup_by_addr_resolved
 108 function is similar to the
 109 .Fn Pxlookup_by_addr
 110 function; however, it attempts to resolve the paths present in the
 111 .Sy prsyminfo_t
 112 to an absolute path on the file system.
 113 .Pp
 114 The
 115 .Fn Plookup_by_name
 116 function attempts to look up a symbol based on its name.
 117 The
 118 .Fa object
 119 argument allows the caller to specify a specific object that was mapped
 120 in by the run-time link-editor to search for
 121 .Fa symbol
 122 in.
 123 The system provides three special values which may be passed in for
 124 .Fa object .
 125 The value
 126 .Dv PR_OBJ_EXEC
 127 refers to the executable's object (a.out).
 128 The value
 129 .Dv PR_OBJ_LDSO
 130 refers to the object
 131 .Sy ld.so.1 .
 132 The value
 133 .Dv PR_OBJ_EVERY
 134 indicates that every object should be searched.
 135 .Pp
 136 The
 137 .Fn Pxlookup_by_name
 138 function is similar to the
 139 .Fn Plookup_by_name
 140 function; however, it allows a link-map identifier,
 141 .Fa lmid ,
 142 to be specified and also provides additional information about the
 143 symbol in the form of the
 144 .Sy prsyminfo_t
 145 .Fa sip .
 146 The specification of
 147 .Fa lmid
 148 restricts the search for the object named
 149 .Fa object
 150 and symbol named
 151 .Fa symbol
 152 to the specified link-map.
 153 .Pp
 154 There are three special link-map identifiers that may be passed in.
 155 The symbol
 156 .Dv PR_LMID_EVERY
 157 indicates that every link-map should be searched.
 158 The symbol
 159 .Dv LM_ID_BASE
 160 indicates that the base link-map, the one that is used for the
 161 executable should be searched.
 162 Finally, the symbol
 163 .Dv LM_ID_LDSO
 164 refers to the link-map that is used by the run-time link editor, ld.so.1.
 165 The
 166 .Fn Plookup_by_name
 167 function behaves like
 168 .Fn Pxlookup_by_name
 169 when the
 170 .Dv PR_LMID_EVERY
 171 argument is passed to
 172 .Fa lmid ,
 173 indicating that every link-map should be searched.
 174 .Sh RETURN VALUES
 175 Upon successful completion, the
 176 .Fn Plookup_by_addr ,
 177 .Fn Pxlookup_by_addr ,
 178 .Fn Pxlookup_by_addr_resolved ,
 179 .Fn Plookup_by_name ,
 180 and
 181 .Fn Pxlookup_by_name
 182 functions return
 183 .Sy 0
 184 and fill in the symbol information.
 185 Otherwise,
 186 .Sy -1
 187 is returned to indicate that the symbol could not be found.
 188 .Sh INTERFACE STABILITY
 189 .Sy Uncommitted
 190 .Sh MT-LEVEL
 191 See
 192 .Sy LOCKING
 193 in
 194 .Xr libproc 3LIB .
 195 .Sh SEE ALSO
 196 .Xr elf 3ELF ,
 197 .Xr gelf 3ELF ,
 198 .Xr libproc 3LIB ,
 199 .Xr proc 4