Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for nsmodule (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 collection of symbols.  A dynamic shared library is composed of one  or  more
       modules with each of those modules containing a separate collection of symbols.	If a sym-
       bol is used from a module then all the symbols 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 limited to only Mach-O MH_BUNDLE types
       which are used for plugins.  A module name is specified when a module is  linked  so  that
       later  NSNameOfModule  can  be  used  with  the module handle and to do things like report
       errors.	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 program.  If any errors occur the handlers
	      installed with NSInstallLinkEditErrorHandlers 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 symbols of the module can then  be  looked
	      up using NSLookupSymbolInModule.

       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.

       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 logical
	      name.  This is only useful to the zero-link implementation.

       NSUnLinkModule unlinks the specified module handle from the program.  Currently the imple-
       mentation  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  NSUn-
       LinkModule 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  NSInstallLinkEditErrorHandlers 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 mod-
       ule 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' symbols  names	are  pre-
       ceded 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 structure is not of a  bun-
       dle 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
       definition if found.

       The image handle parameter for NSLookupSymbolInImage and NSIsSymbolNameDefinedInImage is a
       pointer to a read-only mach header structure of a dynamic library being used by	the  pro-
       gram.  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)  rou-
       tines 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 symbol.  If any errors  occur	the  han-
       dlers  installed  with  NSInstallLinkEditErrorHandlers 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 environ-
       ment variable DYLD_FORCE_FLAT_NAMESPACE set and the pointer to a mach_header structure  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	definition    found.	 If    the   option   NSLOOKUPSYMBOLINIM-
       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 NSLookupSymbolInImage are as follows:

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND
	      Just bind the non-lazy symbols of module that defines the symbolName  and  let  all
	      lazy symbols in the module be bound on first call.  This should be used in the nor-
	      mal case for a trusted module expected to bind without any errors like a module  in
	      a system 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  without  any
	      errors.

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY
	      Bind  all  the symbols of the module that defines the symbolName and all the depen-
	      dent 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 exe-
	      cuting to handle the signal or error.

       NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
	      With this option if errors occur while binding the module that defines the  symbol-
	      Name  then the module is automaticly unloaded and NULL is returned as the NSSymbol.
	      To get the error information 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 symbol.

       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 struc-
       ture of the dynamic library being used by the program.  For best performance of this  rou-
       tine  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 parameter NSADDIMAGE_OPTION_NONE then
       any error in loading will cause the linkEdit error  handler  set  by  NSInstallLinkEditEr-
       rorHandlers(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 routine NSLinkEditError is then used.	It has the  same  parame-
	      ters  as	the  link  edit  error	handler (see below) except all the parameters are
	      pointers in which the information is returned indirectly.

       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
       _NSGetExecutablePath will return "a path" to the executable not a "real path" to the  exe-
       cutable.  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 NSLinkEditErrorHandlers which con-
       tains three function pointers to be used for handling 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  unde-
       fined  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  suc-
       cessfully  (by  doing  a runtime loading operation to resolve the undefined reference) the
       handler simply 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 sym-
       bol 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 performed in the task at a time.  The	only  programmatic  func-
       tions  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 references.  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 parameter 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.			  March 10, 2001			      NSModule(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:26 PM.