1 .TH NSModule 3 "October 6, 2003" "Apple Computer, Inc."
3 NSModule \- programmatic interface for working with modules and symbols
7 #include <mach-o/dyld.h>
9 typedef void * NSModule;
11 extern NSModule NSLinkModule(
12 NSObjectFileImage objectFileImage,
13 const char *moduleName,
14 unsigned long options);
16 extern enum DYLD_BOOL NSUnLinkModule(
18 unsigned long options);
20 extern const char * NSNameOfModule(
23 extern const char * NSLibraryNameForModule(
26 typedef void * NSSymbol;
28 extern enum DYLD_BOOL NSIsSymbolNameDefined(
29 const char *symbolName);
31 extern enum DYLD_BOOL NSIsSymbolNameDefinedWithHint(
32 const char *symbolName
33 const char *libraryNameHint);
35 extern enum DYLD_BOOL NSIsSymbolNameDefinedInImage(
36 const struct mach_header *image,
37 const char *symbolName);
39 extern NSSymbol NSLookupAndBindSymbol(
40 const char *symbolName);
42 extern NSSymbol NSLookupAndBindSymbolWithHint(
43 const char *symbolName
44 const char *libraryNameHint);
46 extern NSSymbol NSLookupSymbolInModule(
48 const char *symbolName);
50 extern NSSymbol NSLookupSymbolInImage(
51 const struct mach_header *image,
52 const char *symbolName,
53 unsigned long options);
55 extern const char * NSNameOfSymbol(
58 extern void * NSAddressOfSymbol(
61 extern NSModule NSModuleForSymbol(
64 extern enum DYLD_BOOL NSAddLibrary(
65 const char *pathName);
67 extern enum DYLD_BOOL NSAddLibraryWithSearching(
68 const char *pathName);
70 extern const struct mach_header * NSAddImage(
71 const char *image_name,
72 unsigned long options);
74 extern long NSVersionOfRunTimeLibrary(
75 const char *libraryName);
77 extern long NSVersionOfLinkTimeLibrary(
78 const char *libraryName);
80 extern int _NSGetExecutablePath(
82 unsigned long *bufsize)
84 extern void NSInstallLinkEditErrorHandlers(
85 NSLinkEditErrorHandlers *handlers);
87 extern void NSLinkEditError(
90 const char **fileName,
91 const char **errorString);
96 extern NSModule NSReplaceModule(
97 NSModule moduleToReplace,
98 NSObjectFileImage newObjectFileImage,
99 unsigned long options);
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.
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.
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)
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.
125 links the specified object file image into the program and returns the module
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
131 can be used with the module handle and to do things like report errors.
134 to be able to debug your module, when calling
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.
141 can have a set of options or'ed together. The options for
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.
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.
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.
163 .B NSLINKMODULE_OPTION_RETURN_ON_ERROR
164 With this option if errors occur while binding this module it is automaticly
167 is returned as the module handle. To get the error information for the module
168 that failed to load the routine
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
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.
178 .B NSLINKMODULE_OPTION_TRAILING_PHYS_NAME
179 With this option the parameter,
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.
186 unlinks the specified module handle from the program. Currently the
187 implementation is limited to only allow modules linked with
189 to be unlinked. The parameter,
191 can have a set of options or'ed together. The options for
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.
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.
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
213 is passed a module handle and returns the name of the module. If the module
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
225 .I NSIsSymbolNameDefined
226 is passed a global symbol name (global 'C' symbols names are preceded with an
227 underbar '\_') and returns
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.
234 .I NSIsSymbolNameDefinedWithHint
236 .I NSIsSymbolNameDefined
239 parameter provides a hint as to where to start the lookup in a prebound
242 parameter is matched up with the actual library install names with
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
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
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
259 .B NSLINKMODULE_OPTION_PRIVATE
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.
265 The image handle parameter for
266 .I NSLookupSymbolInImage
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
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
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.
284 .I NSLookupAndBindSymbol
285 is passed a global symbol name and looks up and binds the symbol into the
287 It returns an NSSymbol for the symbol. If any errors occur the handlers
289 .I NSInstallLinkEditErrorHandlers
290 are called or the default action is taken if there are no handlers.
292 .I NSLookupAndBindSymbolWithHint
294 .I NSLookupAndBindSymbol
297 parameter provides a hint as to where to start the lookup in a prebound
300 parameter is matched up with the actual library install names with
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
307 If the symbol is found an NSSymbol for the symbol is returned otherwise
309 is returned and no error occurs.
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
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
322 .B NSLINKMODULE_OPTION_PRIVATE
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.
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.
333 .I NSLookupSymbolInImage
336 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND
337 Just bind the non-lazy symbols of module that defines the
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.
343 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW
344 Bind all the non-lazy and lazy symbols of module that defines the
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
351 .B NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY
352 Bind all the symbols of the module that defines the
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.
358 .B NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR
359 With this option if errors occur while binding the module that defines the
361 then the module is automaticly unloaded and
363 is returned as the NSSymbol. To get the error information for why the module
364 that failed to bind the routine
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
371 is passed an NSSymbol and returns the name of the symbol.
374 is passed an NSSymbol and returns the address of the symbol.
377 is passed an NSSymbol and returns the NSModule that symbol is defined in.
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
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
390 environment variables as if this library were linked into the program. If it
391 is successful it returns
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
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
408 are needed to determine it is the same file as one already loaded.
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
420 .B NSADDIMAGE_OPTION_RETURN_ON_ERROR
421 With this option if errors occur while loading this library it is automatically
424 is returned. To get the error information for the library that failed to load
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
431 .B NSADDIMAGE_OPTION_WITH_SEARCHING
434 passed for the library and all its dependents will be effected by the various
436 environment variables as if this library were linked into the program.
438 .B NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED
439 With this option if the
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
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.
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.
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.
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.
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:
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;
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
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
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.
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
507 error handler when the
509 is NSLinkEditWarningError, then the default is to do nothing).
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.
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
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
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.
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
554 These major error classes include:
558 NSLinkEditFileAccessError,
559 NSLinkEditFileFormatError,
560 NSLinkEditMachResourceError,
561 NSLinkEditUnixResourceError,
562 NSLinkEditOtherError,
563 NSLinkEditWarningError,
564 NSLinkEditMultiplyDefinedError,
565 NSLinkEditUndefinedError
570 For the error class NSLinkEditUnixResourceError the
576 For the error class NSLinkEditMachResourceError the
581 For the error class NSLinkEditOtherError the
583 parameter will be a one of the following values:
587 NSOtherErrorRelocation,
588 NSOtherErrorLazyBind,
589 NSOtherErrorIndrLoop,
590 NSOtherErrorLazyInit,
591 NSOtherErrorInvalidArgs
592 } NSOtherErrorNumbers;
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
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
610 NSObjectFileImage(3), dyld(3)