1@section @code{typedef bfd}
2A BFD has type @code{bfd}; objects of this type are the
3cornerstone of any application using BFD. Using BFD
4consists of making references though the BFD and to data in the BFD.
5
6Here is the structure that defines the type @code{bfd}.  It
7contains the major data about the file and pointers
8to the rest of the data.
9
10
11@example
12
13struct bfd
14@{
15  /* A unique identifier of the BFD  */
16  unsigned int id;
17
18  /* The filename the application opened the BFD with.  */
19  const char *filename;
20
21  /* A pointer to the target jump table.  */
22  const struct bfd_target *xvec;
23
24  /* To avoid dragging too many header files into every file that
25     includes `@code{bfd.h}', IOSTREAM has been declared as a "char *",
26     and MTIME as a "long".  Their correct types, to which they
27     are cast when used, are "FILE *" and "time_t".    The iostream
28     is the result of an fopen on the filename.  However, if the
29     BFD_IN_MEMORY flag is set, then iostream is actually a pointer
30     to a bfd_in_memory struct.  */
31  void *iostream;
32
33  /* Is the file descriptor being cached?  That is, can it be closed as
34     needed, and re-opened when accessed later?  */
35  bfd_boolean cacheable;
36
37  /* Marks whether there was a default target specified when the
38     BFD was opened. This is used to select which matching algorithm
39     to use to choose the back end.  */
40  bfd_boolean target_defaulted;
41
42  /* The caching routines use these to maintain a
43     least-recently-used list of BFDs.  */
44  struct bfd *lru_prev, *lru_next;
45
46  /* When a file is closed by the caching routines, BFD retains
47     state information on the file here...  */
48  ufile_ptr where;
49
50  /* ... and here: (``once'' means at least once).  */
51  bfd_boolean opened_once;
52
53  /* Set if we have a locally maintained mtime value, rather than
54     getting it from the file each time.  */
55  bfd_boolean mtime_set;
56
57  /* File modified time, if mtime_set is TRUE.  */
58  long mtime;
59
60  /* Reserved for an unimplemented file locking extension.  */
61  int ifd;
62
63  /* The format which belongs to the BFD. (object, core, etc.)  */
64  bfd_format format;
65
66  /* The direction with which the BFD was opened.  */
67  enum bfd_direction
68    @{
69      no_direction = 0,
70      read_direction = 1,
71      write_direction = 2,
72      both_direction = 3
73    @}
74  direction;
75
76  /* Format_specific flags.  */
77  flagword flags;
78
79  /* Currently my_archive is tested before adding origin to
80     anything. I believe that this can become always an add of
81     origin, with origin set to 0 for non archive files.  */
82  ufile_ptr origin;
83
84  /* Remember when output has begun, to stop strange things
85     from happening.  */
86  bfd_boolean output_has_begun;
87
88  /* A hash table for section names.  */
89  struct bfd_hash_table section_htab;
90
91  /* Pointer to linked list of sections.  */
92  struct bfd_section *sections;
93
94  /* The place where we add to the section list.  */
95  struct bfd_section **section_tail;
96
97  /* The number of sections.  */
98  unsigned int section_count;
99
100  /* Stuff only useful for object files:
101     The start address.  */
102  bfd_vma start_address;
103
104  /* Used for input and output.  */
105  unsigned int symcount;
106
107  /* Symbol table for output BFD (with symcount entries).  */
108  struct bfd_symbol  **outsymbols;
109
110  /* Used for slurped dynamic symbol tables.  */
111  unsigned int dynsymcount;
112
113  /* Pointer to structure which contains architecture information.  */
114  const struct bfd_arch_info *arch_info;
115
116  /* Stuff only useful for archives.  */
117  void *arelt_data;
118  struct bfd *my_archive;      /* The containing archive BFD.  */
119  struct bfd *next;            /* The next BFD in the archive.  */
120  struct bfd *archive_head;    /* The first BFD in the archive.  */
121  bfd_boolean has_armap;
122
123  /* A chain of BFD structures involved in a link.  */
124  struct bfd *link_next;
125
126  /* A field used by _bfd_generic_link_add_archive_symbols.  This will
127     be used only for archive elements.  */
128  int archive_pass;
129
130  /* Used by the back end to hold private data.  */
131  union
132    @{
133      struct aout_data_struct *aout_data;
134      struct artdata *aout_ar_data;
135      struct _oasys_data *oasys_obj_data;
136      struct _oasys_ar_data *oasys_ar_data;
137      struct coff_tdata *coff_obj_data;
138      struct pe_tdata *pe_obj_data;
139      struct xcoff_tdata *xcoff_obj_data;
140      struct ecoff_tdata *ecoff_obj_data;
141      struct ieee_data_struct *ieee_data;
142      struct ieee_ar_data_struct *ieee_ar_data;
143      struct srec_data_struct *srec_data;
144      struct ihex_data_struct *ihex_data;
145      struct tekhex_data_struct *tekhex_data;
146      struct elf_obj_tdata *elf_obj_data;
147      struct nlm_obj_tdata *nlm_obj_data;
148      struct bout_data_struct *bout_data;
149      struct mmo_data_struct *mmo_data;
150      struct sun_core_struct *sun_core_data;
151      struct sco5_core_struct *sco5_core_data;
152      struct trad_core_struct *trad_core_data;
153      struct som_data_struct *som_data;
154      struct hpux_core_struct *hpux_core_data;
155      struct hppabsd_core_struct *hppabsd_core_data;
156      struct sgi_core_struct *sgi_core_data;
157      struct lynx_core_struct *lynx_core_data;
158      struct osf_core_struct *osf_core_data;
159      struct cisco_core_struct *cisco_core_data;
160      struct versados_data_struct *versados_data;
161      struct netbsd_core_struct *netbsd_core_data;
162      struct mach_o_data_struct *mach_o_data;
163      struct mach_o_fat_data_struct *mach_o_fat_data;
164      struct bfd_pef_data_struct *pef_data;
165      struct bfd_pef_xlib_data_struct *pef_xlib_data;
166      struct bfd_sym_data_struct *sym_data;
167      void *any;
168    @}
169  tdata;
170
171  /* Used by the application to hold private data.  */
172  void *usrdata;
173
174  /* Where all the allocated stuff under this BFD goes.  This is a
175     struct objalloc *, but we use void * to avoid requiring the inclusion
176     of objalloc.h.  */
177  void *memory;
178@};
179
180@end example
181@section Error reporting
182Most BFD functions return nonzero on success (check their
183individual documentation for precise semantics).  On an error,
184they call @code{bfd_set_error} to set an error condition that callers
185can check by calling @code{bfd_get_error}.
186If that returns @code{bfd_error_system_call}, then check
187@code{errno}.
188
189The easiest way to report a BFD error to the user is to
190use @code{bfd_perror}.
191
192@subsection Type @code{bfd_error_type}
193The values returned by @code{bfd_get_error} are defined by the
194enumerated type @code{bfd_error_type}.
195
196
197@example
198
199typedef enum bfd_error
200@{
201  bfd_error_no_error = 0,
202  bfd_error_system_call,
203  bfd_error_invalid_target,
204  bfd_error_wrong_format,
205  bfd_error_wrong_object_format,
206  bfd_error_invalid_operation,
207  bfd_error_no_memory,
208  bfd_error_no_symbols,
209  bfd_error_no_armap,
210  bfd_error_no_more_archived_files,
211  bfd_error_malformed_archive,
212  bfd_error_file_not_recognized,
213  bfd_error_file_ambiguously_recognized,
214  bfd_error_no_contents,
215  bfd_error_nonrepresentable_section,
216  bfd_error_no_debug_section,
217  bfd_error_bad_value,
218  bfd_error_file_truncated,
219  bfd_error_file_too_big,
220  bfd_error_invalid_error_code
221@}
222bfd_error_type;
223
224@end example
225@findex bfd_get_error
226@subsubsection @code{bfd_get_error}
227@strong{Synopsis}
228@example
229bfd_error_type bfd_get_error (void);
230@end example
231@strong{Description}@*
232Return the current BFD error condition.
233
234@findex bfd_set_error
235@subsubsection @code{bfd_set_error}
236@strong{Synopsis}
237@example
238void bfd_set_error (bfd_error_type error_tag);
239@end example
240@strong{Description}@*
241Set the BFD error condition to be @var{error_tag}.
242
243@findex bfd_errmsg
244@subsubsection @code{bfd_errmsg}
245@strong{Synopsis}
246@example
247const char *bfd_errmsg (bfd_error_type error_tag);
248@end example
249@strong{Description}@*
250Return a string describing the error @var{error_tag}, or
251the system error if @var{error_tag} is @code{bfd_error_system_call}.
252
253@findex bfd_perror
254@subsubsection @code{bfd_perror}
255@strong{Synopsis}
256@example
257void bfd_perror (const char *message);
258@end example
259@strong{Description}@*
260Print to the standard error stream a string describing the
261last BFD error that occurred, or the last system error if
262the last BFD error was a system call failure.  If @var{message}
263is non-NULL and non-empty, the error string printed is preceded
264by @var{message}, a colon, and a space.  It is followed by a newline.
265
266@subsection BFD error handler
267Some BFD functions want to print messages describing the
268problem.  They call a BFD error handler function.  This
269function may be overridden by the program.
270
271The BFD error handler acts like printf.
272
273
274@example
275
276typedef void (*bfd_error_handler_type) (const char *, ...);
277
278@end example
279@findex bfd_set_error_handler
280@subsubsection @code{bfd_set_error_handler}
281@strong{Synopsis}
282@example
283bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
284@end example
285@strong{Description}@*
286Set the BFD error handler function.  Returns the previous
287function.
288
289@findex bfd_set_error_program_name
290@subsubsection @code{bfd_set_error_program_name}
291@strong{Synopsis}
292@example
293void bfd_set_error_program_name (const char *);
294@end example
295@strong{Description}@*
296Set the program name to use when printing a BFD error.  This
297is printed before the error message followed by a colon and
298space.  The string must not be changed after it is passed to
299this function.
300
301@findex bfd_get_error_handler
302@subsubsection @code{bfd_get_error_handler}
303@strong{Synopsis}
304@example
305bfd_error_handler_type bfd_get_error_handler (void);
306@end example
307@strong{Description}@*
308Return the BFD error handler function.
309
310@findex bfd_archive_filename
311@subsubsection @code{bfd_archive_filename}
312@strong{Synopsis}
313@example
314const char *bfd_archive_filename (bfd *);
315@end example
316@strong{Description}@*
317For a BFD that is a component of an archive, returns a string
318with both the archive name and file name.  For other BFDs, just
319returns the file name.
320
321@section Symbols
322
323
324@findex bfd_get_reloc_upper_bound
325@subsubsection @code{bfd_get_reloc_upper_bound}
326@strong{Synopsis}
327@example
328long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
329@end example
330@strong{Description}@*
331Return the number of bytes required to store the
332relocation information associated with section @var{sect}
333attached to bfd @var{abfd}.  If an error occurs, return -1.
334
335@findex bfd_canonicalize_reloc
336@subsubsection @code{bfd_canonicalize_reloc}
337@strong{Synopsis}
338@example
339long bfd_canonicalize_reloc
340   (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
341@end example
342@strong{Description}@*
343Call the back end associated with the open BFD
344@var{abfd} and translate the external form of the relocation
345information attached to @var{sec} into the internal canonical
346form.  Place the table into memory at @var{loc}, which has
347been preallocated, usually by a call to
348@code{bfd_get_reloc_upper_bound}.  Returns the number of relocs, or
349-1 on error.
350
351The @var{syms} table is also needed for horrible internal magic
352reasons.
353
354@findex bfd_set_reloc
355@subsubsection @code{bfd_set_reloc}
356@strong{Synopsis}
357@example
358void bfd_set_reloc
359   (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
360@end example
361@strong{Description}@*
362Set the relocation pointer and count within
363section @var{sec} to the values @var{rel} and @var{count}.
364The argument @var{abfd} is ignored.
365
366@findex bfd_set_file_flags
367@subsubsection @code{bfd_set_file_flags}
368@strong{Synopsis}
369@example
370bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
371@end example
372@strong{Description}@*
373Set the flag word in the BFD @var{abfd} to the value @var{flags}.
374
375Possible errors are:
376@itemize @bullet
377
378@item
379@code{bfd_error_wrong_format} - The target bfd was not of object format.
380@item
381@code{bfd_error_invalid_operation} - The target bfd was open for reading.
382@item
383@code{bfd_error_invalid_operation} -
384The flag word contained a bit which was not applicable to the
385type of file.  E.g., an attempt was made to set the @code{D_PAGED} bit
386on a BFD format which does not support demand paging.
387@end itemize
388
389@findex bfd_get_arch_size
390@subsubsection @code{bfd_get_arch_size}
391@strong{Synopsis}
392@example
393int bfd_get_arch_size (bfd *abfd);
394@end example
395@strong{Description}@*
396Returns the architecture address size, in bits, as determined
397by the object file's format.  For ELF, this information is
398included in the header.
399
400@strong{Returns}@*
401Returns the arch size in bits if known, @code{-1} otherwise.
402
403@findex bfd_get_sign_extend_vma
404@subsubsection @code{bfd_get_sign_extend_vma}
405@strong{Synopsis}
406@example
407int bfd_get_sign_extend_vma (bfd *abfd);
408@end example
409@strong{Description}@*
410Indicates if the target architecture "naturally" sign extends
411an address.  Some architectures implicitly sign extend address
412values when they are converted to types larger than the size
413of an address.  For instance, bfd_get_start_address() will
414return an address sign extended to fill a bfd_vma when this is
415the case.
416
417@strong{Returns}@*
418Returns @code{1} if the target architecture is known to sign
419extend addresses, @code{0} if the target architecture is known to
420not sign extend addresses, and @code{-1} otherwise.
421
422@findex bfd_set_start_address
423@subsubsection @code{bfd_set_start_address}
424@strong{Synopsis}
425@example
426bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
427@end example
428@strong{Description}@*
429Make @var{vma} the entry point of output BFD @var{abfd}.
430
431@strong{Returns}@*
432Returns @code{TRUE} on success, @code{FALSE} otherwise.
433
434@findex bfd_get_gp_size
435@subsubsection @code{bfd_get_gp_size}
436@strong{Synopsis}
437@example
438unsigned int bfd_get_gp_size (bfd *abfd);
439@end example
440@strong{Description}@*
441Return the maximum size of objects to be optimized using the GP
442register under MIPS ECOFF.  This is typically set by the @code{-G}
443argument to the compiler, assembler or linker.
444
445@findex bfd_set_gp_size
446@subsubsection @code{bfd_set_gp_size}
447@strong{Synopsis}
448@example
449void bfd_set_gp_size (bfd *abfd, unsigned int i);
450@end example
451@strong{Description}@*
452Set the maximum size of objects to be optimized using the GP
453register under ECOFF or MIPS ELF.  This is typically set by
454the @code{-G} argument to the compiler, assembler or linker.
455
456@findex bfd_scan_vma
457@subsubsection @code{bfd_scan_vma}
458@strong{Synopsis}
459@example
460bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
461@end example
462@strong{Description}@*
463Convert, like @code{strtoul}, a numerical expression
464@var{string} into a @code{bfd_vma} integer, and return that integer.
465(Though without as many bells and whistles as @code{strtoul}.)
466The expression is assumed to be unsigned (i.e., positive).
467If given a @var{base}, it is used as the base for conversion.
468A base of 0 causes the function to interpret the string
469in hex if a leading "0x" or "0X" is found, otherwise
470in octal if a leading zero is found, otherwise in decimal.
471
472If the value would overflow, the maximum @code{bfd_vma} value is
473returned.
474
475@findex bfd_copy_private_bfd_data
476@subsubsection @code{bfd_copy_private_bfd_data}
477@strong{Synopsis}
478@example
479bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
480@end example
481@strong{Description}@*
482Copy private BFD information from the BFD @var{ibfd} to the
483the BFD @var{obfd}.  Return @code{TRUE} on success, @code{FALSE} on error.
484Possible error returns are:
485
486@itemize @bullet
487
488@item
489@code{bfd_error_no_memory} -
490Not enough memory exists to create private data for @var{obfd}.
491@end itemize
492@example
493#define bfd_copy_private_bfd_data(ibfd, obfd) \
494     BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
495               (ibfd, obfd))
496@end example
497
498@findex bfd_merge_private_bfd_data
499@subsubsection @code{bfd_merge_private_bfd_data}
500@strong{Synopsis}
501@example
502bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
503@end example
504@strong{Description}@*
505Merge private BFD information from the BFD @var{ibfd} to the
506the output file BFD @var{obfd} when linking.  Return @code{TRUE}
507on success, @code{FALSE} on error.  Possible error returns are:
508
509@itemize @bullet
510
511@item
512@code{bfd_error_no_memory} -
513Not enough memory exists to create private data for @var{obfd}.
514@end itemize
515@example
516#define bfd_merge_private_bfd_data(ibfd, obfd) \
517     BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
518               (ibfd, obfd))
519@end example
520
521@findex bfd_set_private_flags
522@subsubsection @code{bfd_set_private_flags}
523@strong{Synopsis}
524@example
525bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
526@end example
527@strong{Description}@*
528Set private BFD flag information in the BFD @var{abfd}.
529Return @code{TRUE} on success, @code{FALSE} on error.  Possible error
530returns are:
531
532@itemize @bullet
533
534@item
535@code{bfd_error_no_memory} -
536Not enough memory exists to create private data for @var{obfd}.
537@end itemize
538@example
539#define bfd_set_private_flags(abfd, flags) \
540     BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
541@end example
542
543@findex Other functions
544@subsubsection @code{Other functions}
545@strong{Description}@*
546The following functions exist but have not yet been documented.
547@example
548#define bfd_sizeof_headers(abfd, reloc) \
549       BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
550
551#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
552       BFD_SEND (abfd, _bfd_find_nearest_line, \
553                 (abfd, sec, syms, off, file, func, line))
554
555#define bfd_debug_info_start(abfd) \
556       BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
557
558#define bfd_debug_info_end(abfd) \
559       BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
560
561#define bfd_debug_info_accumulate(abfd, section) \
562       BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
563
564#define bfd_stat_arch_elt(abfd, stat) \
565       BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
566
567#define bfd_update_armap_timestamp(abfd) \
568       BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
569
570#define bfd_set_arch_mach(abfd, arch, mach)\
571       BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
572
573#define bfd_relax_section(abfd, section, link_info, again) \
574       BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
575
576#define bfd_gc_sections(abfd, link_info) \
577       BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
578
579#define bfd_merge_sections(abfd, link_info) \
580       BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
581
582#define bfd_discard_group(abfd, sec) \
583       BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
584
585#define bfd_link_hash_table_create(abfd) \
586       BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
587
588#define bfd_link_hash_table_free(abfd, hash) \
589       BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
590
591#define bfd_link_add_symbols(abfd, info) \
592       BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
593
594#define bfd_link_just_syms(sec, info) \
595       BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
596
597#define bfd_final_link(abfd, info) \
598       BFD_SEND (abfd, _bfd_final_link, (abfd, info))
599
600#define bfd_free_cached_info(abfd) \
601       BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
602
603#define bfd_get_dynamic_symtab_upper_bound(abfd) \
604       BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
605
606#define bfd_print_private_bfd_data(abfd, file)\
607       BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
608
609#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
610       BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
611
612#define bfd_get_dynamic_reloc_upper_bound(abfd) \
613       BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
614
615#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
616       BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
617
618extern bfd_byte *bfd_get_relocated_section_contents
619  (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
620   bfd_boolean, asymbol **);
621
622@end example
623
624@findex bfd_alt_mach_code
625@subsubsection @code{bfd_alt_mach_code}
626@strong{Synopsis}
627@example
628bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
629@end example
630@strong{Description}@*
631When more than one machine code number is available for the
632same machine type, this function can be used to switch between
633the preferred one (alternative == 0) and any others.  Currently,
634only ELF supports this feature, with up to two alternate
635machine codes.
636
637
638@example
639struct bfd_preserve
640@{
641  void *marker;
642  void *tdata;
643  flagword flags;
644  const struct bfd_arch_info *arch_info;
645  struct bfd_section *sections;
646  struct bfd_section **section_tail;
647  unsigned int section_count;
648  struct bfd_hash_table section_htab;
649@};
650
651@end example
652@findex bfd_preserve_save
653@subsubsection @code{bfd_preserve_save}
654@strong{Synopsis}
655@example
656bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
657@end example
658@strong{Description}@*
659When testing an object for compatibility with a particular
660target back-end, the back-end object_p function needs to set
661up certain fields in the bfd on successfully recognizing the
662object.  This typically happens in a piecemeal fashion, with
663failures possible at many points.  On failure, the bfd is
664supposed to be restored to its initial state, which is
665virtually impossible.  However, restoring a subset of the bfd
666state works in practice.  This function stores the subset and
667reinitializes the bfd.
668
669@findex bfd_preserve_restore
670@subsubsection @code{bfd_preserve_restore}
671@strong{Synopsis}
672@example
673void bfd_preserve_restore (bfd *, struct bfd_preserve *);
674@end example
675@strong{Description}@*
676This function restores bfd state saved by bfd_preserve_save.
677If MARKER is non-NULL in struct bfd_preserve then that block
678and all subsequently bfd_alloc'd memory is freed.
679
680@findex bfd_preserve_finish
681@subsubsection @code{bfd_preserve_finish}
682@strong{Synopsis}
683@example
684void bfd_preserve_finish (bfd *, struct bfd_preserve *);
685@end example
686@strong{Description}@*
687This function should be called when the bfd state saved by
688bfd_preserve_save is no longer needed.  ie. when the back-end
689object_p function returns with success.
690
691