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