doc/man/man3/NSModule.3

   1 .TH NSModule 3 "October 6, 2003" "Apple Computer, Inc."
   2 .SH NAME
   3 NSModule \- programmatic interface for working with modules and symbols
   4 .SH SYNOPSIS
   5 .nf
   6 .PP
   7 #include <mach-o/dyld.h>
   8 .sp .5
   9 typedef void * NSModule;
  10 .sp .5
  11 extern NSModule NSLinkModule(
  12         NSObjectFileImage objectFileImage,
  13         const char *moduleName,
  14         unsigned long options);
  15 .sp .5
  16 extern enum DYLD_BOOL NSUnLinkModule(
  17         NSModule module,
  18         unsigned long options);
  19 .sp .5
  20 extern const char * NSNameOfModule(
  21         NSModule m);
  22 .sp .5
  23 extern const char * NSLibraryNameForModule(
  24         NSModule m);
  25 .sp 2
  26 typedef void * NSSymbol;
  27 .sp .5
  28 extern enum DYLD_BOOL NSIsSymbolNameDefined(
  29         const char *symbolName);
  30 .sp .5
  31 extern enum DYLD_BOOL NSIsSymbolNameDefinedWithHint(
  32         const char *symbolName
  33         const char *libraryNameHint);
  34 .sp .5
  35 extern enum DYLD_BOOL NSIsSymbolNameDefinedInImage(
  36         const struct mach_header *image,
  37         const char *symbolName);
  38 .sp .5
  39 extern NSSymbol NSLookupAndBindSymbol(
  40         const char *symbolName);
  41 .sp .5
  42 extern NSSymbol NSLookupAndBindSymbolWithHint(
  43         const char *symbolName
  44         const char *libraryNameHint);
  45 .sp .5
  46 extern NSSymbol NSLookupSymbolInModule(
  47         NSModule module,
  48         const char *symbolName);
  49 .sp .5
  50 extern NSSymbol NSLookupSymbolInImage(
  51         const struct mach_header *image,
  52         const char *symbolName,
  53         unsigned long options);
  54 .sp .5
  55 extern const char * NSNameOfSymbol(
  56         NSSymbol symbol);
  57 .sp .5
  58 extern void * NSAddressOfSymbol(
  59         NSSymbol symbol);
  60 .sp .5
  61 extern NSModule NSModuleForSymbol(
  62         NSSymbol symbol);
  63 .sp .5
  64 extern enum DYLD_BOOL NSAddLibrary(
  65         const char *pathName);
  66 .sp .5
  67 extern enum DYLD_BOOL NSAddLibraryWithSearching(
  68         const char *pathName);
  69 .sp .5
  70 extern const struct mach_header * NSAddImage(
  71         const char *image_name,
  72         unsigned long options);
  73 .sp .5
  74 extern long NSVersionOfRunTimeLibrary(
  75         const char *libraryName);
  76 .sp .5
  77 extern long NSVersionOfLinkTimeLibrary(
  78         const char *libraryName);
  79 .sp .5
  80 extern int _NSGetExecutablePath(
  81         char *buf,
  82         unsigned long *bufsize)
  83 .sp 2
  84 extern void NSInstallLinkEditErrorHandlers(
  85         NSLinkEditErrorHandlers *handlers);
  86 .sp .5
  87 extern void NSLinkEditError(
  88         NSLinkEditErrors *c,
  89         int *errorNumber,
  90         const char **fileName,
  91         const char **errorString);
  92 .if
  93 .SH "FUTURE SYNOPSIS"
  94 .nf
  95 .PP
  96 extern NSModule NSReplaceModule(
  97         NSModule moduleToReplace,
  98         NSObjectFileImage newObjectFileImage,
  99         unsigned long options);
 100 .fi
 101 .PP
 102 These routines are the programmatic interface for working with modules and
 103 symbols in a program.  A program is composed of a set of images, an executable,
 104 plugins, and dynamic shared libraries.  An image which is an executable or a
 105 plugin is composed of one module containing a collection of symbols.  A dynamic
 106 shared library is composed of one or more modules with each of those modules
 107 containing a separate collection of symbols.  If a symbol is used from a module
 108 then all the symbols from that module are used.
 109 .PP
 110 When a program is executed it selectively binds the symbols it needs from the
 111 modules in the dynamic libraries that are loaded.  Normally a program is
 112 staticly linked against a set of dynamic shared libraries when it is built.
 113 So when the program is executed the dynamic linker will automaticly load those
 114 dynamic shared libraries.
 115 .PP
 116 A program may programmatically load plugins after it starts executing and that
 117 is done with two sets of API's.  The first is the API's of
 118 .IR NSObjectFileImage (3)
 119 and the second is
 120 .I NSLinkModule.
 121 Unlike modules in the dynamic libraries when a plugin is loaded it is not
 122 selectively bound to but always bound into the program.
 123 .PP
 124 .I NSLinkModule
 125 links the specified object file image into the program and returns the module
 126 handle for it.
 127 Currently the implementation is limited to only Mach-O MH_BUNDLE types which
 128 are used for plugins.
 129 A module name is specified when a module is linked so that later
 130 .I NSNameOfModule
 131 can be used with the module handle and to do things like report errors.
 132 If you want
 133 .IR gdb (1)
 134 to be able to debug your module, when calling
 135 .I NSLinkModule
 136 you should pass the image path as the module name.
 137 When a module is linked, all libraries referenced by the module are added to
 138 the list of libraries to be searched.
 139 The parameter,
 140 .I options,
 141 can have a set of options or'ed together.  The options for
 142 .I NSLinkModule
 143 are as follows:
 144 .TP
 145 .B NSLINKMODULE_OPTION_NONE
 146 This specifies no options.  With this the global symbols from the module are
 147 made part of the global symbol table of the program.  If any errors occur the
 148 handlers installed with
 149 .I NSInstallLinkEditErrorHandlers
 150 are called or the default action is taken if there are no handlers.
 151 .TP
 152 .B NSLINKMODULE_OPTION_BINDNOW
 153 This option causes the dynamic link editor to bind all undefined references for
 154 the loaded module and not allow references to be bound as needed.  This affects
 155 all the references in the module and all of the dependent references.
 156 .TP
 157 .B NSLINKMODULE_OPTION_PRIVATE
 158 With this option the global symbols from the module are not made part of
 159 the global symbol table of the program.  The global symbols of the
 160 module can then be looked up using
 161 .I NSLookupSymbolInModule.
 162 .TP
 163 .B NSLINKMODULE_OPTION_RETURN_ON_ERROR
 164 With this option if errors occur while binding this module it is automaticly
 165 unloaded and
 166 .SM NULL
 167 is returned as the module handle.  To get the error information for the module
 168 that failed to load the routine
 169 .I NSLinkEditError
 170 is then used.  It has the same parameters as the link edit error handler (see
 171 below) except all the parameters are pointers in which the information is
 172 returned indirectly.
 173 .TP
 174 .B NSLINKMODULE_OPTION_DONT_CALL_MOD_INIT_ROUTINES
 175 With this option the module init routines are not called.  This is only useful
 176 to the fix-and-continue implementation.
 177 .TP
 178 .B NSLINKMODULE_OPTION_TRAILING_PHYS_NAME
 179 With this option the parameter,
 180 .I moduleName
 181 is assumed to be a string with the logical name of the image with the physical
 182 name of the object file tailing after the NULL character of the logical name.
 183 This is only useful to the zero-link implementation.
 184 .PP
 185 .I NSUnLinkModule
 186 unlinks the specified module handle from the program.  Currently the
 187 implementation is limited to only allow modules linked with
 188 .I NSLinkModule
 189 to be unlinked.  The parameter,
 190 .I options,
 191 can have a set of options or'ed together.  The options for
 192 .I NSUnLinkModule
 193 are as follows:
 194 .TP
 195 .B NSUNLINKMODULE_OPTION_NONE
 196 This specifies no options.  With this the module is unlinked from the program
 197 and the memory for the module is deallocated.  If any errors occur the
 198 handlers installed with
 199 .I NSInstallLinkEditErrorHandlers
 200 are called or the default action is taken if there are no handlers.
 201 .TP
 202 .B NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED
 203 With this option the memory for the module is not deallocated allowing pointers
 204 into the module to still be valid.
 205 .TP
 206 .B NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES
 207 With this option any lazy references (direct function calls) to symbols defined
 208 in the module are reset to be bound on first call again and not cause any
 209 undefined symbol errors.  Currently this is only implemented for the PowerPC
 210 architecture.
 211 .PP
 212 .I NSNameOfModule
 213 is passed a module handle and returns the name of the module.  If the module
 214 handle is invalid
 215 .SM NULL
 216 is returned.
 217 .PP
 218 .I NSLibraryNameForModule
 219 is passed a module handle and returns the name of the library the module is in
 220 if any.  If the module handle is for a module that is not in a library (in the
 221 executable or a plugin) or the module handle is invalid
 222 .SM NULL
 223 is returned.
 224 .PP
 225 .I NSIsSymbolNameDefined
 226 is passed a global symbol name (global 'C' symbols names are preceded with an
 227 underbar '\_') and returns
 228 .SM TRUE
 229 or
 230 .SM FALSE
 231 based on if the symbol is defined in the program's global symbol table.
 232 If the symbol is not defined no error occurs.
 233 .PP
 234 .I NSIsSymbolNameDefinedWithHint
 235 is the same as
 236 .I NSIsSymbolNameDefined
 237 but the
 238 .I libraryNameHint
 239 parameter provides a hint as to where to start the lookup in a prebound
 240 program.  The
 241 .I libraryNameHint
 242 parameter is matched up with the actual library install names with
 243 .IR strstr (3).
 244 .PP
 245 .I NSIsSymbolNameDefinedInImage
 246 is passed a pointer to the mach_header of a mach_header structure of a
 247 dynamic library being used by the program and a symbol name.  This returns
 248 .SM TRUE
 249 or FALSE
 250 based on if the symbol is defined in the specified image or one of the image's
 251 sub-frameworks or sub-umbrellas.
 252 If the program was built with the
 253 .IR ld (1)
 254 .B \-force_flat_namespace
 255 flag or executed with the environment variable
 256 .SM DYLD_FORCE_FLAT_NAMESPACE
 257 set and the pointer to a mach_header structure is not of a bundle loaded with
 258 the
 259 .B NSLINKMODULE_OPTION_PRIVATE
 260 option of
 261 .IR NSLinkModule (3)
 262 then the pointer to a mach_header is ignored and the symbol is looked up in
 263 all the images using the first definition if found.
 264 .PP
 265 The image handle parameter for
 266 .I NSLookupSymbolInImage
 267 and
 268 .I NSIsSymbolNameDefinedInImage
 269 is a pointer to a read-only mach header structure of a dynamic library being
 270 used by the program.  Besides the
 271 .IR NSAddImage (3)
 272 routine the pointer to a mach header can also be obtained by using a link editor
 273 defined symbol as in <mach-o/ldsym.h> and described on the
 274 .IR ld (1)
 275 man page.
 276 Also the
 277 .IR dyld (3)
 278 routine
 279 .IR _dyld_get_image_header (3)
 280 and the mach_header pointer arguments to the call back routines called from
 281 .IR _dyld_register_func_for_add_image (3)
 282 routines can also be used.
 283 .PP
 284 .I NSLookupAndBindSymbol
 285 is passed a global symbol name and looks up and binds the symbol into the
 286 program.
 287 It returns an NSSymbol for the symbol.  If any errors occur the handlers
 288 installed with
 289 .I NSInstallLinkEditErrorHandlers
 290 are called or the default action is taken if there are no handlers.
 291 .PP
 292 .I NSLookupAndBindSymbolWithHint
 293 is the same as
 294 .I NSLookupAndBindSymbol
 295 but the
 296 .I libraryNameHint
 297 parameter provides a hint as to where to start the lookup in a prebound
 298 program.  The
 299 .I libraryNameHint
 300 parameter is matched up with the actual library install names with
 301 .IR strstr (3).
 302 .PP
 303 .I NSLookupSymbolInModule
 304 is passed a symbol name and a module handle and looks up the symbol in that
 305 module.  Currently this is only implemented for module handles returned with
 306 .I NSLinkModule.
 307 If the symbol is found an NSSymbol for the symbol is returned otherwise
 308 .SM NULL
 309 is returned and no error occurs.
 310 .PP
 311 .I NSLookupSymbolInImage
 312 is passed a pointer to a mach_header structure of a dynamic library being used
 313 by the program and a symbol name.  It returns an NSSymbol for the symbol for
 314 defined in the specified image or the image's sub-frameworks or sub-umbrellas.
 315 If the program was built with the
 316 .IR ld (1)
 317 .B \-force_flat_namespace
 318 flag or executed with the environment variable
 319 .SM DYLD_FORCE_FLAT_NAMESPACE
 320 set and the pointer to a mach_header structure is not of a bundle loaded with
 321 the
 322 .B NSLINKMODULE_OPTION_PRIVATE
 323 option of
 324 .IR NSLinkModule (3)
 325 then the pointer to a mach_header is ignored and the symbol is looked up in
 326 all the images using the first definition found.
 327 If the option
 328 .SM NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
 329 is not used if any errors occur the handlers installed with
 330 .I NSInstallLinkEditErrorHandlers
 331 are called or the default action is taken if there are no handlers.
 332 The options of
 333 .I NSLookupSymbolInImage
 334 are as follows:
 335 .TP
 336 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND
 337 Just bind the non-lazy symbols of module that defines the
 338 .I symbolName
 339 and let all lazy symbols in the module be bound on first call.  This should be
 340 used in the normal case for a trusted module expected to bind without any errors
 341 like a module in a system supplied library.
 342 .TP
 343 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW
 344 Bind all the non-lazy and lazy symbols of module that defines the
 345 .I symbolName
 346 and let all dependent symbols in the needed libraries be bound as needed.  This
 347 would be used for a module that might not be expected bind without errors but
 348 links against only system supplied libraries which are expected to bind without
 349 any errors.
 350 .TP
 351 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY
 352 Bind all the symbols of the module that defines the
 353 .I symbolName
 354 and all the dependent symbols of all needed libraries.  This should only be
 355 used for things like signal handlers and linkedit error handlers that can't
 356 bind other symbols when executing to handle the signal or error.
 357 .TP
 358 .B NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
 359 With this option if errors occur while binding the module that defines the
 360 .I symbolName
 361 then the module is automaticly unloaded and
 362 .SM NULL
 363 is returned as the NSSymbol.  To get the error information for why the module
 364 that failed to bind the routine
 365 .I NSLinkEditError
 366 is then used.  It has the same parameters as the link edit error handler (see
 367 below) except all the parameters are pointers in which the information is
 368 returned indirectly.
 369 .PP
 370 .I NSNameOfSymbol
 371 is passed an NSSymbol and returns the name of the symbol.
 372 .PP
 373 .I NSAddressOfSymbol
 374 is passed an NSSymbol and returns the address of the symbol.
 375 .PP
 376 .I NSModuleForSymbol
 377 is passed an NSSymbol and returns the NSModule that symbol is defined in.
 378 .PP
 379 .I NSAddLibrary
 380 is passed the file name of a dynamic shared library to be added to the search
 381 list.  If it is successful it returns
 382 .SM TRUE
 383 else it returns
 384 .SM FALSE.
 385 .PP
 386 .I NSAddLibraryWithSearching
 387 is passed the file name of a dynamic shared library to be added to the search
 388 list the file name passed will be effected by the various
 389 .SM DYLD
 390 environment variables as if this library were linked into the program.  If it
 391 is successful it returns
 392 .SM TRUE
 393 else it returns
 394 .SM FALSE.
 395 .PP
 396 .I NSAddImage
 397 is passed the file name of a dynamic shared library to be added to the search
 398 list of the program if not already loaded.  It returns a pointer to the
 399 mach_header structure of the dynamic library being used by the program.
 400 For best performance of this routine if the library is expected to be already
 401 loaded by the program the
 402 .I image_name
 403 should be a full path name and the same as the name recorded by the program.
 404 If it is a symlink then an
 405 .IR open (2)
 406 and an
 407 .IR fstat (2)
 408 are needed to determine it is the same file as one already loaded.
 409 .PP
 410 If the dynamic shared library has not already been loaded it along with all the
 411 needed dependent libraries are loaded.  With the options parameter
 412 .SM NSADDIMAGE_OPTION_NONE
 413 then any error in loading will cause the linkEdit error handler set by
 414 .IR NSInstallLinkEditErrorHandlers (3)
 415 to be called or the default action of printing the error and exiting to be
 416 taken.  The other options of
 417 .I NSAddImage
 418 are as follows:
 419 .TP
 420 .B NSADDIMAGE_OPTION_RETURN_ON_ERROR
 421 With this option if errors occur while loading this library it is automatically
 422 unloaded and
 423 .SM NULL
 424 is returned.  To get the error information for the library that failed to load
 425 the routine
 426 .I NSLinkEditError
 427 is then used.  It has the same parameters as the link edit error handler (see
 428 below) except all the parameters are pointers in which the information is
 429 returned indirectly.
 430 .TP
 431 .B NSADDIMAGE_OPTION_WITH_SEARCHING
 432 With this option the
 433 .I image_name
 434 passed for the library and all its dependents will be effected by the various
 435 .SM DYLD
 436 environment variables as if this library were linked into the program.
 437 .TP
 438 .B NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED
 439 With this option if the
 440 .I image_name
 441 passed for the library has not already been loaded it is not loaded.  Only if
 442 it has been loaded the pointer to the mach_header will not be
 443 .SM NULL.
 444 .TP
 445 .B NSADDIMAGE_OPTION_MATCH_FILENAME_BY_INSTALLNAME
 446 When this option is specified if a later load of a dependent dynamic library
 447 with a file system path is needed by an image that matches the install name of
 448 the dynamic library loaded with this option, then the dynamic library loaded
 449 with the call to NSAddImage() is used in place of the dependent dynamic library.
 450 .PP
 451 .I NSVersionOfRunTimeLibrary
 452 is passed the install name of a dynamic shared library and returns
 453 current_version number of the library the program is using or \-1 if the
 454 program is not using that library.
 455 .PP
 456 .I NSVersionOfLinkTimeLibrary
 457 is passed the install name of a dynamic shared library and returns the
 458 current_version number of the library the executable program was built
 459 with or \-1 if the program was not built with that library.
 460 .PP
 461 .I _NSGetExecutablePath
 462 copies the path of the executable into the buffer and
 463 returns 0 if the path was successfully copied in the provided buffer. If the
 464 buffer is not large enough, \-1 is returned and the expected buffer size is
 465 copied in *bufsize. Note that _NSGetExecutablePath will return "a path" to
 466 the executable not a "real path" to the executable. That is the path may be
 467 a symbolic link and not the real file. And with deep directories the total
 468 bufsize needed could be more than MAXPATHLEN.
 469 .SH ERROR HANDLING
 470 .PP
 471 .I NSInstallLinkEditErrorHandlers
 472 is passed a pointer to a NSLinkEditErrorHandlers which contains three function
 473 pointers to be used for handling dynamic link errors.  The prototypes for these
 474 functions are given in the following typedef:
 475 .RS
 476 .nf
 477 typedef struct {
 478      void     (*undefined)(const char *symbolName);
 479      NSModule (*multiple)(NSSymbol s, NSModule oldModule, NSModule newModule);
 480      void     (*linkEdit)(NSLinkEditErrors errorClass, int errorNumber,
 481                           const char *fileName, const char *errorString);
 482 } NSLinkEditErrorHandlers;
 483 .fi
 484 .RE
 485 .PP
 486 The first two functions allow the programmer to direct the link edit processing
 487 of undefined symbols and multiply defined symbols.
 488 The third function allows the programmer to catch all other link editor
 489 errors.
 490 .PP
 491 The state when one of the user error functions gets called will be such that no
 492 module will be partially loaded (except in the case of resource errors like out
 493 of memory and other relocation errors).
 494 However, with undefined symbol errors those modules referencing undefined
 495 symbols will be partially bound, and use of such modules can and will crash the
 496 program.
 497 .PP
 498 Great care should be taken when implementing these functions, as the program is
 499 running in a state that will crash if it uses an unbound symbol.
 500 To be safe, these functions should only rely on other things in the same module
 501 or in the executable.
 502 .PP
 503 If the user does not supply these functions, the default will be to write an
 504 error message on to file descriptor 2 (usually stderr) and exit the program
 505 (except for the
 506 .I linkEdit
 507 error handler when the
 508 .I NSLinkEditErrors
 509 is NSLinkEditWarningError, then the default is to do nothing).
 510 .PP
 511 The specified undefined handler may make calls to any of the runtime loading
 512 functions to add modules based on the undefined symbol name.
 513 After dealing with this symbol name successfully (by doing a runtime loading
 514 operation to resolve the undefined reference) the handler simply returns.
 515 If more symbol's names remain undefined the handler will be called repeatedly
 516 with an undefined symbol name.
 517 If the handler can't deal with the symbol it should not return (put up a panel,
 518 abort, etc) and cause the program to exit.
 519 Or it can remove itself as the undefined handler and return which will cause
 520 the default action of printing the undefined symbol names and exiting.
 521 .PP
 522 The specified multiply defined symbol handler is called during the process of
 523 runtime linking and thus it may not call any of the runtime loading functions
 524 as only one set of linking operations can be performed in the task at a time.
 525 The only programmatic functions that can be called from a multiply defined
 526 symbol handler are
 527 .I NSNameOfSymbol,
 528 .I NSNameOfModule
 529 and
 530 .I NSLibraryNameForModule
 531 (provided they are linked into the program before the handler is called).
 532 This handler returns the module handle for the symbol that is to be used for
 533 further link editing, either the
 534 .I oldModule
 535 or the
 536 .I newModule.
 537 It may also record one of the module handles to later take action after the
 538 runtime linking process has completed (for example later unlink the module).
 539 The dynamic link editor updates the references to the symbol if the handler
 540 specifies the new symbol is to be used.
 541 The references which are updated are those that the compiler system generated
 542 as indirect references.  Initialized data and references that were created at
 543 runtime are not effected.
 544 .PP
 545 The specified
 546 .I linkEdit
 547 error handler is called for all other runtime linking errors.
 548 These other runtime linking errors are either warnings or fatal errors.
 549 If the user's link edit error handler function returns
 550 for a fatal error it will cause the program to exit.
 551 There is small set of major error classes which have specific error numbers.
 552 These numbers are be passed in the parameter
 553 .I errorClass.
 554 These major error classes include:
 555 .RS
 556 .nf
 557 typedef enum {
 558         NSLinkEditFileAccessError,
 559         NSLinkEditFileFormatError,
 560         NSLinkEditMachResourceError,
 561         NSLinkEditUnixResourceError,
 562         NSLinkEditOtherError,
 563         NSLinkEditWarningError,
 564         NSLinkEditMultiplyDefinedError,
 565         NSLinkEditUndefinedError
 566 } NSLinkEditErrors;
 567 .fi
 568 .RE
 569 .PP
 570 For the error class NSLinkEditUnixResourceError the
 571 .I errorNumber
 572 parameter will be an
 573 .I errno
 574 value (see
 575 .IR intro (2)).
 576 For the error class NSLinkEditMachResourceError the
 577 .I errorNumber
 578 parameter will be a
 579 .I kern_return_t
 580 value.
 581 For the error class NSLinkEditOtherError the
 582 .I errorNumber
 583 parameter will be a one of the following values:
 584 .RS
 585 .nf
 586 typedef enum {
 587     NSOtherErrorRelocation,
 588     NSOtherErrorLazyBind,
 589     NSOtherErrorIndrLoop,
 590     NSOtherErrorLazyInit,
 591     NSOtherErrorInvalidArgs
 592 } NSOtherErrorNumbers;
 593 .fi
 594 .RE
 595 .PP
 596 For all errors, an attempt to pass an error string will be made.
 597 In some cases such as resource errors, it may not be possible to return a
 598 string.
 599 In those cases the
 600 .I errorString
 601 parameter will be
 602 .sm NULL.
 603 .PP
 604 For file access errors and file format errors, an attempt to return a file name
 605 will also be passed, and if that is not possible the
 606 .I filename
 607 parameter will be
 608 .sm NULL.
 609 .SH ALSO SEE
 610 NSObjectFileImage(3), dyld(3)