5 Each port of BFD to a different machine requires the creation
6 of a target back end. All the back end provides to the root
7 part of BFD is a structure containing pointers to functions
8 which perform certain low level operations on files. BFD
9 translates the applications's requests through a pointer into
10 calls to the back end routines.
12 When a file is opened with @code{bfd_openr}, its format and
13 target are unknown. BFD uses various mechanisms to determine
14 how to interpret the file. The operations performed are:
19 Create a BFD by calling the internal routine
20 @code{_bfd_new_bfd}, then call @code{bfd_find_target} with the
21 target string supplied to @code{bfd_openr} and the new BFD pointer.
24 If a null target string was provided to @code{bfd_find_target},
25 look up the environment variable @code{GNUTARGET} and use
26 that as the target string.
29 If the target string is still @code{NULL}, or the target string is
30 @code{default}, then use the first item in the target vector
31 as the target type, and set @code{target_defaulted} in the BFD to
32 cause @code{bfd_check_format} to loop through all the targets.
33 @xref{bfd_target}. @xref{Formats}.
36 Otherwise, inspect the elements in the target vector
37 one by one, until a match on target name is found. When found,
41 Otherwise return the error @code{bfd_error_invalid_target} to
45 @code{bfd_openr} attempts to open the file using
46 @code{bfd_open_file}, and returns the BFD.
48 Once the BFD has been opened and the target selected, the file
49 format may be determined. This is done by calling
50 @code{bfd_check_format} on the BFD with a suggested format.
51 If @code{target_defaulted} has been set, each possible target
52 type is tried to see if it recognizes the specified format.
53 @code{bfd_check_format} returns @code{TRUE} when the caller guesses right.
58 @node bfd_target, , Targets, Targets
60 @subsection bfd_target
63 @strong{Description}@*
64 This structure contains everything that BFD knows about a
65 target. It includes things like its byte order, name, and which
66 routines to call to do various operations.
68 Every BFD points to a target structure with its @code{xvec}
71 The macros below are used to dispatch to functions through the
72 @code{bfd_target} vector. They are used in a number of macros further
73 down in @file{bfd.h}, and are also used when calling various
74 routines by hand inside the BFD implementation. The @var{arglist}
75 argument must be parenthesized; it contains all the arguments
76 to the called function.
78 They make the documentation (more) unpleasant to read, so if
79 someone wants to fix this and not break the above, please do.
81 #define BFD_SEND(bfd, message, arglist) \
82 ((*((bfd)->xvec->message)) arglist)
86 #define BFD_SEND(bfd, message, arglist) \
87 (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
88 ((*((bfd)->xvec->message)) arglist) : \
89 (bfd_assert (__FILE__,__LINE__), NULL))
92 For operations which index on the BFD format:
94 #define BFD_SEND_FMT(bfd, message, arglist) \
95 (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
99 #define BFD_SEND_FMT(bfd, message, arglist) \
100 (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
101 (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
102 (bfd_assert (__FILE__,__LINE__), NULL))
106 This is the structure which defines the type of BFD this is. The
107 @code{xvec} member of the struct @code{bfd} itself points here. Each
108 module that implements access to a different target under BFD,
109 defines one of these.
111 FIXME, these names should be rationalised with the names of
112 the entry points which call them. Too bad we can't have one
113 macro to define them both!
117 bfd_target_unknown_flavour,
118 bfd_target_aout_flavour,
119 bfd_target_coff_flavour,
120 bfd_target_ecoff_flavour,
121 bfd_target_xcoff_flavour,
122 bfd_target_elf_flavour,
123 bfd_target_ieee_flavour,
124 bfd_target_nlm_flavour,
125 bfd_target_oasys_flavour,
126 bfd_target_tekhex_flavour,
127 bfd_target_srec_flavour,
128 bfd_target_ihex_flavour,
129 bfd_target_som_flavour,
130 bfd_target_os9k_flavour,
131 bfd_target_versados_flavour,
132 bfd_target_msdos_flavour,
133 bfd_target_ovax_flavour,
134 bfd_target_evax_flavour,
135 bfd_target_mmo_flavour,
136 bfd_target_mach_o_flavour,
137 bfd_target_pef_flavour,
138 bfd_target_pef_xlib_flavour,
139 bfd_target_sym_flavour
142 enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
144 /* Forward declaration. */
145 typedef struct bfd_link_info _bfd_link_info;
147 typedef struct bfd_target
149 /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */
152 /* The "flavour" of a back end is a general indication about
153 the contents of a file. */
154 enum bfd_flavour flavour;
156 /* The order of bytes within the data area of a file. */
157 enum bfd_endian byteorder;
159 /* The order of bytes within the header parts of a file. */
160 enum bfd_endian header_byteorder;
162 /* A mask of all the flags which an executable may have set -
163 from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}. */
164 flagword object_flags;
166 /* A mask of all the flags which a section may have set - from
167 the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}. */
168 flagword section_flags;
170 /* The character normally found at the front of a symbol.
171 (if any), perhaps `_'. */
172 char symbol_leading_char;
174 /* The pad character for file names within an archive header. */
177 /* The maximum number of characters in an archive header. */
178 unsigned short ar_max_namelen;
180 /* Entries for byte swapping for data. These are different from the
181 other entry points, since they don't take a BFD asthe first argument.
182 Certain other handlers could do the same. */
183 bfd_uint64_t (*bfd_getx64) (const void *);
184 bfd_int64_t (*bfd_getx_signed_64) (const void *);
185 void (*bfd_putx64) (bfd_uint64_t, void *);
186 bfd_vma (*bfd_getx32) (const void *);
187 bfd_signed_vma (*bfd_getx_signed_32) (const void *);
188 void (*bfd_putx32) (bfd_vma, void *);
189 bfd_vma (*bfd_getx16) (const void *);
190 bfd_signed_vma (*bfd_getx_signed_16) (const void *);
191 void (*bfd_putx16) (bfd_vma, void *);
193 /* Byte swapping for the headers. */
194 bfd_uint64_t (*bfd_h_getx64) (const void *);
195 bfd_int64_t (*bfd_h_getx_signed_64) (const void *);
196 void (*bfd_h_putx64) (bfd_uint64_t, void *);
197 bfd_vma (*bfd_h_getx32) (const void *);
198 bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
199 void (*bfd_h_putx32) (bfd_vma, void *);
200 bfd_vma (*bfd_h_getx16) (const void *);
201 bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
202 void (*bfd_h_putx16) (bfd_vma, void *);
204 /* Format dependent routines: these are vectors of entry points
205 within the target vector structure, one for each format to check. */
207 /* Check the format of a file being read. Return a @code{bfd_target *} or zero. */
208 const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
210 /* Set the format of a file being written. */
211 bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
213 /* Write cached information into a file being written, at @code{bfd_close}. */
214 bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
217 The general target vector. These vectors are initialized using the
218 BFD_JUMP_TABLE macros.
221 /* Generic entry points. */
222 #define BFD_JUMP_TABLE_GENERIC(NAME) \
223 NAME##_close_and_cleanup, \
224 NAME##_bfd_free_cached_info, \
225 NAME##_new_section_hook, \
226 NAME##_get_section_contents, \
227 NAME##_get_section_contents_in_window
229 /* Called when the BFD is being closed to do any necessary cleanup. */
230 bfd_boolean (*_close_and_cleanup) (bfd *);
231 /* Ask the BFD to free all cached information. */
232 bfd_boolean (*_bfd_free_cached_info) (bfd *);
233 /* Called when a new section is created. */
234 bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
235 /* Read the contents of a section. */
236 bfd_boolean (*_bfd_get_section_contents)
237 (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
238 bfd_boolean (*_bfd_get_section_contents_in_window)
239 (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
241 /* Entry points to copy private data. */
242 #define BFD_JUMP_TABLE_COPY(NAME) \
243 NAME##_bfd_copy_private_bfd_data, \
244 NAME##_bfd_merge_private_bfd_data, \
245 NAME##_bfd_copy_private_section_data, \
246 NAME##_bfd_copy_private_symbol_data, \
247 NAME##_bfd_set_private_flags, \
248 NAME##_bfd_print_private_bfd_data
250 /* Called to copy BFD general private data from one object file
252 bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
253 /* Called to merge BFD general private data from one object file
254 to a common output file when linking. */
255 bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
256 /* Called to copy BFD private section data from one object file
258 bfd_boolean (*_bfd_copy_private_section_data)
259 (bfd *, sec_ptr, bfd *, sec_ptr);
260 /* Called to copy BFD private symbol data from one symbol
262 bfd_boolean (*_bfd_copy_private_symbol_data)
263 (bfd *, asymbol *, bfd *, asymbol *);
264 /* Called to set private backend flags. */
265 bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
267 /* Called to print private BFD data. */
268 bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
270 /* Core file entry points. */
271 #define BFD_JUMP_TABLE_CORE(NAME) \
272 NAME##_core_file_failing_command, \
273 NAME##_core_file_failing_signal, \
274 NAME##_core_file_matches_executable_p
276 char * (*_core_file_failing_command) (bfd *);
277 int (*_core_file_failing_signal) (bfd *);
278 bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
280 /* Archive entry points. */
281 #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
282 NAME##_slurp_armap, \
283 NAME##_slurp_extended_name_table, \
284 NAME##_construct_extended_name_table, \
285 NAME##_truncate_arname, \
286 NAME##_write_armap, \
287 NAME##_read_ar_hdr, \
288 NAME##_openr_next_archived_file, \
289 NAME##_get_elt_at_index, \
290 NAME##_generic_stat_arch_elt, \
291 NAME##_update_armap_timestamp
293 bfd_boolean (*_bfd_slurp_armap) (bfd *);
294 bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
295 bfd_boolean (*_bfd_construct_extended_name_table)
296 (bfd *, char **, bfd_size_type *, const char **);
297 void (*_bfd_truncate_arname) (bfd *, const char *, char *);
298 bfd_boolean (*write_armap)
299 (bfd *, unsigned int, struct orl *, unsigned int, int);
300 void * (*_bfd_read_ar_hdr_fn) (bfd *);
301 bfd * (*openr_next_archived_file) (bfd *, bfd *);
302 #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
303 bfd * (*_bfd_get_elt_at_index) (bfd *, symindex);
304 int (*_bfd_stat_arch_elt) (bfd *, struct stat *);
305 bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
307 /* Entry points used for symbols. */
308 #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
309 NAME##_get_symtab_upper_bound, \
310 NAME##_canonicalize_symtab, \
311 NAME##_make_empty_symbol, \
312 NAME##_print_symbol, \
313 NAME##_get_symbol_info, \
314 NAME##_bfd_is_local_label_name, \
316 NAME##_find_nearest_line, \
317 NAME##_bfd_make_debug_symbol, \
318 NAME##_read_minisymbols, \
319 NAME##_minisymbol_to_symbol
321 long (*_bfd_get_symtab_upper_bound) (bfd *);
322 long (*_bfd_canonicalize_symtab)
323 (bfd *, struct bfd_symbol **);
325 (*_bfd_make_empty_symbol) (bfd *);
326 void (*_bfd_print_symbol)
327 (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type);
328 #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e))
329 void (*_bfd_get_symbol_info)
330 (bfd *, struct bfd_symbol *, symbol_info *);
331 #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
332 bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
334 alent * (*_get_lineno) (bfd *, struct bfd_symbol *);
335 bfd_boolean (*_bfd_find_nearest_line)
336 (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
337 const char **, const char **, unsigned int *);
338 /* Back-door to allow format-aware applications to create debug symbols
339 while using BFD for everything else. Currently used by the assembler
340 when creating COFF files. */
341 asymbol * (*_bfd_make_debug_symbol)
342 (bfd *, void *, unsigned long size);
343 #define bfd_read_minisymbols(b, d, m, s) \
344 BFD_SEND (b, _read_minisymbols, (b, d, m, s))
345 long (*_read_minisymbols)
346 (bfd *, bfd_boolean, void **, unsigned int *);
347 #define bfd_minisymbol_to_symbol(b, d, m, f) \
348 BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
349 asymbol * (*_minisymbol_to_symbol)
350 (bfd *, bfd_boolean, const void *, asymbol *);
352 /* Routines for relocs. */
353 #define BFD_JUMP_TABLE_RELOCS(NAME) \
354 NAME##_get_reloc_upper_bound, \
355 NAME##_canonicalize_reloc, \
356 NAME##_bfd_reloc_type_lookup
358 long (*_get_reloc_upper_bound) (bfd *, sec_ptr);
359 long (*_bfd_canonicalize_reloc)
360 (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
361 /* See documentation on reloc types. */
363 (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
365 /* Routines used when writing an object file. */
366 #define BFD_JUMP_TABLE_WRITE(NAME) \
367 NAME##_set_arch_mach, \
368 NAME##_set_section_contents
370 bfd_boolean (*_bfd_set_arch_mach)
371 (bfd *, enum bfd_architecture, unsigned long);
372 bfd_boolean (*_bfd_set_section_contents)
373 (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
375 /* Routines used by the linker. */
376 #define BFD_JUMP_TABLE_LINK(NAME) \
377 NAME##_sizeof_headers, \
378 NAME##_bfd_get_relocated_section_contents, \
379 NAME##_bfd_relax_section, \
380 NAME##_bfd_link_hash_table_create, \
381 NAME##_bfd_link_hash_table_free, \
382 NAME##_bfd_link_add_symbols, \
383 NAME##_bfd_link_just_syms, \
384 NAME##_bfd_final_link, \
385 NAME##_bfd_link_split_section, \
386 NAME##_bfd_gc_sections, \
387 NAME##_bfd_merge_sections, \
388 NAME##_bfd_discard_group
390 int (*_bfd_sizeof_headers) (bfd *, bfd_boolean);
391 bfd_byte * (*_bfd_get_relocated_section_contents)
392 (bfd *, struct bfd_link_info *, struct bfd_link_order *,
393 bfd_byte *, bfd_boolean, struct bfd_symbol **);
395 bfd_boolean (*_bfd_relax_section)
396 (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
398 /* Create a hash table for the linker. Different backends store
399 different information in this table. */
400 struct bfd_link_hash_table *
401 (*_bfd_link_hash_table_create) (bfd *);
403 /* Release the memory associated with the linker hash table. */
404 void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
406 /* Add symbols from this object file into the hash table. */
407 bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
409 /* Indicate that we are only retrieving symbol values from this section. */
410 void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
412 /* Do a link based on the link_order structures attached to each
413 section of the BFD. */
414 bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
416 /* Should this section be split up into smaller pieces during linking. */
417 bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
419 /* Remove sections that are not referenced from the output. */
420 bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
422 /* Attempt to merge SEC_MERGE sections. */
423 bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
425 /* Discard members of a group. */
426 bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
428 /* Routines to handle dynamic symbols and relocs. */
429 #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
430 NAME##_get_dynamic_symtab_upper_bound, \
431 NAME##_canonicalize_dynamic_symtab, \
432 NAME##_get_dynamic_reloc_upper_bound, \
433 NAME##_canonicalize_dynamic_reloc
435 /* Get the amount of memory required to hold the dynamic symbols. */
436 long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
437 /* Read in the dynamic symbols. */
438 long (*_bfd_canonicalize_dynamic_symtab)
439 (bfd *, struct bfd_symbol **);
440 /* Get the amount of memory required to hold the dynamic relocs. */
441 long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
442 /* Read in the dynamic relocs. */
443 long (*_bfd_canonicalize_dynamic_reloc)
444 (bfd *, arelent **, struct bfd_symbol **);
447 A pointer to an alternative bfd_target in case the current one is not
448 satisfactory. This can happen when the target cpu supports both big
449 and little endian code, and target chosen by the linker has the wrong
450 endianness. The function open_output() in ld/ldlang.c uses this field
451 to find an alternative output format that is suitable.
453 /* Opposite endian version of this target. */
454 const struct bfd_target * alternative_target;
456 /* Data for use by back-end routines, which isn't
457 generic enough to belong in this structure. */
458 const void *backend_data;
464 @findex bfd_set_default_target
465 @subsubsection @code{bfd_set_default_target}
468 bfd_boolean bfd_set_default_target (const char *name);
470 @strong{Description}@*
471 Set the default target vector to use when recognizing a BFD.
472 This takes the name of the target, which may be a BFD target
473 name or a configuration triplet.
475 @findex bfd_find_target
476 @subsubsection @code{bfd_find_target}
479 const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
481 @strong{Description}@*
482 Return a pointer to the transfer vector for the object target
483 named @var{target_name}. If @var{target_name} is @code{NULL}, choose the
484 one in the environment variable @code{GNUTARGET}; if that is null or not
485 defined, then choose the first entry in the target list.
486 Passing in the string "default" or setting the environment
487 variable to "default" will cause the first entry in the target
488 list to be returned, and "target_defaulted" will be set in the
489 BFD. This causes @code{bfd_check_format} to loop over all the
490 targets to find the one that matches the file being read.
492 @findex bfd_target_list
493 @subsubsection @code{bfd_target_list}
496 const char ** bfd_target_list (void);
498 @strong{Description}@*
499 Return a freshly malloced NULL-terminated
500 vector of the names of all the valid BFD targets. Do not
503 @findex bfd_seach_for_target
504 @subsubsection @code{bfd_seach_for_target}
507 const bfd_target *bfd_search_for_target
508 (int (*search_func) (const bfd_target *, void *),
511 @strong{Description}@*
512 Return a pointer to the first transfer vector in the list of
513 transfer vectors maintained by BFD that produces a non-zero
514 result when passed to the function @var{search_func}. The
515 parameter @var{data} is passed, unexamined, to the search