NSObjectFileImage(3)NSObjectFileImage(3)NAMENSObjectFileImage - programmatic interface for working with Mach-O
files
SYNOPSIS
#include <mach-o/dyld.h>
extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromFile(
const char *pathName,
NSObjectFileImage *objectFileImage);
extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromMemory(
void *address,
unsigned long size,
NSObjectFileImage *objectFileImage);
extern NSObjectFileImageReturnCode NSCreateCoreFileImageFromFile(
const char *pathName,
NSObjectFileImage *objectFileImage);
extern enum DYLD_BOOL NSDestroyObjectFileImage(
NSObjectFileImage objectFileImage);
extern unsigned long NSSymbolDefinitionCountInObjectFileImage(
NSObjectFileImage objectFileImage);
extern const char * NSSymbolDefinitionNameInObjectFileImage(
NSObjectFileImage objectFileImage,
unsigned long ordinal);
extern unsigned long NSSymbolReferenceCountInObjectFileImage(
NSObjectFileImage objectFileImage);
extern const char * NSSymbolReferenceNameInObjectFileImage(
NSObjectFileImage objectFileImage,
unsigned long ordinal,
enum DYLD_BOOL *tentative_definition); /* can be NULL */
extern enum DYLD_BOOL NSIsSymbolDefinedInObjectFileImage(
NSObjectFileImage objectFileImage,
const char *symbolName);
extern void * NSGetSectionDataInObjectFileImage(
NSObjectFileImage objectFileImage,
const char *segmentName,
const char *sectionName,
unsigned long* size); /* can be NULL */
extern enum DYLD_BOOL NSHasModInitObjectFileImage(
NSObjectFileImage objectFileImage);
DESCRIPTION
These routines are the programmatic interface for working with Mach-O
files. They bring the Mach-O file into memory and the API allows the
file to be inspected or loaded into the program. On creation of an
object file image it is checked to insure it is a valid format and it
is compatible with the host machine's cpu architecture.
NSCreateObjectFileImageFromFile takes the parameter pathName as the
path name to the file name in the file system and creates and returns
an NSObjectFileImage. Currently only MH_BUNDLE files can be used with
NSCreateObjectFileImageFromFile which can then be loaded into the pro‐
gram using NSLinkModule(3). If the file is valid an NSObjectFileImage
is returned and the return code is NSObjectFileImageSuccess. NSCre‐
ateObjectFileImageFromMemory does the same as NSCreateObjectFileImage‐
FromFile but takes two parameters address and size for the Mach-O file
that is in memory.
NSCreateCoreFileImageFromFile takes the parameter pathName as the path
name to a core file in the file system and creates and returns an NSOb‐
jectFileImage. This NSObjectFileImage can then can be loaded into a
task with _dyld_debug_task_from_core(3) to determine what libraries
were loaded and which modules were linked.
NSSymbolDefinitionCountInObjectFileImage returns the number of symbol
definitions in the NSObjectFileImage.
NSSymbolDefinitionNameInObjectFileImage returns the name of the i'th
symbol definitions in the NSObjectFileImage. The 'C' string returned
should not be freed. If the ordinal specified is outside the range
[0..NSSymbolDefinitionCountInObjectFileImage], NULL will be returned.
NSSymbolReferenceCountInObjectFileImage returns the number of refer‐
ences to undefined symbols the NSObjectFileImage.
NSSymbolReferenceNameInObjectFileImage returns the name of the i'th
undefined symbol in the NSObjectFileImage. The 'C' string returned
should not be freed. If the ordinal specified is outside the range
[0..NSSymbolReferenceCountInObjectFileImage], NULL will be returned.
NSIsSymbolDefinedInObjectFileImage returns TRUE if the specified symbol
name has a definition in the NSObjectFileImage.
NSGetSectionDataInObjectFileImage returns the address of the data for
the named section in the named segment in the NSObjectFileImage. If
the parameter size is not NULL, the size of the section is returned in
size. If the section cannot be found or a zerofill section, NULL is
returned and the size returned is zero.
NSHasModInitObjectFileImage returns TRUE if the NSObjectFileImage has
any module initialization routines and FALSE otherwise.
RETURN CODES
The API's that create NSObjectFileImage's return an NSObjectFileIm‐
ageReturnCode with the following possible values:
NSObjectFileImageSuccess
Indicates the API was successful and it returned a valid NSOb‐
jectFileImage for the host machine's cpu architecture.
NSObjectFileImageFailure
Indicates the API failed and no NSObjectFileImage was returned.
If this is returned an error message is printed on stderr as to
the reason for the failure.
NSObjectFileImageInappropriateFile
Indicates the API failed because the file passed to it was not
an appropriate type of object file.
NSObjectFileImageArch
Indicates the API failed because the host machine's cpu archi‐
tecture could not be found in the file.
NSObjectFileImageFormat
Indicates the API failed because the Mach-O format was mal‐
formed. If this is returned an error message is printed on
stderr as to the format error.
NSObjectFileImageAccess
Indicates the API failed because the file could not be accessed.
ALSO SEENSModule(3), dyld(3)Apple Computer, Inc. March 14, 2003 NSObjectFileImage(3)