143051d27SRobert Mustacchi.\" 243051d27SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 343051d27SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 443051d27SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 543051d27SRobert Mustacchi.\" 1.0 of the CDDL. 643051d27SRobert Mustacchi.\" 743051d27SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 843051d27SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 943051d27SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1043051d27SRobert Mustacchi.\" 1143051d27SRobert Mustacchi.\" 1243051d27SRobert Mustacchi.\" Copyright 2015 Joyent, Inc. 1343051d27SRobert Mustacchi.\" 1443051d27SRobert Mustacchi.Dd May 11, 2016 1543051d27SRobert Mustacchi.Dt PSYMBOL_ITER 3PROC 1643051d27SRobert Mustacchi.Os 1743051d27SRobert Mustacchi.Sh NAME 1843051d27SRobert Mustacchi.Nm Psymbol_iter , 1943051d27SRobert Mustacchi.Nm Psymbol_iter_by_addr , 2043051d27SRobert Mustacchi.Nm Psymbol_iter_by_lmid , 2143051d27SRobert Mustacchi.Nm Psymbol_iter_by_name , 2243051d27SRobert Mustacchi.Nm Pxsymbol_iter 2343051d27SRobert Mustacchi.Nd iterate symbols in a process 24ab618543SJohn Levon.Sh LIBRARY 2543051d27SRobert Mustacchi.Lb libproc 26ab618543SJohn Levon.Sh SYNOPSIS 2743051d27SRobert Mustacchi.In libproc.h 2843051d27SRobert Mustacchi.Ft int 2943051d27SRobert Mustacchi.Fo Psymbol_iter 3043051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 3143051d27SRobert Mustacchi.Fa "const char *object_name" 3243051d27SRobert Mustacchi.Fa "int which" 3343051d27SRobert Mustacchi.Fa "int mask" 3443051d27SRobert Mustacchi.Fa "proc_sym_f *func" 3543051d27SRobert Mustacchi.Fa "void *data" 3643051d27SRobert Mustacchi.Fc 3743051d27SRobert Mustacchi.Ft int 3843051d27SRobert Mustacchi.Fo Psymbol_iter_by_addr 3943051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 4043051d27SRobert Mustacchi.Fa "const char *object_name" 4143051d27SRobert Mustacchi.Fa "int which" 4243051d27SRobert Mustacchi.Fa "int mask" 4343051d27SRobert Mustacchi.Fa "proc_sym_f *func" 4443051d27SRobert Mustacchi.Fa "void *data" 4543051d27SRobert Mustacchi.Fc 4643051d27SRobert Mustacchi.Ft int 4743051d27SRobert Mustacchi.Fo Psymbol_iter_by_lmid 4843051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 4943051d27SRobert Mustacchi.Fa "Lmid_t lmid" 5043051d27SRobert Mustacchi.Fa "const char *object_name" 5143051d27SRobert Mustacchi.Fa "int which" 5243051d27SRobert Mustacchi.Fa "int mask" 5343051d27SRobert Mustacchi.Fa "proc_sym_f *func" 5443051d27SRobert Mustacchi.Fa "void *data" 5543051d27SRobert Mustacchi.Fc 5643051d27SRobert Mustacchi.Ft int 5743051d27SRobert Mustacchi.Fo Psymbol_iter_by_name 5843051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 5943051d27SRobert Mustacchi.Fa "const char *object_name" 6043051d27SRobert Mustacchi.Fa "int which" 6143051d27SRobert Mustacchi.Fa "int mask" 6243051d27SRobert Mustacchi.Fa "proc_sym_f *func" 6343051d27SRobert Mustacchi.Fa "void *data" 6443051d27SRobert Mustacchi.Fc 6543051d27SRobert Mustacchi.Ft int 6643051d27SRobert Mustacchi.Fo Pxsymbol_iter 6743051d27SRobert Mustacchi.Fa "struct ps_prochandle *P" 6843051d27SRobert Mustacchi.Fa "Lmid_t lmid" 6943051d27SRobert Mustacchi.Fa "const char *object_name" 7043051d27SRobert Mustacchi.Fa "int which" 7143051d27SRobert Mustacchi.Fa "int mask" 7243051d27SRobert Mustacchi.Fa "proc_xsym_f *func" 7343051d27SRobert Mustacchi.Fa "void *data" 7443051d27SRobert Mustacchi.Fc 7543051d27SRobert Mustacchi.Sh DESCRIPTION 7643051d27SRobert MustacchiThe 7743051d27SRobert Mustacchi.Fn Psymbol_iter , 7843051d27SRobert Mustacchi.Fn Psymbol_iter_by_addr , 7943051d27SRobert Mustacchi.Fn Psymbol_iter_by_lmid , 8043051d27SRobert Mustacchi.Fn Psymbol_iter_by_name , 8143051d27SRobert Mustacchiand 8243051d27SRobert Mustacchi.Fn Pxsymbol_iter 8343051d27SRobert Mustacchifunctions are used to iterate over the symbols present in the process 8443051d27SRobert Mustacchireferred to by the handle 8543051d27SRobert Mustacchi.Fa P . 8643051d27SRobert MustacchiFor each symbol found, the callback function 8743051d27SRobert Mustacchi.Fa func 8843051d27SRobert Mustacchiwill be called once and the argument 8943051d27SRobert Mustacchi.Fa data 9043051d27SRobert Mustacchiwill be passed to it along with an ELF symbol entry in the form of the 9143051d27SRobert Mustacchi.Sy GElf_Sym 9243051d27SRobert Mustacchialong with the name of the symbol, if known. 9343051d27SRobert MustacchiIn the case of the 9443051d27SRobert Mustacchi.Fn Pxsymbol_iter 9543051d27SRobert Mustacchifunction an additional 9643051d27SRobert Mustacchi.Sy prsyminfo_t 9772d3dbb9SYuri Pankovargument will be provided to the callback. 9872d3dbb9SYuri PankovThe definitions of 9943051d27SRobert Mustacchi.Sy proc_sym_f , 10043051d27SRobert Mustacchi.Sy proc_xsym_f , 10143051d27SRobert Mustacchiand 10243051d27SRobert Mustacchi.Sy prsyminfo_t 10343051d27SRobert Mustacchiare found in 10443051d27SRobert Mustacchi.Xr libproc 3LIB . 10543051d27SRobert Mustacchi.Pp 10643051d27SRobert MustacchiThe 10743051d27SRobert Mustacchi.Fa object_name 10843051d27SRobert Mustacchiargument names the object that is a part of the controlled process which 10972d3dbb9SYuri Pankovwill be searched for symbols. 11072d3dbb9SYuri PankovOnly one object may be searched at any given time. 11172d3dbb9SYuri PankovValid object names may be obtained through the 11243051d27SRobert Mustacchi.Xr Pobjname 3PROC 11343051d27SRobert Mustacchiand 11443051d27SRobert Mustacchi.Xr Pobject_iter 3PROC 11572d3dbb9SYuri Pankovfunctions, among others. 11672d3dbb9SYuri PankovThe system also has two special object names that may be passed in to refer to 11772d3dbb9SYuri Pankovthe objects of the executable file and for ld.so.1. 11872d3dbb9SYuri PankovThe symbol 11943051d27SRobert Mustacchi.Dv PR_OBJ_EXEC 12043051d27SRobert Mustacchirefers to the executables object and the symbol 12143051d27SRobert Mustacchi.Dv PR_OBJ_LDSO 12243051d27SRobert Mustacchirefers to the object ld.so.1. 12343051d27SRobert Mustacchi.Pp 12443051d27SRobert MustacchiThe 12543051d27SRobert Mustacchi.Fa which 12643051d27SRobert Mustacchiargument controls which of two possible symbol tables will be searched. 12743051d27SRobert MustacchiIf the argument is 12843051d27SRobert Mustacchi.Dv PR_SYMTAB 12972d3dbb9SYuri Pankovthen the ELF symbol table will be searched. 13072d3dbb9SYuri PankovOtherwise, if it is 13143051d27SRobert Mustacchi.Dv PR_DYNSYM 13243051d27SRobert Mustacchithen the symbol table associated with the dynamic section will be 13372d3dbb9SYuri Pankovsearched instead. 13472d3dbb9SYuri PankovIf any other value is specified for 13543051d27SRobert Mustacchi.Fa which , 13643051d27SRobert Mustacchithen an error will be returned. 13743051d27SRobert Mustacchi.Pp 13843051d27SRobert MustacchiThe 13943051d27SRobert Mustacchi.Fa mask 14072d3dbb9SYuri Pankovargument controls which symbols will be included. 14172d3dbb9SYuri PankovThe 14243051d27SRobert Mustacchi.Fa mask 14343051d27SRobert Mustacchiargument allows for control over both the symbol's binding and the 14472d3dbb9SYuri Pankovsymbol's type. 14572d3dbb9SYuri PankovThese flags logically correspond to the various ELF symbol bindings and types. 14672d3dbb9SYuri PankovThe following values may be passed as a bitwise-inclusive-OR into the 14743051d27SRobert Mustacchi.Fa flags 14843051d27SRobert Mustacchiargument: 14943051d27SRobert Mustacchi.Bl -tag -width Dv -offset indent 15043051d27SRobert Mustacchi.It Dv BIND_LOCAL 15172d3dbb9SYuri PankovThe symbol is a local symbol. 15272d3dbb9SYuri PankovLocal symbols are not visible outside of their object file. 15343051d27SRobert Mustacchi.It Dv BIND_GLOBAL 15472d3dbb9SYuri PankovThe symbol is a global symbol. 15572d3dbb9SYuri PankovGlobal symbols are visible outside of their object file and may be referred to 15672d3dbb9SYuri Pankovby other ELF objects. 15743051d27SRobert Mustacchi.It Dv BIND_WEAK 15872d3dbb9SYuri PankovThe symbol is a weak symbol. 15972d3dbb9SYuri PankovWeak symbols are visible outside of their object file, but another definition of 16072d3dbb9SYuri Pankovthe symbol may be used instead. 16143051d27SRobert Mustacchi.It Dv BIND_ANY 16243051d27SRobert MustacchiThis is a combination of 16343051d27SRobert Mustacchi.Dv BIND_LOCAL , 16443051d27SRobert Mustacchi.Dv BIND_GLOBAL , 16543051d27SRobert Mustacchiand 16643051d27SRobert Mustacchi.Dv BIND_WEAK . 16743051d27SRobert MustacchiEvery symbol's binding will match this value. 16843051d27SRobert Mustacchi.It Dv TYPE_NOTYPE 16943051d27SRobert MustacchiThe symbol's type is not specified. 17043051d27SRobert Mustacchi.It Dv TYPE_OBJECT 17172d3dbb9SYuri PankovThe symbol refers to a data object. 17272d3dbb9SYuri PankovFor example, variables. 17343051d27SRobert Mustacchi.It Dv TYPE_FUNC 17443051d27SRobert MustacchiThe symbol refers to a function. 17543051d27SRobert Mustacchi.It Dv TYPE_SECTION 17643051d27SRobert MustacchiThe symbol refers to an ELF section. 17743051d27SRobert Mustacchi.It Dv TYPE_FILE 17843051d27SRobert MustacchiThe symbol refers to the name of a source file associated with an object 17943051d27SRobert Mustacchifile. 18043051d27SRobert Mustacchi.It Dv TYPE_ANY 18143051d27SRobert MustacchiThis is a combination of 18243051d27SRobert Mustacchi.Dv TYPE_NOTYPE , 18343051d27SRobert Mustacchi.Dv TYPE_OBJECT , 18443051d27SRobert Mustacchi.Dv TYPE_FUNC , 18543051d27SRobert Mustacchi.Dv TYPE_SECTION , 18643051d27SRobert Mustacchiand 18743051d27SRobert Mustacchi.Dv TYPE_FILE . 18843051d27SRobert MustacchiEvery symbol's type will match this value. 18943051d27SRobert Mustacchi.El 19043051d27SRobert Mustacchi.Pp 19143051d27SRobert MustacchiTo obtain all of the symbols in an object, the caller would pass the 19243051d27SRobert Mustacchiexpression 19343051d27SRobert Mustacchi.Dv BIND_ANY | 19443051d27SRobert Mustacchi.Dv TYPE_ANY 19543051d27SRobert Mustacchiin as the value of 19643051d27SRobert Mustacchi.Fa mask. 19743051d27SRobert Mustacchi.Pp 19843051d27SRobert MustacchiThe 19943051d27SRobert Mustacchi.Fn Psymbol_iter_by_lmid 20043051d27SRobert Mustacchiand 20143051d27SRobert Mustacchi.Fn Pxsymbol_iter 20243051d27SRobert Mustacchifunctions allow for a link-map identifier to be specified in the 20343051d27SRobert Mustacchi.Fa lmid 20472d3dbb9SYuri Pankovargument. 20572d3dbb9SYuri PankovThis will restrict the search for the object specified in 20643051d27SRobert Mustacchi.Fa object_name 20772d3dbb9SYuri Pankovto the specified link-map. 20872d3dbb9SYuri PankovThere are three special link-map identifiers that may be passed in. 20972d3dbb9SYuri PankovThe symbol 21043051d27SRobert Mustacchi.Dv PR_LMID_EVERY 21172d3dbb9SYuri Pankovindicates that every link-map should be searched. 21272d3dbb9SYuri PankovThe symbol 21343051d27SRobert Mustacchi.Dv LM_ID_BASE 21443051d27SRobert Mustacchiindicates that the base link-map, the one that is used for the 21572d3dbb9SYuri Pankovexecutable should be searched. 21672d3dbb9SYuri PankovFinally, the symbol 21743051d27SRobert Mustacchi.Dv LM_ID_LDSO 21872d3dbb9SYuri Pankovrefers to the link-map that is used by the run-time link editor, ld.so.1. 21972d3dbb9SYuri PankovThe functions which do not allow a link-map identifier to be specified always 22072d3dbb9SYuri Pankovsearch every link-map. 22143051d27SRobert Mustacchi.Pp 22243051d27SRobert MustacchiBy default, symbols are iterated based on the order of the symbol 22372d3dbb9SYuri Pankovtable being searched. 22472d3dbb9SYuri PankovHowever, it is also possible to iterate based on the name of the symbol and 22572d3dbb9SYuri Pankovbased on the address of the symbol. 22672d3dbb9SYuri PankovTo iterate by name use the 22743051d27SRobert Mustacchi.Fn Psymbol_iter_by_name 22872d3dbb9SYuri Pankovfunction. 22972d3dbb9SYuri PankovTo iterate by address use the 23043051d27SRobert Mustacchi.Fn Psymbol_iter_by_addr 23172d3dbb9SYuri Pankovfunction. 23272d3dbb9SYuri PankovThe 23343051d27SRobert Mustacchi.Fn Psymbol_iter , 23443051d27SRobert Mustacchi.Fn Psymbol_iter_by_lmid , 23543051d27SRobert Mustacchiand 23643051d27SRobert Mustacchi.Fn Pxsymbol_iter 23743051d27SRobert Mustacchifunctions all sort based on the order of the symbol table. 23843051d27SRobert Mustacchi.Pp 23943051d27SRobert MustacchiThe return value of the callback function 24043051d27SRobert Mustacchi.Fa func 24172d3dbb9SYuri Pankovdetermines whether or not iteration continues. 24272d3dbb9SYuri PankovIf 24343051d27SRobert Mustacchi.Fa func 24443051d27SRobert Mustacchireturns 24543051d27SRobert Mustacchi.Sy 0, 24672d3dbb9SYuri Pankovthen iteration will continue. 24772d3dbb9SYuri PankovHowever, if 24843051d27SRobert Mustacchi.Fa func 24943051d27SRobert Mustacchireturns non-zero, then iteration will halt and that value will be used 25043051d27SRobert Mustacchias the return value of the 25143051d27SRobert Mustacchi.Fn Psymbol_iter , 25243051d27SRobert Mustacchi.Fn Psymbol_iter_by_addr , 25343051d27SRobert Mustacchi.Fn Psymbol_iter_by_lmid , 25443051d27SRobert Mustacchi.Fn Psymbol_iter_by_name , 25543051d27SRobert Mustacchiand 25643051d27SRobert Mustacchi.Fn Pxsymbol_iter 25772d3dbb9SYuri Pankovfunctions. 25872d3dbb9SYuri PankovBecause these functions return 25943051d27SRobert Mustacchi.Sy -1 26043051d27SRobert Mustacchion internal failure, it is recommended that the callback function not return 26143051d27SRobert Mustacchi.Sy -1 26243051d27SRobert Mustacchito indicate an error so that the caller may distinguish between the 26343051d27SRobert Mustacchifailure of the callback function and the failure of these functions. 26443051d27SRobert Mustacchi.Sh RETURN VALUES 26543051d27SRobert MustacchiUpon successful completion, the 26643051d27SRobert Mustacchi.Fn Psymbol_iter , 26743051d27SRobert Mustacchi.Fn Psymbol_iter_by_addr , 26843051d27SRobert Mustacchi.Fn Psymbol_iter_by_lmid , 26943051d27SRobert Mustacchi.Fn Psymbol_iter_by_name , 27043051d27SRobert Mustacchiand 27143051d27SRobert Mustacchi.Fn Pxsymbol_iter 27243051d27SRobert Mustacchifunctions return 27343051d27SRobert Mustacchi.Sy 0 . 27443051d27SRobert MustacchiIf there was an internal error then 27543051d27SRobert Mustacchi.Sy -1 27672d3dbb9SYuri Pankovis returned. 27772d3dbb9SYuri PankovOtherwise, if the callback function 27843051d27SRobert Mustacchi.Fa func 27943051d27SRobert Mustacchireturns non-zero, then its return value will be returned instead. 28043051d27SRobert Mustacchi.Sh INTERFACE STABILITY 28143051d27SRobert Mustacchi.Sy Uncommitted 28243051d27SRobert Mustacchi.Sh MT-LEVEL 28343051d27SRobert MustacchiSee 28443051d27SRobert Mustacchi.Sy LOCKING 28543051d27SRobert Mustacchiin 28643051d27SRobert Mustacchi.Xr libproc 3LIB . 28743051d27SRobert Mustacchi.Sh SEE ALSO 28843051d27SRobert Mustacchi.Xr elf 3ELF , 28943051d27SRobert Mustacchi.Xr gelf 3ELF , 29043051d27SRobert Mustacchi.Xr libproc 3LIB , 291*bbf21555SRichard Lowe.Xr proc 5 292