dyld-239.3.tar.gz

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

diff --git a/doc/man/man3/dyld.3 b/doc/man/man3/dyld.3
index 9e10b9012b550f251a6f13de8f09459686cc0af7..cb9f6e4baf36a5a8e5e294ce2295b2a369202ad0 100644 (file)
--- 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
 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
 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
 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
 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