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)