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 PLOOKUP_BY_ADDR 3PROC 16.Os 17.Sh NAME 18.Nm Plookup_by_addr , 19.Nm Pxlookup_by_addr , 20.Nm Pxlookup_by_addr_resolved , 21.Nm Plookup_by_name , 22.Nm Pxlookup_by_name 23.Nd lookup symbols in a process 24.Sh SYNOPSIS 25.Lb libproc 26.In libproc.h 27.Ft int 28.Fo Plookup_by_addr 29.Fa "struct ps_prochandle *P" 30.Fa "uintptr_t addr" 31.Fa "char *buf" 32.Fa "size_t size" 33.Fa "Gelf_Sym *symp" 34.Fc 35.Ft int 36.Fo Pxlookup_by_addr 37.Fa "struct ps_prochandle *P" 38.Fa "uintptr_t addr" 39.Fa "char *buf" 40.Fa "size_t size" 41.Fa "Gelf_Sym *symp" 42.Fa "prsyminfo_t *sip" 43.Fc 44.Ft int 45.Fo Pxlookup_by_addr_resolved 46.Fa "struct ps_prochandle *P" 47.Fa "uintptr_t addr" 48.Fa "char *buf" 49.Fa "size_t size" 50.Fa "Gelf_Sym *symp" 51.Fa "prsyminfo_t *sip" 52.Fc 53.Ft int 54.Fo Plookup_by_name 55.Fa "struct ps_prochandle *P" 56.Fa "const char *object" 57.Fa "const char *symbol" 58.Fa "GElf_Sym *symp" 59.Fc 60.Ft int 61.Fo Pxlookup_by_name 62.Fa "struct ps_prochandle *P" 63.Fa "Lmid_t lmid" 64.Fa "const char *object" 65.Fa "const char *symbol" 66.Fa "GElf_Sym *symp" 67.Fa "prsyminfo_t *sip" 68.Fc 69.Sh DESCRIPTION 70The 71.Fn Plookup_by_addr , 72.Fn Pxlookup_by_addr , 73.Fn Pxlookup_by_addr_resolved , 74.Fn Plookup_by_name , 75and 76.Fn Pxlookup_by_name 77functions look up symbol information in the process handle 78.Fa P 79and fill in the ELF symbol information in 80.Fa symp 81with the found symbol. 82Symbols may be looked up both by address and name. 83.Pp 84The 85.Fn Plookup_by_addr 86function looks up symbol information corresponding to the address 87.Fa addr . 88If found, up to 89.Fa size 90bytes of the symbol's name, including the null terminator will be filled 91in to the buffer 92.Fa buf . 93.Pp 94The 95.Fn Pxlookup_by_addr 96function is identical to the 97.Fn Plookup_by_addr 98function, except that it also fills in the structure 99.Fa sip 100with additional information. 101The definition of the 102.Sy prsyminfo_t 103is found in 104.Xr libproc 3LIB . 105.Pp 106The 107.Fn Pxlookup_by_addr_resolved 108function is similar to the 109.Fn Pxlookup_by_addr 110function; however, it attempts to resolve the paths present in the 111.Sy prsyminfo_t 112to an absolute path on the file system. 113.Pp 114The 115.Fn Plookup_by_name 116function attempts to look up a symbol based on its name. 117The 118.Fa object 119argument allows the caller to specify a specific object that was mapped 120in by the run-time link-editor to search for 121.Fa symbol 122in. 123The system provides three special values which may be passed in for 124.Fa object . 125The value 126.Dv PR_OBJ_EXEC 127refers to the executable's object (a.out). 128The value 129.Dv PR_OBJ_LDSO 130refers to the object 131.Sy ld.so.1 . 132The value 133.Dv PR_OBJ_EVERY 134indicates that every object should be searched. 135.Pp 136The 137.Fn Pxlookup_by_name 138function is similar to the 139.Fn Plookup_by_name 140function; however, it allows a link-map identifier, 141.Fa lmid , 142to be specified and also provides additional information about the 143symbol in the form of the 144.Sy prsyminfo_t 145.Fa sip . 146The specification of 147.Fa lmid 148restricts the search for the object named 149.Fa object 150and symbol named 151.Fa symbol 152to the specified link-map. 153.Pp 154There are three special link-map identifiers that may be passed in. 155The symbol 156.Dv PR_LMID_EVERY 157indicates that every link-map should be searched. 158The symbol 159.Dv LM_ID_BASE 160indicates that the base link-map, the one that is used for the 161executable should be searched. 162Finally, the symbol 163.Dv LM_ID_LDSO 164refers to the link-map that is used by the run-time link editor, ld.so.1. 165The 166.Fn Plookup_by_name 167function behaves like 168.Fn Pxlookup_by_name 169when the 170.Dv PR_LMID_EVERY 171argument is passed to 172.Fa lmid , 173indicating that every link-map should be searched. 174.Sh RETURN VALUES 175Upon successful completion, the 176.Fn Plookup_by_addr , 177.Fn Pxlookup_by_addr , 178.Fn Pxlookup_by_addr_resolved , 179.Fn Plookup_by_name , 180and 181.Fn Pxlookup_by_name 182functions return 183.Sy 0 184and fill in the symbol information. 185Otherwise, 186.Sy -1 187is returned to indicate that the symbol could not be found. 188.Sh INTERFACE STABILITY 189.Sy Uncommitted 190.Sh MT-LEVEL 191See 192.Sy LOCKING 193in 194.Xr libproc 3LIB . 195.Sh SEE ALSO 196.Xr elf 3ELF , 197.Xr gelf 3ELF , 198.Xr libproc 3LIB , 199.Xr proc 4 200