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 5
120