NSObjectFileImage(3)

✨ NAME ✨

okay so bestie, this page is NSObjectFileImage(3) from the Library Functions Manual, and it's literally the programmatic interface for working with Mach-O files. no cap. 💅

🦋 SYNOPSIS 🦋

bestie, here's the exact include + declarations vibe, character for character:

       #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 💖

okay so these routines are the programmatic interface for working with Mach-O files. they bring the Mach-O file into memory, and the API lets the file be inspected or loaded into the program. when an object file image is created, it gets checked to make sure it's a valid format and compatible with the host machine's cpu architecture. slay. ✨

• 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 program using NSLinkModule(3). if the file is valid, an NSObjectFileImage is returned and the return code is NSObjectFileImageSuccess. 💅
• NSCreateObjectFileImageFromMemory — does the same as NSCreateObjectFileImageFromFile 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 NSObjectFileImage. this NSObjectFileImage can then 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 references to undefined symbols the NSObjectFileImage has. 🌸
• 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 NSObjectFileImageReturnCode with the following possible values, bestie:

• NSObjectFileImageSuccess — indicates the API was successful and it returned a valid NSObjectFileImage 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 architecture could not be found in the file. 💀
• NSObjectFileImageFormat — indicates the API failed because the Mach-O format was malformed. 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 SEE 👀

• NSModule(3)
• dyld(3)

💖 cute sign-off tea: this page comes from Apple Computer, Inc., dated March 14, 2003, and it's the NSObjectFileImage(3) manual page — periodt. 🫶