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_MAP 3PROC
16.Os
17.Sh NAME
18.Nm Paddr_to_map ,
19.Nm Paddr_to_text_map ,
20.Nm Plmid_to_map ,
21.Nm Pname_to_map
22.Nd lookup memory map information
23.Sh SYNOPSIS
24.Lb libproc
25.In libproc.h
26.Ft "const prmap_t *"
27.Fo Paddr_to_map
28.Fa "struct ps_prochandle *P"
29.Fa "uintptr_t addr"
30.Fc
31.Ft "const prmap_t *"
32.Fo Paddr_to_text_map
33.Fa "struct ps_prochandle *P"
34.Fa "uintptr_t addr"
35.Fc
36.Ft "const prmap_t *"
37.Fo Plmid_to_map
38.Fa "struct ps_prochandle *P"
39.Fa "Lmid_t lmid"
40.Fa "const char *name"
41.Fc
42.Ft "const prmap_t *"
43.Fo Pname_to_map
44.Fa "struct ps_prochandle *P"
45.Fa "const char *name"
46.Fc
47.Sh DESCRIPTION
48The
49.Fn Paddr_to_map ,
50.Fn Paddr_to_text_map ,
51.Fn Plmid_to_map ,
52and
53.Fn Pname_to_map
54functions lookup memory map information in the process handle
55.Fa P .
56The
57.Sy prmap_t
58structure provides information such as the size, offset, and object of
59the mapping and is defined in
60.Xr proc 4 .
61.Pp
62The pointer to the data returned by the library will only be valid for
63as long as the handle
64.Fa P
65is valid.
66Any calls to
67.Xr Prelease 3PROC
68will invalidate the data.
69.Pp
70The
71.Fn Paddr_to_map
72function attempts to find the mapping information corresponding to the
73address
74.Fa addr .
75.Pp
76The
77.Fn Paddr_to_text_map
78function is similar to the
79.Fn Paddr_to_map
80function; however, it only returns successfully if the specified address
81corresponds to a text mapping as identified by the run-time link-editor.
82One use of this is to ensure that a mapping is actually a text-mapping
83before inserting a breakpoint in it.
84.Pp
85The
86.Fn Pname_to_map
87function looks up the object named
88.Fa name
89and returns the corresponding mapping information.
90Two special values may be used for name.
91The macro
92.Dv PR_OBJ_EXEC
93refers to the executable object itself and the macro
94.Dv PR_OBJ_LDSO refers to the object ld.so.1 .
95.Pp
96The
97.Fn Plmid_to_map
98function is similar to
99.Fn Pname_to_map .
100It allows passing a link-map identifier,
101.Fa lmid ,
102which constricts the search of the object named with
103.Fa name
104to that link-map.
105The special value of
106.Dv PR_LMID_EVERY
107may be passed to indicate that every link-map should be searched, which
108is equivalent in behavior to the
109.Fn Pname_to_map
110function.
111.Sh RETURN VALUES
112Upon successful completion, the
113.Fn Paddr_to_map ,
114.Fn Paddr_to_text_map ,
115.Fn Plmid_to_map ,
116and
117.Fn Pname_to_map
118functions return a pointer to the corresponding mapping information.
119If none exists then
120.Dv NULL
121is returned.
122.Sh INTERFACE STABILITY
123.Sy Uncommitted
124.Sh MT-LEVEL
125See
126.Sy LOCKING
127in
128.Xr libproc 3LIB .
129.Sh SEE ALSO
130.Xr libproc 3LIB ,
131.Xr Prelease 3PROC ,
132.Xr proc 4
133