| blob | 256f2039eec99b51bce3d20df3697916092c9ad2 |
1 .TH REDO_PREBINDING 3 "July 28, 2005" "Apple Computer, Inc."
2 .SH NAME
3 redo_prebinding library functions
4 .SH SYNOPSIS
5 .nf
6 .PP
7 .ft B
8 #include <mach-o/redo_prebinding.h>
9 .sp .5
10 extern char ** dependent_libs(
11 const char *file_name,
12 const char *program_name,
13 char **error_message);
14 .sp .5
15 extern char * install_name(
16 const char *file_name,
17 const char *program_name,
18 char **error_message);
19 .sp .5
20 extern enum redo_prebinding_retval redo_prebinding(
21 const char *file_name,
22 const char *executable_path,
23 const char *root_dir,
24 const char *output_file,
25 const char *program_name,
26 char **error_message,
27 unsigned long slide_to_address,
28 int only_if_needed,
29 int zero_out_prebind_checksum,
30 cpu_type_t allow_missing_architectures,
31 unsigned long *throttle);
32 .sp .5
33 extern enum needs_redo_prebinding_retval needs_redo_prebinding(
34 const char *file_name,
35 const char *executable_path,
36 const char *root_dir,
37 const char *program_name,
38 char **error_message,
39 unsigned long expected_address,
40 cpu_type_t allow_missing_architectures);
41 .sp .5
42 extern enum redo_prebinding_retval unprebind(
43 const char *file_name,
44 const char *output_file,
45 const char *program_name,
46 char **error_message,
47 int zero_checksum);
48 .sp .5
49 extern enum object_file_type_retval object_file_type(
50 const char *file_name,
51 const char *program_name,
52 char **error_message);
53 .sp .5
54 extern int get_prebind_cksums(
55 const char *file_name,
56 struct prebind_cksum_arch **cksums,
57 unsigned long *ncksums,
58 const char *program_name,
59 char **error_message);
60 .SH DESCRIPTION
61 These functions are intended for use by
62 .IR update_prebinding (1)
63 and Mac OS X Build and Integration tools.
64 .PP
65 For all of these functions in the parameters
66 .I program_name
67 and
68 .I error_message
69 are used the same. For unrecoverable resource errors like being unable to
70 allocate memory each function prints a message to stderr precede with
71 .I program_name
72 then calls
73 .IR exit (2)
74 with the value
75 .SM EXIT_FAILURE.
76 If a function is unsuccessful and if
77 .I error_message
78 pass to it is not
79 .SM NULL it is set to a
80 .IR malloc (3)'ed
81 buffer with a
82 .SM NULL
83 terminated string with the error message. For all functions
84 when they return they release all resources (memory, open file descriptors,
85 etc).
86 .PP
87 The file_name parameter for these functions may be of the form
88 .I foo(bar)
89 which is NOT interpreted as an archive name and a member name in that archive.
90 As these functions deal with prebinding and prebound binaries ready for
91 execution can't be in archives.
92 .PP
93 If the
94 .I executable_path
95 parameter for these functions is not
96 .SM NULL
97 it is used for any dependent library has a path that starts with
98 .I @executable_path.
99 Then
100 .I @executable_path
101 is replaced with
102 .I executable_path.
103 .PP
104 If the
105 .I root_dir
106 parameter is not
107 .SM NULL
108 it is prepended to all the rooted dependent library paths.
109 .PP
110 .IR dependent_libs ()
111 takes a
112 .I file_name
113 of a binary and returns a
114 .IR malloc (3)'ed
115 array of pointers (NULL terminated) to names (also
116 .IR malloc (3)'ed
117 and '\\0' terminated names) of all the dependent libraries for that binary (not
118 recursive) for all of the architectures of that binary. If successful
119 .I dependent_libs()
120 returns a non
121 .SM NULL
122 value (at minimum a pointer to one
123 .SM NULL
124 pointer). If unsuccessful
125 .I dependent_libs returns
126 NULL.
127 .PP
128 .IR install_name ()
129 takes a
130 .I file_name
131 of a binary and returns a malloc(3)'ed pointer to a
132 .SM NULL
133 terminated string containing the install_name value for the binary. If
134 unsuccessful install_name() returns
135 .SM NULL.
136 In particular,
137 .SM NULL
138 is returned if the binary is not a dylib and there is no error_message
139 set. If the all of the arch's are dylibs but all the install names don't
140 match
141 .SM NULL
142 is returned and a error_message is set. If some but not all of
143 the archs are dylibs
144 .SM NULL
145 is returned and a error_message is set.
146 .PP
147 .IR redo_prebinding ()
148 takes a
149 .I file_name
150 of a binary and redoes the prebinding on it. If
151 .I output_file
152 is not
153 .SM NULL
154 the update file is written to
155 .I output_file,
156 if not it is written to
157 .I file_name.
158 If
159 .IR redo_prebinding ()
160 is successful it returns
161 .SM REDO_PREBINDING_SUCCESS
162 otherwise it returns
163 .SM REDO_PREBINDING_FAILURE.
164 If the
165 .I slide_to_address
166 parameter is non-zero and the binary is a dynamic library it is relocated to
167 have that has its prefered address.
168 If the parameter
169 .I allow_missing_architectures
170 is zero and not all architectures can be updated it is not successful and
171 nothing is done and this returns
172 .SM REDO_PREBINDING_FAILURE.
173 If the parameter
174 .I allow_missing_architectures
175 is non-zero then only problems with missing architectures for the architecure
176 of the cputype specified by
177 .I allow_missing_architectures
178 will cause this call to fail. Other architectures that could not be prebound
179 due to missing architectures in depending libraries will not have their
180 prebinding updated but will not cause the call to fail.
181 If the parameter
182 .I only_if_needed
183 is non-zero the prebinding is checked first and only done if needed. The
184 checking includes checking the prefered address against the
185 .I slide_to_address
186 value if it is non-zero. If
187 .I only_if_needed
188 is non-zero and the prebinding does not have to be redone
189 .SM REDO_PREBINDING_NOT_NEEDED
190 is returned, if the binary is not prebound
191 .SM REDO_PREBINDING_NOT_PREBOUND
192 is returned and if the new load commands do not fit in the binary and it needs
193 to be rebuilt
194 .SM REDO_PREBINDING_NEEDS_REBUILDING
195 is returned. If
196 .I zero_out_prebind_checksum
197 is non-zero then the cksum field of the
198 .SM LC_PREBIND_CKSUM
199 load command (if any) is set to zero on output (this should always be set by B&I
200 tools and never set by the
201 .IR update_prebinding (1)
202 command).
203 If
204 .I throttle
205 is non-NULL it points to a value of the maximum bytes per second to use for
206 writting the output. If the value is ULONG_MAX then the actual bytes per
207 second is returned indirectly through *throttle.
208 .PP
209 .IR unprebind ()
210 takes a
211 .I file_name
212 of a binary and resets or removes prebinding information from it. If
213 .I output_file
214 is not
215 .SM NULL
216 the updated file is written to
217 .I output_file,
218 if not it is written to
219 .I file_name.
220 If
221 .IR unprebind ()
222 is successful it returns
223 .SM REDO_PREBINDING_SUCCESS
224 otherwise it returns
225 .SM REDO_PREBINDING_FAILURE.
226 If the binary is already unprebound (it has the
227 .SM MH_PREBINDABLE
228 flag set) then
229 .SM REDO_PREBINDING_NOT_NEEDED
230 is returned. If
231 .I zero_out_prebind_checksum
232 is non-zero then the cksum field of the
233 .SM LC_PREBIND_CKSUM
234 load command (if any) is set to zero on output, otherwise it is left alone
235 (for the purpose of patching, this parameter should be non-zero, such that for binaries which
236 are the same - minus prebinding - the unprebinding process produces binaries
237 that are identical).
238 Unprebinding slides dynamic libraries to address zero, resets prebound symbols
239 to address zero and type undefined, resets symbol pointers, removes
240 .SM LC_PREBOUND_DYLIB
241 commands, resets library timestamps, resets two-level hints, and updates
242 relocation entries if necessary. Unprebound binaries have the
243 .SM MH_PREBINDABLE
244 flag set, but not
245 .SM MH_PREBOUND.
246 It will also set the the
247 .SM MH_ALLMODSBOUND
248 flag if all two-level libraries were used and all modules were found to be
249 bound in the
250 .SM LC_PREBOUND_DYLIB
251 commands. As unprebinding is intended to produce a canonical Mach-O
252 binary, bundles and non-prebound executables and dylibs are acceptable
253 as input. For these files, the unprebind operation will zero library time
254 stamps and version numbers and zero entries in the two-level hints
255 table. These files will not gain the
256 .SM MH_PREBINDABLE
257 flag. All resulting binaries successfully processed by unprebind() will have
258 the MH_CANONICAL flag.
259 .PP
260 .IR needs_redo_prebinding()
261 takes a
262 .I file_name
263 and determines if it is a binary and if its prebinding is uptodate. It returns
264 one of the return values below depending on the state of the binary and
265 libraries. If the parameter
266 .I allow_missing_architectures
267 is zero then architectures for universal files are checked. If the parameter
268 .I allow_missing_architectures
269 is non-zero then the value returned is based on the cputype specified by
270 .I allow_missing_architectures.
271 If that architecture is not present then
272 .SM PREBINDING_UPTODATE
273 is returned. If the parameter
274 .I expected_address
275 is not zero and the binary is a dynamic library then the library is checked to
276 see if it is at the expected_address if not the prebinding is assumed to be out
277 of date and
278 .SM PREBINDING_OUTOFDATE
279 is returned.
280 .PP
281 Return values for
282 .I needs_redo_prebinding():
283 .TP
284 .B PREBINDING_UPTODATE
285 a binary who's prebinding is up todate.
286 .TP
287 .B PREBINDING_OUTOFDATE
288 a binary who's prebinding is out of date.
289 .TP
290 .B NOT_PREBOUND
291 a binary, but not built prebound.
292 .TP
293 .B NOT_PREBINDABLE
294 not a binary or statically linked, prebinding does not apply.
295 .TP
296 .B PREBINDING_UNKNOWN
297 a binary who's prebinding can't be determined because it is malformed, a
298 library it depends on is missing, etc.
299 .PP
300 .IR object_file_type ()
301 takes a file_name and determines what type of object file it is and returns
302 on the the values below.
303 .TP
304 .B OFT_EXECUTABLE,
305 the file is an Mach-O executable.
306 .TP
307 .B OFT_DYLIB,
308 the file is an Mach-O dyanmic library.
309 .TP
310 .B OFT_BUNDLE,
311 the file is an Mach-O bundle.
312 .TP
313 .B OFT_ARCHIVE,
314 the file is an archive.
315 .TP
316 .B OFT_OTHER,
317 the file is something other than the above files.
318 .TP
319 .B OFT_INCONSISTENT,
320 the file is a universal file and the architectures are not of the same type.
321 .TP
322 .B OFT_FILE_ERROR
323 The file can't be opened, read or malformed
324 .PP
325 .IR get_prebind_cksums ()
326 takes a file_name that is a Mach-O file or universal file containing Mach-O
327 files and returns a
328 .IR malloc (3)'ed
329 array of
330 .I prebind_cksum_arch
331 structures indirectly through the
332 .I cksums
333 parameter. The number of
334 .I prebind_cksum_arch
335 structures is returned indirectly through the
336 .I ncksums
337 parameter. If successful it returns zero else it returns non-zero.
338 .PP
339 The structure
340 .I prebind_cksum_arch
341 is defined in
342 .I <mach-o/redo_prebinding.h>
343 as follows:
344 .nf
345 struct prebind_cksum_arch {
346 cpu_type_t cputype;
347 cpu_subtype_t cpusubtype;
348 unsigned long has_cksum;
349 unsigned long cksum;
350 };
351 .fi
352 .PP
353 The
354 .I cputype
355 and
356 .I cpusubtype
357 are filled in with the cpu specifier and the machine specifier for the
358 architecture of the Mach-O file (or zero if not a Mach-O file).
359 The field
360 .I has_cksum
361 is set to one if the architecture as an
362 .SM LC_PREBIND_CKSUM
363 load command and zero otherwise.
364 The field
365 .I cksum
366 is set to the value of the cksum in
367 .SM LC_PREBIND_CKSUM
368 load command (or zero if it does not have one).
369 .SH "SEE ALSO"
370 .IR redo_prebinding (1),
371 .IR update_prebinding (1)