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