[apple/dyld.git] / doc / man / man3 / dyld.3

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