1.Dd November 29, 2010
2.Dt dyld 3
3.Sh NAME
4.Nm _dyld_image_count,
5.Nm _dyld_get_image_header,
6.Nm _dyld_get_image_vmaddr_slide,
7.Nm _dyld_get_image_name,
8.Nm _dyld_register_func_for_add_image,
9.Nm _dyld_register_func_for_remove_image,
10.Nm NSVersionOfRunTimeLibrary,
11.Nm NSVersionOfLinkTimeLibrary
12.Nm _NSGetExecutablePath
13.Sh SYNOPSIS
14.In mach-o/dyld.h
15.Ft uint32_t
16.Fo _dyld_image_count
17.Fa "void"
18.Fc
19.Ft const struct mach_header*
20.Fo _dyld_get_image_header
21.Fa "uint32_t image_index"
22.Fc
23.Ft intptr_t
24.Fo _dyld_get_image_vmaddr_slide
25.Fa "uint32_t image_index"
26.Fc
27.Ft const char*
28.Fo _dyld_get_image_name
29.Fa "uint32_t image_index"
30.Fc
31.Ft void
32.Fo _dyld_register_func_for_add_image
33.Fa "void \*[lp]*func\*[rp]\*[lp]const struct mach_header* mh, intptr_t vmaddr_slide\*[rp]"
34.Fc
35.Ft void
36.Fo _dyld_register_func_for_remove_image
37.Fa "void \*[lp]*func\*[rp]\*[lp]const struct mach_header* mh, intptr_t vmaddr_slide\*[rp]"
38.Fc
39.Ft int32_t
40.Fo NSVersionOfRunTimeLibrary
41.Fa "const char* libraryName"
42.Fc
43.Ft int32_t
44.Fo NSVersionOfLinkTimeLibrary
45.Fa "const char* libraryName"
46.Fc
47.Ft int
48.Fo _NSGetExecutablePath
49.Fa "char* buf"
50.Fa "uint32_t* bufsize"
51.Fc
52.Sh DESCRIPTION
53These routines provide additional introspection of dyld beyond that provided by
54.Fn dlopen
55and
56.Fn dladdr
57.
58.Pp
59.Fn _dyld_image_count
60returns the current number of images mapped in by dyld. Note that using this
61count to iterate all images is not thread safe, because another thread
62may be adding or removing images during the iteration.
63.Pp
64.Fn _dyld_get_image_header
65returns a pointer to the mach header of the image indexed by image_index.  If 
66.Fa image_index
67is out of range, NULL is returned.
68.Pp
69.Fn _dyld_get_image_vmaddr_slide
70returns the virtural memory address slide amount of the image indexed by
71.Fa image_index.
72If
73.Fa image_index
74is out of range zero is returned.
75.Pp
76.Fn _dyld_get_image_name
77returns the name of the image indexed by
78.Fa image_index.
79The C-string continues to be owned by dyld and should not deleted.
80If 
81.Fa image_index
82is out of range NULL is returned.
83.Pp
84.Fn _dyld_register_func_for_add_image
85registers the specified function to be called when a new image is added
86(a bundle or a dynamic shared library) to the program.  When this function is
87first registered it is called for once for each image that is currently part of
88the process.
89.Pp
90.Fn _dyld_register_func_for_remove_image
91registers the specified function to be called when an image is removed
92(a bundle or a dynamic shared library) from the process.
93.Pp
94.Fn NSVersionOfRunTimeLibrary
95returns the current_version number of the currently loaded dylib 
96specifed by the libraryName.  The libraryName parameter would be "bar" for /path/libbar.3.dylib and
97"Foo" for /path/Foo.framework/Versions/A/Foo.  This function returns -1 if no such library is loaded.
98.Pp
99.Fn NSVersionOfLinkTimeLibrary
100returns the current_version number that the main executable was linked
101against at build time.  The libraryName parameter would be "bar" for /path/libbar.3.dylib and
102"Foo" for /path/Foo.framework/Versions/A/Foo.  This function returns -1 if the main executable did not link
103against the specified library.
104.Pp
105.Fn _NSGetExecutablePath
106copies the path of the main executable into the buffer
107.Fa buf .
108The 
109.Fa bufsize
110parameter should initially be the size of the buffer.  This function returns 0 if the path was successfully copied,
111and  *
112.Fa bufsize
113is left unchanged. 
114It returns -1 if the buffer is not large enough, and *
115.Fa bufsize
116is set to the size required. 
117Note that 
118.Fn _NSGetExecutablePath 
119will return "a path" to the executable not a "real path" to the executable. 
120That is, the path may be a symbolic link and not the real file. With deep directories the total bufsize 
121needed could be more than MAXPATHLEN.
122.Sh SEE ALSO
123.Xr dlopen 3
124.Xr dladdr 3
125.Xr dyld 1
126http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/index.html