[apple/dyld.git] / doc / man / man3 / NSModule.3
1 .TH NSModule 3 "October 6, 2003" "Apple Computer, Inc."
3 NSModule \- programmatic interface for working with modules and symbols
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
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
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
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
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
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
175 With this option the module init routines are not called.  This is only useful
176 to the fix-and-continue implementation.
177 .TP 
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
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
203 With this option the memory for the module is not deallocated allowing pointers
204 into the module to still be valid.
205 .TP
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
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
257 set and the pointer to a mach_header structure is not of a bundle loaded with
258 the 
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
320 set and the pointer to a mach_header structure is not of a bundle loaded with
321 the 
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
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
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
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
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
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
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
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
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
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
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.
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.
610 NSObjectFileImage(3), dyld(3)