Mac Developer Library

Developer

OS X ABI Dynamic Loader Reference

Options
Deployment Target:

On This Page

OS X ABI Dynamic Loader Reference

Most Mac apps need to load and use dynamic shared libraries or bundles at runtime. The dynamic loader, dyld, is a shared library that programs use to gain access to other shared libraries. The dynamic loader locates Mach-O files on disk and maps them into the memory space of the current program.

Well-written programs don’t load shared libraries until they are needed. This minimizes the launch time and memory footprint of the application. It may also improve the general performance of the system through reduced paging.

This document describes the low-level functions of the Mac app binary interface (ABI) that you can use to load, link, and unload Mach-O files at runtime.

You should read this document if you develop applications that use dynamic shared libraries or libraries that use other libraries.

These documents provide information about the runtime loading of code:

Functions

These are the recommended functions to use to interact with the dynamic loader. These functions work in OS X v10.3 and v10.4. However, in OS X v10.4 they are more efficient than other image-loading functions. These functions are declared in /usr/include/dlfcn.h.

  • Finds the image and nearest symbol corresponding to an address. Available only in dynamically linked programs.

    Declaration

    Objective-C

    int dladdr( const void* addr, Dl_info * info);

    Parameters

    addr

    On input, an address within the address space of the program.

    info

    Storage for a Dl_info object. On return, the symbolic information found.

    Return Value

    When an image containing the address specified in addr cannot be found, this function returns 0. Otherwise, the result is a value other than 0.

    Discussion

    This is the declaration for the Dl_info structure:

    • typedef struct dl_info {
    • const char* dli_fname;
    • void* dli_fbase;
    • const char* dli_sname;
    • void* dli_saddr;
    • } Dl_info;

    The descriptions for the fields in Dl_info are:

    • dli_fname: The pathname of the image containing the address in addr.

    • dli_fbase: The base address (mach_header) at which the image is mapped into the address space of the program.

    • dli_sname: The name of the nearest runtime symbol.

    • dli_saddr: The value of the symbol specified by dli_sname.

    If the image containing addr is found, but no near symbol is found, the dli_sname and dli_saddr fields in the Dl_info object are set to NULL. A near symbol is a symbol within the image whose address is equal to or lower than addr.

    See also dlopen, dlsym.

    Availability

    Available in OS X v10.3 and later.

  • Closes a dynamic library or bundle.

    Declaration

    Objective-C

    int dlclose( void* handle);

    Parameters

    handle

    Handle obtained through a call to dlopen.

    Return Value

    This function returns 0 when successful and a value other than 0 when unsuccessful.

    Discussion

    This function decreases the reference count of the image referenced by handle. When the reference count for handle becomes 0, the termination routines in the image are called, and the image is removed from the address space of the current process. After that point, handle is rendered invalid.

    If this function is unsuccessful, it sets an error condition that can be queried with dlerror.

    See also dlopen, dlerror.

    Availability

    Available in OS X v10.3 and later.

  • Provides diagnostic information corresponding to problems with calls to dlopen, dlsym, and dlclose in the same thread.

    Declaration

    Objective-C

    const char* dlerror( void);

    Return Value

    When there’s a problem to report, this function returns a pointer to a null-terminated string describing the problem. Otherwise, this function returns NULL.

    Discussion

    Each call to dlerror resets its diagnostic buffer. If a program needs to keep a record of past error messages, it must store them itself. Subsequent calls to dlerror in the same thread with no calls to dlopen, dlsym, or dlclose, return NULL.

    See also dlopen, dlsym, dlclose.

    Availability

    Available in OS X v10.3 and later.

  • Loads and links a dynamic library or bundle.

    Declaration

    Objective-C

    void* dlopen( const char* path, int mode);

    Parameters

    path

    Path to the image to open.

    mode

    Specifies when the loaded image’s external symbols are bound to their definitions in dependent libraries (lazy or at load time) and the visibility of the image’s exported symbols (global or local). The value of this parameter is made up by ORing one binding behavior value with one visibility specification value.

    The following values specify the binding behavior:

    • RTLD_LAZY (default): Each external symbol reference is bound the first time it’s used.

    • RTLD_NOW: All external symbol references are bound immediately.

    The following values specify external symbol visibility:

    • RTLD_GLOBAL (default): The loaded image’s exported symbols are available to any images that use a flat namespace or to calls to dlsym when using a special handle (see dlsym for details).

    • RTLD_LOCAL: The loaded image’s exported symbols are generally hidden. They are available only to dlsym invocations that use the handle returned by this function.

    Return Value

    A handle that can be used with calls to dlsym and dlclose.

    Discussion

    This function examines the Mach-O file specified by path. If the image is compatible with the current process and has not already been loaded into the process, the image is loaded and linked. If the image contains initializer functions, they are executed before this function returns.

    Subsequent calls to dlopen to load the same image return the same handle, but the internal reference count for the handle is incremented. Therefore, all dlopen calls must be balanced with dlclose calls.

    For efficiency, the RTLD_LAZY binding mode is preferred over RTLD_NOW. However, using RTLD_NOW ensures that any undefined symbols are discovered during the call to dlopen.

    The dynamic loader looks in the paths specified by a set of environment variables, and in the process’s current directory, when it searches for a library. These paths are called dynamic loader search paths. The environment variables are LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, and DYLD_FALLBACK_LIBRARY_PATH. The default value of DYLD_FALLBACK_LIBRARY_PATH (used when this variable is not set), is $HOME/lib;/usr/local/lib;/usr/lib.

    The order in which the search paths are searched depends on whether path is a filename (it does not contain a slash) or a pathname (it contains at least one slash).

    When path is a filename, the dynamic loader searches for the library in the search paths in the following order:

    1. $LD_LIBRARY_PATH

    2. $DYLD_LIBRARY_PATH

    3. The process’s working directory

    4. $DYLD_FALLBACK_LIBRARY_PATH

    When path is a pathname, the dynamic loader searches for the library in the search paths in the following order:

    1. $DYLD_LIBRARY_PATH

    2. The given pathname

    3. $DYLD_FALLBACK_LIBRARY_PATH using the filename

    If this function cannot open an image, it sets an error condition that can be accessed with dlerror.

    See also dlsym, dlclose, dlerror.

    Availability

    Available in OS X v10.3 and later.

  • Returns the address of a symbol.

    Declaration

    Objective-C

    void* dlsym( void* handle, const char* symbol);

    Parameters

    handle

    Handle obtained by a call to dlopen, or a special handle. If the handle was obtained by a call to dlopen, it must not have been closed with a call to dlclose. These are the possible special-handle values: RTLD_DEFAULT, and RTLD_NEXT.

    symbol

    Null-terminated character string containing the C name of the symbol being sought.

    Return Value

    When successful, this function returns the address of symbol. Otherwise, it returns a null pointer.

    Discussion

    The value of handle specifies what images this function searches for to locate the symbol specified by the symbol parameter. Table 1 describes the possible values for the handle parameter.

    Table 1Values for the handle parameter

    Handle value

    Search scope

    dlopen handle

    Image associated with the dlopen handle.

    RTLD_DEFAULT

    Every dependent library or RTLD_GLOBAL–opened library in the current process, in the order they were loaded.

    RTLD_NEXT

    Dependent libraries that were loaded after the one calling this function. Libraries opened with dlopen are not searched.

    Unlike in the NS... functions, the symbol parameter doesn’t require a leading underscore to be part of the symbol name.

    If this function is unsuccessful, it sets an error condition that can be queried with dlerror.

    See also dlopen, dlerror.

    Availability

    Available in OS X v10.3 and later.

These functions are for loading Mach-O bundle files. They are declared in /usr/include/mach-o/dyld.h. The use of these functions is discouraged. You should use the more efficient functions described in Dynamic Loader Compatibility Functions.

  • Creates an image reference for a given Mach-O file.

    Declaration

    Objective-C

    NSObjectFileImageReturnCode NSCreateObjectFileImageFromFile( const char* pathName, NSObjectFileImage * objectFileImage);

    Parameters

    pathName

    A C string. Pass the pathname to a Mach-O executable file. You must have previously built this file with the -bundle linker option; otherwise, this function returns an error.

    objectFileImage

    On output, a pointer to an NSObjectFileImage opaque data structure.

    Discussion

    Given a pathname to a Mach-O executable, this function creates and returns a NSObjectFileImage reference. The current implementation works only with bundles, so you must build the Mach-O executable file using the -bundle linker option.

    For portability and efficiency, consider using dlopen.

  • Creates an image reference for a Mach-O file currently in memory.

    Declaration

    Objective-C

    NSObjectFileImageReturnCode NSCreateObjectFileImageFromMemory( const void* address, size_t size, NSObjectFileImage * objectFileImage);

    Parameters

    address

    A pointer to the memory block containing the Mach-O file contents.

    size

    The size of the memory block, in bytes.

    objectFileImage

    On output, a pointer to an NSObjectFileImage opaque data structure.

    Discussion

    Given a pointer to a Mach-O file in memory, this function creates and returns an NSObjectFileImage reference. The current implementation works only with bundles, so you must build the Mach-O executable file using the -bundle linker option.

    The memory block that address points to, must be allocated with vm_allocate (/usr/include/mach/vm_map.h).

    See also NSDestroyObjectFileImage.

    Availability

    Available in OS X v10.3 and later.

  • Releases the given object file image.

    Declaration

    Objective-C

    bool NSDestroyObjectFileImage( NSObjectFileImage objectFileImage);

    Parameters

    objectFileImage

    A reference to the object file image to destroy.

    Return Value

    TRUE if the image was successfully destroyed, FALSE if not.

    Discussion

    When this function is called, the dynamic loader calls vm_deallocate (/usr/include/mach/vm_map.h) on the memory pointed to by the objectFileImage parameter.

    For portability and efficiency, consider using dlopen in conjunction with dlclose.

    See also NSCreateObjectFileImageFromMemory.

  • Links the given object file image as a module into the current program.

    Declaration

    Objective-C

    NSModule NSLinkModule( NSObjectFileImage objectFileImage, const char* moduleName, uint32_t options);

    Parameters

    objectFileImage

    An object file image reference. Pass a reference created using the NSCreateObjectFileImageFromFile function.

    moduleName

    A C string. Pass the absolute path to the object file image. GDB uses this path to retrieve debug symbol information from the library.

    options

    An unsigned long value. Pass one or more of the following bit masks or NSLINKMODULE_OPTION_NONE to specify no options:

    NSLINKMODULE_OPTION_BINDNOW

    The dynamic linker binds all undefined references immediately, rather than waiting until the references are actually used. All dependent libraries are also bound.

    NSLINKMODULE_OPTION_PRIVATE

    Do not add the global symbols from the module to the global symbol list. Instead, you must use the NSLookupSymbolInModule function to obtain symbols from this module.

    NSLINKMODULE_OPTION_RETURN_ON_ERROR

    If an error occurs while binding the module, return NULL. You can then use the function NSLinkEditError to retrieve information about the error.

    Without this option, this function calls the linkEdit error handler you have installed using the NSInstallLinkEditErrorHandlers function. If you have not installed a link edit error handler, this function prints a message to the standard error stream and causes a breakpoint trap to end the program.

    Return Value

    A reference to the linked module.

    Discussion

    When you call this function, all libraries referenced by the given module are added to the library search list. Unless you pass the NSLINKMODULE_OPTION_PRIVATE, NSLinkModule adds all global symbols in the module to the global symbol list.

    For portability and efficiency, consider using dlopen.

    See Building Mach-O Files in Mach-O Programming Topics for more information about modules.

  • Given a symbol name, returns the corresponding symbol from the global symbol table.

    Declaration

    Objective-C

    NSSymbol NSLookupAndBindSymbol( const char* symbolName);

    Parameters

    symbolName

    A pointer to a C string. Pass the name of the symbol you wish to find.

    Return Value

    The symbol reference for the requested symbol.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

    On error, if you have installed a link edit error handler, it is called; otherwise, this function writes an error message to file descriptor 2 (usually the standard error stream, stderr) and causes a breakpoint trap to end the program.

    If you know the name of the library in which the symbol is likely to be located, you can use the NSLookupAndBindSymbolWithHint function, which may be faster than this function. You should use the NSLookupSymbolInImage function to perform a two-level namespace lookup.

  • Given a symbol name, returns the corresponding symbol from the global symbol table.

    Declaration

    Objective-C

    NSSymbol NSLookupAndBindSymbolWithHint( const char* symbolName, const char* libraryNameHint);

    Parameters

    symbolName

    A pointer to a C string. Pass the name of the symbol you wish to find.

    libraryNameHint

    A pointer to a C string. Pass any part of the name of the library that the symbol is likely to be found in.

    Return Value

    The symbol reference for the requested symbol.

    Discussion

    On error, if you have installed a link edit error handler, it is called; otherwise, this function writes an error message to file descriptor 2 (usually the standard error stream, stderr), and causes a breakpoint trap to end the program.

    Note that this function performs a flat lookup even if the symbol namespace of the current program has two levels. You should use the NSLookupSymbolInImage function to perform a two-level namespace lookup.

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

  • Given a module reference, returns a reference to the symbol with the given name.

    Declaration

    Objective-C

    NSSymbol NSLookupSymbolInModule( NSModule module, const char* symbolName);

    Parameters

    module

    A module reference. Pass the module that contains the symbol.

    symbolname

    A pointer to a C string. Pass the name of the symbol to look up.

    Return Value

    The symbol reference or NULL if the symbol cannot be found.

    Discussion

    For portability and efficiency, consider using dlsym.

  • Returns the name of the given module.

    Declaration

    Objective-C

    const char* NSNameOfModule( NSModule module);

    Parameters

    module

    A module reference. Pass the module whose name you wish to retrieve.

    Return Value

    A C string containing the name of the module. The string is owned by the dynamic linker and you should not free it.

    Discussion

    See “Building Mach-O Files” in OS X ABI File Format Reference.for more information about modules.

  • Returns TRUE if the given symbol is defined in the current program.

    Declaration

    Objective-C

    enum bool NSIsSymbolNameDefined ( const char* symbolName );

    Parameters

    symbolName

    A C string. Pass the name of the symbol whose definition status you wish to discover.

    Return Value

    TRUE when the symbol is defined by any image loaded in the current process; FALSE when the symbol cannot be found.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

    If you know the name of the library in which the symbol is likely to be located, you can use the NSIsSymbolNameDefinedWithHint function, which may be faster than this function. You should use the NSIsSymbolNameDefinedInImage function to perform a two-level namespace lookup.

  • Returns TRUE if the given image contains the named symbol.

    Declaration

    Objective-C

    enum bool NSIsSymbolNameDefinedInImage ( const struct mach_header * image , const char* symbolName );

    Parameters

    image

    A pointer to a mach_header (Mach-O Runtime Architecture) data structure.

    symbolName

    A C string. Pass the name of the symbol.

    Return Value

    TRUE if the image contains a symbol with the given name, false otherwise.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

  • Returns TRUE if the given symbol is defined in the current program, with a hint specifying the name of the shared library likely to contain the symbol.

    Declaration

    Objective-C

    enum bool NSIsSymbolNameDefinedWithHint ( const char* symbolName , const char* libraryNameHint );

    Parameters

    symbolName

    A C string. Pass the name of the symbol whose definition status you wish to discover.

    libraryNameHint

    A C string. Pass any part of the name of the shared library that is likely to contain the symbol. It searches only the first shared library that matches.

    Return Value

    TRUE when the symbol is defined by any image loaded in the current process; FALSE when the symbol cannot be found.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

    The library name you pass to this function allows it to determine a position in the list of loaded symbols from which to start the search. This can result in a considerably faster lookup search time than is possible using NSIsSymbolNameDefined.

    Note that this function performs a flat lookup even if the symbol namespace of the current program has two levels. You should use the NSIsSymbolNameDefinedInImage function to perform a two-level namespace lookup.

  • Returns a reference to the module containing the given symbol.

    Declaration

    Objective-C

    NSModule NSModuleForSymbol( NSSymbol symbol);

    Parameters

    symbol

    A symbol reference. Pass the symbol whose module you wish to obtain.

    Return Value

    A reference to the module that contains the given symbol.

  • Unlinks the given module from the current program.

    Declaration

    Objective-C

    bool NSUnLinkModule( NSModule module, uint32_t options);

    Parameters

    module

    A module reference. Pass a reference to a module that you have previously linked using the NSLinkModule function.

    options

    An unsigned long value. You can specify one or more of the following bit masks:

    NSUNLINKMODULE_OPTION_NONE

    Unlink the module and deallocate the memory it occupies.

    NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED

    Unlink the module, but do not deallocate the memory it occupies. Addresses that reside within the module remain valid. You cannot unmap this memory later; it’s released when the process exits or is terminated.

    NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES

    Unlink the module and reset lazy references from other modules that are bound to the module. You can then link a new module that implements the same symbols, and the function call references are bound to the new module when accessed.

    Discussion

    For portability and efficiency, consider using dlopen in conduction with dlclose.

    See Building Mach-O Files in Mach-O Programming Topics for more information about modules.

    Special Considerations

    In OS X v10.2 and later, NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES can be used only with PowerPC CPU executables.

The functions described in this section are declared in /usr/include/mach-o/dyld.h. The use of these functions is discouraged. You should use the more efficient functions described in Dynamic Loader Compatibility Functions.

  • Adds the specified Mach-O image to the currently running process.

    Declaration

    Objective-C

    const struct mach_header* NSAddImage( const char* image_name, uint32_t options);

    Parameters

    image_name

    A pointer to a C string. Pass the pathname to a shared library on disk. For best performance, specify the full pathname of the shared library—not a symlink.

    options

    A bit mask. Pass one or more of the following options or NSADDIMAGE_OPTION_NONE to specify no options:

    NSADDIMAGE_OPTION_RETURN_ON_ERROR

    If an error occurs and you have specified this option, this function returns NULL. You can then use the function NSLinkEditError to retrieve information about the error.

    If an error occurs, and you have not specified this option, this function calls the linkEdit error handler you have installed using the NSInstallLinkEditErrorHandlers function. If you have not installed a link edit error handler, this function prints an error to stderr and causes a breakpoint trap to end the program.

    NSADDIMAGE_OPTION_WITH_SEARCHING

    With this option, the image_name passed for the library and all its dependents is affected by the various dyld environment variables as if this library were linked into the program.

    NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED

    With this option, this function returns NULL if the shared library was not loaded prior to the call to this function.

    Return Value

    A pointer to a mach_header (“OS X ABI Mach-O File Format Reference”) data structure. This is a pointer to the start of the loaded image.

    Discussion

    This function loads the shared library specified by image_name into the current process, returning a pointer to the mach_header data structure of the loaded image. Any libraries that the specified library depends on are also loaded.

    The linkEdit error handler is documented in the NSModule(3) man page.

    For portability and efficiency, consider using dlopen.

    Availability

    Available in OS X v10.1 and later.

  • Adds a dynamic shared library to the search list.

    Declaration

    Objective-C

    extern bool NSAddLibrary( const char* pathName);

    Parameters

    pathName

    A C string. Pass the name of a dynamic shared library.

    Return Value

    TRUE if the library was successfully added to the search list, FALSE otherwise.

    Discussion

    Deprecated in OS X v10.4. Use NSAddImage instead.

    Special Considerations

    Instead of using this function, you should use NSAddImage with the NSADDIMAGE_OPTION_NONE option.

  • Adds a dynamic shared library to the search list—using the various dyld environment variables—as if the library were linked into the program.

    Declaration

    Objective-C

    extern bool NSAddLibraryWithSearching( const char* pathName);

    Parameters

    pathName

    A C string. Pass the name of a dynamic shared library.

    Return Value

    TRUE if the library was successfully added to the search list, FALSE otherwise.

    Discussion

    Deprecated in OS X v10.4. Use NSAddImage instead.

    Special Considerations

    Instead of using this function, you should use NSAddImage with the NSADDIMAGE_OPTION_WITH_SEARCHING option.

  • Returns the address in the program’s address space of the data represented by the given symbol. The data may be a variable, a constant, or the first instruction of a function.

    Declaration

    Objective-C

    void* NSAddressOfSymbol( NSSymbol symbol);

    Parameters

    symbol

    A symbol reference. Pass the symbol whose address you wish to obtain.

    Return Value

    A pointer to the data represented by the given symbol.

    Discussion

    For portability and efficiency, consider using dlsym.

  • Returns the name of the library that contains the given module.

    Declaration

    Objective-C

    const char* NSLibraryNameOfModule( NSModule module);

    Parameters

    module

    A module reference. Pass the module whose library name you wish to retrieve.

    Return Value

    A C string containing the name of the library that contains the module. The string is owned by the dynamic linker and you should not free it.

    Discussion

    See Building Mach-O Files in Mach-O Programming Topics for more information about modules.

  • Returns a reference to the specified symbol from the specified image.

    Declaration

    Objective-C

    NSSymbol NSLookupSymbolInImage( const struct mach_header * image, const char* symbolName uint32_t options);

    Parameters

    image

    A pointer to a mach_header data structure. Pass a pointer to the start of the image that contains the symbol. You can get this pointer from a shared library name using NSAddImage.

    If the process does not have a two-level namespace, NSLookupSymbolInImage ignores this argument and searches for the symbol in the global symbol table.

    symbolName

    A pointer to a C string. Pass the name of the symbol you wish to find.

    options

    A bit mask. Pass any of the following options:

    NSLOOKUPSYMBOLINIMAGE_OPTION_BIND

    Bind the nonlazy symbols of the module in the image that defines symbolName and let all lazy symbols in the module be bound on first call. You should pass this option when you expect the module to bind without errors (for example, a library supplied with the system). If, later, you call a lazy symbol, and the lazy symbol fails to bind, the runtime calls the link edit error handler you have installed using the NSInstallLinkEditErrorHandlers function.

    If there is no link edit error handler installed, the runtime prints a message to the standard error stream and causes a breakpoint trap to end the program.

    NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW

    Bind all the nonlazy and lazy symbols of the module in the image that defines the symbol name, and bind symbols in the dependent libraries as needed.

    Pass this option for a library that might not be expected to bind without errors but that links against only system-supplied libraries that are themselves expected to bind without any errors.

    NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY

    Bind all the symbols of the module that defines symbolName and all the dependent symbols of all needed libraries.

    Because it may take a long time to fully bind the image, you should pass this option only for libraries that cannot bind other symbols once executed, such as code that implements signal handlers.

    NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR

    Return NULL if the symbol cannot be bound.

    Return Value

    The symbol reference for the requested symbol, or NULL if the symbol cannot be found and you passed the option NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR.

    Discussion

    On error, if you have installed a link edit error handler, it is called; otherwise, this function writes an error message to file descriptor 2 (usually the standard error stream, stderr) and causes a breakpoint trap to end the program.

    For portability and efficiency, consider using dlsym.

    Availability

    Available in OS X v10.1 and later.

  • Returns the name of the given symbol.

    Declaration

    Objective-C

    const char* NSNameOfSymbol( NSSymbol symbol);

    Parameters

    symbol

    A symbol reference. Pass the symbol whose name you wish to obtain.

    Return Value

    A pointer to a C string containing the name of the reference. The dynamic linker owns this string and you should not free it.

The functions described in this section are declared in /usr/include/mach-o/getsect.h.

  • Returns a data structure representing a section of the Mach-O file that contains the main executable program of the current process.

    Declaration

    Objective-C

    const struct section* getsectbyname( const char* segname, const char* sectname);

    Parameters

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    Return Value

    A pointer to a section (Mach-O File Format Reference) data structure.

  • Returns the data structure representing a section of a specified 32-bit Mach-O file.

    Declaration

    Objective-C

    const struct section* getsectbynamefromheader( const struct mach_header * mhp, const char* segname, const char* sectname);

    Parameters

    mhp

    A pointer to a mach_header data structure. Pass the mach_header of the file containing the section data you wish to retrieve.

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    Return Value

    A pointer to a section data structure.

  • Returns the data structure representing a section of a specified 64-bit Mach-O file.

    Declaration

    Objective-C

    const struct section_64* getsectbynamefromheader( const struct mach_header_64 * mhp, const char* segname, const char* sectname);

    Parameters

    mhp

    A pointer to a mach_header_64 data structure. Pass the mach_header of the file containing the section data you wish to retrieve.

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    Return Value

    A pointer to a section_64 data structure.

  • Returns the data for a section from the Mach-O file of the main executable program of the current process.

    Declaration

    Objective-C

    char* getsectdata( const char* segname, const char* sectname, unsigned long* size);

    Parameters

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    size

    A pointer to a long integer. On output, contains the length (in bytes) of the section.

    Return Value

    A pointer to the data of the section.

  • Returns the data for a section of the Mach-O file containing a specified framework.

    Declaration

    Objective-C

    char* getsectdatafromFramework( const char* FrameworkName, const char* segname, const char* sectname, unsigned long* size);

    Parameters

    FrameworkName

    A pointer to a C string. Pass the name of the framework in which the section resides.

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    size

    A pointer to a long integer. On output, contains the length (in bytes) of the section.

    Return Value

    A pointer to the data of the section. If the Mach-O file is a dynamic shared library (MH_DYLIB), you need to add the virtual memory slide amount to this address to get the true address of the data. See _dyld_get_image_vmaddr_slide for more information.

  • Returns the data for a section of a specified 32-bit Mach-O file.

    Declaration

    Objective-C

    char* getsectdatafromheader( const struct mach_header * mhp, const char* segname, const char* sectname, uint32_t* size);

    Parameters

    mhp

    A pointer to a mach_header data structure. Pass the mach_header of the file containing the section data you wish to retrieve.

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    size

    A pointer to a long integer. On output, contains the length (in bytes) of the section.

    Return Value

    A pointer to the data of the section. If the Mach-O file is a dynamic shared library (MH_DYLIB), you need to add the virtual memory slide amount to this address to get the true address of the data. See _dyld_get_image_vmaddr_slide for more information.

  • Returns the data for a section of a specified 64-bit Mach-O file.

    Declaration

    Objective-C

    char* getsectdatafromheader( const struct mach_header_64 * mhp, const char* segname, const char* sectname, uint64_t* size);

    Parameters

    mhp

    A pointer to a mach_header_64 data structure. Pass the mach_header of the file containing the section data you wish to retrieve.

    segname

    A pointer to a C string. Pass the name of the segment in which the section resides.

    sectname

    A pointer to a C string. Pass the name of the section.

    size

    A pointer to a long integer. On output, contains the length (in bytes) of the section.

    Return Value

    A pointer to the data of the section. If the Mach-O file is a dynamic shared library (MH_DYLIB), you need to add the virtual memory slide amount to this address to get the true address of the data. See _dyld_get_image_vmaddr_slide for more information.

  • Returns a data structure representing a segment of the Mach-O file containing the main executable program of the current process.

    Declaration

    Objective-C

    const struct segment_command* getsegbyname( const char* segname);

    Parameters

    segname

    A pointer to a C string. Pass the name of the segment.

    Return Value

    A pointer to a segment_command (Mach-O File Format Reference) data structure.

  • Finds the image containing the specified address and fully binds all the modules within it.

    Declaration

    Objective-C

    bool _dyld_bind_fully_image_containing_address( const void* address);

    Parameters

    address

    A pointer to an address located somewhere within a loaded image.

    Return Value

    A Boolean value. If true, the address resides somewhere within a loaded image, and so _dyld_bind_fully_image_containing_address attempted to bind that image. If false, the address does not reside within a loaded image, and so _dyld_bind_fully_image_containing_address did nothing.

    Discussion

    You can use this function to bind error handing code like signal handlers when you have the address of a function, but not the symbol name. This may bind more symbols than are actually needed.

    If the image containing the address is a flat namespace image, multiple-defined errors can occur even if the symbols are not really used. Errors in binding are reported through the normal error reporting mechanisms.

  • Binds the module that contains a given Objective-C address.

    Declaration

    Objective-C

    void _dyld_bind_objc_module( const void* objc_module);

    Parameters

    objc_module

    A pointer. Pass any address residing within the __OBJC,__module section of a loaded Mach-O file.

    Discussion

    This function is used by the Objective-C runtime library.

  • Obtains the address of the implementation of a dyld library function.

    Declaration

    Objective-C

    int _dyld_func_lookup( const char* dyld_func_name, void** address);

    Parameters

    dyld_func_name

    A pointer to a C string. Pass the name of a dyld library function.

    address

    A pointer to a pointer. On output, points to the address of the function if the function is found, otherwise the value is undefined.

    Return Value

    An integer value. Nonzero if the function was found. Zero if the function was not found.

    Discussion

    This function is used by the library code that implements the dyld functions.

  • Returns the data structure for the header of a specified image. The image is specified by index into the list of images maintained by dyld for the current process.

    Declaration

    Objective-C

    const struct mach_header* _dyld_get_image_header( uint32_t image_index);

    Parameters

    image_index

    A long integer. Pass a zero-based index indicating the position of the image in the list of images loaded into the address space of the current process.

    Return Value

    A pointer to the mach_header data structure of the specified image. If image_index is greater than the number of loaded images, this pointer is null.

  • Retrieves the name of an image.

    Declaration

    Objective-C

    const char* _dyld_get_image_name( uint32_t image_index);

    Parameters

    image_index

    A long integer. Pass a zero-based index indicating the position of the image in the list of images loaded into the address space of the current process.

    Return Value

    A pointer to a C string. If image_index is greater than the number of loaded images, the string pointer is null.

    Discussion

    Returns the name of the image located at the given index into the global image list.

  • Returns the virtual memory address slide amount of an image.

    Declaration

    Objective-C

    intptr_t _dyld_get_image_vmaddr_slide( uint32_t image_index);

    Parameters

    image_index

    A long integer. Pass a zero-based index indicating the position of the image in the list of images loaded into the address space of the current process.

    Return Value

    If image_index is greater than or equal to the value returned by _dyld_image_count, zero. Otherwise, the vmaddr_slide value for the specified image.

    Discussion

    When the dynamic linker loads an image, the image must be mapped into the virtual address space of the process at an unoccupied address. The dynamic linker accomplishes this by adding a value—the virtual memory slide amount—to the base address of the image.

  • Obtains the size and starting location of an Objective-C module.

    Declaration

    Objective-C

    void _dyld_get_objc_module_sect_for_module( NSModule module, void** objc_module, size_t* size);

    Parameters

    module

    A module reference from an image.

    objc_modulet

    A pointer to a pointer. On output, contains a pointer to the start of the __OBJC,__module section for the specified module.

    size

    A pointer to a long integer. On output, the long integer contains the a value indicating the size of the output module.

    Discussion

    This function is used by the Objective-C runtime library.

  • Returns the number of images that dyld has mapped into the address space of the current process.

    Declaration

    Objective-C

    uint32_t _dyld_image_count(void);

    Return Value

    A long integer containing the number of images that dyld has mapped into the address space of the current process.

    Discussion

    This function provides you with a count of the number of the images in the image list. You can use this number to iterate the images loaded into the address space of the current process, using functions such as _dyld_get_image_header and _dyld_get_image_name.

  • Returns whether or not a specified address is within any loaded image.

    Declaration

    Objective-C

    bool _dyld_image_containing_address( const void* address);

    Parameters

    address

    An unsigned long integer. Pass the address that you wish to obtain status about.

    Return Value

    TRUE if the address is located within an image loaded by the dynamic linker, FALSE otherwise.

  • Returns whether or not the dynamic linker was able to launch the program with the prebinding optimization enabled.

    Declaration

    Objective-C

    bool _dyld_launched_prebound(void);

    Return Value

    A Boolean value. TRUE if the program was launched successfully using the prebound state; FALSE if the either the program was not prebound or the prebinding couldn’t be used for some reason.

    Discussion

    If the program was not successfully launched with the prebinding optimization, the linker did not prebind the program, the addresses of some images overlapped and so the linker could not use the prebound addresses, or some other problem occurred. In any case, the program continues to launch, but it runs slower than with prebinding enabled.

  • Finds the given symbol name and binds it into the program.

    Declaration

    Objective-C

    void _dyld_lookup_and_bind( const char* symbol_name, void ** address NSModule * module);

    Parameters

    symbol_name

    A pointer to a C string. Specify the name of the symbol to bind.

    address

    A pointer to a pointer. On output, points to the address of the symbol specified by symbol_name. This parameter is optional; pass NULL for this pointer on input if you do not want to retrieve this data.

    module

    A pointer to a module pointer. On output, the module pointer contains the module of the symbol specified by symbol_name. This parameter is optional; specify NULL for this pointer on input if you do not want to retrieve this data.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

    You can use _dyld_lookup_and_bind to find a given symbol name in the global search list and bind it (and all other defined symbols in the same module) into the program.

    If the program is prebound and you know the name of the library that contains the symbol, consider using _dyld_lookup_and_bind_with_hint instead.

  • Finds the module containing the specified symbol and fully binds all the symbol references within it.

    Declaration

    Objective-C

    void _dyld_lookup_and_bind_fully( const char* symbol_name, void** address, NSModule * module);

    Parameters

    symbol_name

    A pointer to a C string. Specify the name of the symbol to bind.

    address

    A pointer to a pointer. On output, points to the address of the specified symbol.

    module

    A pointer to a pointer. On output, the pointer is set to the address of the module in which the specified symbol resides.

    Discussion

    You can use this function to bind modules containing signal handlers or other error handling code that cannot be initialized lazily.

    Errors in binding are reported through the normal mechanisms.

  • Obtains and binds the Objective-C module that contains the specified symbol.

    Declaration

    Objective-C

    void _dyld_lookup_and_bind_objc( const char* symbol_name, void** address, NSModule * module);

    Parameters

    symbol_name

    A pointer to a C string. Specify the name of the symbol to bind, such as .objc_class_name_Foo.

    address

    A pointer to a pointer. On output, points to the address of the symbol specified by symbol_name. This parameter is optional; pass NULL for this pointer on input if you do not want to retrieve this data.

    module

    A pointer to a module pointer. On output, the module pointer contains the module of the symbol specified by symbol_name. This parameter is optional; specify NULL for this pointer on input if you do not want to retrieve this data.

    Discussion

    This routine is used by the Objective-C runtime library. It performs the same function as _dyld_lookup_and_bind but, for performance reasons, does not update the symbol pointers if the symbol is in a bound module. An Objective-C symbol such as .objc_class_name_Object is never used by a symbol pointer, and updating the symbol pointers is a relatively expensive operation; so this provides a way for the Objective-C runtime to avoid that overhead.

  • Finds the given symbol name and binds it into the program, with a hint to allow dyld to speed up the symbol search for a prebound program.

    Declaration

    Objective-C

    void _dyld_lookup_and_bind_with_hint( const char* symbol_name, const char* library_name_hint, void** address, NSModule * module);

    Parameters

    symbol_name

    A pointer to a C string. Specify the name of the symbol to bind.

    library_name_hint

    A pointer to a C string. Specify the name of the library in which the symbol is probably located. The dynamic linker compares this name with the actual library install names using the standard C library function strstr.

    address

    A pointer to a pointer. On output, points to the address of the symbol specified by symbol_name. This parameter is optional; pass NULL for this pointer on input if you do not want to retrieve this data.

    module

    A pointer to a module pointer. On output, the module pointer contains the module of the symbol specified by symbol_name. This parameter is optional; specify NULL for this pointer on input if you do not want to retrieve this data.

    Discussion

    Deprecated in OS X v10.4. Use NSLookupSymbolInImage instead.

    You can use _dyld_lookup_and_bind_with_hint to quickly find a given symbol name in the global search list of a prebound program and bind the symbol (and all other defined symbols in the same module) into the program.

  • This function is used by the profiling routine moninit to allow images other than the main executable to be profiled.

    Declaration

    Objective-C

    void _dyld_moninit( void (*monaddition)( char* lowpc, char* highpc);

    Parameters

    monaddition

    A pointer to a callback function. The callback is called when an image is first mapped in.

    Discussion

    This function is usually called by the profiling runtime (specifically, from the moninit function). It is documented here for completeness. See the man page for moninit and monaddtion for further information.

  • Indicates whether or not the dynamic linker is loaded into the current program

    Declaration

    Objective-C

    bool _dyld_present (void);

    Return Value

    A Boolean value indicating the presence of dyld. This value is FALSE if dyld is not loaded in the current process, and TRUE if dyld is loaded in the current process.

  • Registers a function to be called by the dynamic linker runtime when an image is added to the program.

    Declaration

    Objective-C

    void _dyld_register_func_for_add_image( void (*func)(struct mach_header * mh, intptr_t vmaddr_slide));

    Parameters

    func

    A pointer to a callback function that accepts a pointer to a mach_header data structure and a virtual memory slide amount. The virtual memory slide amount specifies the difference between the address at which the image was linked and the address at which the image is loaded.

    Discussion

    When you call _dyld_register_func_for_add_image, the dynamic linker runtime calls the specified callback (func) once for each of the images that are currently loaded into the program. When a new image is added to the program, your callback is called again with the mach_header for the new image, and the virtual memory slide amount of the new image.

    You might use this, for example, in implementing a runtime system, such as the Objective-C runtime, to discover when new images are added to the program.

  • Registers a function to be called by the dynamic linker runtime when a module is linked into the program.

    Declaration

    Objective-C

    void _dyld_register_func_for_link_module( void (*func)( NSModule module));

    Parameters

    func

    A pointer to a callback that accepts a module reference.

    Discussion

    When you call _dyld_register_func_for_link_module, the dynamic linker runtime calls the specified callback (func) once for each module that is currently linked into the program. When a new module is linked into the program, the func callback is called again for that module.

  • Registers a function to be called by the dynamic linker runtime when an image is removed from the program.

    Declaration

    Objective-C

    void _dyld_register_func_for_remove_image( void (*func) (struct mach_header * mh), intptr_t vmaddr_slide) );

    Parameters

    func

    A pointer to a callback function that accepts a pointer to a mach_header data structure and a virtual memory slide amount. The virtual memory slide amount specifies the difference between the address at which the image was linked and the address at which the image is loaded.

  • Assembly-language glue code that performs binding for a lazy function symbol.

    Declaration

    Objective-C

    .private_extern dyld_stub_binding_helper

    Parameters

    PowerPC: r11 x86: stack-based parameter

    A pointer to the lazy symbol pointer for the function to be bound.

    Discussion

    The dyld stub binding helper is a glue function that assists the dynamic linker in lazily binding an external function. When the compiler sees a call to an external function, it generates a symbol stub and a lazy pointer for the function. At the call site, the compiler generates a call to the symbol stub. The symbol stub is a sequence of code that loads the lazy pointer and jumps to it. Initially, the sequence of code and the contents of the lazy pointer call this function, which calls the dynamic linker to bind the symbol. After the symbol is bound, the lazy pointer is set to the address of the symbol, and the symbol is reached directly by jumping to the lazy pointer.

    Thereafter, because the address has been changed to the actual address of the function, all calls to the external function call the external function.

    On entry, this function accepts the address of the lazy symbol pointer. On exit, the value of the lazy symbol pointer is set to the address of the external function. The dyld stub binding helper is assembly-language based and does not use standard calling conventions, and as such, the location of the parameters are specific to each CPU architecture. On PowerPC, the address of the lazy symbol pointer is expected to be in GPR11. On x86, the address of the lazy symbol pointer should be the pushed on the stack.

    This function is located in the runtime startup files that are statically linked into the image. For executables, the file is /lib/crt1.o. For bundles, it is /lib/bundle1.o, and for shared libraries, it is /lib/dylib1.o.

Constants

  • Potential return values when creating a Mach-O image.

    Declaration

    Objective-C

    typedef enum { NSObjectFileImageFailure, NSObjectFileImageSuccess, NSObjectFileImageInappropriateFile, NSObjectFileImageArch, NSObjectFileImageFormat, NSObjectFileImageAccess } NSObjectFileImageReturnCode;

    Constants

    • NSObjectFileImageSuccess

      NSObjectFileImageSuccess

      The image creation operation was completed successfully.

    • NSObjectFileImageFailure

      NSObjectFileImageFailure

      The image creation operation was not successfully completed.

      When this value is returned, an error message is printed to the standard error stream.

    • NSObjectFileImageInappropriateFile

      NSObjectFileImageInappropriateFile

      The Mach-O file is not of a type the called function can operate upon.

    • NSObjectFileImageArch

      NSObjectFileImageArch

      The specified Mach-O file is for a different CPU architecture.

    • NSObjectFileImageFormat

      NSObjectFileImageFormat

      The specified file or memory block does not appear to point to a Mach-O file.

    • NSObjectFileImageAccess

      NSObjectFileImageAccess

      The access permissions for the specified file do not permit the creation of the image.

    Discussion

    These return values are returned from NSCreateObjectFileImageFromFile and NSCreateObjectFileImageFromMemory.