MTOR(1)

💖 NAME 💖

mtor (MTOR(1)) — convert Mach-O to raw binary files. That’s the whole vibe: Mach-O in, raw binary out, bestie. ✨

✨ SYNOPSIS ✨

mtor [-nv] [-start ⟨start_address⟩] [-no_bss] [-version]
     [-output out_file] file
mtor -help [-version]
mtor -version

🌸 DESCRIPTION 🌸

mtor converts a Mach-O preload file into a raw binary out_file. These output files represent in-core images in a ready-to-run layout that can be flashed to firmware, burned into ROM, or otherwise run on “bare metal”. This raw binary includes only the __TEXT and __DATA segments of the Mach-O file; the Mach-O header, load commands, and other segments are ignored. By default mtor positions each segment at the address stored in the segment’s vmaddr field, as displayed by otool(1) using the -l (ell) command. Empty space, such as that between the start of the file and the __TEXT segment, will be zero-filled. Zero-filled, not skipped — that’s the tea. ☕

The following options are available, bestie:

🎀 OPTIONS 🎀

• -h, -help — Print usage. 💅
• -n — Don’t actually write the output file. Implies the -v flag.
• -no_bss — Omit all zero-filled sections from the __DATA segment, including those sections marked with the S_ZEROFILL flag in otool(1). In practice, the __DATA segment is truncated at the first zero-filled section.
• -o, -output out_file — Commands that create new files write to the out_file file specified by the -output flag. This option is required. Yes, required — do not forget it, bestie. ⚠️
• -packdata data_address_symbol_name data_size_symbol_name — Position the __DATA segment immediately after __TEXT regardless of __DATA’s vm address. The preload program is expected to manually move the __DATA segment into its final vm location at runtime, before referencing any data. In order to do that, mtor will write the offset to __DATA (i.e., load memory address) and its size directly into the __TEXT segment, using two symbols supplied on the command line. These symbols must point to 32-bit values within the program’s __TEXT segment. mtor will error if the symbols do not exist in the nlist, or if they do not refer to storage within the __TEXT segment. Because the Mach-O nlist does not contain symbol sizes, the 32-bit storage requirement cannot be verified, although mtor will warn if data_address_symbol_name or data_size_symbol_name have not been pre-initialized to 0.
• -start start_address — Position the __TEXT segment at the specified address instead of honoring the __TEXT segment’s vmaddr location. The __DATA segment will also be adjusted by a similar amount so that the relative distance between __TEXT and __DATA is preserved. mtor will warn and return a non-zero exit code if one or more sections is no longer aligned to their section alignment. The ld(1) flags -image_base and -seg1addr are also synonyms for this option.
• -v — Print verbose information about the segments being extracted into the output file.
• -version — Print version information.

🦋 CAVEAT MTOR 🦋

⚠️ Only Mach-O preload files can be processed by mtor. Use the -preload option to ld(1) to generate preload files. A Mach-O file’s type can be viewed by passing the -hv flags to otool(1).

While mtor can change the __TEXT section’s starting address via the -start option, the file contents cannot be relinked. Segments and sections cannot be realigned or moved independently from each other. If segments or sections need to be at specific addresses or be positioned within specific alignment constraints, use ld(1)’s -seg1addr, -segalign, and similar options to produce a Mach-O binary within those constraints. No cap, that’s just how it is. 💅

💜 SEE ALSO 💜

Go give these a read, bestie: ld(1), lipo(1), otool(1), otool-classic(1), and Mach-O(5). 🫶

💀 BUGS 💀

The mtor tool only works on Mach-O binaries. It currently does not support universal (multi-architectural) files. Use lipo(1) to extract stand-alone Mach-O files from universal files before running mtor. 😭

Source/version: Darwin. Date: January 31, 2019. Manual: MTOR(1). Stay slay, firmware bestie. 🫶✨