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. Symbols may be looked up both by address and 82name. 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. The definition of the 101.Sy prsyminfo_t 102is found in 103.Xr libproc 3PROC . 104.Pp 105The 106.Fn Pxlookup_by_addr_resolved 107function is similar to the 108.Fn Pxlookup_by_addr 109function; however, it attempts to resolve the paths present in the 110.Sy prsyminfo_t 111to an absolute path on the file system. 112.Pp 113The 114.Fn Plookup_by_name 115function attempts to look up a symbol based on its name. The 116.Fa object 117argument allows the caller to specify a specific object that was mapped 118in by the run-time link-editor to search for 119.Fa symbol 120in. The system provides three special values which may be passed in for 121.Fa object . 122The value 123.Dv PR_OBJ_EXEC 124refers to the executable's object (a.out). The value 125.Dv PR_OBJ_LDSO 126refers to the object 127.Sy ld.so.1 . 128The value 129.Dv PR_OBJ_EVERY 130indicates that every object should be searched. 131.Pp 132The 133.Fn Pxlookup_by_name 134function is similar to the 135.Fn Plookup_by_name 136function; however, it allows a link-map identifier, 137.Fa lmid , 138to be specified and also provides additional information about the 139symbol in the form of the 140.Sy prsyminfo_t 141.Fa sip . 142The specification of 143.Fa lmid 144restricts the search for the object named 145.Fa object 146and symbol named 147.Fa symbol 148to the specified link-map. 149.Pp 150There are three special link-map identifiers 151that may be passed in. The symbol 152.Dv PR_LMID_EVERY 153indicates that every link-map should be searched. The symbol 154.Dv LM_ID_BASE 155indicates that the base link-map, the one that is used for the 156executable should be searched. Finally, the symbol 157.Dv LM_ID_LDSO 158refers to the link-map that is used by the run-time link editor, 159ld.so.1. The 160.Fn Plookup_by_name 161function behaves like 162.Fn Pxlookup_by_name 163when the 164.Dv PR_LMID_EVERY 165argument is passed to 166.Fa lmid , 167indicating that every link-map should be searched. 168.Sh RETURN VALUES 169Upon successful completion, the 170.Fn Plookup_by_addr , 171.Fn Pxlookup_by_addr , 172.Fn Pxlookup_by_addr_resolved , 173.Fn Plookup_by_name , 174and 175.Fn Pxlookup_by_name 176functions return 177.Sy 0 178and fill in the symbol information. Otherwise, 179.Sy -1 180is returned to indicate that the symbol could not be found. 181.Sh INTERFACE STABILITY 182.Sy Uncommitted 183.Sh MT-LEVEL 184See 185.Sy LOCKING 186in 187.Xr libproc 3LIB . 188.Sh SEE ALSO 189.Xr elf 3ELF , 190.Xr gelf 3ELF , 191.Xr libproc 3LIB , 192.Xr proc 4 193