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