]> git.ipfire.org Git - thirdparty/binutils-gdb.git/blob - bfd/bfd.doc
c74c8ce48ee592b9b28e5835fcfca6e863108eb8
[thirdparty/binutils-gdb.git] / bfd / bfd.doc
1 This file contains -*- Text -*-.
2
3 BFD is a set of routines for reading and writing binary files.
4
5 The user should call only the interface routines at the end of bfd.h.
6 The one I'm working out of is /4/gumby/bfd/bfd.h
7
8 Sample "strip" program using BFD:
9
10 #include "bfd.h"
11
12 doit ()
13 {
14 ibfd = bfd_openr(...)
15 obfd = bfd_openw(...)
16 bfd_check_format (ibfd, object);
17 bfd_set_format (obfd, object);
18
19 bfd_set_arch_mach (obfd, ...)
20 bfd_set_start_address (obfd, ...)
21 etc...
22
23 [optionally:
24 asymbol * foo = malloc (get_symtab_upper_bound (ibfd));
25 bfd_canonicalize_symtab (ibfd, foo);
26 <sort foo, frob foo, etc, using asymbol def from bfd.h>
27 bfd_set_symtab (obfd, foo, updated_symbol_count);
28 ]
29
30 bfd_map_over_sections (abfd, setup, NULL);
31 bfd_map_over_sections (abfd, cleaner, NULL);
32
33 bfd_close (obfd);
34 bfd_close (ibfd);
35 }
36
37 setup (ibfd, sect)
38 {
39 osect = make_section (obfd, bfd_section_name (ibfd, sect));
40 bfd_set_section_size (obfd, osect, bfd_section_size (ibfd, sect));
41 ...
42 }
43
44 cleaner (ibfd, sect)
45 {
46 osect = bfd_get_section_by_name (obfd,
47 bfd_section_name (ibfd, sect));
48 bfd_copy_section (ibfd, sect, obfd, osect);
49 [perhaps: bfd_set_reloc (osect, NULL, 0); ]
50 }
51
52
53 \f
54 BFD is a package for manipulating binary files required for developing
55 programs. It implements a group of structured operations designed to
56 shield the programmer from the underlying representation of these
57 binary files. It understands object (compiled) files, archive
58 libraries, and core files. It is designed to work in a variety of
59 target environments.
60
61 To use the library, include bfd.h and link with libbfd.a.
62
63 A bfd iteself is a representation for a particular file. It is opened
64 in a manner similar to a file; code then manipulates it rather than
65 the raw files.
66 \f
67 BFD makes a distinction between TARGETS (families of file formats) and
68 FORMATS (individual file formats). For instance, the "sun4os4" target
69 can handle core, object and archive formats of files. The exact
70 layout of the different formats depends on the target environment.
71
72 The target "default" means the first one known (usually used for
73 environments that only support one format, or where the common format
74 is known at compile or link time). The target NULL means the one
75 specified at runtime in the environment variable GNUTARGET; if that is
76 null or not defined then the first entry in the target list is chosen
77 (on output), or all targets are searched (on input) to find a matching
78 one..
79
80 Most programs should use the target NULL.
81
82 There is a way to get a list of the names of all the targets:
83 char** bfd_target_list ()
84 This function returns a freshly-malloced list of all the
85 defined targets (or NULL if it could not malloc). The names
86 are read-only. You could use this to prompt the user, or
87 perhaps to error-check.
88
89 char * bfd_format_string (bfd_format format)
90 This function will give you a printable, single-word description
91 (like "core" or "archive") for a bfd format.
92 \f
93 Error handling
94
95 General rules:
96 functions which are boolean return true on success and false on failure
97 (unless they're a predicate). Functions which return pointers to
98 objects return NULL on error. The specifics are documented with each
99 function.
100
101 If a function fails, you should check the variable bfd_error. If the
102 value is no_error, then check the C variable errno just as you would
103 with any other program. The other values bfd_error may take on are
104 documented in bfd.h.
105
106 If you would prefer a comprehensible string for the error message, use
107 the function bfd_errmsg:
108 char * bfd_errmsg (error_tag)
109 This function returns a read-only string which documents the error
110 code. If the error code is no_error then it will return a string
111 depending on the value of errno.
112
113 bfd_perror() is like the perror() function except it understands
114 bfd_error.
115 \f
116 Operations on bfds themselves
117
118 bfd * bfd_openr (char *filename, char *target);
119 bfd * bfd_fdopenr (int fd, char *target, char *filename);
120
121 Open a binary file for reading. TARGET is the type of the file,
122 a char string like "sun4os4" or "elf". (Note this is not the
123 "function" of the file, e.g. an object versus a core file
124 versus an archive, but instead describes how all these files
125 are encoded.) Returns a new bfd or NULL upon failure.
126
127 bfd * bfd_openw (char *filename, char *target);
128
129 Open a file named `filename' for writing. If an existing
130 file has the same name, then it will be overwritten by a
131 successful bfd_close on the returned bfd. Will return either
132 a new bfd or NULL upon failure.
133
134 boolean bfd_close (bfd *abfd);
135
136 Close a BFD opened for either reading or writing. May involve
137 several filesystem operations, depending on the data format;
138 some things may not be known to the system until file-closing
139 time. Returns true if it successfully wrote the file, false
140 if not. A false return will not leave a partially-written
141 file behind with the name supplied to bfd_openw.
142
143 On a bfd open for reading will generally successfully
144 complete.
145
146 It is an error to call this on a file opened from inside an
147 archive.
148
149 FIXME -- show which error codes may be recoverable and
150 followed by another call to bfd_close!
151
152
153 The defined formats are specified by the enumeration bfd_format.
154
155 boolean bfd_check_format (bfd *abfd, bfd_format format);
156
157 This routine must be called after a bfd_openr. It sets up
158 internal data structures based on the contents of the file.
159 It returns FALSE if the file is not really in the specified
160 format.
161
162 boolean bfd_set_format (bfd *abfd, bfd_format format);
163
164 This routine must be called after a bfd_openw. It sets up
165 internal data structures for the proper format of file.
166 It returns FALSE if that format is not supported for output
167 (e.g. core files).
168
169 The following macros may be used to obtain information about a bfd:
170
171 bfd_get_filename -- returns a pointer to a null-terminated string
172 which names the bfd's file, or NULL if that is not known.
173 Don't side-effect this string!
174 bfd_get_format -- returns the format code for the bfd.
175 bfd_get_target -- returns the string which names the bfd's target.
176 bfd_get_mtime -- returns an time_t indicating the modification time of an
177 input bfd, if that could be determined, or 0 of not.
178 \f
179 Object files have certain properties. For input bfds, these
180 properties may be read at any time. For output bfds you should set
181 them before you begin building any sections.
182
183 bfd_vma bfd_get_start_address (bfd *abfd);
184
185 Returns the address in an object file where execution will begin.
186
187 boolean bfd_set_start_address (bfd *abfd, int vma);
188
189 Set the address where execution will start in an object file.
190
191 If the address you select is incorrect for your architecture
192 (for instance, if it's required to be on a page_boundary and
193 your supplied starting address is not, then you may get the
194 invalid_operation error. It is not always possible to
195 generate an error in this case.
196
197 An object file has an architecture, which is the general instruction
198 set of the instructions that it contains. Architectures are defined in
199 enum bfd_architecture in bfd.h. New architectures can be added by
200 putting them in the enum, updating architectures.c, and adding code to
201 handle them for the object files that know that architecture. The
202 bfd_architecture values are not stored in files, but are only used
203 within the BFD library and its callers.
204
205 An object file also has a machine type, which is the specific machine
206 within the architecture. For example, if the architecture is bfd_arch_m68k,
207 the Motorola 68000 series, then the machine type might be 68010, the mc68010
208 chip. For architectures such as the SPARC where specific versions of
209 the architecture exist, the version number should probably be used.
210
211 Particular object file formats may or may not store the machine architecture
212 and type. When copying an object file, you should copy these fields.
213 Most callers of BFD will not need to know the particular values that
214 these fields contain, but will instead propagate them from file to file,
215 or compare the architectures from two files.
216
217 enum bfd_architecture bfd_get_architecture (bfd *abfd);
218 unsigned long bfd_get_machine (bfd *abfd);
219
220 Get the machine type and architecture.
221
222 boolean bfd_set_arch_mach (bfd *abfd, enum bfd_architecture arch,
223 unsigned long machine);
224
225 Set the architecture and machine type. The result is true
226 if the object file can exactly represent the specified type.
227 The result is false otherwise.
228
229 boolean bfd_arch_compatible (bfd *abfd, bfd *bbfd,
230 enum bfd_architecture *res_arch,
231 unsigned long *res_machine);
232
233 Decides whether two BFD's contain compatible architectures and
234 machine types. If the result is TRUE and the res_arch and
235 res_machine pointers are non-NULL, the resulting "merged"
236 architecture and machine type are returned through the pointers.
237 A linker could call this to decide whether two object files
238 can be linked, and to deterine the arch and machine type of
239 the resulting file.
240
241 char * bfd_printable_arch_mach (enum bfd_architecture arch,
242 unsigned long machine);
243
244 Returns a printable string that represents the particular
245 combination of architecture and machine type.
246
247 boolean bfd_scan_arch_mach (char *string, enum bfd_architecture *archp,
248 unsigned long *machinep);
249
250 Examines a printable string and tries to extract an
251 architecture and machine type from it. The intended use is for
252 parsing specifications from the user, e.g. command line
253 arguments. The result is true if a known architecture was
254 found, and the resulting architecture and machine type are
255 stored through the argument pointers. Note that an
256 architecture scannable by this function might not be
257 representable by the particular object file format in use.
258 (i.e. bfd_set_arch_mach might return false).
259
260
261 There are also a number of boolean flags which apply to object bfds.
262
263 flagword bfd_get_file_flags (bfd *abfd);
264
265 returns a flagword containing the bfd's flags.
266
267 boolean bfd_set_file_flags (bfd *abfd, flagword flags,
268 boolean on_or_off);
269
270 sets (on_or_off == true) or clears (on_or_off == false) the flags
271 specified by flagword. All other flags are unaffected.
272 Some flag combinations don't make sense; It is not always
273 possible to detect them (since they may depend on other information).
274 Returns true if the flags could be modified as requested,
275 false if not. Upon a false return, no flags will have been
276 altered.
277
278
279 flagword bfd_applicable_file_flags (bfd *abfd);
280
281 returns a flagword with bits set for all the flags which are
282 meaningful for the bfd.
283
284 The flags are:
285 HAS_RELOC -- file contains unresolved relocation information.
286 EXEC_P -- file can be executed. These two may both be on in the
287 case of some dynamically-linked binaries.
288 HAS_LINENO -- has line number information.
289 HAS_DEBUG -- has debugging information.
290 HAS_SYMS -- has any symbols.
291 HAS_LOCALS -- has local symbols.
292 DYNAMIC -- binary is dynamically linked.
293 WP_TEXT -- text is write-protected
294 D_PAGED -- binary should be demand-paged
295
296 These flags are one bit wide and may be OR-ed together with |.
297
298 If you are building a large application with bfd there may be data
299 specific to your program that you may wish to associate with a bfd.
300 Rather than require you to build a parallel table structure, bfd
301 provides a void* pointer in each bfd for arbitrary user data. The
302 macro bfd_usrdata (bfd *abfd) extracts these data; you may set them
303 with = (ie bfd_usrdata (my_bfd) = frob_it (my_bfd, moon_phase);).
304 \f
305 Object and core files have sections.
306
307 File sections are represented by opaque pointers. You may map over
308 the sections of a file or you may ask for one by name. Note that not
309 all files may have all the possible sections.
310
311 Section pointers are valid from the time you get them until the bfd
312 to which they refer is closed.
313
314 When doing output, you must set up all the file's sections before
315 outputting to any. All that means is that all the file's sections
316 must have already been created and their size set before output
317 commences.
318
319 Each section contains some small information, plus three chunks of
320 data in the object file: contents, relocation, and line numbers.
321 In some file formats (e.g. a.out), the line number part is always
322 empty, and line number information (if any) is instead recorded in
323 the symbol table.
324
325 sec_ptr bfd_get_section_by_name (bfd *abfd, char *name);
326 Returns a section named NAME, or NULL if none by that name
327 exists. Works on input and output bfds.
328
329 sec_ptr bfd_make_section (bfd *abfd, char *name);
330 Creates a section named name in the output bfd abfd.
331 returns NULL if it cannot create the section (if, for instance,
332 the output format does not permit such a section). If a
333 section with that name already exists, it is returned; a new
334 one with the same name is NOT created.
335
336 unsigned int bfd_count_sections (bfd *abfd)
337
338 This function returns the number of sections in the bfd abfd.
339
340 void bfd_map_over_sections (bfd *abfd, void (*operation)(),
341 void *user_storage);
342
343 This is how you operate on all sections of an input file.
344 Pass in a function pointer. The function will be called for each
345 section of the file, in random order. It will be passed
346 three arguments: the bfd, the sec_ptr for the section, and
347 whatever was passed in as user_storage.
348
349 char * bfd_section_name (bfd *abfd, sec_ptr ptr);
350
351 Produces the name of a section, e.g. ".text" or ".data".
352 This will produce arbitrary names for files with extensible
353 section names (e.g. COFF, ELF) so don't assume that you will
354 only see a few values here.
355
356 long bfd_section_size (bfd *abfd, sec_ptr ptr);
357
358 The size of a section in bytes. Result == -1 for error.
359
360 boolean bfd_set_section_size (bfd *abfd, sec_ptr section unsigned long size);
361
362 Set the size of a section. This must be done before any data
363 transfer is done for the section.
364
365 bfd_vma bfd_section_vma (bfd *abfd, sec_ptr ptr);
366
367 Virtual memory address where a section "belongs".
368
369 boolean bfd_set_section_vma (bfd *abfd, bfd_vma vma);
370
371 Set the virtual memory address of a section.
372
373 int bfd_get_section_alignment (bfd *abfd, sec_ptr ptr);
374
375 returns the alignment of a section. If alignment is not
376 possible, return value is undefined.
377
378 boolean bfd_set_section_alignment (bfd *abfd, sec_ptr ptr, int alignment)
379
380 returns true if it can set the section to the requested value.
381 Alignment is an integer; it refers to the power of two
382 specifying the byte boundary we want (ie 0 is byte-aligned; 4
383 is word aligned). If the requested alignment is not available
384 any existing value is unchanged.
385
386 Sections have properties just as object files may:
387
388 flagword bfd_get_section_flags (bfd *abfd, sec_ptr section);
389
390 returns a flagword containing the section's flags.
391
392 boolean bfd_set_section_flags (bfd *abfd, sec_ptr section,
393 flagword flags, boolean on_or_off);
394
395 sets (on_or_off == true) or clears (on_or_off == false) the flags
396 specified by flagword. All other flags are unaffected.
397 Some flag combinations don't make sense; It is not always
398 possible to detect them (since they may depend on other information).
399 Returns true if the flags could me modified as requested,
400 false if not. Unpon a false return, no flags will have been
401 altered.
402
403 flagword bfd_applicable_section_flags (bfd *abfd);
404
405 returns a flagword with bits set for all the flags which are
406 meaningful for a section.
407
408 The flags are:
409
410 SEC_BALIGN -- segment can be byte-aligned.
411 SEC_RELOC -- segment should be relocated.
412 SEC_ALLOC -- when converted into a memory image with the intent of
413 constructing a runable process, memory space will be
414 allocated for this section.
415 SEC_LOAD -- when converted into a memory image with the intent of
416 constructing a runable process, section contents will be
417 copied from the object file into memory. When this flag
418 is set, SEC_ALLOC is guaranteed to also be set.
419 SEC_HAS_CONTENTS -- The contents of this section exist in the
420 object file. Sections whose contents do not exist in the
421 object file may still have their contents read. On read,
422 a segment filled with zeroes will be invented to satisfy
423 the read request. It is an error to attempt to set the
424 contents of a section that has no contents.
425
426 These last three probably need some explanation. In a traditional,
427 native unix object format, there are three real sections, text, data,
428 and bss. The text section will be allocated memory on exec, and will
429 be loaded from file into memory on exec. So the flags for a
430 traditional unix text section would typically be at least (SEC_ALLOC |
431 SEC_LOAD | SEC_HAS_CONTENTS). The data section has basically these
432 same traits. The bss section, however is a little different. It is
433 not relocated, and it is not loaded from file on exec, but it is
434 allocated memory on exec. Thus, its flags would be more like
435 (SEC_ALLOC). It is possible to have a section which is the converse
436 of the bss section. That is, (SEC_HAS_CONTENTS & ~SEC_ALLOC). This
437 could be anything from profiling information or notes from one pass of
438 a toolchain to another to time and version stamp information.
439
440 Note that the section flags currently lack information on position
441 dependance.
442
443 boolean bfd_get_section_contents (bfd *abfd, sec_ptr section,
444 unsigned char *location,
445 int offset, int count);
446
447 Stores count bytes from the section's contents starting at
448 offset from within those contents. The values are stored into
449 location. Returns true if it could do so. Supplying invalid
450 values for offset and count will produce unpredictable results.
451
452 boolean bfd_set_section_contents (bfd *abfd, sec_ptr section,
453 unsigned char *location,
454 int offset, int count);
455 Stores count bytes from location into offset within the
456 section contents. You need not write all the contents contiguously
457 (that is, you may write words 5-7 followed by 0-4 if you
458 wish). However once you start writing into a section, any
459 other sections into which you have previously written are
460 considered finished, and you may not write in them any more.
461
462 *** Line numbers ***
463
464 bfd_get_section_lineno_size (bfd *abfd, sec_ptr section);
465 Returns how many bytes of line numbers are associated with this
466 section.
467
468 bfd_set_section_lineno_size (bfd *abfd, sec_ptr section, unsigned long val);
469 Sets the number of bytes of line numbers that this section should
470 contain.
471
472 boolean bfd_get_section_linenos (bfd *abfd, sec_ptr section,
473 unsigned char *location,
474 int offset, int count);
475 Same as get_section_contents, except that it works on the linenos
476 for this section.
477
478 boolean bfd_set_section_linenos (bfd *abfd, sec_ptr section,
479 unsigned char *location,
480 int offset, int count);
481 Same as set_section_contents, except that it works on the linenos
482 for this section.
483
484 As with files, you may associate arbitrary program-specific data with
485 a section of a bfd. The following two functions are provided for
486 manipulating these data:
487
488 void * bfd_get_section_userdata (bfd *abfd, sec_ptr section)
489 Returns whatever was stored in section's user data, or NULL if nothing.
490
491 boolean bfd_set_section_userdata (bfd *abfd, sec_ptr section, void *contents)
492 Set the section contents. Returns true if it can, false if not.
493 \f
494 Core files
495
496 Core files are currently only supported for reading.
497
498 Apart from opening them, looking at the various sections (generally
499 the .data, .stack, and .regs sections; maybe a .user_struct section
500 eventually), you can make some queries about the status of the core
501 file, detailed below. The ".regs" section contains the general and
502 floating point registers of the process that died, in some machine-
503 specific order and format "intended to be unsurprising to someone who
504 knows the machine".
505
506 char * bfd_core_file_failing_command (bfd *abfd);
507
508 The command name of the program that failed, creating the core file.
509 The result is NULL if BFD can't figure out what the failing command was.
510
511 int bfd_core_file_failing_signal (bfd *abfd);
512
513 The signal number which caused the program to die, causing the
514 core file to be created. It will be positive if valid.
515
516 boolean core_file_matches_executable_p (bfd *core_bfd, bfd *exec_bfd);
517
518 For debuggers, checks whether a core file "matches" (is likely to
519 have come from) an executable file. This will not be perfect on
520 most systems, but will just provide a way to reject gross mismatches.
521 \f
522 Archives.
523
524 An archive is a special file which can contain other files.
525 Originally it was intended to be a general way to group files, the way
526 tar is today. But now it is used almost exclusively to hold object
527 files.
528
529 An archive may be opened for reading or writing just like any other
530 bfd. Once it is open for reading you may obtain bfds for each of the
531 files contained within it with the following function:
532
533 bfd * bfd_openr_next_archived_file (bfd *arch_bfd, bfd *last_file);
534
535 If called with NULL as the second argument, returns the first
536 file contained in the archive arch_bfd. If called with a file
537 contained within arch_bfd, returns the one which follows that
538 one, or NULL if it was the last. Returns NULL also if the
539 bfd supplied as last_file did not come from the archive arch_bfd.
540
541 Any bfd open for read may be placed in an output archive. When the
542 output archive is closed, the contents will be placed into the
543 archive.
544
545 You control the order of files in an archive. You set the first one
546 with the following function:
547
548 boolean bfd_set_archive_head (bfd *output_archive, bfd *new_head)
549
550 This function sets the first file in the archive
551 output_archive to be the bfd new_head.
552
553 bfd's contain a pointer called next, which is bfd *. It is used by
554 bfd_close when an archive is closed to decide which file should next
555 go into the archive. So to place a group of files into an archive,
556 open bfds for each of them, chain them together using the next pointer
557 in the order you desire (be sure to store NULL into the final one's
558 next pointer), then do bfd_set_archive_head with the head of the
559 chain. The next pointer may be freely smashed at any time; it is only
560 looked at when closing an output archive.
561
562 bfds for files contained within archives are normal bfds; you can do
563 any input operations on them that you can do with a normal bfd.
564
565 bfd_my_archive is a macro which takes an input bfd and returns NULL if
566 it lives in the filesystem and a bfd if it is contained in an archive.
567 In the latter case, the returned bfd is the archive itself.
568
569 Archives containing only object files may have a "map" -- a table in
570 the front which maps external symbols to the files which contain them.
571
572 Archive maps will refer only to object files; if an archive contains a
573 file which is not an archive that file will of course not appear in
574 the map.
575
576 boolean bfd_has_map (bfd *archive_bfd)
577
578 This macro takes a bfd of an archive and returns true or
579 false depending on whether the bfd has a map. For output
580 bfds this may be set to true or false, depending on whether
581 you want the map to be maintained or not. For some targets,
582 setting this to false will cause no map to be generated; for
583 others it will merely cause an empty map to be created, since
584 a map is required by that target.
585
586 For archives with maps you may use the following function:
587
588 int bfd_get_next_mapent (bfd *abfd, int prev, char **name)
589
590 You may use this to step through all the entries in the archive
591 map. Supply BFD_NO_MORE_SYMBOLS as the 'prev' entry to get the
592 first entry; then use successive returned values from this
593 function to get the succeeding ones. The name of the next entry
594 will be stored through the pointer name.
595
596 This function returns BFD_NO_MORE_SYMBOLS when there are no more
597 entries or on error.
598
599 bfd * bfd_get_elt_at_index (abfd, int index)
600
601 This function takes an index as returned by bfd_get_next_mapent
602 and returns the bfd which corresponds to that entry. Returns NULL
603 on error.
604 \f
605 Symbol and relocation information.
606
607 Symbol-table information is the area of greatest incompatibility.
608 bfd has a canonical symbol representation; all formats are parsed into
609 and out of it.
610
611 Note that canonicalize_symtab takes a pointer to an array of pointers
612 to canonical symbols. This is necessary so that the end of the array
613 can be marked with NULL. You may shuffle the pointers and you may
614 clobber the symbol contents. But don't move the symbols themselves.
615
616 unsigned int bfd_get_symtab_upper_bound (bfd *abfd);
617
618 Returns the maximum number of bytes that would be taken by
619 the output of canonicalize_symtab. Returns 0 on error.
620
621 unsigned int bfd_canonicalize_symtab (bfd *abfd, asymbol **location);
622
623 Produces a symbol table in canonical format at LOCATION, which
624 must be of size specified by get_symtab_upper_bound bytes.
625 Not all those bytes may be used. Returns the number of
626 symbol pointers written. Returns 0 upon error.
627
628 boolean bfd_set_symtab (bfd *outbfd, asymbol **location,
629 unsigned int symcount);
630
631 Takes a generic symbol table and an output bfd. Used to set
632 the symbol table for an output bfd. Do not change the table
633 after using this function (although the storage may be
634 reclaimed once the bfd has been closed).
635
636 If you're done with the symbol table you can tell bfd about it by
637 calling bfd_reclaim_symbol_table, which takes a bfd. Calling this
638 function will also reclaim any relocation entries you may have
639 requested. If you don't use this function, bfd will keep around all
640 symbol information until the bfd is closed.
641
642 Similarly, relocations have a canonical format. See the file bfd.h for
643 the exact definition. It is similar to the sun-4 relocation format.
644 Please note that:
645 o - Each relocation has a pointer to a generic symbol.
646 o - Not all values of reloc_type are supported for all targets. There
647 is a bitvector which explains which are; you can index into it by
648 relocation type. The macro which extracts it is bfd_valid_reloc_types.
649
650 Since relocation information is saved on a per-section basis, the
651 interface is slightly different from that of the symbol table:
652
653 unsigned int get_reloc_upper_bound (bfd *abfd, sec_ptr asect);
654
655 Returns the maximum number of bytes that would be taken by
656 the output of canonicalize_reloc. Returns 0 on error.
657
658 unsigned int canonicalize_reloc (bfd *abfd, sec_ptr asect, arelent *location);
659
660 Produces a relocation table in canonical format at LOCATION,
661 which must be of size specified by get_reloc_upper_bound
662 bytes. Not all those bytes may be used. Returns the number
663 of entries written. Returns 0 upon error.
664
665 boolean bfd_set_reloc (bfd *outbfd, sec_ptr asect, arelent *location,
666 unsigned int count);
667
668 Takes a generic reloc table and an output bfd. Used to set
669 the reloc table for an output bfd. Do not change the table
670 after using this function (although the storage may be
671 reclaimed once the bfd has been closed).
672 \f
673 Byte-swapping
674
675 Unfortunately, not all machines have the same byte order. Worse,
676 storage layout is in general highly machine-dependent. Although bfd
677 can hide that from you in most cases, it cannot do so with the section
678 contents, since they are totally uninterpreted. Hence you must
679 byte-swap those data yourself. This is not usually much of an issue
680 since you should just generate your data in the correct byte order.
681
682 [THIS IS WRONG AND ALSO DOES NOT REFLECT THE CODE WHICH IS CORRECT]
683
684 Fortunately, bfd can tell if byte-swapping or realignment is required
685 at all! The macro bfd_bit_twiddle_required takes a pointer to a bfd
686 and returns true if byte-swapping is required, false if not.
687
688 However if you don't wish to check this you may just use the following
689 functions which will do the conversions required:
690
691
692 long bfd_getlong (bfd *abfd, unsigned char *ptr);
693 bfd_putlong (bfd *abfd, unsigned char *ptr, long time);
694
695 short bfd_getshort (bfd *abfd, unsigned char *ptr);
696 bfd_putshort (bfd *abfd, unsigned char *ptr, short stop);
697
698 These functions take a pointer that points to data which is,
699 or will be, part of a section contents. They extract numbers
700 from the data, or insert numbers into the data. The argument
701 or result is in the host's number format; the data stored at
702 the pointer or retrieved from it is in the target's number format.
703 Typically this transfer is either a no-op or is a byte-swap;
704 sometimes it involves an access to a "misaligned" location from
705 the host's point of view..