daily update
[binutils.git] / bfd / bfd.c
blob733f6ee0272db1beb8b385505719f27f45929391
1 /* Generic BFD library interface and support routines.
2 Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
3 2000, 2001, 2002, 2003, 2004, 2005, 2006
4 Free Software Foundation, Inc.
5 Written by Cygnus Support.
7 This file is part of BFD, the Binary File Descriptor library.
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */
24 SECTION
25 <<typedef bfd>>
27 A BFD has type <<bfd>>; objects of this type are the
28 cornerstone of any application using BFD. Using BFD
29 consists of making references though the BFD and to data in the BFD.
31 Here is the structure that defines the type <<bfd>>. It
32 contains the major data about the file and pointers
33 to the rest of the data.
35 CODE_FRAGMENT
37 .struct bfd
39 . {* A unique identifier of the BFD *}
40 . unsigned int id;
42 . {* The filename the application opened the BFD with. *}
43 . const char *filename;
45 . {* A pointer to the target jump table. *}
46 . const struct bfd_target *xvec;
48 . {* The IOSTREAM, and corresponding IO vector that provide access
49 . to the file backing the BFD. *}
50 . void *iostream;
51 . const struct bfd_iovec *iovec;
53 . {* Is the file descriptor being cached? That is, can it be closed as
54 . needed, and re-opened when accessed later? *}
55 . bfd_boolean cacheable;
57 . {* Marks whether there was a default target specified when the
58 . BFD was opened. This is used to select which matching algorithm
59 . to use to choose the back end. *}
60 . bfd_boolean target_defaulted;
62 . {* The caching routines use these to maintain a
63 . least-recently-used list of BFDs. *}
64 . struct bfd *lru_prev, *lru_next;
66 . {* When a file is closed by the caching routines, BFD retains
67 . state information on the file here... *}
68 . ufile_ptr where;
70 . {* ... and here: (``once'' means at least once). *}
71 . bfd_boolean opened_once;
73 . {* Set if we have a locally maintained mtime value, rather than
74 . getting it from the file each time. *}
75 . bfd_boolean mtime_set;
77 . {* File modified time, if mtime_set is TRUE. *}
78 . long mtime;
80 . {* Reserved for an unimplemented file locking extension. *}
81 . int ifd;
83 . {* The format which belongs to the BFD. (object, core, etc.) *}
84 . bfd_format format;
86 . {* The direction with which the BFD was opened. *}
87 . enum bfd_direction
88 . {
89 . no_direction = 0,
90 . read_direction = 1,
91 . write_direction = 2,
92 . both_direction = 3
93 . }
94 . direction;
96 . {* Format_specific flags. *}
97 . flagword flags;
99 . {* Currently my_archive is tested before adding origin to
100 . anything. I believe that this can become always an add of
101 . origin, with origin set to 0 for non archive files. *}
102 . ufile_ptr origin;
104 . {* Remember when output has begun, to stop strange things
105 . from happening. *}
106 . bfd_boolean output_has_begun;
108 . {* A hash table for section names. *}
109 . struct bfd_hash_table section_htab;
111 . {* Pointer to linked list of sections. *}
112 . struct bfd_section *sections;
114 . {* The last section on the section list. *}
115 . struct bfd_section *section_last;
117 . {* The number of sections. *}
118 . unsigned int section_count;
120 . {* Stuff only useful for object files:
121 . The start address. *}
122 . bfd_vma start_address;
124 . {* Used for input and output. *}
125 . unsigned int symcount;
127 . {* Symbol table for output BFD (with symcount entries). *}
128 . struct bfd_symbol **outsymbols;
130 . {* Used for slurped dynamic symbol tables. *}
131 . unsigned int dynsymcount;
133 . {* Pointer to structure which contains architecture information. *}
134 . const struct bfd_arch_info *arch_info;
136 . {* Flag set if symbols from this BFD should not be exported. *}
137 . bfd_boolean no_export;
139 . {* Stuff only useful for archives. *}
140 . void *arelt_data;
141 . struct bfd *my_archive; {* The containing archive BFD. *}
142 . struct bfd *next; {* The next BFD in the archive. *}
143 . struct bfd *archive_head; {* The first BFD in the archive. *}
144 . bfd_boolean has_armap;
146 . {* A chain of BFD structures involved in a link. *}
147 . struct bfd *link_next;
149 . {* A field used by _bfd_generic_link_add_archive_symbols. This will
150 . be used only for archive elements. *}
151 . int archive_pass;
153 . {* Used by the back end to hold private data. *}
154 . union
156 . struct aout_data_struct *aout_data;
157 . struct artdata *aout_ar_data;
158 . struct _oasys_data *oasys_obj_data;
159 . struct _oasys_ar_data *oasys_ar_data;
160 . struct coff_tdata *coff_obj_data;
161 . struct pe_tdata *pe_obj_data;
162 . struct xcoff_tdata *xcoff_obj_data;
163 . struct ecoff_tdata *ecoff_obj_data;
164 . struct ieee_data_struct *ieee_data;
165 . struct ieee_ar_data_struct *ieee_ar_data;
166 . struct srec_data_struct *srec_data;
167 . struct ihex_data_struct *ihex_data;
168 . struct tekhex_data_struct *tekhex_data;
169 . struct elf_obj_tdata *elf_obj_data;
170 . struct nlm_obj_tdata *nlm_obj_data;
171 . struct bout_data_struct *bout_data;
172 . struct mmo_data_struct *mmo_data;
173 . struct sun_core_struct *sun_core_data;
174 . struct sco5_core_struct *sco5_core_data;
175 . struct trad_core_struct *trad_core_data;
176 . struct som_data_struct *som_data;
177 . struct hpux_core_struct *hpux_core_data;
178 . struct hppabsd_core_struct *hppabsd_core_data;
179 . struct sgi_core_struct *sgi_core_data;
180 . struct lynx_core_struct *lynx_core_data;
181 . struct osf_core_struct *osf_core_data;
182 . struct cisco_core_struct *cisco_core_data;
183 . struct versados_data_struct *versados_data;
184 . struct netbsd_core_struct *netbsd_core_data;
185 . struct mach_o_data_struct *mach_o_data;
186 . struct mach_o_fat_data_struct *mach_o_fat_data;
187 . struct bfd_pef_data_struct *pef_data;
188 . struct bfd_pef_xlib_data_struct *pef_xlib_data;
189 . struct bfd_sym_data_struct *sym_data;
190 . void *any;
192 . tdata;
194 . {* Used by the application to hold private data. *}
195 . void *usrdata;
197 . {* Where all the allocated stuff under this BFD goes. This is a
198 . struct objalloc *, but we use void * to avoid requiring the inclusion
199 . of objalloc.h. *}
200 . void *memory;
205 #include "bfd.h"
206 #include "bfdver.h"
207 #include "sysdep.h"
208 #include <stdarg.h>
209 #include "libiberty.h"
210 #include "safe-ctype.h"
211 #include "bfdlink.h"
212 #include "libbfd.h"
213 #include "coff/internal.h"
214 #include "coff/sym.h"
215 #include "libcoff.h"
216 #include "libecoff.h"
217 #undef obj_symbols
218 #include "elf-bfd.h"
220 #ifndef EXIT_FAILURE
221 #define EXIT_FAILURE 1
222 #endif
225 /* provide storage for subsystem, stack and heap data which may have been
226 passed in on the command line. Ld puts this data into a bfd_link_info
227 struct which ultimately gets passed in to the bfd. When it arrives, copy
228 it to the following struct so that the data will be available in coffcode.h
229 where it is needed. The typedef's used are defined in bfd.h */
232 SECTION
233 Error reporting
235 Most BFD functions return nonzero on success (check their
236 individual documentation for precise semantics). On an error,
237 they call <<bfd_set_error>> to set an error condition that callers
238 can check by calling <<bfd_get_error>>.
239 If that returns <<bfd_error_system_call>>, then check
240 <<errno>>.
242 The easiest way to report a BFD error to the user is to
243 use <<bfd_perror>>.
245 SUBSECTION
246 Type <<bfd_error_type>>
248 The values returned by <<bfd_get_error>> are defined by the
249 enumerated type <<bfd_error_type>>.
251 CODE_FRAGMENT
253 .typedef enum bfd_error
255 . bfd_error_no_error = 0,
256 . bfd_error_system_call,
257 . bfd_error_invalid_target,
258 . bfd_error_wrong_format,
259 . bfd_error_wrong_object_format,
260 . bfd_error_invalid_operation,
261 . bfd_error_no_memory,
262 . bfd_error_no_symbols,
263 . bfd_error_no_armap,
264 . bfd_error_no_more_archived_files,
265 . bfd_error_malformed_archive,
266 . bfd_error_file_not_recognized,
267 . bfd_error_file_ambiguously_recognized,
268 . bfd_error_no_contents,
269 . bfd_error_nonrepresentable_section,
270 . bfd_error_no_debug_section,
271 . bfd_error_bad_value,
272 . bfd_error_file_truncated,
273 . bfd_error_file_too_big,
274 . bfd_error_invalid_error_code
276 .bfd_error_type;
280 static bfd_error_type bfd_error = bfd_error_no_error;
282 const char *const bfd_errmsgs[] =
284 N_("No error"),
285 N_("System call error"),
286 N_("Invalid bfd target"),
287 N_("File in wrong format"),
288 N_("Archive object file in wrong format"),
289 N_("Invalid operation"),
290 N_("Memory exhausted"),
291 N_("No symbols"),
292 N_("Archive has no index; run ranlib to add one"),
293 N_("No more archived files"),
294 N_("Malformed archive"),
295 N_("File format not recognized"),
296 N_("File format is ambiguous"),
297 N_("Section has no contents"),
298 N_("Nonrepresentable section on output"),
299 N_("Symbol needs debug section which does not exist"),
300 N_("Bad value"),
301 N_("File truncated"),
302 N_("File too big"),
303 N_("#<Invalid error code>")
307 FUNCTION
308 bfd_get_error
310 SYNOPSIS
311 bfd_error_type bfd_get_error (void);
313 DESCRIPTION
314 Return the current BFD error condition.
317 bfd_error_type
318 bfd_get_error (void)
320 return bfd_error;
324 FUNCTION
325 bfd_set_error
327 SYNOPSIS
328 void bfd_set_error (bfd_error_type error_tag);
330 DESCRIPTION
331 Set the BFD error condition to be @var{error_tag}.
334 void
335 bfd_set_error (bfd_error_type error_tag)
337 bfd_error = error_tag;
341 FUNCTION
342 bfd_errmsg
344 SYNOPSIS
345 const char *bfd_errmsg (bfd_error_type error_tag);
347 DESCRIPTION
348 Return a string describing the error @var{error_tag}, or
349 the system error if @var{error_tag} is <<bfd_error_system_call>>.
352 const char *
353 bfd_errmsg (bfd_error_type error_tag)
355 #ifndef errno
356 extern int errno;
357 #endif
358 if (error_tag == bfd_error_system_call)
359 return xstrerror (errno);
361 if (error_tag > bfd_error_invalid_error_code)
362 error_tag = bfd_error_invalid_error_code; /* sanity check */
364 return _(bfd_errmsgs [error_tag]);
368 FUNCTION
369 bfd_perror
371 SYNOPSIS
372 void bfd_perror (const char *message);
374 DESCRIPTION
375 Print to the standard error stream a string describing the
376 last BFD error that occurred, or the last system error if
377 the last BFD error was a system call failure. If @var{message}
378 is non-NULL and non-empty, the error string printed is preceded
379 by @var{message}, a colon, and a space. It is followed by a newline.
382 void
383 bfd_perror (const char *message)
385 if (bfd_get_error () == bfd_error_system_call)
386 /* Must be a system error then. */
387 perror ((char *) message);
388 else
390 if (message == NULL || *message == '\0')
391 fprintf (stderr, "%s\n", bfd_errmsg (bfd_get_error ()));
392 else
393 fprintf (stderr, "%s: %s\n", message, bfd_errmsg (bfd_get_error ()));
398 SUBSECTION
399 BFD error handler
401 Some BFD functions want to print messages describing the
402 problem. They call a BFD error handler function. This
403 function may be overridden by the program.
405 The BFD error handler acts like printf.
407 CODE_FRAGMENT
409 .typedef void (*bfd_error_handler_type) (const char *, ...);
413 /* The program name used when printing BFD error messages. */
415 static const char *_bfd_error_program_name;
417 /* This is the default routine to handle BFD error messages.
418 Like fprintf (stderr, ...), but also handles some extra format specifiers.
420 %A section name from section. For group components, print group name too.
421 %B file name from bfd. For archive components, prints archive too.
424 void
425 _bfd_default_error_handler (const char *fmt, ...)
427 va_list ap;
428 char *bufp;
429 const char *new_fmt, *p;
430 size_t avail = 1000;
431 char buf[1000];
433 if (_bfd_error_program_name != NULL)
434 fprintf (stderr, "%s: ", _bfd_error_program_name);
435 else
436 fprintf (stderr, "BFD: ");
438 va_start (ap, fmt);
439 new_fmt = fmt;
440 bufp = buf;
442 /* Reserve enough space for the existing format string. */
443 avail -= strlen (fmt) + 1;
444 if (avail > 1000)
445 _exit (EXIT_FAILURE);
447 p = fmt;
448 while (1)
450 char *q;
451 size_t len, extra, trim;
453 p = strchr (p, '%');
454 if (p == NULL || p[1] == '\0')
456 if (new_fmt == buf)
458 len = strlen (fmt);
459 memcpy (bufp, fmt, len + 1);
461 break;
464 if (p[1] == 'A' || p[1] == 'B')
466 len = p - fmt;
467 memcpy (bufp, fmt, len);
468 bufp += len;
469 fmt = p + 2;
470 new_fmt = buf;
472 /* If we run out of space, tough, you lose your ridiculously
473 long file or section name. It's not safe to try to alloc
474 memory here; We might be printing an out of memory message. */
475 if (avail == 0)
477 *bufp++ = '*';
478 *bufp++ = '*';
479 *bufp = '\0';
481 else
483 if (p[1] == 'B')
485 bfd *abfd = va_arg (ap, bfd *);
486 if (abfd->my_archive)
487 snprintf (bufp, avail, "%s(%s)",
488 abfd->my_archive->filename, abfd->filename);
489 else
490 snprintf (bufp, avail, "%s", abfd->filename);
492 else
494 asection *sec = va_arg (ap, asection *);
495 bfd *abfd = sec->owner;
496 const char *group = NULL;
497 struct coff_comdat_info *ci;
499 if (abfd != NULL
500 && bfd_get_flavour (abfd) == bfd_target_elf_flavour
501 && elf_next_in_group (sec) != NULL
502 && (sec->flags & SEC_GROUP) == 0)
503 group = elf_group_name (sec);
504 else if (abfd != NULL
505 && bfd_get_flavour (abfd) == bfd_target_coff_flavour
506 && (ci = bfd_coff_get_comdat_section (sec->owner,
507 sec)) != NULL)
508 group = ci->name;
509 if (group != NULL)
510 snprintf (bufp, avail, "%s[%s]", sec->name, group);
511 else
512 snprintf (bufp, avail, "%s", sec->name);
514 len = strlen (bufp);
515 avail = avail - len + 2;
517 /* We need to replace any '%' we printed by "%%".
518 First count how many. */
519 q = bufp;
520 bufp += len;
521 extra = 0;
522 while ((q = strchr (q, '%')) != NULL)
524 ++q;
525 ++extra;
528 /* If there isn't room, trim off the end of the string. */
529 q = bufp;
530 bufp += extra;
531 if (extra > avail)
533 trim = extra - avail;
534 bufp -= trim;
537 if (*--q == '%')
538 --extra;
540 while (--trim != 0);
541 *q = '\0';
542 avail = extra;
544 avail -= extra;
546 /* Now double all '%' chars, shuffling the string as we go. */
547 while (extra != 0)
549 while ((q[extra] = *q) != '%')
550 --q;
551 q[--extra] = '%';
552 --q;
556 p = p + 2;
559 vfprintf (stderr, new_fmt, ap);
560 va_end (ap);
562 putc ('\n', stderr);
565 /* This is a function pointer to the routine which should handle BFD
566 error messages. It is called when a BFD routine encounters an
567 error for which it wants to print a message. Going through a
568 function pointer permits a program linked against BFD to intercept
569 the messages and deal with them itself. */
571 bfd_error_handler_type _bfd_error_handler = _bfd_default_error_handler;
574 FUNCTION
575 bfd_set_error_handler
577 SYNOPSIS
578 bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
580 DESCRIPTION
581 Set the BFD error handler function. Returns the previous
582 function.
585 bfd_error_handler_type
586 bfd_set_error_handler (bfd_error_handler_type pnew)
588 bfd_error_handler_type pold;
590 pold = _bfd_error_handler;
591 _bfd_error_handler = pnew;
592 return pold;
596 FUNCTION
597 bfd_set_error_program_name
599 SYNOPSIS
600 void bfd_set_error_program_name (const char *);
602 DESCRIPTION
603 Set the program name to use when printing a BFD error. This
604 is printed before the error message followed by a colon and
605 space. The string must not be changed after it is passed to
606 this function.
609 void
610 bfd_set_error_program_name (const char *name)
612 _bfd_error_program_name = name;
616 FUNCTION
617 bfd_get_error_handler
619 SYNOPSIS
620 bfd_error_handler_type bfd_get_error_handler (void);
622 DESCRIPTION
623 Return the BFD error handler function.
626 bfd_error_handler_type
627 bfd_get_error_handler (void)
629 return _bfd_error_handler;
633 SECTION
634 Miscellaneous
636 SUBSECTION
637 Miscellaneous functions
641 FUNCTION
642 bfd_get_reloc_upper_bound
644 SYNOPSIS
645 long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
647 DESCRIPTION
648 Return the number of bytes required to store the
649 relocation information associated with section @var{sect}
650 attached to bfd @var{abfd}. If an error occurs, return -1.
654 long
655 bfd_get_reloc_upper_bound (bfd *abfd, sec_ptr asect)
657 if (abfd->format != bfd_object)
659 bfd_set_error (bfd_error_invalid_operation);
660 return -1;
663 return BFD_SEND (abfd, _get_reloc_upper_bound, (abfd, asect));
667 FUNCTION
668 bfd_canonicalize_reloc
670 SYNOPSIS
671 long bfd_canonicalize_reloc
672 (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
674 DESCRIPTION
675 Call the back end associated with the open BFD
676 @var{abfd} and translate the external form of the relocation
677 information attached to @var{sec} into the internal canonical
678 form. Place the table into memory at @var{loc}, which has
679 been preallocated, usually by a call to
680 <<bfd_get_reloc_upper_bound>>. Returns the number of relocs, or
681 -1 on error.
683 The @var{syms} table is also needed for horrible internal magic
684 reasons.
687 long
688 bfd_canonicalize_reloc (bfd *abfd,
689 sec_ptr asect,
690 arelent **location,
691 asymbol **symbols)
693 if (abfd->format != bfd_object)
695 bfd_set_error (bfd_error_invalid_operation);
696 return -1;
699 return BFD_SEND (abfd, _bfd_canonicalize_reloc,
700 (abfd, asect, location, symbols));
704 FUNCTION
705 bfd_set_reloc
707 SYNOPSIS
708 void bfd_set_reloc
709 (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
711 DESCRIPTION
712 Set the relocation pointer and count within
713 section @var{sec} to the values @var{rel} and @var{count}.
714 The argument @var{abfd} is ignored.
718 void
719 bfd_set_reloc (bfd *ignore_abfd ATTRIBUTE_UNUSED,
720 sec_ptr asect,
721 arelent **location,
722 unsigned int count)
724 asect->orelocation = location;
725 asect->reloc_count = count;
729 FUNCTION
730 bfd_set_file_flags
732 SYNOPSIS
733 bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
735 DESCRIPTION
736 Set the flag word in the BFD @var{abfd} to the value @var{flags}.
738 Possible errors are:
739 o <<bfd_error_wrong_format>> - The target bfd was not of object format.
740 o <<bfd_error_invalid_operation>> - The target bfd was open for reading.
741 o <<bfd_error_invalid_operation>> -
742 The flag word contained a bit which was not applicable to the
743 type of file. E.g., an attempt was made to set the <<D_PAGED>> bit
744 on a BFD format which does not support demand paging.
748 bfd_boolean
749 bfd_set_file_flags (bfd *abfd, flagword flags)
751 if (abfd->format != bfd_object)
753 bfd_set_error (bfd_error_wrong_format);
754 return FALSE;
757 if (bfd_read_p (abfd))
759 bfd_set_error (bfd_error_invalid_operation);
760 return FALSE;
763 bfd_get_file_flags (abfd) = flags;
764 if ((flags & bfd_applicable_file_flags (abfd)) != flags)
766 bfd_set_error (bfd_error_invalid_operation);
767 return FALSE;
770 return TRUE;
773 void
774 bfd_assert (const char *file, int line)
776 (*_bfd_error_handler) (_("BFD %s assertion fail %s:%d"),
777 BFD_VERSION_STRING, file, line);
780 /* A more or less friendly abort message. In libbfd.h abort is
781 defined to call this function. */
783 void
784 _bfd_abort (const char *file, int line, const char *fn)
786 if (fn != NULL)
787 (*_bfd_error_handler)
788 (_("BFD %s internal error, aborting at %s line %d in %s\n"),
789 BFD_VERSION_STRING, file, line, fn);
790 else
791 (*_bfd_error_handler)
792 (_("BFD %s internal error, aborting at %s line %d\n"),
793 BFD_VERSION_STRING, file, line);
794 (*_bfd_error_handler) (_("Please report this bug.\n"));
795 _exit (EXIT_FAILURE);
799 FUNCTION
800 bfd_get_arch_size
802 SYNOPSIS
803 int bfd_get_arch_size (bfd *abfd);
805 DESCRIPTION
806 Returns the architecture address size, in bits, as determined
807 by the object file's format. For ELF, this information is
808 included in the header.
810 RETURNS
811 Returns the arch size in bits if known, <<-1>> otherwise.
815 bfd_get_arch_size (bfd *abfd)
817 if (abfd->xvec->flavour == bfd_target_elf_flavour)
818 return get_elf_backend_data (abfd)->s->arch_size;
820 return -1;
824 FUNCTION
825 bfd_get_sign_extend_vma
827 SYNOPSIS
828 int bfd_get_sign_extend_vma (bfd *abfd);
830 DESCRIPTION
831 Indicates if the target architecture "naturally" sign extends
832 an address. Some architectures implicitly sign extend address
833 values when they are converted to types larger than the size
834 of an address. For instance, bfd_get_start_address() will
835 return an address sign extended to fill a bfd_vma when this is
836 the case.
838 RETURNS
839 Returns <<1>> if the target architecture is known to sign
840 extend addresses, <<0>> if the target architecture is known to
841 not sign extend addresses, and <<-1>> otherwise.
845 bfd_get_sign_extend_vma (bfd *abfd)
847 char *name;
849 if (bfd_get_flavour (abfd) == bfd_target_elf_flavour)
850 return get_elf_backend_data (abfd)->sign_extend_vma;
852 name = bfd_get_target (abfd);
854 /* Return a proper value for DJGPP & PE COFF (x86 COFF variants).
855 This function is required for DWARF2 support, but there is
856 no place to store this information in the COFF back end.
857 Should enough other COFF targets add support for DWARF2,
858 a place will have to be found. Until then, this hack will do. */
859 if (strncmp (name, "coff-go32", sizeof ("coff-go32") - 1) == 0
860 || strcmp (name, "pe-i386") == 0
861 || strcmp (name, "pei-i386") == 0)
862 return 1;
864 bfd_set_error (bfd_error_wrong_format);
865 return -1;
869 FUNCTION
870 bfd_set_start_address
872 SYNOPSIS
873 bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
875 DESCRIPTION
876 Make @var{vma} the entry point of output BFD @var{abfd}.
878 RETURNS
879 Returns <<TRUE>> on success, <<FALSE>> otherwise.
882 bfd_boolean
883 bfd_set_start_address (bfd *abfd, bfd_vma vma)
885 abfd->start_address = vma;
886 return TRUE;
890 FUNCTION
891 bfd_get_gp_size
893 SYNOPSIS
894 unsigned int bfd_get_gp_size (bfd *abfd);
896 DESCRIPTION
897 Return the maximum size of objects to be optimized using the GP
898 register under MIPS ECOFF. This is typically set by the <<-G>>
899 argument to the compiler, assembler or linker.
902 unsigned int
903 bfd_get_gp_size (bfd *abfd)
905 if (abfd->format == bfd_object)
907 if (abfd->xvec->flavour == bfd_target_ecoff_flavour)
908 return ecoff_data (abfd)->gp_size;
909 else if (abfd->xvec->flavour == bfd_target_elf_flavour)
910 return elf_gp_size (abfd);
912 return 0;
916 FUNCTION
917 bfd_set_gp_size
919 SYNOPSIS
920 void bfd_set_gp_size (bfd *abfd, unsigned int i);
922 DESCRIPTION
923 Set the maximum size of objects to be optimized using the GP
924 register under ECOFF or MIPS ELF. This is typically set by
925 the <<-G>> argument to the compiler, assembler or linker.
928 void
929 bfd_set_gp_size (bfd *abfd, unsigned int i)
931 /* Don't try to set GP size on an archive or core file! */
932 if (abfd->format != bfd_object)
933 return;
935 if (abfd->xvec->flavour == bfd_target_ecoff_flavour)
936 ecoff_data (abfd)->gp_size = i;
937 else if (abfd->xvec->flavour == bfd_target_elf_flavour)
938 elf_gp_size (abfd) = i;
941 /* Get the GP value. This is an internal function used by some of the
942 relocation special_function routines on targets which support a GP
943 register. */
945 bfd_vma
946 _bfd_get_gp_value (bfd *abfd)
948 if (! abfd)
949 return 0;
950 if (abfd->format != bfd_object)
951 return 0;
953 if (abfd->xvec->flavour == bfd_target_ecoff_flavour)
954 return ecoff_data (abfd)->gp;
955 else if (abfd->xvec->flavour == bfd_target_elf_flavour)
956 return elf_gp (abfd);
958 return 0;
961 /* Set the GP value. */
963 void
964 _bfd_set_gp_value (bfd *abfd, bfd_vma v)
966 if (! abfd)
967 BFD_FAIL ();
968 if (abfd->format != bfd_object)
969 return;
971 if (abfd->xvec->flavour == bfd_target_ecoff_flavour)
972 ecoff_data (abfd)->gp = v;
973 else if (abfd->xvec->flavour == bfd_target_elf_flavour)
974 elf_gp (abfd) = v;
978 FUNCTION
979 bfd_scan_vma
981 SYNOPSIS
982 bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
984 DESCRIPTION
985 Convert, like <<strtoul>>, a numerical expression
986 @var{string} into a <<bfd_vma>> integer, and return that integer.
987 (Though without as many bells and whistles as <<strtoul>>.)
988 The expression is assumed to be unsigned (i.e., positive).
989 If given a @var{base}, it is used as the base for conversion.
990 A base of 0 causes the function to interpret the string
991 in hex if a leading "0x" or "0X" is found, otherwise
992 in octal if a leading zero is found, otherwise in decimal.
994 If the value would overflow, the maximum <<bfd_vma>> value is
995 returned.
998 bfd_vma
999 bfd_scan_vma (const char *string, const char **end, int base)
1001 bfd_vma value;
1002 bfd_vma cutoff;
1003 unsigned int cutlim;
1004 int overflow;
1006 /* Let the host do it if possible. */
1007 if (sizeof (bfd_vma) <= sizeof (unsigned long))
1008 return strtoul (string, (char **) end, base);
1010 #ifdef HAVE_STRTOULL
1011 if (sizeof (bfd_vma) <= sizeof (unsigned long long))
1012 return strtoull (string, (char **) end, base);
1013 #endif
1015 if (base == 0)
1017 if (string[0] == '0')
1019 if ((string[1] == 'x') || (string[1] == 'X'))
1020 base = 16;
1021 else
1022 base = 8;
1026 if ((base < 2) || (base > 36))
1027 base = 10;
1029 if (base == 16
1030 && string[0] == '0'
1031 && (string[1] == 'x' || string[1] == 'X')
1032 && ISXDIGIT (string[2]))
1034 string += 2;
1037 cutoff = (~ (bfd_vma) 0) / (bfd_vma) base;
1038 cutlim = (~ (bfd_vma) 0) % (bfd_vma) base;
1039 value = 0;
1040 overflow = 0;
1041 while (1)
1043 unsigned int digit;
1045 digit = *string;
1046 if (ISDIGIT (digit))
1047 digit = digit - '0';
1048 else if (ISALPHA (digit))
1049 digit = TOUPPER (digit) - 'A' + 10;
1050 else
1051 break;
1052 if (digit >= (unsigned int) base)
1053 break;
1054 if (value > cutoff || (value == cutoff && digit > cutlim))
1055 overflow = 1;
1056 value = value * base + digit;
1057 ++string;
1060 if (overflow)
1061 value = ~ (bfd_vma) 0;
1063 if (end != NULL)
1064 *end = string;
1066 return value;
1070 FUNCTION
1071 bfd_copy_private_header_data
1073 SYNOPSIS
1074 bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
1076 DESCRIPTION
1077 Copy private BFD header information from the BFD @var{ibfd} to the
1078 the BFD @var{obfd}. This copies information that may require
1079 sections to exist, but does not require symbol tables. Return
1080 <<true>> on success, <<false>> on error.
1081 Possible error returns are:
1083 o <<bfd_error_no_memory>> -
1084 Not enough memory exists to create private data for @var{obfd}.
1086 .#define bfd_copy_private_header_data(ibfd, obfd) \
1087 . BFD_SEND (obfd, _bfd_copy_private_header_data, \
1088 . (ibfd, obfd))
1093 FUNCTION
1094 bfd_copy_private_bfd_data
1096 SYNOPSIS
1097 bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
1099 DESCRIPTION
1100 Copy private BFD information from the BFD @var{ibfd} to the
1101 the BFD @var{obfd}. Return <<TRUE>> on success, <<FALSE>> on error.
1102 Possible error returns are:
1104 o <<bfd_error_no_memory>> -
1105 Not enough memory exists to create private data for @var{obfd}.
1107 .#define bfd_copy_private_bfd_data(ibfd, obfd) \
1108 . BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
1109 . (ibfd, obfd))
1114 FUNCTION
1115 bfd_merge_private_bfd_data
1117 SYNOPSIS
1118 bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
1120 DESCRIPTION
1121 Merge private BFD information from the BFD @var{ibfd} to the
1122 the output file BFD @var{obfd} when linking. Return <<TRUE>>
1123 on success, <<FALSE>> on error. Possible error returns are:
1125 o <<bfd_error_no_memory>> -
1126 Not enough memory exists to create private data for @var{obfd}.
1128 .#define bfd_merge_private_bfd_data(ibfd, obfd) \
1129 . BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
1130 . (ibfd, obfd))
1135 FUNCTION
1136 bfd_set_private_flags
1138 SYNOPSIS
1139 bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
1141 DESCRIPTION
1142 Set private BFD flag information in the BFD @var{abfd}.
1143 Return <<TRUE>> on success, <<FALSE>> on error. Possible error
1144 returns are:
1146 o <<bfd_error_no_memory>> -
1147 Not enough memory exists to create private data for @var{obfd}.
1149 .#define bfd_set_private_flags(abfd, flags) \
1150 . BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
1155 FUNCTION
1156 Other functions
1158 DESCRIPTION
1159 The following functions exist but have not yet been documented.
1161 .#define bfd_sizeof_headers(abfd, reloc) \
1162 . BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
1164 .#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
1165 . BFD_SEND (abfd, _bfd_find_nearest_line, \
1166 . (abfd, sec, syms, off, file, func, line))
1168 .#define bfd_find_line(abfd, syms, sym, file, line) \
1169 . BFD_SEND (abfd, _bfd_find_line, \
1170 . (abfd, syms, sym, file, line))
1172 .#define bfd_find_inliner_info(abfd, file, func, line) \
1173 . BFD_SEND (abfd, _bfd_find_inliner_info, \
1174 . (abfd, file, func, line))
1176 .#define bfd_debug_info_start(abfd) \
1177 . BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
1179 .#define bfd_debug_info_end(abfd) \
1180 . BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
1182 .#define bfd_debug_info_accumulate(abfd, section) \
1183 . BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
1185 .#define bfd_stat_arch_elt(abfd, stat) \
1186 . BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
1188 .#define bfd_update_armap_timestamp(abfd) \
1189 . BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
1191 .#define bfd_set_arch_mach(abfd, arch, mach)\
1192 . BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
1194 .#define bfd_relax_section(abfd, section, link_info, again) \
1195 . BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
1197 .#define bfd_gc_sections(abfd, link_info) \
1198 . BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
1200 .#define bfd_merge_sections(abfd, link_info) \
1201 . BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
1203 .#define bfd_is_group_section(abfd, sec) \
1204 . BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
1206 .#define bfd_discard_group(abfd, sec) \
1207 . BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
1209 .#define bfd_link_hash_table_create(abfd) \
1210 . BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
1212 .#define bfd_link_hash_table_free(abfd, hash) \
1213 . BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
1215 .#define bfd_link_add_symbols(abfd, info) \
1216 . BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
1218 .#define bfd_link_just_syms(abfd, sec, info) \
1219 . BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
1221 .#define bfd_final_link(abfd, info) \
1222 . BFD_SEND (abfd, _bfd_final_link, (abfd, info))
1224 .#define bfd_free_cached_info(abfd) \
1225 . BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
1227 .#define bfd_get_dynamic_symtab_upper_bound(abfd) \
1228 . BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
1230 .#define bfd_print_private_bfd_data(abfd, file)\
1231 . BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
1233 .#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
1234 . BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
1236 .#define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
1237 . BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
1238 . dyncount, dynsyms, ret))
1240 .#define bfd_get_dynamic_reloc_upper_bound(abfd) \
1241 . BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
1243 .#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
1244 . BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
1246 .extern bfd_byte *bfd_get_relocated_section_contents
1247 . (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
1248 . bfd_boolean, asymbol **);
1253 bfd_byte *
1254 bfd_get_relocated_section_contents (bfd *abfd,
1255 struct bfd_link_info *link_info,
1256 struct bfd_link_order *link_order,
1257 bfd_byte *data,
1258 bfd_boolean relocatable,
1259 asymbol **symbols)
1261 bfd *abfd2;
1262 bfd_byte *(*fn) (bfd *, struct bfd_link_info *, struct bfd_link_order *,
1263 bfd_byte *, bfd_boolean, asymbol **);
1265 if (link_order->type == bfd_indirect_link_order)
1267 abfd2 = link_order->u.indirect.section->owner;
1268 if (abfd2 == NULL)
1269 abfd2 = abfd;
1271 else
1272 abfd2 = abfd;
1274 fn = abfd2->xvec->_bfd_get_relocated_section_contents;
1276 return (*fn) (abfd, link_info, link_order, data, relocatable, symbols);
1279 /* Record information about an ELF program header. */
1281 bfd_boolean
1282 bfd_record_phdr (bfd *abfd,
1283 unsigned long type,
1284 bfd_boolean flags_valid,
1285 flagword flags,
1286 bfd_boolean at_valid,
1287 bfd_vma at,
1288 bfd_boolean includes_filehdr,
1289 bfd_boolean includes_phdrs,
1290 unsigned int count,
1291 asection **secs)
1293 struct elf_segment_map *m, **pm;
1294 bfd_size_type amt;
1296 if (bfd_get_flavour (abfd) != bfd_target_elf_flavour)
1297 return TRUE;
1299 amt = sizeof (struct elf_segment_map);
1300 amt += ((bfd_size_type) count - 1) * sizeof (asection *);
1301 m = bfd_alloc (abfd, amt);
1302 if (m == NULL)
1303 return FALSE;
1305 m->next = NULL;
1306 m->p_type = type;
1307 m->p_flags = flags;
1308 m->p_paddr = at;
1309 m->p_flags_valid = flags_valid;
1310 m->p_paddr_valid = at_valid;
1311 m->includes_filehdr = includes_filehdr;
1312 m->includes_phdrs = includes_phdrs;
1313 m->count = count;
1314 if (count > 0)
1315 memcpy (m->sections, secs, count * sizeof (asection *));
1317 for (pm = &elf_tdata (abfd)->segment_map; *pm != NULL; pm = &(*pm)->next)
1319 *pm = m;
1321 return TRUE;
1324 void
1325 bfd_sprintf_vma (bfd *abfd, char *buf, bfd_vma value)
1327 if (bfd_get_flavour (abfd) == bfd_target_elf_flavour)
1328 get_elf_backend_data (abfd)->elf_backend_sprintf_vma (abfd, buf, value);
1329 else
1330 sprintf_vma (buf, value);
1333 void
1334 bfd_fprintf_vma (bfd *abfd, void *stream, bfd_vma value)
1336 if (bfd_get_flavour (abfd) == bfd_target_elf_flavour)
1337 get_elf_backend_data (abfd)->elf_backend_fprintf_vma (abfd, stream, value);
1338 else
1339 fprintf_vma ((FILE *) stream, value);
1343 FUNCTION
1344 bfd_alt_mach_code
1346 SYNOPSIS
1347 bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
1349 DESCRIPTION
1351 When more than one machine code number is available for the
1352 same machine type, this function can be used to switch between
1353 the preferred one (alternative == 0) and any others. Currently,
1354 only ELF supports this feature, with up to two alternate
1355 machine codes.
1358 bfd_boolean
1359 bfd_alt_mach_code (bfd *abfd, int alternative)
1361 if (bfd_get_flavour (abfd) == bfd_target_elf_flavour)
1363 int code;
1365 switch (alternative)
1367 case 0:
1368 code = get_elf_backend_data (abfd)->elf_machine_code;
1369 break;
1371 case 1:
1372 code = get_elf_backend_data (abfd)->elf_machine_alt1;
1373 if (code == 0)
1374 return FALSE;
1375 break;
1377 case 2:
1378 code = get_elf_backend_data (abfd)->elf_machine_alt2;
1379 if (code == 0)
1380 return FALSE;
1381 break;
1383 default:
1384 return FALSE;
1387 elf_elfheader (abfd)->e_machine = code;
1389 return TRUE;
1392 return FALSE;
1396 CODE_FRAGMENT
1398 .struct bfd_preserve
1400 . void *marker;
1401 . void *tdata;
1402 . flagword flags;
1403 . const struct bfd_arch_info *arch_info;
1404 . struct bfd_section *sections;
1405 . struct bfd_section *section_last;
1406 . unsigned int section_count;
1407 . struct bfd_hash_table section_htab;
1413 FUNCTION
1414 bfd_preserve_save
1416 SYNOPSIS
1417 bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
1419 DESCRIPTION
1420 When testing an object for compatibility with a particular
1421 target back-end, the back-end object_p function needs to set
1422 up certain fields in the bfd on successfully recognizing the
1423 object. This typically happens in a piecemeal fashion, with
1424 failures possible at many points. On failure, the bfd is
1425 supposed to be restored to its initial state, which is
1426 virtually impossible. However, restoring a subset of the bfd
1427 state works in practice. This function stores the subset and
1428 reinitializes the bfd.
1432 bfd_boolean
1433 bfd_preserve_save (bfd *abfd, struct bfd_preserve *preserve)
1435 preserve->tdata = abfd->tdata.any;
1436 preserve->arch_info = abfd->arch_info;
1437 preserve->flags = abfd->flags;
1438 preserve->sections = abfd->sections;
1439 preserve->section_last = abfd->section_last;
1440 preserve->section_count = abfd->section_count;
1441 preserve->section_htab = abfd->section_htab;
1443 if (! bfd_hash_table_init (&abfd->section_htab, bfd_section_hash_newfunc,
1444 sizeof (struct section_hash_entry)))
1445 return FALSE;
1447 abfd->tdata.any = NULL;
1448 abfd->arch_info = &bfd_default_arch_struct;
1449 abfd->flags &= BFD_IN_MEMORY;
1450 abfd->sections = NULL;
1451 abfd->section_last = NULL;
1452 abfd->section_count = 0;
1454 return TRUE;
1458 FUNCTION
1459 bfd_preserve_restore
1461 SYNOPSIS
1462 void bfd_preserve_restore (bfd *, struct bfd_preserve *);
1464 DESCRIPTION
1465 This function restores bfd state saved by bfd_preserve_save.
1466 If MARKER is non-NULL in struct bfd_preserve then that block
1467 and all subsequently bfd_alloc'd memory is freed.
1471 void
1472 bfd_preserve_restore (bfd *abfd, struct bfd_preserve *preserve)
1474 bfd_hash_table_free (&abfd->section_htab);
1476 abfd->tdata.any = preserve->tdata;
1477 abfd->arch_info = preserve->arch_info;
1478 abfd->flags = preserve->flags;
1479 abfd->section_htab = preserve->section_htab;
1480 abfd->sections = preserve->sections;
1481 abfd->section_last = preserve->section_last;
1482 abfd->section_count = preserve->section_count;
1484 /* bfd_release frees all memory more recently bfd_alloc'd than
1485 its arg, as well as its arg. */
1486 if (preserve->marker != NULL)
1488 bfd_release (abfd, preserve->marker);
1489 preserve->marker = NULL;
1494 FUNCTION
1495 bfd_preserve_finish
1497 SYNOPSIS
1498 void bfd_preserve_finish (bfd *, struct bfd_preserve *);
1500 DESCRIPTION
1501 This function should be called when the bfd state saved by
1502 bfd_preserve_save is no longer needed. ie. when the back-end
1503 object_p function returns with success.
1507 void
1508 bfd_preserve_finish (bfd *abfd ATTRIBUTE_UNUSED, struct bfd_preserve *preserve)
1510 /* It would be nice to be able to free more memory here, eg. old
1511 tdata, but that's not possible since these blocks are sitting
1512 inside bfd_alloc'd memory. The section hash is on a separate
1513 objalloc. */
1514 bfd_hash_table_free (&preserve->section_htab);