Merge remote-tracking branch 'origin/master'
[unleashed/lotheac.git] / share / man / man3proc / Paddr_to_loadobj.3proc
blob6430d8eae4fefcf00dd0389784ba7ee45709ebb2
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_LOADOBJ 3PROC
16 .Os
17 .Sh NAME
18 .Nm Paddr_to_loadobj ,
19 .Nm Plmid_to_loadobj ,
20 .Nm Pname_to_loadobj
21 .Nd lookup loaded object information
22 .Sh SYNOPSIS
23 .Lb libproc
24 .In libproc.h
25 .Ft "const rd_loadobj_t *"
26 .Fo Paddr_to_loadobj
27 .Fa "struct ps_prochandle *P"
28 .Fa "uintptr_t addr"
29 .Fc
30 .Ft "const rd_loadobj_t *"
31 .Fo Plmid_to_loadobj
32 .Fa "struct ps_prochandle *P"
33 .Fa "Lmid_t lmid"
34 .Fa "const char *name"
35 .Fc
36 .Ft "const rd_loadobj_t *"
37 .Fo Pname_to_loadobj
38 .Fa "struct ps_prochandle *P"
39 .Fa "const char *name"
40 .Fc
41 .Sh DESCRIPTION
42 The
43 .Fn Paddr_to_loadobj ,
44 .Fn Plmid_to_loadobj ,
45 and
46 .Fn Pname_to_loadobj
47 functions lookup loaded object information from the process handle
48 .Fa P .
49 This information is provided by the run-time link-editor,
50 .Xr ld.so.1 1 ,
51 and provides information about the loaded object such as the link-map
52 identifier, the TLS module ID, and the address of various sections.
53 .Pp
54 The pointer to the data returned by the library will only be valid for
55 as long as the handle
56 .Fa P
57 is valid.
58 Any calls to
59 .Xr Prelease 3PROC
60 will invalidate the data.
61 .Pp
62 The
63 .Fn Paddr_to_loadobj
64 function attempts to find the loaded object information, if any, that exists for
65 the address
66 .Fa addr .
67 Not all address correspond to memory regions that were loaded by the
68 run-time link-editor.
69 For example, if a user creates a region of anonymous memory through the
70 .Xr mmap 2
71 function, then it will not have any corresponding loaded module.
72 .Pp
73 The
74 .Fn Pname_to_loadobj
75 function looks up the object named
76 .Fa name
77 and returns the corresponding loaded object information.
78 Two special values may be used for name.
79 The macro
80 .Dv PR_OBJ_EXEC
81 refers to the executable object itself and the macro
82 .Dv PR_OBJ_LDSO refers to the object ld.so.1 .
83 .Pp
84 The
85 .Fn Plmid_to_loadobj
86 function is similar to
87 .Fn Pname_to_loadobj .
88 It allows the use of a link-map identifier,
89 .Fa lmid ,
90 which constricts the search of the object named with
91 .Fa name
92 to that link-map.
93 The special value of
94 .Dv PR_LMID_EVERY
95 may be passed to indicate that every link-map should be searched, which
96 is equivalent in behavior to the
97 .Fn Pname_to_loadobj
98 function.
99 .Sh RETURN VALUES
100 Upon successful completion, the
101 .Fn Paddr_to_loadobj ,
102 .Fn Plmid_to_loadobj ,
104 .Fn Pname_to_loadobj
105 functions return a pointer to the corresponding loadable object
106 information.
107 Otherwise, if none exists then
108 .Dv NULL
109 is returned.
110 .Sh INTERFACE STABILITY
111 .Sy Uncommitted
112 .Sh MT-LEVEL
114 .Sy LOCKING
116 .Xr libproc 3LIB .
117 .Sh SEE ALSO
118 .Xr libproc 3LIB ,
119 .Xr librtld_db 3LIB ,
120 .Xr Prelease 3PROC