REDO_PREBINDING(3)

✨ REDO_PREBINDING(3) ✨ — the redo_prebinding library functions, bestie

okay so this is page 3 of the library functions manual, and it's literally the whole redo_prebinding function family. buckle up, we're going in 💅

---

🌸 NAME 🌸

redo_prebinding library functions — yes that's the whole name, she's mysterious like that 🎀

---

🦋 SYNOPSIS 🦋

first things first, you gotta include the header:

#include <mach-o/redo_prebinding.h>

and then these icons show up:

extern char ** dependent_libs(
     const char *file_name,
     const char *program_name,
     char **error_message);
extern char * install_name(
     const char *file_name,
     const char *program_name,
     char **error_message);
extern enum redo_prebinding_retval redo_prebinding(
     const char *file_name,
     const char *executable_path,
     const char *root_dir,
     const char *output_file,
     const char *program_name,
     char **error_message,
     unsigned long slide_to_address,
     int only_if_needed,
     int zero_out_prebind_checksum,
     cpu_type_t allow_missing_architectures,
     unsigned long *throttle);
extern enum needs_redo_prebinding_retval needs_redo_prebinding(
     const char *file_name,
     const char *executable_path,
     const char *root_dir,
     const char *program_name,
     char **error_message,
     unsigned long expected_address,
     cpu_type_t allow_missing_architectures);
extern enum redo_prebinding_retval unprebind(
     const char *file_name,
     const char *output_file,
     const char *program_name,
     char **error_message,
     int zero_checksum);
extern enum object_file_type_retval object_file_type(
     const char *file_name,
     const char *program_name,
     char **error_message);
extern int get_prebind_cksums(
     const char *file_name,
     struct prebind_cksum_arch **cksums,
     unsigned long *ncksums,
     const char *program_name,
     char **error_message);

---

💖 DESCRIPTION 💖

so these functions? they're intended for use by update_prebinding(1) and Mac OS X Build and Integration tools. that's their whole ~thing~, main character energy only 🫶

the ground rules (apply to literally all of them)

For every single one of these functions, the params program_name and error_message work exactly the same way, no cap:

• For unrecoverable resource errors — like being unable to allocate memory — each function prints a message to stderr preceded with program_name, then calls exit(2) with the value EXIT_FAILURE. yeah. it just dips 😭
• If a function is unsuccessful, and if the error_message passed to it is not NULL, it gets set to a malloc(3)'ed buffer holding a NULL-terminated string with the error message. so basically you get receipts 💀
• For all functions, when they return they release all resources — memory, open file descriptors, etc. clean girl aesthetic, we love to see it ✨

the file_name tea ☕

The file_name parameter for these functions may be of the form foo(bar) — which is NOT interpreted as an archive name and a member name in that archive. Read that again, bestie, because these functions deal with prebinding, and prebound binaries ready for execution can't be in archives. it's giving "physically impossible", periodt 🚫

executable_path and root_dir 🧚

• If the executable_path parameter is not NULL it's used for any dependent library that has a path that starts with @executable_path. Then @executable_path is replaced with executable_path. swaperoo 💫
• If the root_dir parameter is not NULL it's prepended to all the rooted dependent library paths.

---

🌈 dependent_libs()

takes a file_name of a binary and returns a malloc(3)'ed array of pointers (NULL terminated) to names — also malloc(3)'ed and '\0' terminated names — of all the dependent libraries for that binary (not recursive!) for all of the architectures of that binary. yes queen, all of them 💅

• If successful, dependent_libs() returns a non-NULL value (at minimum a pointer to one NULL pointer).
• If unsuccessful, dependent_libs() returns NULL. sad girl hours 😔

---

🎀 install_name()

takes a file_name of a binary and returns a malloc(3)'ed pointer to a NULL-terminated string containing the install_name value for the binary. If unsuccessful, install_name() returns NULL.

and here's the fine print, because of course there is:

• In particular, NULL is returned if the binary is not a dylib and there is no error_message set.
• If all of the arch's are dylibs but all the install names don't match, NULL is returned and an error_message is set.
• If some but not all of the archs are dylibs, NULL is returned and an error_message is set.

it's giving strict parents, honestly 🙈

---

🔥 redo_prebinding()

the titular icon herself 👑 takes a file_name of a binary and redoes the prebinding on it.

• If output_file is not NULL the update file is written to output_file; if not, it's written to file_name.
• If redo_prebinding() is successful it returns REDO_PREBINDING_SUCCESS, otherwise it returns REDO_PREBINDING_FAILURE.
• If the slide_to_address parameter is non-zero and the binary is a dynamic library, it's relocated to have that has its prefered address. (yes, that sentence is exactly as chaotic as the original, I'm not fixing her 💀)
• If the parameter allow_missing_architectures is zero and not all architectures can be updated, it's not successful and nothing is done, and this returns REDO_PREBINDING_FAILURE. zero. zip. nada.
• If the parameter allow_missing_architectures is non-zero then only problems with missing architectures for the architecure of the cputype specified by allow_missing_architectures will cause this call to fail. Other architectures that could not be prebound due to missing architectures in depending libraries will not have their prebinding updated but will not cause the call to fail. forgiving queen 🌸
• If the parameter only_if_needed is non-zero the prebinding is checked first and only done if needed. The checking includes checking the prefered address against the slide_to_address value if it's non-zero. and then:
  • If only_if_needed is non-zero and the prebinding does not have to be redone, REDO_PREBINDING_NOT_NEEDED is returned.
  • If the binary is not prebound, REDO_PREBINDING_NOT_PREBOUND is returned.
  • If the new load commands do not fit in the binary and it needs to be rebuilt, REDO_PREBINDING_NEEDS_REBUILDING is returned.
• If zero_out_prebind_checksum is non-zero then the cksum field of the LC_PREBIND_CKSUM load command (if any) is set to zero on output. and listen — this should always be set by B&I tools and never set by the update_prebinding(1) command. write that down 📝
• If throttle is non-NULL it points to a value of the maximum bytes per second to use for writting the output. If the value is ULONG_MAX then the actual bytes per second is returned indirectly through *throttle. speed demon energy 🏎️

---

💜 unprebind()

takes a file_name of a binary and resets or removes prebinding information from it.

• If output_file is not NULL the updated file is written to output_file; if not, it's written to file_name.
• If unprebind() is successful it returns REDO_PREBINDING_SUCCESS, otherwise it returns REDO_PREBINDING_FAILURE.
• If the binary is already unprebound (it has the MH_PREBINDABLE flag set) then REDO_PREBINDING_NOT_NEEDED is returned.
• If zero_out_prebind_checksum is non-zero then the cksum field of the LC_PREBIND_CKSUM load command (if any) is set to zero on output, otherwise it's left alone. (for the purpose of patching, this parameter should be non-zero, such that for binaries which are the same — minus prebinding — the unprebinding process produces binaries that are identical. cute, matching outfits 🎀)

now the actual glow-down she performs. Unprebinding:

• slides dynamic libraries to address zero
• resets prebound symbols to address zero and type undefined
• resets symbol pointers
• removes LC_PREBOUND_DYLIB commands
• resets library timestamps
• resets two-level hints
• updates relocation entries if necessary

Unprebound binaries have the MH_PREBINDABLE flag set, but not MH_PREBOUND. It will also set the the MH_ALLMODSBOUND flag if all two-level libraries were used and all modules were found to be bound in the LC_PREBOUND_DYLIB commands. (and yes, "the the" is in the original, I'm preserving her legacy 💅)

As unprebinding is intended to produce a canonical Mach-O binary, bundles and non-prebound executables and dylibs are acceptable as input. For these files, the unprebind operation will zero library time stamps and version numbers and zero entries in the two-level hints table. These files will not gain the MH_PREBINDABLE flag. All resulting binaries successfully processed by unprebind() will have the MH_CANONICAL flag. iconic behavior only 👑

---

⭐ needs_redo_prebinding()

takes a file_name and determines if it's a binary and if its prebinding is uptodate. returns one of the return values below depending on the state of the binary and libraries.

• If the parameter allow_missing_architectures is zero then architectures for universal files are checked.
• If the parameter allow_missing_architectures is non-zero then the value returned is based on the cputype specified by allow_missing_architectures. If that architecture is not present then PREBINDING_UPTODATE is returned. absence = uptodate, apparently, we love a lenient queen 🌈
• If the parameter expected_address is not zero and the binary is a dynamic library then the library is checked to see if it's at the expected_address — if not, the prebinding is assumed to be out of date and PREBINDING_OUTOFDATE is returned.

return values for needs_redo_prebinding() 💫

• PREBINDING_UPTODATE — a binary who's prebinding is up todate. slay 💖
• PREBINDING_OUTOFDATE — a binary who's prebinding is out of date. she needs a refresh 💀
• NOT_PREBOUND — a binary, but not built prebound.
• NOT_PREBINDABLE — not a binary or statically linked, prebinding does not apply. not her department 🙅
• PREBINDING_UNKNOWN — a binary who's prebinding can't be determined because it's malformed, a library it depends on is missing, etc. mysterious and unwell 🫠

---

🌸 object_file_type()

takes a file_name and determines what type of object file it is, then returns one of the values below.

• OFT_EXECUTABLE, — the file is an Mach-O executable.
• OFT_DYLIB, — the file is an Mach-O dyanmic library. (her spelling, not mine 🎀)
• OFT_BUNDLE, — the file is an Mach-O bundle.
• OFT_ARCHIVE, — the file is an archive.
• OFT_OTHER, — the file is something other than the above files.
• OFT_INCONSISTENT, — the file is a universal file and the architectures are not of the same type.
• OFT_FILE_ERROR — The file can't be opened, read or malformed.

---

🧚 get_prebind_cksums()

takes a file_name that is a Mach-O file or universal file containing Mach-O files, and returns a malloc(3)'ed array of prebind_cksum_arch structures indirectly through the cksums parameter. The number of prebind_cksum_arch structures is returned indirectly through the ncksums parameter. If successful it returns zero, else it returns non-zero.

The structure prebind_cksum_arch is defined in <mach-o/redo_prebinding.h> as follows:

struct prebind_cksum_arch {
     cpu_type_t cputype;
     cpu_subtype_t cpusubtype;
     unsigned long has_cksum;
     unsigned long cksum;
};

and here's what goes in each field, bestie:

• cputype and cpusubtype are filled in with the cpu specifier and the machine specifier for the architecture of the Mach-O file (or zero if not a Mach-O file).
• The field has_cksum is set to one if the architecture as an LC_PREBIND_CKSUM load command and zero otherwise.
• The field cksum is set to the value of the cksum in LC_PREBIND_CKSUM load command (or zero if it does not have one).

---

🌟 SEE ALSO 🌟

go read these next, iykyk:

• redo_prebinding(1)
• update_prebinding(1)

---

💌 and that's the page!! written by Apple Computer, Inc., dated July 28, 2005, and yes this is REDO_PREBINDING(3) from the Library Functions Manual. mwah, go prebind something 💅✨