1@node Dynamic Linker
2@c @node Dynamic Linker, Internal Probes, Threads, Top
3@c %MENU% Loading programs and shared objects.
4@chapter Dynamic Linker
5@cindex dynamic linker
6@cindex dynamic loader
7
8The @dfn{dynamic linker} is responsible for loading dynamically linked
9programs and their dependencies (in the form of shared objects).  The
10dynamic linker in @theglibc{} also supports loading shared objects (such
11as plugins) later at run time.
12
13Dynamic linkers are sometimes called @dfn{dynamic loaders}.
14
15@menu
16* Dynamic Linker Introspection::    Interfaces for querying mapping information.
17@end menu
18
19@node Dynamic Linker Introspection
20@section Dynamic Linker Introspection
21
22@Theglibc{} provides various functions for querying information from the
23dynamic linker.
24
25@deftp {Data Type} {struct dl_find_object}
26@standards{GNU, dlfcn.h}
27This structure contains information about a main program or loaded
28object.  The @code{_dl_find_object} function uses it to return
29result data to the caller.
30
31@table @code
32@item unsigned long long int dlfo_flags
33Currently unused and always 0.
34
35@item void *dlfo_map_start
36The start address of the inspected mapping.  This information comes from
37the program header, so it follows its convention, and the address is not
38necessarily page-aligned.
39
40@item void *dlfo_map_end
41The end address of the mapping.
42
43@item struct link_map *dlf_link_map
44This member contains a pointer to the link map of the object.
45
46@item struct link_map *dlf_link_map
47This member contains a pointer to the exception handling data of the
48object.  See @code{DLFO_EH_SEGMENT_TYPE} below.
49
50@end table
51
52This structure is a GNU extension.
53@end deftp
54
55@deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE
56@standards{GNU, dlfcn.h}
57On most targets, this macro is defined as @code{0}.  If it is defined to
58@code{1}, @code{struct dl_find_object} contains an additional member
59@code{dlfo_eh_dbase} of type @code{void *}.  It is the base address for
60@code{DW_EH_PE_datarel} DWARF encodings to this location.
61
62This macro is a GNU extension.
63@end deftypevr
64
65@deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT
66@standards{GNU, dlfcn.h}
67On most targets, this macro is defined as @code{0}.  If it is defined to
68@code{1}, @code{struct dl_find_object} contains an additional member
69@code{dlfo_eh_count} of type @code{int}.  It is the number of exception
70handling entries in the EH frame segment identified by the
71@code{dlfo_eh_frame} member.
72
73This macro is a GNU extension.
74@end deftypevr
75
76@deftypevr Macro int DLFO_EH_SEGMENT_TYPE
77@standards{GNU, dlfcn.h}
78On targets using DWARF-based exception unwinding, this macro expands to
79@code{PT_GNU_EH_FRAME}.  This indicates that @code{dlfo_eh_frame} in
80@code{struct dl_find_object} points to the @code{PT_GNU_EH_FRAME}
81segment of the object.  On targets that use other unwinding formats, the
82macro expands to the program header type for the unwinding data.
83
84This macro is a GNU extension.
85@end deftypevr
86
87@deftypefun {int} _dl_find_object (void *@var{address}, struct dl_find_object *@var{result})
88@standards{GNU, dlfcn.h}
89@safety{@mtsafe{}@assafe{}@acsafe{}}
90On success, this function returns 0 and writes about the object
91surrounding the address to @code{*@var{result}}.  On failure, -1 is
92returned.
93
94The @var{address} can be a code address or data address.  On
95architectures using function descriptors, no attempt is made to decode
96the function descriptor.  Depending on how these descriptors are
97implemented, @code{_dl_find_object} may return the object that defines
98the function descriptor (and not the object that contains the code
99implementing the function), or fail to find any object at all.
100
101On success @var{address} is greater than or equal to
102@code{@var{result}->dlfo_map_start} and less than
103@code{@var{result}->dlfo_map_end}, that is, the supplied code address is
104located within the reported mapping.
105
106This function returns a pointer to the unwinding information for the
107object that contains the program code @var{address} in
108@code{@var{result}->dlfo_eh_frame}.  If the platform uses DWARF
109unwinding information, this is the in-memory address of the
110@code{PT_GNU_EH_FRAME} segment.  See @code{DLFO_EH_SEGMENT_TYPE} above.
111In case @var{address} resides in an object that lacks unwinding information,
112the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame}
113to a null pointer.
114
115@code{_dl_find_object} itself is thread-safe.  However, if the
116application invokes @code{dlclose} for the object that contains
117@var{address} concurrently with @code{_dl_find_object} or after the call
118returns, accessing the unwinding data for that object or the link map
119(through @code{@var{result}->dlfo_link_map}) is not safe.  Therefore, the
120application needs to ensure by other means (e.g., by convention) that
121@var{address} remains a valid code address while the unwinding
122information is processed.
123
124This function is a GNU extension.
125@end deftypefun
126
127
128@c FIXME these are undocumented:
129@c dladdr
130@c dladdr1
131@c dlclose
132@c dlerror
133@c dlinfo
134@c dlmopen
135@c dlopen
136@c dlsym
137@c dlvsym
138