redo_prebinding.3   [plain text]


.TH REDO_PREBINDING 3 "July 28, 2005" "Apple Computer, Inc."
.SH NAME
redo_prebinding library functions
.SH SYNOPSIS
.nf
.PP
.ft B
#include <mach-o/redo_prebinding.h>
.sp .5
extern char ** dependent_libs(
	const char *file_name,
	const char *program_name,
	char **error_message);
.sp .5
extern char * install_name(
	const char *file_name,
	const char *program_name,
	char **error_message);
.sp .5
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);
.sp .5
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);
.sp .5
extern enum redo_prebinding_retval unprebind(
	const char *file_name,
	const char *output_file,
	const char *program_name,
	char **error_message,
	int zero_checksum);
.sp .5
extern enum object_file_type_retval object_file_type(
	const char *file_name,
	const char *program_name,
	char **error_message);
.sp .5
extern int get_prebind_cksums(
	const char *file_name,
	struct prebind_cksum_arch **cksums,
	unsigned long *ncksums,
	const char *program_name,
	char **error_message);
.SH DESCRIPTION
These functions are intended for use by
.IR update_prebinding (1)
and Mac OS X Build and Integration tools.
.PP
For all of these functions in the parameters
.I program_name
and
.I  error_message
are used the same.  For unrecoverable resource errors like being unable to
allocate memory each function prints a message to stderr precede with
.I program_name
then calls
.IR exit (2)
with the value
.SM EXIT_FAILURE.
If a function is unsuccessful and if
.I error_message
pass to it is not
.SM NULL it is set to a
.IR malloc (3)'ed
buffer with a
.SM NULL
terminated string with the error message.  For all functions
when they return they release all resources (memory, open file descriptors,
etc). 
.PP
The file_name parameter for these functions may be of the form
.I foo(bar)
which is NOT interpreted as an archive name and a member name in that archive.
As these functions deal with prebinding and prebound binaries ready for
execution can't be in archives.
.PP
If the
.I executable_path
parameter for these functions is not
.SM NULL
it is used for any dependent library has a path that starts with
.I @executable_path.
Then
.I @executable_path
is replaced with
.I executable_path. 
.PP
If the
.I root_dir
parameter is not
.SM NULL
it is prepended to all the rooted dependent library paths. 
.PP
.IR dependent_libs ()
takes a
.I file_name
of a binary and returns a
.IR malloc (3)'ed
array of pointers (NULL terminated) to names (also
.IR 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.  If successful
.I dependent_libs()
returns a non
.SM NULL
value (at minimum a pointer to one
.SM NULL
pointer). If unsuccessful
.I dependent_libs returns
NULL.
.PP
.IR install_name ()
takes a
.I file_name
of a binary and returns a malloc(3)'ed pointer to a
.SM NULL
terminated string containing the install_name value for the binary. If
unsuccessful install_name() returns
.SM NULL.
 In particular,
.SM NULL
is returned if the binary is not a dylib and there is no error_message
set.  If the all of the arch's are dylibs but all the install names don't
match
.SM NULL
is returned and a error_message is set.  If some but not all of
the archs are dylibs
.SM NULL
is returned and a error_message is set.
.PP
.IR redo_prebinding ()
takes a
.I file_name
of a binary and redoes the prebinding on it.  If
.I output_file
is not
.SM NULL
the update file is written to
.I output_file,
if not it is written to
.I file_name.
If
.IR redo_prebinding ()
is successful it returns
.SM REDO_PREBINDING_SUCCESS
otherwise it returns
.SM REDO_PREBINDING_FAILURE.
If the 
.I slide_to_address
parameter is non-zero and the binary is a dynamic library it is relocated to
have that has its prefered address.
If the parameter
.I allow_missing_architectures
is zero and not all architectures can be updated it is not successful and
nothing is done and this returns
.SM REDO_PREBINDING_FAILURE.
If the parameter
.I allow_missing_architectures
is non-zero then only problems with missing architectures for the architecure
of the cputype specified by 
.I 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.
If the parameter
.I 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
.I slide_to_address
value if it is non-zero.  If
.I only_if_needed
is non-zero and the prebinding does not have to be redone
.SM REDO_PREBINDING_NOT_NEEDED
is returned, if the binary is not prebound
.SM REDO_PREBINDING_NOT_PREBOUND
is returned and if the new load commands do not fit in the binary and it needs
to be rebuilt
.SM REDO_PREBINDING_NEEDS_REBUILDING
is returned.  If
.I zero_out_prebind_checksum
is non-zero then the cksum field of the
.SM LC_PREBIND_CKSUM
load command (if any) is set to zero on output (this should always be set by B&I
tools and never set by the
.IR update_prebinding (1)
command).
If
.I 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.
.PP
.IR unprebind ()
takes a
.I file_name
of a binary and resets or removes prebinding information from it.  If
.I output_file
is not
.SM NULL
the updated file is written to
.I output_file,
if not it is written to
.I file_name.
If
.IR unprebind ()
is successful it returns
.SM REDO_PREBINDING_SUCCESS
otherwise it returns
.SM REDO_PREBINDING_FAILURE.
If the binary is already unprebound (it has the 
.SM MH_PREBINDABLE
flag set) then 
.SM REDO_PREBINDING_NOT_NEEDED
is returned.  If
.I zero_out_prebind_checksum
is non-zero then the cksum field of the
.SM LC_PREBIND_CKSUM
load command (if any) is set to zero on output, otherwise it is 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).
Unprebinding slides dynamic libraries to address zero, resets prebound symbols
to address zero and type undefined, resets symbol pointers, removes 
.SM LC_PREBOUND_DYLIB
commands, resets library timestamps, resets two-level hints, and updates 
relocation entries if necessary.  Unprebound binaries have the 
.SM MH_PREBINDABLE
flag set, but not 
.SM MH_PREBOUND.
It will also set the the
.SM MH_ALLMODSBOUND
flag if all two-level libraries were used and all modules were found to be
bound in the
.SM LC_PREBOUND_DYLIB
commands.  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
.SM MH_PREBINDABLE
flag.  All resulting binaries successfully processed by unprebind() will have
the MH_CANONICAL flag.
.PP
.IR needs_redo_prebinding()
takes a
.I file_name
and determines if it is a binary and if its prebinding is uptodate.  It returns
one of the return values below depending on the state of the binary and
libraries.  If the parameter
.I allow_missing_architectures
is zero then architectures for universal files are checked.  If the parameter
.I allow_missing_architectures
is non-zero then the value returned is based on the cputype specified by
.I allow_missing_architectures.
If that architecture is not present then
.SM PREBINDING_UPTODATE
is returned.  If the parameter
.I expected_address
is not zero and the binary is a dynamic library then the library is checked to
see if it is at the expected_address if not the prebinding is assumed to be out
of date and
.SM PREBINDING_OUTOFDATE
is returned.
.PP
Return values for
.I needs_redo_prebinding():
.TP
.B PREBINDING_UPTODATE
a binary who's prebinding is up todate.
.TP
.B PREBINDING_OUTOFDATE
a binary who's prebinding is out of date.
.TP
.B NOT_PREBOUND
a binary, but not built prebound.
.TP
.B NOT_PREBINDABLE
not a binary or statically linked, prebinding does not apply.
.TP
.B PREBINDING_UNKNOWN
a binary who's prebinding can't be determined because it is malformed, a
library it depends on is missing, etc.
.PP
.IR object_file_type ()
takes a file_name and determines what type of object file it is and returns
on the the values below.
.TP
.B OFT_EXECUTABLE,
the file is an Mach-O executable.
.TP
.B OFT_DYLIB,
the file is an Mach-O dyanmic library.
.TP
.B OFT_BUNDLE,
the file is an Mach-O bundle.
.TP
.B OFT_ARCHIVE,
the file is an archive.
.TP
.B OFT_OTHER,
the file is something other than the above files.
.TP
.B OFT_INCONSISTENT,
the file is a universal file and the architectures are not of the same type.
.TP
.B OFT_FILE_ERROR
The file can't be opened, read or malformed
.PP
.IR get_prebind_cksums ()
takes a file_name that is a Mach-O file or universal file containing Mach-O
files and returns a
.IR malloc (3)'ed
array of
.I prebind_cksum_arch
structures indirectly through the
.I cksums
parameter. The number of
.I prebind_cksum_arch
structures is returned indirectly through the
.I ncksums
parameter.  If successful it returns zero else it returns non-zero.
.PP
The structure
.I prebind_cksum_arch
is defined in
.I <mach-o/redo_prebinding.h>
as follows:
.nf
	struct prebind_cksum_arch {
		cpu_type_t cputype;
		cpu_subtype_t cpusubtype;
		unsigned long has_cksum;
		unsigned long cksum;
	};
.fi
.PP
The
.I cputype
and
.I 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
.I has_cksum
is set to one if the architecture as an
.SM LC_PREBIND_CKSUM
load command and zero otherwise.
The field
.I cksum
is set to the value of the cksum in
.SM LC_PREBIND_CKSUM
load command (or zero if it does not have one).
.SH "SEE ALSO"
.IR redo_prebinding (1),
.IR update_prebinding (1)