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