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 PADDR_TO_CTF 3PROC 16.Os 17.Sh NAME 18.Nm Paddr_to_ctf , 19.Nm Plmid_to_ctf , 20.Nm Pname_to_ctf 21.Nd lookup CTF data 22.Sh LIBRARY 23.Lb libproc 24.Sh SYNOPSIS 25.In libproc.h 26.Ft "ctf_file_t *" 27.Fo Paddr_to_ctf 28.Fa "struct ps_prochandle *P" 29.Fa "uintptr_t addr" 30.Fc 31.Ft "ctf_file_t *" 32.Fo Plmid_to_ctf 33.Fa "struct ps_prochandle *P" 34.Fa "Lmid_t lmid" 35.Fa "const char *name" 36.Fc 37.Ft "ctf_file_t *" 38.Fo Pname_to_ctf 39.Fa "struct ps_prochandle *P" 40.Fa "const char *name" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn Paddr_to_ctf , 45.Fn Plmid_to_ctf , 46and 47.Fn Pname_to_ctf 48functions lookup CTF (Compact C Type Format) data, for use with 49.Sy libctf , 50from the process represented by the handle 51.Fa P . 52In all cases, the CTF sections of both the running executable and its 53shared libraries are searched. 54.Pp 55The CTF container returned is valid as long as the process handle 56.Fa P 57is valid. 58That is, until a call to 59.Xr Prelease 3PROC 60is made. 61Further, consumers must not close the CTF container. 62.Pp 63The 64.Fn Paddr_to_ctf 65function attempts to find the CTF section, if any, that exists for the 66address 67.Fa addr . 68Note, not all addresses correspond to memory regions that have CTF 69data. 70For example, if a user creates a region of anonymous memory through the 71.Xr mmap 2 72function, then it will not have any corresponding CTF information. 73.Pp 74The 75.Fn Pname_to_ctf 76function looks up the object named 77.Fa name 78and returns the corresponding CTF section, if any exists. 79Two special values may be used for name. 80The macro 81.Dv PR_OBJ_EXEC 82refers to the executable object itself and the macro 83.Dv PR_OBJ_LDSO refers to the object ld.so.1 . 84.Pp 85The 86.Fn Plmid_to_ctf 87function is similar to 88.Fn Pname_to_ctf . 89It allows the passing of a link-map identifier, 90.Fa lmid , 91which constricts the search of the object named with 92.Fa name 93to that link-map. 94The special value of 95.Dv PR_LMID_EVERY 96indicates that every link-map should be searched, which is equivalent 97in behavior to the 98.Fn Pname_to_ctf 99function. 100.Sh RETURN VALUES 101Upon successful completion, the 102.Fn Paddr_to_ctf , 103.Fn Plmid_to_ctf , 104and 105.Fn Pname_to_ctf 106functions return a pointer to the corresponding CTF container. 107Otherwise, if none exists then 108.Dv NULL 109is returned. 110.Sh INTERFACE STABILITY 111.Sy Uncommitted 112.Sh MT-LEVEL 113See 114.Sy LOCKING 115in 116.Xr libproc 3LIB . 117.Sh SEE ALSO 118.Xr libproc 3LIB , 119.Xr ctf 4 120