Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC
ADC Home > Reference Library > Reference > Darwin > Mac OS X Man Pages

NSModule(3)                                                        NSModule(3)



NAME
       NSModule - programmatic interface for working with modules and symbols

SYNOPSIS
       #include <mach-o/dyld.h>
       typedef void * NSModule;
       extern NSModule NSLinkModule(
            NSObjectFileImage objectFileImage,
            const char *moduleName,
            unsigned long options);
       extern enum DYLD_BOOL NSUnLinkModule(
            NSModule module,
            unsigned long options);
       extern const char * NSNameOfModule(
            NSModule m);
       extern const char * NSLibraryNameForModule(
            NSModule m);


       typedef void * NSSymbol;
       extern enum DYLD_BOOL NSIsSymbolNameDefined(
            const char *symbolName);
       extern enum DYLD_BOOL NSIsSymbolNameDefinedWithHint(
            const char *symbolName
            const char *libraryNameHint);
       extern enum DYLD_BOOL NSIsSymbolNameDefinedInImage(
            const struct mach_header *image,
            const char *symbolName);
       extern NSSymbol NSLookupAndBindSymbol(
            const char *symbolName);
       extern NSSymbol NSLookupAndBindSymbolWithHint(
            const char *symbolName
            const char *libraryNameHint);
       extern NSSymbol NSLookupSymbolInModule(
            NSModule module,
            const char *symbolName);
       extern NSSymbol NSLookupSymbolInImage(
            const struct mach_header *image,
            const char *symbolName,
            unsigned long options);
       extern const char * NSNameOfSymbol(
            NSSymbol symbol);
       extern void * NSAddressOfSymbol(
            NSSymbol symbol);
       extern NSModule NSModuleForSymbol(
            NSSymbol symbol);
       extern enum DYLD_BOOL NSAddLibrary(
            const char *pathName);
       extern enum DYLD_BOOL NSAddLibraryWithSearching(
            const char *pathName);
       extern const struct mach_header * NSAddImage(
            const char *image_name,
            unsigned long options);
       extern long NSVersionOfRunTimeLibrary(
            const char *libraryName);
       extern long NSVersionOfLinkTimeLibrary(
            const char *libraryName);
       extern int _NSGetExecutablePath(
            char *buf,
            unsigned long *bufsize)


       extern void NSInstallLinkEditErrorHandlers(
            NSLinkEditErrorHandlers *handlers);
       extern void NSLinkEditError(
            NSLinkEditErrors *c,
            int *errorNumber,
            const char **fileName,
            const char **errorString);

       extern NSModule NSReplaceModule(
            NSModule moduleToReplace,
            NSObjectFileImage newObjectFileImage,
            unsigned long options);

       These  routines are the programmatic interface for working with modules
       and symbols in a program.  A program is composed of a set of images, an
       executable,  plugins,  and dynamic shared libraries.  An image which is
       an executable or a plugin is composed of one module containing  a  col-collection
       lection  of  symbols.   A  dynamic shared library is composed of one or
       more modules with each of those modules containing a  separate  collec-collection
       tion  of  symbols.  If a symbol is used from a module then all the sym-symbols
       bols from that module are used.

       When a program is executed it selectively binds the  symbols  it  needs
       from  the modules in the dynamic libraries that are loaded.  Normally a
       program is staticly linked against a set of  dynamic  shared  libraries
       when  it  is built.  So when the program is executed the dynamic linker
       will automaticly load those dynamic shared libraries.

       A program may programmatically load plugins after it  starts  executing
       and  that  is  done  with two sets of API's.  The first is the API's of
       NSObjectFileImage(3) and the second is NSLinkModule.  Unlike modules in
       the  dynamic  libraries  when  a plugin is loaded it is not selectively
       bound to but always bound into the program.

       NSLinkModule links the specified object file image into the program and
       returns the module handle for it.  Currently the implementation is lim-limited
       ited to only Mach-O MH_BUNDLE types which are used for plugins.  A mod-module
       ule  name  is specified when a module is linked so that later NSNameOf-NSNameOfModule
       Module can be used with the module handle and to do things like  report
       errors.  If you want gdb(1) to be able to debug your module, when call-calling
       ing NSLinkModule you should pass the image path  as  the  module  name.
       When  a  module  is  linked, all libraries referenced by the module are
       added to the list of libraries to be searched.  The parameter, options,
       can have a set of options or'ed together.  The options for NSLinkModule
       are as follows:

       NSLINKMODULE_OPTION_NONE
              This specifies no options.  With this the  global  symbols  from
              the  module are made part of the global symbol table of the pro-program.
              gram.  If any errors occur the handlers installed with NSInstal-NSInstallLinkEditErrorHandlers
              lLinkEditErrorHandlers are called or the default action is taken
              if there are no handlers.

       NSLINKMODULE_OPTION_BINDNOW
              This option causes the dynamic link editor to bind all undefined
              references  for the loaded module and not allow references to be
              bound as needed.  This affects all the references in the  module
              and all of the dependent references.

       NSLINKMODULE_OPTION_PRIVATE
              With this option the global symbols from the module are not made
              part of the global symbol table of the program.  The global sym-symbols
              bols of the module can then be looked up using NSLookupSymbolIn-NSLookupSymbolInModule.
              Module.

       NSLINKMODULE_OPTION_RETURN_ON_ERROR
              With this option if errors occur while binding this module it is
              automaticly  unloaded and NULL is returned as the module handle.
              To get the error information for the module that failed to  load
              the  routine  NSLinkEditError  is  then  used.   It has the same
              parameters as the link edit error handler (see below) except all
              the parameters are pointers in which the information is returned
              indirectly.

       NSLINKMODULE_OPTION_DONT_CALL_MOD_INIT_ROUTINES
              With this option the module init routines are not called.   This
              is only useful to the fix-and-continue implementation.

       NSLINKMODULE_OPTION_TRAILING_PHYS_NAME
              With  this  option  the parameter, moduleName is assumed to be a
              string with the logical name of the image with the physical name
              of the object file tailing after the NULL character of the logi-logical
              cal name.  This is only useful to the zero-link  implementation.

       NSUnLinkModule  unlinks  the  specified module handle from the program.
       Currently the implementation is limited to only  allow  modules  linked
       with  NSLinkModule  to be unlinked.  The parameter, options, can have a
       set of options or'ed together.  The options for NSUnLinkModule  are  as
       follows:

       NSUNLINKMODULE_OPTION_NONE
              This  specifies  no  options.   With this the module is unlinked
              from the program and the memory for the module  is  deallocated.
              If  any  errors  occur  the  handlers  installed  with NSInstal-NSInstallLinkEditErrorHandlers
              lLinkEditErrorHandlers are called or the default action is taken
              if there are no handlers.

       NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED
              With  this  option  the memory for the module is not deallocated
              allowing pointers into the module to still be valid.

       NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES
              With this option any lazy references (direct function calls)  to
              symbols  defined  in  the  module are reset to be bound on first
              call again and not cause any undefined symbol errors.  Currently
              this is only implemented for the PowerPC architecture.

       NSNameOfModule  is  passed  a module handle and returns the name of the
       module.  If the module handle is invalid NULL is returned.

       NSLibraryNameForModule is passed a module handle and returns  the  name
       of  the library the module is in if any.  If the module handle is for a
       module that is not in a library (in the executable or a plugin) or  the
       module handle is invalid NULL is returned.

       NSIsSymbolNameDefined  is  passed a global symbol name (global 'C' sym-symbols
       bols names are preceded with an underbar '_') and returns TRUE or FALSE
       based on if the symbol is defined in the program's global symbol table.
       If the symbol is not defined no error occurs.

       NSIsSymbolNameDefinedWithHint is the same as NSIsSymbolNameDefined  but
       the  libraryNameHint parameter provides a hint as to where to start the
       lookup in a prebound program.  The libraryNameHint parameter is matched
       up with the actual library install names with strstr(3).

       NSIsSymbolNameDefinedInImage  is passed a pointer to the mach_header of
       a mach_header structure of a dynamic library being used by the  program
       and  a  symbol name.  This returns TRUE or FALSE based on if the symbol
       is defined in the specified image or one of the image's  sub-frameworks
       or   sub-umbrellas.    If   the   program  was  built  with  the  ld(1)
       -force_flat_namespace flag or executed with  the  environment  variable
       DYLD_FORCE_FLAT_NAMESPACE  set  and the pointer to a mach_header struc-structure
       ture is not of a bundle  loaded  with  the  NSLINKMODULE_OPTION_PRIVATE
       option  of NSLinkModule(3) then the pointer to a mach_header is ignored
       and the symbol is looked up in all the images using the  first  defini-definition
       tion if found.

       The  image  handle  parameter for NSLookupSymbolInImage and NSIsSymbol-NSIsSymbolNameDefinedInImage
       NameDefinedInImage is a pointer to a read-only mach header structure of
       a dynamic library being used by the program.  Besides the NSAddImage(3)
       routine the pointer to a mach header can also be obtained  by  using  a
       link  editor defined symbol as in <mach-o/ldsym.h> and described on the
       ld(1) man page.  Also the dyld(3) routine _dyld_get_image_header(3) and
       the mach_header pointer arguments to the call back routines called from
       _dyld_register_func_for_add_image(3) routines can also be used.

       NSLookupAndBindSymbol is passed a global symbol name and looks  up  and
       binds the symbol into the program.  It returns an NSSymbol for the sym-symbol.
       bol.  If  any  errors  occur  the  handlers  installed  with  NSInstal-NSInstallLinkEditErrorHandlers
       lLinkEditErrorHandlers  are  called  or  the default action is taken if
       there are no handlers.

       NSLookupAndBindSymbolWithHint is the same as NSLookupAndBindSymbol  but
       the  libraryNameHint parameter provides a hint as to where to start the
       lookup in a prebound program.  The libraryNameHint parameter is matched
       up with the actual library install names with strstr(3).

       NSLookupSymbolInModule  is passed a symbol name and a module handle and
       looks up the symbol in that module.  Currently this is only implemented
       for  module handles returned with NSLinkModule.  If the symbol is found
       an NSSymbol for the symbol is returned otherwise NULL is  returned  and
       no error occurs.

       NSLookupSymbolInImage is passed a pointer to a mach_header structure of
       a dynamic library being used by the program  and  a  symbol  name.   It
       returns  an  NSSymbol for the symbol for defined in the specified image
       or the image's sub-frameworks or sub-umbrellas.   If  the  program  was
       built  with  the  ld(1) -force_flat_namespace flag or executed with the
       environment variable DYLD_FORCE_FLAT_NAMESPACE set and the pointer to a
       mach_header  structure  is  not  of a bundle loaded with the NSLINKMOD-NSLINKMODULE_OPTION_PRIVATE
       ULE_OPTION_PRIVATE option of NSLinkModule(3)  then  the  pointer  to  a
       mach_header  is  ignored  and the symbol is looked up in all the images
       using the first definition found.  If  the  option  NSLOOKUPSYMBOLINIM-NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
       AGE_OPTION_RETURN_ON_ERROR is not used if any errors occur the handlers
       installed with NSInstallLinkEditErrorHandlers are called or the default
       action  is taken if there are no handlers.  The options of NSLookupSym-NSLookupSymbolInImage
       bolInImage are as follows:

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND
              Just bind the non-lazy symbols of module that defines  the  sym-symbolName
              bolName and let all lazy symbols in the module be bound on first
              call.  This should be used in the normal case for a trusted mod-module
              ule  expected to bind without any errors like a module in a sys-system
              tem supplied library.

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW
              Bind all the non-lazy and lazy symbols of  module  that  defines
              the  symbolName  and  let  all  dependent  symbols in the needed
              libraries be bound as needed.  This would be used for  a  module
              that might not be expected bind without errors but links against
              only system supplied libraries which are expected to bind  with-without
              out any errors.

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY
              Bind  all  the symbols of the module that defines the symbolName
              and all the dependent symbols of  all  needed  libraries.   This
              should only be used for things like signal handlers and linkedit
              error handlers that can't bind other symbols when  executing  to
              handle the signal or error.

       NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
              With  this  option if errors occur while binding the module that
              defines the symbolName then the module is  automaticly  unloaded
              and NULL is returned as the NSSymbol.  To get the error informa-information
              tion for  why  the  module  that  failed  to  bind  the  routine
              NSLinkEditError is then used.  It has the same parameters as the
              link edit error handler (see below) except  all  the  parameters
              are pointers in which the information is returned indirectly.

       NSNameOfSymbol  is  passed an NSSymbol and returns the name of the sym-symbol.
       bol.

       NSAddressOfSymbol is passed an NSSymbol and returns the address of  the
       symbol.

       NSModuleForSymbol  is  passed an NSSymbol and returns the NSModule that
       symbol is defined in.

       NSAddLibrary is passed the file name of a dynamic shared library to  be
       added  to the search list.  If it is successful it returns TRUE else it
       returns FALSE.

       NSAddLibraryWithSearching is passed the file name of a  dynamic  shared
       library  to  be  added  to the search list the file name passed will be
       effected by the various DYLD environment variables as if  this  library
       were linked into the program.  If it is successful it returns TRUE else
       it returns FALSE.

       NSAddImage is passed the file name of a dynamic shared  library  to  be
       added  to  the  search  list  of the program if not already loaded.  It
       returns a pointer to the mach_header structure of the  dynamic  library
       being used by the program.  For best performance of this routine if the
       library is expected to be already loaded by the program the  image_name
       should  be  a  full  path name and the same as the name recorded by the
       program.  If it is a symlink then an open(2) and an fstat(2) are needed
       to determine it is the same file as one already loaded.

       If the dynamic shared library has not already been loaded it along with
       all the needed dependent libraries are loaded.  With the options param-parameter
       eter  NSADDIMAGE_OPTION_NONE  then  any error in loading will cause the
       linkEdit error handler set by NSInstallLinkEditErrorHandlers(3)  to  be
       called  or  the  default action of printing the error and exiting to be
       taken.  The other options of NSAddImage are as follows:

       NSADDIMAGE_OPTION_RETURN_ON_ERROR
              With this option if errors occur while loading this  library  it
              is  automatically  unloaded  and  NULL  is returned.  To get the
              error information for the library that failed to load  the  rou-routine
              tine  NSLinkEditError  is then used.  It has the same parameters
              as the link edit error handler (see below) except all the param-parameters
              eters  are  pointers  in which the information is returned indi-indirectly.
              rectly.

       NSADDIMAGE_OPTION_WITH_SEARCHING
              With this option the image_name passed for the library  and  all
              its  dependents will be effected by the various DYLD environment
              variables as if this library were linked into the program.

       NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED
              With this option if the image_name passed for  the  library  has
              not  already  been loaded it is not loaded.  Only if it has been
              loaded the pointer to the mach_header will not be NULL.

       NSADDIMAGE_OPTION_MATCH_FILENAME_BY_INSTALLNAME
              When this option is specified if a later  load  of  a  dependent
              dynamic  library  with  a file system path is needed by an image
              that matches the install name of the dynamic library loaded with
              this  option,  then  the dynamic library loaded with the call to
              NSAddImage() is used in place of the dependent dynamic  library.

       NSVersionOfRunTimeLibrary  is  passed  the  install  name  of a dynamic
       shared library and returns current_version number of  the  library  the
       program is using or -1 if the program is not using that library.

       NSVersionOfLinkTimeLibrary  is  passed  the  install  name of a dynamic
       shared library and returns the current_version number  of  the  library
       the  executable  program  was  built  with or -1 if the program was not
       built with that library.

       _NSGetExecutablePath copies the path of the executable into the  buffer
       and  returns  0  if  the  path  was successfully copied in the provided
       buffer. If the buffer is not large  enough,  -1  is  returned  and  the
       expected  buffer  size  is  copied  in  *bufsize.  Note that _NSGetExe-_NSGetExecutablePath
       cutablePath 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. And with deep directories the total bufsize needed could  be
       more than MAXPATHLEN.

ERROR HANDLING
       NSInstallLinkEditErrorHandlers  is  passed a pointer to a NSLinkEditEr-NSLinkEditErrorHandlers
       rorHandlers which contains three function pointers to be used for  han-handling
       dling  dynamic  link  errors.   The  prototypes for these functions are
       given in the following typedef:
              typedef struct {
                   void     (*undefined)(const char *symbolName);
                   NSModule (*multiple)(NSSymbol s, NSModule oldModule, NSModule newModule);
                   void     (*linkEdit)(NSLinkEditErrors errorClass, int errorNumber,
                                        const char *fileName, const char *errorString);
              } NSLinkEditErrorHandlers;

       The first two functions allow the programmer to direct  the  link  edit
       processing  of  undefined  symbols  and  multiply defined symbols.  The
       third function allows the programmer to catch  all  other  link  editor
       errors.

       The state when one of the user error functions gets called will be such
       that no module will be partially loaded (except in the case of resource
       errors  like out of memory and other relocation errors).  However, with
       undefined symbol errors those  modules  referencing  undefined  symbols
       will be partially bound, and use of such modules can and will crash the
       program.

       Great care should be taken when implementing these  functions,  as  the
       program  is  running  in  a state that will crash if it uses an unbound
       symbol.  To be safe, these functions should only rely on  other  things
       in the same module or in the executable.

       If  the  user  does  not supply these functions, the default will be to
       write an error message on to file descriptor  2  (usually  stderr)  and
       exit  the  program  (except  for  the  linkEdit  error handler when the
       NSLinkEditErrors is NSLinkEditWarningError, then the default is  to  do
       nothing).

       The  specified  undefined  handler may make calls to any of the runtime
       loading functions to add modules based on the  undefined  symbol  name.
       After  dealing  with  this symbol name successfully (by doing a runtime
       loading operation to resolve the undefined reference) the handler  sim-simply
       ply  returns.  If more symbol's names remain undefined the handler will
       be called repeatedly with an undefined symbol  name.   If  the  handler
       can't deal with the symbol it should not return (put up a panel, abort,
       etc) and cause the program to exit.  Or it can  remove  itself  as  the
       undefined  handler  and  return  which will cause the default action of
       printing the undefined symbol names and exiting.

       The specified multiply defined symbol  handler  is  called  during  the
       process  of runtime linking and thus it may not call any of the runtime
       loading functions as only one set of linking  operations  can  be  per-performed
       formed in the task at a time.  The only programmatic functions that can
       be called from a multiply defined symbol  handler  are  NSNameOfSymbol,
       NSNameOfModule  and  NSLibraryNameForModule  (provided  they are linked
       into the program before the handler is called).  This  handler  returns
       the  module  handle  for the symbol that is to be used for further link
       editing, either the oldModule or the newModule.  It may also record one
       of  the  module  handles to later take action after the runtime linking
       process has completed (for  example  later  unlink  the  module).   The
       dynamic link editor updates the references to the symbol if the handler
       specifies the new symbol is to  be  used.   The  references  which  are
       updated are those that the compiler system generated as indirect refer-references.
       ences.  Initialized data and references that were  created  at  runtime
       are not effected.

       The  specified  linkEdit  error handler is called for all other runtime
       linking errors.  These other runtime linking errors are either warnings
       or  fatal  errors.   If  the  user's  link  edit error handler function
       returns for a fatal error it will cause the program to exit.  There  is
       small  set  of  major  error classes which have specific error numbers.
       These numbers are be passed in the parameter errorClass.   These  major
       error classes include:
              typedef enum {
                   NSLinkEditFileAccessError,
                   NSLinkEditFileFormatError,
                   NSLinkEditMachResourceError,
                   NSLinkEditUnixResourceError,
                   NSLinkEditOtherError,
                   NSLinkEditWarningError,
                   NSLinkEditMultiplyDefinedError,
                   NSLinkEditUndefinedError
              } NSLinkEditErrors;

       For the error class NSLinkEditUnixResourceError the errorNumber parame-parameter
       ter will be an  errno  value  (see  intro(2)).   For  the  error  class
       NSLinkEditMachResourceError   the   errorNumber  parameter  will  be  a
       kern_return_t value.  For  the  error  class  NSLinkEditOtherError  the
       errorNumber parameter will be a one of the following values:
              typedef enum {
                  NSOtherErrorRelocation,
                  NSOtherErrorLazyBind,
                  NSOtherErrorIndrLoop,
                  NSOtherErrorLazyInit,
                  NSOtherErrorInvalidArgs
              } NSOtherErrorNumbers;

       For  all  errors,  an attempt to pass an error string will be made.  In
       some cases such as resource errors, it may not be possible to return  a
       string.  In those cases the errorString parameter will be

       For  file  access errors and file format errors, an attempt to return a
       file name will also be passed, and if that is not possible the filename
       parameter will be

ALSO SEE
       NSObjectFileImage(3), dyld(3)



Apple Computer, Inc.            October 6, 2003                    NSModule(3)



Did this document help you?
Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.