dyld-43.tar.gz
[apple/dyld.git] / doc / man / man3 / NSObjectFileImage.3
1 .TH NSObjectFileImage 3 "March 14, 2003" "Apple Computer, Inc."
2 .SH NAME
3 NSObjectFileImage \- programmatic interface for working with Mach-O files
4 .SH SYNOPSIS
5 .nf
6 .PP
7 #include <mach-o/dyld.h>
8 .sp .5
9 extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromFile(
10         const char *pathName,
11         NSObjectFileImage *objectFileImage);
12 .sp .5
13 extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromMemory(
14         void *address,
15         unsigned long size, 
16         NSObjectFileImage *objectFileImage);
17 .sp .5
18 extern NSObjectFileImageReturnCode NSCreateCoreFileImageFromFile(
19         const char *pathName,
20         NSObjectFileImage *objectFileImage);
21 .sp .5
22 extern enum DYLD_BOOL NSDestroyObjectFileImage(
23         NSObjectFileImage objectFileImage);
24 .sp .5
25 extern unsigned long NSSymbolDefinitionCountInObjectFileImage(
26         NSObjectFileImage objectFileImage);
27 .sp .5
28 extern const char * NSSymbolDefinitionNameInObjectFileImage(
29         NSObjectFileImage objectFileImage,
30         unsigned long ordinal);
31 .sp .5
32 extern unsigned long NSSymbolReferenceCountInObjectFileImage(
33         NSObjectFileImage objectFileImage);
34 .sp .5
35 extern const char * NSSymbolReferenceNameInObjectFileImage(
36         NSObjectFileImage objectFileImage,
37         unsigned long ordinal,
38         enum DYLD_BOOL *tentative_definition); /* can be NULL */
39 .sp .5
40 extern enum DYLD_BOOL NSIsSymbolDefinedInObjectFileImage(
41         NSObjectFileImage objectFileImage,
42         const char *symbolName);
43 .sp .5
44 extern void * NSGetSectionDataInObjectFileImage(
45         NSObjectFileImage objectFileImage,
46         const char *segmentName,
47         const char *sectionName,
48         unsigned long* size); /* can be NULL */
49 .sp .5
50 extern enum DYLD_BOOL NSHasModInitObjectFileImage(
51         NSObjectFileImage objectFileImage);
52 .fi
53 .SH DESCRIPTION
54 .PP
55 These routines are the programmatic interface for working with Mach-O files.
56 They bring the Mach-O file into memory and the API allows the file to
57 be inspected or loaded into the program.  On creation of an object file image
58 it is checked to insure it is a valid format and it is compatible with the host
59 machine's cpu architecture.
60 .PP
61 .I NSCreateObjectFileImageFromFile
62 takes the parameter
63 .I pathName
64 as the path name to the file name in the file system and creates and returns
65 an NSObjectFileImage.  Currently only
66 .SM MH_BUNDLE
67 files can be used with
68 .I NSCreateObjectFileImageFromFile
69 which can then be loaded into the program using
70 .IR NSLinkModule (3).
71 If the file is valid an NSObjectFileImage is returned and the return code is
72 NSObjectFileImageSuccess.
73 .I NSCreateObjectFileImageFromMemory
74 does the same as
75 .I NSCreateObjectFileImageFromFile
76 but takes two parameters
77 .I address
78 and
79 .I size
80 for the Mach-O file that is in memory.
81 .PP
82 .I NSCreateCoreFileImageFromFile
83 takes the parameter
84 .I pathName
85 as the path name to a core file in the file system and creates and returns
86 an NSObjectFileImage.  This NSObjectFileImage can then can be loaded into a
87 task with
88 .IR _dyld_debug_task_from_core (3)
89 to determine what libraries were loaded and which modules were linked.
90 .PP
91 .I NSSymbolDefinitionCountInObjectFileImage
92 returns the number of symbol definitions in the NSObjectFileImage. 
93 .PP
94 .I NSSymbolDefinitionNameInObjectFileImage
95 returns the name of the i'th symbol definitions in the NSObjectFileImage. 
96 The 'C' string returned should not be freed.  If the ordinal specified is
97 outside the range [0..NSSymbolDefinitionCountInObjectFileImage], NULL will be
98 returned. 
99 .PP
100 .I NSSymbolReferenceCountInObjectFileImage
101 returns the number of references to undefined symbols the NSObjectFileImage. 
102 .PP
103 .I NSSymbolReferenceNameInObjectFileImage
104 returns the name of the i'th undefined symbol in the NSObjectFileImage. 
105 The 'C' string returned should not be freed.  If the ordinal specified is
106 outside the range [0..NSSymbolReferenceCountInObjectFileImage], NULL will be
107 returned. 
108 .PP
109 .I NSIsSymbolDefinedInObjectFileImage
110 returns TRUE if the specified symbol name has a definition in the
111 NSObjectFileImage. 
112 .PP
113 .I NSGetSectionDataInObjectFileImage
114 returns the address of the data for the named section in the named segment in 
115 the NSObjectFileImage.  If the parameter size is not NULL, the size of the
116 section is returned in size.  If the section cannot be found or a zerofill
117 section, NULL is returned and the size returned is zero.
118 .PP
119 .I NSHasModInitObjectFileImage
120 returns TRUE if the NSObjectFileImage has any module initialization routines
121 and FALSE otherwise.
122
123 .SH RETURN CODES
124 The API's that create NSObjectFileImage's return an NSObjectFileImageReturnCode
125 with the following possible values:
126 .TP
127 .B NSObjectFileImageSuccess
128 Indicates the API was successful and it returned a valid NSObjectFileImage for
129 the host machine's cpu architecture.
130 .TP
131 .B NSObjectFileImageFailure
132 Indicates the API failed and no NSObjectFileImage was returned.  If this is
133 returned an error message is printed on stderr as to the reason for the 
134 failure.
135 .TP
136 .B NSObjectFileImageInappropriateFile
137 Indicates the API failed because the file passed to it was not an appropriate
138 type of object file.
139 .TP
140 .B NSObjectFileImageArch
141 Indicates the API failed because the host machine's cpu architecture could not
142 be found in the file.
143 .TP
144 .B NSObjectFileImageFormat
145 Indicates the API failed because the Mach-O format was malformed.  If this is
146 returned an error message is printed on stderr as to the format error.
147 .TP
148 .B NSObjectFileImageAccess
149 Indicates the API failed because the file could not be accessed.
150 .SH ALSO SEE
151 NSModule(3), dyld(3)