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