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