aboutsummaryrefslogtreecommitdiff
path: root/manual/dynlink.texi
blob: 54091be18e6d43b497074a58d958401c61c9e550 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
@node Dynamic Linker
@c @node Dynamic Linker, Internal Probes, Threads, Top
@c %MENU% Loading programs and shared objects.
@chapter Dynamic Linker
@cindex dynamic linker
@cindex dynamic loader

The @dfn{dynamic linker} is responsible for loading dynamically linked
programs and their dependencies (in the form of shared objects).  The
dynamic linker in @theglibc{} also supports loading shared objects (such
as plugins) later at run time.

Dynamic linkers are sometimes called @dfn{dynamic loaders}.

@menu
* Dynamic Linker Introspection::    Interfaces for querying mapping information.
@end menu

@node Dynamic Linker Introspection
@section Dynamic Linker Introspection

@Theglibc{} provides various functions for querying information from the
dynamic linker.

@deftp {Data Type} {struct dl_find_object}
@standards{GNU, dlfcn.h}
This structure contains information about a main program or loaded
object.  The @code{_dl_find_object} function uses it to return
result data to the caller.

@table @code
@item unsigned long long int dlfo_flags
Currently unused and always 0.

@item void *dlfo_map_start
The start address of the inspected mapping.  This information comes from
the program header, so it follows its convention, and the address is not
necessarily page-aligned.

@item void *dlfo_map_end
The end address of the mapping.

@item struct link_map *dlf_link_map
This member contains a pointer to the link map of the object.

@item struct link_map *dlf_link_map
This member contains a pointer to the exception handling data of the
object.  See @code{DLFO_EH_SEGMENT_TYPE} below.

@end table

This structure is a GNU extension.
@end deftp

@deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE
@standards{GNU, dlfcn.h}
On most targets, this macro is defined as @code{0}.  If it is defined to
@code{1}, @code{struct dl_find_object} contains an additional member
@code{dlfo_eh_dbase} of type @code{void *}.  It is the base address for
@code{DW_EH_PE_datarel} DWARF encodings to this location.

This macro is a GNU extension.
@end deftypevr

@deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT
@standards{GNU, dlfcn.h}
On most targets, this macro is defined as @code{0}.  If it is defined to
@code{1}, @code{struct dl_find_object} contains an additional member
@code{dlfo_eh_count} of type @code{int}.  It is the number of exception
handling entries in the EH frame segment identified by the
@code{dlfo_eh_frame} member.

This macro is a GNU extension.
@end deftypevr

@deftypevr Macro int DLFO_EH_SEGMENT_TYPE
@standards{GNU, dlfcn.h}
On targets using DWARF-based exception unwinding, this macro expands to
@code{PT_GNU_EH_FRAME}.  This indicates that @code{dlfo_eh_frame} in
@code{struct dl_find_object} points to the @code{PT_GNU_EH_FRAME}
segment of the object.  On targets that use other unwinding formats, the
macro expands to the program header type for the unwinding data.

This macro is a GNU extension.
@end deftypevr

@deftypefun {int} _dl_find_object (void *@var{address}, struct dl_find_object *@var{result})
@standards{GNU, dlfcn.h}
@safety{@mtsafe{}@assafe{}@acsafe{}}
On success, this function returns 0 and writes about the object
surrounding the address to @code{*@var{result}}.  On failure, -1 is
returned.

The @var{address} can be a code address or data address.  On
architectures using function descriptors, no attempt is made to decode
the function descriptor.  Depending on how these descriptors are
implemented, @code{_dl_find_object} may return the object that defines
the function descriptor (and not the object that contains the code
implementing the function), or fail to find any object at all.

On success @var{address} is greater than or equal to
@code{@var{result}->dlfo_map_start} and less than
@code{@var{result}->dlfo_map_end}, that is, the supplied code address is
located within the reported mapping.

This function returns a pointer to the unwinding information for the
object that contains the program code @var{address} in
@code{@var{result}->dlfo_eh_frame}.  If the platform uses DWARF
unwinding information, this is the in-memory address of the
@code{PT_GNU_EH_FRAME} segment.  See @code{DLFO_EH_SEGMENT_TYPE} above.
In case @var{address} resides in an object that lacks unwinding information,
the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame}
to a null pointer.

@code{_dl_find_object} itself is thread-safe.  However, if the
application invokes @code{dlclose} for the object that contains
@var{address} concurrently with @code{_dl_find_object} or after the call
returns, accessing the unwinding data for that object or the link map
(through @code{@var{result}->dlfo_link_map}) is not safe.  Therefore, the
application needs to ensure by other means (e.g., by convention) that
@var{address} remains a valid code address while the unwinding
information is processed.

This function is a GNU extension.
@end deftypefun


@c FIXME these are undocumented:
@c dladdr
@c dladdr1
@c dlclose
@c dlerror
@c dlinfo
@c dlmopen
@c dlopen
@c dlsym
@c dlvsym