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