X-Git-Url: https://git.saurik.com/apple/dyld.git/blobdiff_plain/0959b6d4289bd106fddb7fe7d84a346159895fdd..2fd3f4e8fd2c2f2c7d149fbea471d8b3fb56f15a:/doc/man/man3/dyld.3?ds=sidebyside

diff --git a/doc/man/man3/dyld.3 b/doc/man/man3/dyld.3
index 9e10b90..cb9f6e4 100644
--- a/doc/man/man3/dyld.3
+++ b/doc/man/man3/dyld.3
@@ -1,200 +1,126 @@
-.TH DYLD 3 "January 15, 2005" "Apple Computer, Inc."
-.SH NAME
-dyld \- low level programatic interface to the dynamic link editor
-.SH SYNOPSIS
-.nf
-.PP
-#include <mach-o/dyld.h>
-bool _dyld_present(void);
-.sp .5
-uint32_t _dyld_image_count(void);
-.sp .5
-const struct mach_header *_dyld_get_image_header(
-	uint32_t image_index);
-.sp .5
-intptr_t _dyld_get_image_vmaddr_slide(
-	uint32_t image_index);
-.sp .5
-const char *_dyld_get_image_name(
-	uint32_t image_index);
-.sp .5
-void _dyld_lookup_and_bind(
-	const char *symbol_name,
-	void **address,
-	NSModule *module);
-.sp .5
-void _dyld_lookup_and_bind_with_hint(
-	const char *symbol_name,
-	const char *library_name_hint,
-	void **address,
-	NSModule *module);
-.sp .5
-void _dyld_lookup_and_bind_fully(
-	const char *symbol_name,
-	void **address,
-	NSModule *module);
-.sp .5
-bool _dyld_bind_fully_image_containing_address(
-	const void *address);
-.sp .5
-bool _dyld_image_containing_address(
-	const void* address);
-.sp .5
-const struct mach_header * _dyld_get_image_header_containing_address(
-	const void* address);
-.sp .5
-bool _dyld_launched_prebound(void);
-.sp .5
-bool _dyld_all_twolevel_modules_prebound(void);
-.sp .5
-int _dyld_func_lookup(
-	const char *dyld_func_name,
-	void **address);
-.sp .5
-extern void _dyld_bind_objc_module(
-	const void *objc_module);
-.sp .5 
-extern void _dyld_get_objc_module_sect_for_module(
-	NSModule module,
-	void **objc_module,
-	size_t *size);
-.sp .5
-extern void _dyld_lookup_and_bind_objc(
-	const char *symbol_name,
-	void **address,
-	NSModule *module);
-.sp .5
-extern void _dyld_moninit(
-	void (*monaddition)(char *lowpc, char *highpc));
-.sp .5
-
-extern void _dyld_register_func_for_add_image(
-	void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
-.sp .5
-extern void _dyld_register_func_for_remove_image(
-	void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
-.sp .5
-extern void _dyld_register_func_for_link_module(
-	void (*func)(NSModule module));
-.fi
-.SH DESCRIPTION
-These routines are the low level programatic interface to the dynamic link
-editor.
-.PP
-.I _dyld_present returns non-zero if the dynamic linker is being used in the
-program and zero otherwise.  If this returns zero this rest of these functions
-should not be called and most likely crash the program if called.
-.PP
-.I _dyld_image_count
-returns the current number of images mapped in by the dynamic link editor.
-.PP
-.I _dyld_get_image_header
-returns the mach header of the image indexed by image_index.  If image_index is
-out of range NULL is returned.
-.PP
-.I _dyld_get_image_vmaddr_slide
+.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
-.I image_index.
-If image_index is out of range zero is returned.
-.PP
-.I _dyld_get_image_name
+.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
-.I image_index.
-If image_index is out of range NULL is returned.
-.PP
-.I _dyld_lookup_and_bind
-looks up the
-.I symbol_name
-and binds it into the program.  It indirectly returns the
-.I address
-and and a pointer to the
-.I module
-that defined the symbol.
-.PP
-.I _dyld_lookup_and_bind_with_hint
-is the same as
-.I _dyld_lookup_and_bind
-but the
-.I library_name_hint
-parameter provides a hint as to where to start the lookup in a prebound
-program.  The
-.I library_name_hint
-parameter is matched up with the actual library install names with
-.IR strstr (3).
-.PP
-.I _dyld_lookup_and_bind_fully
-looks up the
-.I symbol_name
-and binds it and all of its references into the program.  It indirectly returns
-the
-.I address
-and and a pointer to the
-.I module
-that defined the symbol.
-.PP
-.I _dyld_bind_fully_image_containing_address
-fully binds the image containing the specified address.  It returns TRUE if the
-address is contained in a loaded image and FALSE otherwise.
-.PP
-.I _dyld_image_containing_address
-It returns TRUE if the address is contained in an image dyld loaded and FALSE
-otherwise.
-.PP
-.I _dyld_get_image_header_containing_address
-It returns a pointer to the mach header of the image if the address is contained
-in an image dyld loaded and NULL otherwise.
-.PP
-.I _dyld_launched_prebound
-returns TRUE if the program was launched using the prebound state and FALSE
-otherwise.
-.PP
-.I_dyld_all_twolevel_modules_prebound(void);
-returns TRUE if all the libraries currently in use by the program are being used
-as two-level namespace libraries, are prebound and have all their modules bound.
-Otherwise it returns FALSE.
-.PP
-.I _dyld_func_lookup
-is passed a name,
-.I dyld_func_name,
-of a dynamic link editor function and returns the
-.I address
-of the function indirectly.  It returns non-zero if the function is found
-and zero otherwise.
-.PP
-.I _dyld_bind_objc_module
-is passed a pointer to something in an (__OBJC,__module) section and causes the
-module that is associated with that address to be bound.
-.PP
-.I _dyld_get_objc_module_sect_for_module
-is passed a module and sets a pointer to the (__OBJC,__module) section and its
-size for the specified module.
-.PP
-.I _dyld_lookup_and_bind_objc()
-is the same as _dyld_lookup_and_bind() but does not update the symbol pointers
-if the symbol is in a bound module.  The reason for this is that an objc symbol
-like
-.I .objc_class_name_Object
-is never used by a symbol pointer.  Since this is done a lot by the objc
-runtime and updating symbol pointers is not cheep it should not be done.
-.PP
-.I _dyld_moninit
-is called from the profiling runtime routine
-.IR moninit(3)
-to cause the dyld loaded code to be profiled.  It is passed a pointer to the
-the profiling runtime routine
-.IR monaddtion(3)
-to be called after an image had been mapped in.
-.PP
-.I _dyld_register_func_for_add_image
+.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 program.
-.PP
-.I _dyld_register_func_for_remove_image
+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 program.
-.I _dyld_register_func_for_link_module
-registers the specified function to be called when a module is bound into the
-program.  When this function is first registered it is called for once for each
-module that is currently bound into the program.
+(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
\ No newline at end of file