5 Each port of BFD to a different machine requries 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))
105 This is the structure which defines the type of BFD this is. The
106 @code{xvec} member of the struct @code{bfd} itself points here. Each
107 module that implements access to a different target under BFD,
108 defines one of these.
110 FIXME, these names should be rationalised with the names of
111 the entry points which call them. Too bad we can't have one
112 macro to define them both!
115 bfd_target_unknown_flavour,
116 bfd_target_aout_flavour,
117 bfd_target_coff_flavour,
118 bfd_target_ecoff_flavour,
119 bfd_target_elf_flavour,
120 bfd_target_ieee_flavour,
121 bfd_target_nlm_flavour,
122 bfd_target_oasys_flavour,
123 bfd_target_tekhex_flavour,
124 bfd_target_srec_flavour,
125 bfd_target_ihex_flavour,
126 bfd_target_som_flavour,
127 bfd_target_os9k_flavour,
128 bfd_target_versados_flavour,
129 bfd_target_msdos_flavour,
130 bfd_target_evax_flavour
133 enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
135 /* Forward declaration. */
136 typedef struct bfd_link_info _bfd_link_info;
138 typedef struct bfd_target
141 Identifies the kind of target, e.g., SunOS4, Ultrix, etc.
145 The "flavour" of a back end is a general indication about the contents
148 enum bfd_flavour flavour;
150 The order of bytes within the data area of a file.
152 enum bfd_endian byteorder;
154 The order of bytes within the header parts of a file.
156 enum bfd_endian header_byteorder;
158 A mask of all the flags which an executable may have set -
159 from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.
161 flagword object_flags;
163 A mask of all the flags which a section may have set - from
164 the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.
166 flagword section_flags;
168 The character normally found at the front of a symbol
169 (if any), perhaps `_'.
171 char symbol_leading_char;
173 The pad character for file names within an archive header.
177 The maximum number of characters in an archive header.
179 unsigned short ar_max_namelen;
181 Entries for byte swapping for data. These are different from the other
182 entry points, since they don't take a BFD asthe first argument.
183 Certain other handlers could do the same.
185 bfd_vma (*bfd_getx64) PARAMS ((const bfd_byte *));
186 bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((const bfd_byte *));
187 void (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
188 bfd_vma (*bfd_getx32) PARAMS ((const bfd_byte *));
189 bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((const bfd_byte *));
190 void (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
191 bfd_vma (*bfd_getx16) PARAMS ((const bfd_byte *));
192 bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((const bfd_byte *));
193 void (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));
195 Byte swapping for the headers
197 bfd_vma (*bfd_h_getx64) PARAMS ((const bfd_byte *));
198 bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((const bfd_byte *));
199 void (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
200 bfd_vma (*bfd_h_getx32) PARAMS ((const bfd_byte *));
201 bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((const bfd_byte *));
202 void (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
203 bfd_vma (*bfd_h_getx16) PARAMS ((const bfd_byte *));
204 bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((const bfd_byte *));
205 void (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));
207 Format dependent routines: these are vectors of entry points
208 within the target vector structure, one for each format to check.
210 Check the format of a file being read. Return a @code{bfd_target *} or zero.
212 const struct bfd_target *(*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));
214 Set the format of a file being written.
216 boolean (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));
218 Write cached information into a file being written, at @code{bfd_close}.
220 boolean (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));
222 The general target vector.
225 /* Generic entry points. */
226 #define BFD_JUMP_TABLE_GENERIC(NAME)\
227 CAT(NAME,_close_and_cleanup),\
228 CAT(NAME,_bfd_free_cached_info),\
229 CAT(NAME,_new_section_hook),\
230 CAT(NAME,_get_section_contents),\
231 CAT(NAME,_get_section_contents_in_window)
233 /* Called when the BFD is being closed to do any necessary cleanup. */
234 boolean (*_close_and_cleanup) PARAMS ((bfd *));
235 /* Ask the BFD to free all cached information. */
236 boolean (*_bfd_free_cached_info) PARAMS ((bfd *));
237 /* Called when a new section is created. */
238 boolean (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
239 /* Read the contents of a section. */
240 boolean (*_bfd_get_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
241 file_ptr, bfd_size_type));
242 boolean (*_bfd_get_section_contents_in_window)
243 PARAMS ((bfd *, sec_ptr, bfd_window *,
244 file_ptr, bfd_size_type));
246 /* Entry points to copy private data. */
247 #define BFD_JUMP_TABLE_COPY(NAME)\
248 CAT(NAME,_bfd_copy_private_bfd_data),\
249 CAT(NAME,_bfd_merge_private_bfd_data),\
250 CAT(NAME,_bfd_copy_private_section_data),\
251 CAT(NAME,_bfd_copy_private_symbol_data),\
252 CAT(NAME,_bfd_set_private_flags),\
253 CAT(NAME,_bfd_print_private_bfd_data)\
254 /* Called to copy BFD general private data from one object file
256 boolean (*_bfd_copy_private_bfd_data) PARAMS ((bfd *, bfd *));
257 /* Called to merge BFD general private data from one object file
258 to a common output file when linking. */
259 boolean (*_bfd_merge_private_bfd_data) PARAMS ((bfd *, bfd *));
260 /* Called to copy BFD private section data from one object file
262 boolean (*_bfd_copy_private_section_data) PARAMS ((bfd *, sec_ptr,
264 /* Called to copy BFD private symbol data from one symbol
266 boolean (*_bfd_copy_private_symbol_data) PARAMS ((bfd *, asymbol *,
268 /* Called to set private backend flags */
269 boolean (*_bfd_set_private_flags) PARAMS ((bfd *, flagword));
271 /* Called to print private BFD data */
272 boolean (*_bfd_print_private_bfd_data) PARAMS ((bfd *, PTR));
274 /* Core file entry points. */
275 #define BFD_JUMP_TABLE_CORE(NAME)\
276 CAT(NAME,_core_file_failing_command),\
277 CAT(NAME,_core_file_failing_signal),\
278 CAT(NAME,_core_file_matches_executable_p)
279 char * (*_core_file_failing_command) PARAMS ((bfd *));
280 int (*_core_file_failing_signal) PARAMS ((bfd *));
281 boolean (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));
283 /* Archive entry points. */
284 #define BFD_JUMP_TABLE_ARCHIVE(NAME)\
285 CAT(NAME,_slurp_armap),\
286 CAT(NAME,_slurp_extended_name_table),\
287 CAT(NAME,_construct_extended_name_table),\
288 CAT(NAME,_truncate_arname),\
289 CAT(NAME,_write_armap),\
290 CAT(NAME,_read_ar_hdr),\
291 CAT(NAME,_openr_next_archived_file),\
292 CAT(NAME,_get_elt_at_index),\
293 CAT(NAME,_generic_stat_arch_elt),\
294 CAT(NAME,_update_armap_timestamp)
295 boolean (*_bfd_slurp_armap) PARAMS ((bfd *));
296 boolean (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
297 boolean (*_bfd_construct_extended_name_table)
298 PARAMS ((bfd *, char **, bfd_size_type *, const char **));
299 void (*_bfd_truncate_arname) PARAMS ((bfd *, CONST char *, char *));
300 boolean (*write_armap) PARAMS ((bfd *arch,
301 unsigned int elength,
303 unsigned int orl_count,
305 PTR (*_bfd_read_ar_hdr_fn) PARAMS ((bfd *));
306 bfd * (*openr_next_archived_file) PARAMS ((bfd *arch, bfd *prev));
307 #define bfd_get_elt_at_index(b,i) BFD_SEND(b, _bfd_get_elt_at_index, (b,i))
308 bfd * (*_bfd_get_elt_at_index) PARAMS ((bfd *, symindex));
309 int (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));
310 boolean (*_bfd_update_armap_timestamp) PARAMS ((bfd *));
312 /* Entry points used for symbols. */
313 #define BFD_JUMP_TABLE_SYMBOLS(NAME)\
314 CAT(NAME,_get_symtab_upper_bound),\
315 CAT(NAME,_get_symtab),\
316 CAT(NAME,_make_empty_symbol),\
317 CAT(NAME,_print_symbol),\
318 CAT(NAME,_get_symbol_info),\
319 CAT(NAME,_bfd_is_local_label_name),\
320 CAT(NAME,_get_lineno),\
321 CAT(NAME,_find_nearest_line),\
322 CAT(NAME,_bfd_make_debug_symbol),\
323 CAT(NAME,_read_minisymbols),\
324 CAT(NAME,_minisymbol_to_symbol)
325 long (*_bfd_get_symtab_upper_bound) PARAMS ((bfd *));
326 long (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
327 struct symbol_cache_entry **));
328 struct symbol_cache_entry *
329 (*_bfd_make_empty_symbol) PARAMS ((bfd *));
330 void (*_bfd_print_symbol) PARAMS ((bfd *, PTR,
331 struct symbol_cache_entry *,
332 bfd_print_symbol_type));
333 #define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
334 void (*_bfd_get_symbol_info) PARAMS ((bfd *,
335 struct symbol_cache_entry *,
337 #define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
338 boolean (*_bfd_is_local_label_name) PARAMS ((bfd *, const char *));
340 alent * (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));
341 boolean (*_bfd_find_nearest_line) PARAMS ((bfd *abfd,
342 struct sec *section, struct symbol_cache_entry **symbols,
343 bfd_vma offset, CONST char **file, CONST char **func,
344 unsigned int *line));
345 /* Back-door to allow format-aware applications to create debug symbols
346 while using BFD for everything else. Currently used by the assembler
347 when creating COFF files. */
348 asymbol * (*_bfd_make_debug_symbol) PARAMS ((
351 unsigned long size));
352 #define bfd_read_minisymbols(b, d, m, s) \
353 BFD_SEND (b, _read_minisymbols, (b, d, m, s))
354 long (*_read_minisymbols) PARAMS ((bfd *, boolean, PTR *,
356 #define bfd_minisymbol_to_symbol(b, d, m, f) \
357 BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
358 asymbol *(*_minisymbol_to_symbol) PARAMS ((bfd *, boolean, const PTR,
361 /* Routines for relocs. */
362 #define BFD_JUMP_TABLE_RELOCS(NAME)\
363 CAT(NAME,_get_reloc_upper_bound),\
364 CAT(NAME,_canonicalize_reloc),\
365 CAT(NAME,_bfd_reloc_type_lookup)
366 long (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
367 long (*_bfd_canonicalize_reloc) PARAMS ((bfd *, sec_ptr, arelent **,
368 struct symbol_cache_entry **));
369 /* See documentation on reloc types. */
371 (*reloc_type_lookup) PARAMS ((bfd *abfd,
372 bfd_reloc_code_real_type code));
374 /* Routines used when writing an object file. */
375 #define BFD_JUMP_TABLE_WRITE(NAME)\
376 CAT(NAME,_set_arch_mach),\
377 CAT(NAME,_set_section_contents)
378 boolean (*_bfd_set_arch_mach) PARAMS ((bfd *, enum bfd_architecture,
380 boolean (*_bfd_set_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
381 file_ptr, bfd_size_type));
383 /* Routines used by the linker. */
384 #define BFD_JUMP_TABLE_LINK(NAME)\
385 CAT(NAME,_sizeof_headers),\
386 CAT(NAME,_bfd_get_relocated_section_contents),\
387 CAT(NAME,_bfd_relax_section),\
388 CAT(NAME,_bfd_link_hash_table_create),\
389 CAT(NAME,_bfd_link_add_symbols),\
390 CAT(NAME,_bfd_final_link),\
391 CAT(NAME,_bfd_link_split_section)
392 int (*_bfd_sizeof_headers) PARAMS ((bfd *, boolean));
393 bfd_byte * (*_bfd_get_relocated_section_contents) PARAMS ((bfd *,
394 struct bfd_link_info *, struct bfd_link_order *,
395 bfd_byte *data, boolean relocateable,
396 struct symbol_cache_entry **));
398 boolean (*_bfd_relax_section) PARAMS ((bfd *, struct sec *,
399 struct bfd_link_info *, boolean *again));
401 /* Create a hash table for the linker. Different backends store
402 different information in this table. */
403 struct bfd_link_hash_table *(*_bfd_link_hash_table_create) PARAMS ((bfd *));
405 /* Add symbols from this object file into the hash table. */
406 boolean (*_bfd_link_add_symbols) PARAMS ((bfd *, struct bfd_link_info *));
408 /* Do a link based on the link_order structures attached to each
409 section of the BFD. */
410 boolean (*_bfd_final_link) PARAMS ((bfd *, struct bfd_link_info *));
412 /* Should this section be split up into smaller pieces during linking. */
413 boolean (*_bfd_link_split_section) PARAMS ((bfd *, struct sec *));
415 /* Routines to handle dynamic symbols and relocs. */
416 #define BFD_JUMP_TABLE_DYNAMIC(NAME)\
417 CAT(NAME,_get_dynamic_symtab_upper_bound),\
418 CAT(NAME,_canonicalize_dynamic_symtab),\
419 CAT(NAME,_get_dynamic_reloc_upper_bound),\
420 CAT(NAME,_canonicalize_dynamic_reloc)
421 /* Get the amount of memory required to hold the dynamic symbols. */
422 long (*_bfd_get_dynamic_symtab_upper_bound) PARAMS ((bfd *));
423 /* Read in the dynamic symbols. */
424 long (*_bfd_canonicalize_dynamic_symtab)
425 PARAMS ((bfd *, struct symbol_cache_entry **));
426 /* Get the amount of memory required to hold the dynamic relocs. */
427 long (*_bfd_get_dynamic_reloc_upper_bound) PARAMS ((bfd *));
428 /* Read in the dynamic relocs. */
429 long (*_bfd_canonicalize_dynamic_reloc)
430 PARAMS ((bfd *, arelent **, struct symbol_cache_entry **));
433 Data for use by back-end routines, which isn't generic enough to belong
440 @findex bfd_set_default_target
441 @subsubsection @code{bfd_set_default_target}
444 boolean bfd_set_default_target (const char *name);
446 @strong{Description}@*
447 Set the default target vector to use when recognizing a BFD.
448 This takes the name of the target, which may be a BFD target
449 name or a configuration triplet.
451 @findex bfd_find_target
452 @subsubsection @code{bfd_find_target}
455 const bfd_target *bfd_find_target(CONST char *target_name, bfd *abfd);
457 @strong{Description}@*
458 Return a pointer to the transfer vector for the object target
459 named @var{target_name}. If @var{target_name} is @code{NULL}, choose the
460 one in the environment variable @code{GNUTARGET}; if that is null or not
461 defined, then choose the first entry in the target list.
462 Passing in the string "default" or setting the environment
463 variable to "default" will cause the first entry in the target
464 list to be returned, and "target_defaulted" will be set in the
465 BFD. This causes @code{bfd_check_format} to loop over all the
466 targets to find the one that matches the file being read.
468 @findex bfd_target_list
469 @subsubsection @code{bfd_target_list}
472 const char **bfd_target_list(void);
474 @strong{Description}@*
475 Return a freshly malloced NULL-terminated
476 vector of the names of all the valid BFD targets. Do not