share/man/man3proc/Psymbol_iter.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 PSYMBOL_ITER 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Psymbol_iter ,
  19 .Nm Psymbol_iter_by_addr ,
  20 .Nm Psymbol_iter_by_lmid ,
  21 .Nm Psymbol_iter_by_name ,
  22 .Nm Pxsymbol_iter
  23 .Nd iterate symbols in a process
  24 .Sh SYNOPSIS
  25 .Lb libproc
  26 .In libproc.h
  27 .Ft int
  28 .Fo Psymbol_iter
  29 .Fa "struct ps_prochandle *P"
  30 .Fa "const char *object_name"
  31 .Fa "int which"
  32 .Fa "int mask"
  33 .Fa "proc_sym_f *func"
  34 .Fa "void *data"
  35 .Fc
  36 .Ft int
  37 .Fo Psymbol_iter_by_addr
  38 .Fa "struct ps_prochandle *P"
  39 .Fa "const char *object_name"
  40 .Fa "int which"
  41 .Fa "int mask"
  42 .Fa "proc_sym_f *func"
  43 .Fa "void *data"
  44 .Fc
  45 .Ft int
  46 .Fo Psymbol_iter_by_lmid
  47 .Fa "struct ps_prochandle *P"
  48 .Fa "Lmid_t lmid"
  49 .Fa "const char *object_name"
  50 .Fa "int which"
  51 .Fa "int mask"
  52 .Fa "proc_sym_f *func"
  53 .Fa "void *data"
  54 .Fc
  55 .Ft int
  56 .Fo Psymbol_iter_by_name
  57 .Fa "struct ps_prochandle *P"
  58 .Fa "const char *object_name"
  59 .Fa "int which"
  60 .Fa "int mask"
  61 .Fa "proc_sym_f *func"
  62 .Fa "void *data"
  63 .Fc
  64 .Ft int
  65 .Fo Pxsymbol_iter
  66 .Fa "struct ps_prochandle *P"
  67 .Fa "Lmid_t lmid"
  68 .Fa "const char *object_name"
  69 .Fa "int which"
  70 .Fa "int mask"
  71 .Fa "proc_xsym_f *func"
  72 .Fa "void *data"
  73 .Fc
  74 .Sh DESCRIPTION
  75 The
  76 .Fn Psymbol_iter ,
  77 .Fn Psymbol_iter_by_addr ,
  78 .Fn Psymbol_iter_by_lmid ,
  79 .Fn Psymbol_iter_by_name ,
  80 and
  81 .Fn Pxsymbol_iter
  82 functions are used to iterate over the symbols present in the process
  83 referred to by the handle
  84 .Fa P .
  85 For each symbol found, the callback function
  86 .Fa func
  87 will be called once and the argument
  88 .Fa data
  89 will be passed to it along with an ELF symbol entry in the form of the
  90 .Sy GElf_Sym
  91 along with the name of the symbol, if known.
  92 In the case of the
  93 .Fn Pxsymbol_iter
  94 function an additional
  95 .Sy prsyminfo_t
  96 argument will be provided to the callback.
  97 The definitions of
  98 .Sy proc_sym_f ,
  99 .Sy proc_xsym_f ,
 100 and
 101 .Sy prsyminfo_t
 102 are found in
 103 .Xr libproc 3LIB .
 104 .Pp
 105 The
 106 .Fa object_name
 107 argument names the object that is a part of the controlled process which
 108 will be searched for symbols.
 109 Only one object may be searched at any given time.
 110 Valid object names may be obtained through the
 111 .Xr Pobjname 3PROC
 112 and
 113 .Xr Pobject_iter 3PROC
 114 functions, among others.
 115 The system also has two special object names that may be passed in to refer to
 116 the objects of the executable file and for ld.so.1.
 117 The symbol
 118 .Dv PR_OBJ_EXEC
 119 refers to the executables object and the symbol
 120 .Dv PR_OBJ_LDSO
 121 refers to the object ld.so.1.
 122 .Pp
 123 The
 124 .Fa which
 125 argument controls which of two possible symbol tables will be searched.
 126 If the argument is
 127 .Dv PR_SYMTAB
 128 then the ELF symbol table will be searched.
 129 Otherwise, if it is
 130 .Dv PR_DYNSYM
 131 then the symbol table associated with the dynamic section will be
 132 searched instead.
 133 If any other value is specified for
 134 .Fa which ,
 135 then an error will be returned.
 136 .Pp
 137 The
 138 .Fa mask
 139 argument controls which symbols will be included.
 140 The
 141 .Fa mask
 142 argument allows for control over both the symbol's binding and the
 143 symbol's type.
 144 These flags logically correspond to the various ELF symbol bindings and types.
 145 The following values may be passed as a bitwise-inclusive-OR into the
 146 .Fa flags
 147 argument:
 148 .Bl -tag -width Dv -offset indent
 149 .It Dv BIND_LOCAL
 150 The symbol is a local symbol.
 151 Local symbols are not visible outside of their object file.
 152 .It Dv BIND_GLOBAL
 153 The symbol is a global symbol.
 154 Global symbols are visible outside of their object file and may be referred to
 155 by other ELF objects.
 156 .It Dv BIND_WEAK
 157 The symbol is a weak symbol.
 158 Weak symbols are visible outside of their object file, but another definition of
 159 the symbol may be used instead.
 160 .It Dv BIND_ANY
 161 This is a combination of
 162 .Dv BIND_LOCAL ,
 163 .Dv BIND_GLOBAL ,
 164 and
 165 .Dv BIND_WEAK .
 166 Every symbol's binding will match this value.
 167 .It Dv TYPE_NOTYPE
 168 The symbol's type is not specified.
 169 .It Dv TYPE_OBJECT
 170 The symbol refers to a data object.
 171 For example, variables.
 172 .It Dv TYPE_FUNC
 173 The symbol refers to a function.
 174 .It Dv TYPE_SECTION
 175 The symbol refers to an ELF section.
 176 .It Dv TYPE_FILE
 177 The symbol refers to the name of a source file associated with an object
 178 file.
 179 .It Dv TYPE_ANY
 180 This is a combination of
 181 .Dv TYPE_NOTYPE ,
 182 .Dv TYPE_OBJECT ,
 183 .Dv TYPE_FUNC ,
 184 .Dv TYPE_SECTION ,
 185 and
 186 .Dv TYPE_FILE .
 187 Every symbol's type will match this value.
 188 .El
 189 .Pp
 190 To obtain all of the symbols in an object, the caller would pass the
 191 expression
 192 .Dv BIND_ANY |
 193 .Dv TYPE_ANY
 194 in as the value of
 195 .Fa mask.
 196 .Pp
 197 The
 198 .Fn Psymbol_iter_by_lmid
 199 and
 200 .Fn Pxsymbol_iter
 201 functions allow for a link-map identifier to be specified in the
 202 .Fa lmid
 203 argument.
 204 This will restrict the search for the object specified in
 205 .Fa object_name
 206 to the specified link-map.
 207 There are three special link-map identifiers that may be passed in.
 208 The symbol
 209 .Dv PR_LMID_EVERY
 210 indicates that every link-map should be searched.
 211 The symbol
 212 .Dv LM_ID_BASE
 213 indicates that the base link-map, the one that is used for the
 214 executable should be searched.
 215 Finally, the symbol
 216 .Dv LM_ID_LDSO
 217 refers to the link-map that is used by the run-time link editor, ld.so.1.
 218 The functions which do not allow a link-map identifier to be specified always
 219 search every link-map.
 220 .Pp
 221 By default, symbols are iterated based on the order of the symbol
 222 table being searched.
 223 However, it is also possible to iterate based on the name of the symbol and
 224 based on the address of the symbol.
 225 To iterate by name use the
 226 .Fn Psymbol_iter_by_name
 227 function.
 228 To iterate by address use the
 229 .Fn Psymbol_iter_by_addr
 230 function.
 231 The
 232 .Fn Psymbol_iter ,
 233 .Fn Psymbol_iter_by_lmid ,
 234 and
 235 .Fn Pxsymbol_iter
 236 functions all sort based on the order of the symbol table.
 237 .Pp
 238 The return value of the callback function
 239 .Fa func
 240 determines whether or not iteration continues.
 241 If
 242 .Fa func
 243 returns
 244 .Sy 0,
 245 then iteration will continue.
 246 However, if
 247 .Fa func
 248 returns non-zero, then iteration will halt and that value will be used
 249 as the return value of the
 250 .Fn Psymbol_iter ,
 251 .Fn Psymbol_iter_by_addr ,
 252 .Fn Psymbol_iter_by_lmid ,
 253 .Fn Psymbol_iter_by_name ,
 254 and
 255 .Fn Pxsymbol_iter
 256 functions.
 257 Because these functions return
 258 .Sy -1
 259 on internal failure, it is recommended that the callback function not return
 260 .Sy -1
 261 to indicate an error so that the caller may distinguish between the
 262 failure of the callback function and the failure of these functions.
 263 .Sh RETURN VALUES
 264 Upon successful completion, the
 265 .Fn Psymbol_iter ,
 266 .Fn Psymbol_iter_by_addr ,
 267 .Fn Psymbol_iter_by_lmid ,
 268 .Fn Psymbol_iter_by_name ,
 269 and
 270 .Fn Pxsymbol_iter
 271 functions return
 272 .Sy 0 .
 273 If there was an internal error then
 274 .Sy -1
 275 is returned.
 276 Otherwise, if the callback function
 277 .Fa func
 278 returns non-zero, then its return value will be returned instead.
 279 .Sh INTERFACE STABILITY
 280 .Sy Uncommitted
 281 .Sh MT-LEVEL
 282 See
 283 .Sy LOCKING
 284 in
 285 .Xr libproc 3LIB .
 286 .Sh SEE ALSO
 287 .Xr elf 3ELF ,
 288 .Xr gelf 3ELF ,
 289 .Xr libproc 3LIB ,
 290 .Xr proc 4