NSModule man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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‐
       lection	of  symbols.   A  dynamic shared library is composed of one or
       more modules with each of those modules containing a  separate  collec‐
       tion  of	 symbols.  If a symbol is used from a module then all the sym‐
       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‐
       ited to only Mach-O MH_BUNDLE types which are used for plugins.	A mod‐
       ule  name  is specified when a module is linked so that later NSNameOf‐
       Module can be used with the module handle and to do things like	report
       errors.	 When a module is linked, all libraries referenced by the mod‐
       ule 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‐
	      gram.  If any errors occur the handlers installed with NSInstal‐
	      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‐
	      bols of the module can then be looked up using NSLookupSymbolIn‐
	      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.

       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 use‐
	      ful 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‐
	      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‐
       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‐
       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‐
       tion if found.

       The image handle parameter for  NSLookupSymbolInImage  and  NSIsSymbol‐
       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‐
       bol.   If  any  errors  occur  the  handlers  installed	with NSInstal‐
       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‐
       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‐
       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‐
       bolInImage are as follows:

       NSLOOKUPSYMBOLINIMAGE_OPTION_BIND
	      Just  bind  the non-lazy symbols of module that defines the sym‐
	      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‐
	      ule expected to bind without any errors like a module in a  sys‐
	      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‐
	      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‐
	      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‐
       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‐
       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‐
	      tine NSLinkEditError is then used.  It has the  same  parameters
	      as the link edit error handler (see below) except all the param‐
	      eters are pointers in which the information  is  returned	 indi‐
	      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 buf‐
       fer. 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  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  MAX‐
       PATHLEN.

ERROR HANDLING
       NSInstallLinkEditErrorHandlers  is  passed a pointer to a NSLinkEditEr‐
       rorHandlers which contains three function pointers to be used for  han‐
       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‐
       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‐
       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‐
       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‐
       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.		March 10, 2001			   NSModule(3)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net