2001-05-28 Philip Blundell <philb@gnu.org>
[binutils.git] / include / bfdlink.h
blobae96323bfa732565f591d39b67ae512e1d021079
1 /* bfdlink.h -- header file for BFD link routines
2 Copyright 1993, 94, 95, 96, 97, 1999 Free Software Foundation, Inc.
3 Written by Steve Chamberlain and Ian Lance Taylor, Cygnus Support.
5 This file is part of BFD, the Binary File Descriptor library.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
21 #ifndef BFDLINK_H
22 #define BFDLINK_H
24 /* Which symbols to strip during a link. */
25 enum bfd_link_strip
27 strip_none, /* Don't strip any symbols. */
28 strip_debugger, /* Strip debugging symbols. */
29 strip_some, /* keep_hash is the list of symbols to keep. */
30 strip_all /* Strip all symbols. */
33 /* Which local symbols to discard during a link. This is irrelevant
34 if strip_all is used. */
35 enum bfd_link_discard
37 discard_none, /* Don't discard any locals. */
38 discard_l, /* Discard local temporary symbols. */
39 discard_all /* Discard all locals. */
42 /* These are the possible types of an entry in the BFD link hash
43 table. */
45 enum bfd_link_hash_type
47 bfd_link_hash_new, /* Symbol is new. */
48 bfd_link_hash_undefined, /* Symbol seen before, but undefined. */
49 bfd_link_hash_undefweak, /* Symbol is weak and undefined. */
50 bfd_link_hash_defined, /* Symbol is defined. */
51 bfd_link_hash_defweak, /* Symbol is weak and defined. */
52 bfd_link_hash_common, /* Symbol is common. */
53 bfd_link_hash_indirect, /* Symbol is an indirect link. */
54 bfd_link_hash_warning /* Like indirect, but warn if referenced. */
57 /* The linking routines use a hash table which uses this structure for
58 its elements. */
60 struct bfd_link_hash_entry
62 /* Base hash table entry structure. */
63 struct bfd_hash_entry root;
64 /* Type of this entry. */
65 enum bfd_link_hash_type type;
67 /* Undefined and common symbols are kept in a linked list through
68 this field. This field is not in the union because that would
69 force us to remove entries from the list when we changed their
70 type, which would force the list to be doubly linked, which would
71 waste more memory. When an undefined or common symbol is
72 created, it should be added to this list, the head of which is in
73 the link hash table itself. As symbols are defined, they need
74 not be removed from the list; anything which reads the list must
75 doublecheck the symbol type.
77 Weak symbols are not kept on this list.
79 Defined and defweak symbols use this field as a reference marker.
80 If the field is not NULL, or this structure is the tail of the
81 undefined symbol list, the symbol has been referenced. If the
82 symbol is undefined and becomes defined, this field will
83 automatically be non-NULL since the symbol will have been on the
84 undefined symbol list. */
85 struct bfd_link_hash_entry *next;
86 /* A union of information depending upon the type. */
87 union
89 /* Nothing is kept for bfd_hash_new. */
90 /* bfd_link_hash_undefined, bfd_link_hash_undefweak. */
91 struct
93 bfd *abfd; /* BFD symbol was found in. */
94 } undef;
95 /* bfd_link_hash_defined, bfd_link_hash_defweak. */
96 struct
98 bfd_vma value; /* Symbol value. */
99 asection *section; /* Symbol section. */
100 } def;
101 /* bfd_link_hash_indirect, bfd_link_hash_warning. */
102 struct
104 struct bfd_link_hash_entry *link; /* Real symbol. */
105 const char *warning; /* Warning (bfd_link_hash_warning only). */
106 } i;
107 /* bfd_link_hash_common. */
108 struct
110 /* The linker needs to know three things about common
111 symbols: the size, the alignment, and the section in
112 which the symbol should be placed. We store the size
113 here, and we allocate a small structure to hold the
114 section and the alignment. The alignment is stored as a
115 power of two. We don't store all the information
116 directly because we don't want to increase the size of
117 the union; this structure is a major space user in the
118 linker. */
119 bfd_size_type size; /* Common symbol size. */
120 struct bfd_link_hash_common_entry
122 unsigned int alignment_power; /* Alignment. */
123 asection *section; /* Symbol section. */
124 } *p;
125 } c;
126 } u;
129 /* This is the link hash table. It is a derived class of
130 bfd_hash_table. */
132 struct bfd_link_hash_table
134 /* The hash table itself. */
135 struct bfd_hash_table table;
136 /* The back end which created this hash table. This indicates the
137 type of the entries in the hash table, which is sometimes
138 important information when linking object files of different
139 types together. */
140 const bfd_target *creator;
141 /* A linked list of undefined and common symbols, linked through the
142 next field in the bfd_link_hash_entry structure. */
143 struct bfd_link_hash_entry *undefs;
144 /* Entries are added to the tail of the undefs list. */
145 struct bfd_link_hash_entry *undefs_tail;
148 /* Look up an entry in a link hash table. If FOLLOW is true, this
149 follows bfd_link_hash_indirect and bfd_link_hash_warning links to
150 the real symbol. */
151 extern struct bfd_link_hash_entry *bfd_link_hash_lookup
152 PARAMS ((struct bfd_link_hash_table *, const char *, boolean create,
153 boolean copy, boolean follow));
155 /* Look up an entry in the main linker hash table if the symbol might
156 be wrapped. This should only be used for references to an
157 undefined symbol, not for definitions of a symbol. */
159 extern struct bfd_link_hash_entry *bfd_wrapped_link_hash_lookup
160 PARAMS ((bfd *, struct bfd_link_info *, const char *, boolean, boolean,
161 boolean));
163 /* Traverse a link hash table. */
164 extern void bfd_link_hash_traverse
165 PARAMS ((struct bfd_link_hash_table *,
166 boolean (*) (struct bfd_link_hash_entry *, PTR),
167 PTR));
169 /* Add an entry to the undefs list. */
170 extern void bfd_link_add_undef
171 PARAMS ((struct bfd_link_hash_table *, struct bfd_link_hash_entry *));
173 /* This structure holds all the information needed to communicate
174 between BFD and the linker when doing a link. */
176 struct bfd_link_info
178 /* Function callbacks. */
179 const struct bfd_link_callbacks *callbacks;
180 /* true if BFD should generate a relocateable object file. */
181 boolean relocateable;
182 /* true if BFD should generate relocation information in the final executable. */
183 boolean emitrelocations;
184 /* true if BFD should generate a "task linked" object file,
185 similar to relocatable but also with globals converted to statics. */
186 boolean task_link;
187 /* true if BFD should generate a shared object. */
188 boolean shared;
189 /* true if BFD should pre-bind symbols in a shared object. */
190 boolean symbolic;
191 /* true if shared objects should be linked directly, not shared. */
192 boolean static_link;
193 /* true if the output file should be in a traditional format. This
194 is equivalent to the setting of the BFD_TRADITIONAL_FORMAT flag
195 on the output file, but may be checked when reading the input
196 files. */
197 boolean traditional_format;
198 /* true if we want to produced optimized output files. This might
199 need much more time and therefore must be explicitly selected. */
200 boolean optimize;
201 /* true if BFD should generate errors for undefined symbols
202 even if generating a shared object. */
203 boolean no_undefined;
204 /* true if BFD should allow undefined symbols in shared objects even
205 when no_undefined is set to disallow undefined symbols. The net
206 result will be that undefined symbols in regular objects will
207 still trigger an error, but undefined symbols in shared objects
208 will be ignored. The implementation of no_undefined makes the
209 assumption that the runtime linker will choke on undefined
210 symbols. However there is at least one system (BeOS) where
211 undefined symbols in shared libraries is normal since the kernel
212 patches them at load time to select which function is most
213 appropriate for the current architecture. I.E. dynamically
214 select an appropriate memset function. Apparently it is also
215 normal for HPPA shared libraries to have undefined symbols. */
216 boolean allow_shlib_undefined;
217 /* Which symbols to strip. */
218 enum bfd_link_strip strip;
219 /* Which local symbols to discard. */
220 enum bfd_link_discard discard;
221 /* true if symbols should be retained in memory, false if they
222 should be freed and reread. */
223 boolean keep_memory;
224 /* The list of input BFD's involved in the link. These are chained
225 together via the link_next field. */
226 bfd *input_bfds;
227 /* If a symbol should be created for each input BFD, this is section
228 where those symbols should be placed. It must be a section in
229 the output BFD. It may be NULL, in which case no such symbols
230 will be created. This is to support CREATE_OBJECT_SYMBOLS in the
231 linker command language. */
232 asection *create_object_symbols_section;
233 /* Hash table handled by BFD. */
234 struct bfd_link_hash_table *hash;
235 /* Hash table of symbols to keep. This is NULL unless strip is
236 strip_some. */
237 struct bfd_hash_table *keep_hash;
238 /* true if every symbol should be reported back via the notice
239 callback. */
240 boolean notice_all;
241 /* Hash table of symbols to report back via the notice callback. If
242 this is NULL, and notice_all is false, then no symbols are
243 reported back. */
244 struct bfd_hash_table *notice_hash;
245 /* Hash table of symbols which are being wrapped (the --wrap linker
246 option). If this is NULL, no symbols are being wrapped. */
247 struct bfd_hash_table *wrap_hash;
248 /* If a base output file is wanted, then this points to it */
249 PTR base_file;
251 /* If non-zero, specifies that branches which are problematic for the
252 MPC860 C0 (or earlier) should be checked for and modified. It gives the
253 number of bytes that should be checked at the end of each text page. */
254 int mpc860c0;
256 /* The function to call when the executable or shared object is
257 loaded. */
258 const char *init_function;
259 /* The function to call when the executable or shared object is
260 unloaded. */
261 const char *fini_function;
263 /* true if the new ELF dynamic tags are enabled. */
264 boolean new_dtags;
266 /* May be used to set DT_FLAGS for ELF. */
267 bfd_vma flags;
269 /* May be used to set DT_FLAGS_1 for ELF. */
270 bfd_vma flags_1;
273 /* This structures holds a set of callback functions. These are
274 called by the BFD linker routines. The first argument to each
275 callback function is the bfd_link_info structure being used. Each
276 function returns a boolean value. If the function returns false,
277 then the BFD function which called it will return with a failure
278 indication. */
280 struct bfd_link_callbacks
282 /* A function which is called when an object is added from an
283 archive. ABFD is the archive element being added. NAME is the
284 name of the symbol which caused the archive element to be pulled
285 in. */
286 boolean (*add_archive_element) PARAMS ((struct bfd_link_info *,
287 bfd *abfd,
288 const char *name));
289 /* A function which is called when a symbol is found with multiple
290 definitions. NAME is the symbol which is defined multiple times.
291 OBFD is the old BFD, OSEC is the old section, OVAL is the old
292 value, NBFD is the new BFD, NSEC is the new section, and NVAL is
293 the new value. OBFD may be NULL. OSEC and NSEC may be
294 bfd_com_section or bfd_ind_section. */
295 boolean (*multiple_definition) PARAMS ((struct bfd_link_info *,
296 const char *name,
297 bfd *obfd,
298 asection *osec,
299 bfd_vma oval,
300 bfd *nbfd,
301 asection *nsec,
302 bfd_vma nval));
303 /* A function which is called when a common symbol is defined
304 multiple times. NAME is the symbol appearing multiple times.
305 OBFD is the BFD of the existing symbol; it may be NULL if this is
306 not known. OTYPE is the type of the existing symbol, which may
307 be bfd_link_hash_defined, bfd_link_hash_defweak,
308 bfd_link_hash_common, or bfd_link_hash_indirect. If OTYPE is
309 bfd_link_hash_common, OSIZE is the size of the existing symbol.
310 NBFD is the BFD of the new symbol. NTYPE is the type of the new
311 symbol, one of bfd_link_hash_defined, bfd_link_hash_common, or
312 bfd_link_hash_indirect. If NTYPE is bfd_link_hash_common, NSIZE
313 is the size of the new symbol. */
314 boolean (*multiple_common) PARAMS ((struct bfd_link_info *,
315 const char *name,
316 bfd *obfd,
317 enum bfd_link_hash_type otype,
318 bfd_vma osize,
319 bfd *nbfd,
320 enum bfd_link_hash_type ntype,
321 bfd_vma nsize));
322 /* A function which is called to add a symbol to a set. ENTRY is
323 the link hash table entry for the set itself (e.g.,
324 __CTOR_LIST__). RELOC is the relocation to use for an entry in
325 the set when generating a relocateable file, and is also used to
326 get the size of the entry when generating an executable file.
327 ABFD, SEC and VALUE identify the value to add to the set. */
328 boolean (*add_to_set) PARAMS ((struct bfd_link_info *,
329 struct bfd_link_hash_entry *entry,
330 bfd_reloc_code_real_type reloc,
331 bfd *abfd, asection *sec, bfd_vma value));
332 /* A function which is called when the name of a g++ constructor or
333 destructor is found. This is only called by some object file
334 formats. CONSTRUCTOR is true for a constructor, false for a
335 destructor. This will use BFD_RELOC_CTOR when generating a
336 relocateable file. NAME is the name of the symbol found. ABFD,
337 SECTION and VALUE are the value of the symbol. */
338 boolean (*constructor) PARAMS ((struct bfd_link_info *,
339 boolean constructor,
340 const char *name, bfd *abfd, asection *sec,
341 bfd_vma value));
342 /* A function which is called to issue a linker warning. For
343 example, this is called when there is a reference to a warning
344 symbol. WARNING is the warning to be issued. SYMBOL is the name
345 of the symbol which triggered the warning; it may be NULL if
346 there is none. ABFD, SECTION and ADDRESS identify the location
347 which trigerred the warning; either ABFD or SECTION or both may
348 be NULL if the location is not known. */
349 boolean (*warning) PARAMS ((struct bfd_link_info *,
350 const char *warning, const char *symbol,
351 bfd *abfd, asection *section,
352 bfd_vma address));
353 /* A function which is called when a relocation is attempted against
354 an undefined symbol. NAME is the symbol which is undefined.
355 ABFD, SECTION and ADDRESS identify the location from which the
356 reference is made. FATAL indicates whether an undefined symbol is
357 a fatal error or not. In some cases SECTION may be NULL. */
358 boolean (*undefined_symbol) PARAMS ((struct bfd_link_info *,
359 const char *name, bfd *abfd,
360 asection *section,
361 bfd_vma address,
362 boolean fatal));
363 /* A function which is called when a reloc overflow occurs. NAME is
364 the name of the symbol or section the reloc is against,
365 RELOC_NAME is the name of the relocation, and ADDEND is any
366 addend that is used. ABFD, SECTION and ADDRESS identify the
367 location at which the overflow occurs; if this is the result of a
368 bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then
369 ABFD will be NULL. */
370 boolean (*reloc_overflow) PARAMS ((struct bfd_link_info *,
371 const char *name,
372 const char *reloc_name, bfd_vma addend,
373 bfd *abfd, asection *section,
374 bfd_vma address));
375 /* A function which is called when a dangerous reloc is performed.
376 The canonical example is an a29k IHCONST reloc which does not
377 follow an IHIHALF reloc. MESSAGE is an appropriate message.
378 ABFD, SECTION and ADDRESS identify the location at which the
379 problem occurred; if this is the result of a
380 bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then
381 ABFD will be NULL. */
382 boolean (*reloc_dangerous) PARAMS ((struct bfd_link_info *,
383 const char *message,
384 bfd *abfd, asection *section,
385 bfd_vma address));
386 /* A function which is called when a reloc is found to be attached
387 to a symbol which is not being written out. NAME is the name of
388 the symbol. ABFD, SECTION and ADDRESS identify the location of
389 the reloc; if this is the result of a
390 bfd_section_reloc_link_order or bfd_symbol_reloc_link_order, then
391 ABFD will be NULL. */
392 boolean (*unattached_reloc) PARAMS ((struct bfd_link_info *,
393 const char *name,
394 bfd *abfd, asection *section,
395 bfd_vma address));
396 /* A function which is called when a symbol in notice_hash is
397 defined or referenced. NAME is the symbol. ABFD, SECTION and
398 ADDRESS are the value of the symbol. If SECTION is
399 bfd_und_section, this is a reference. */
400 boolean (*notice) PARAMS ((struct bfd_link_info *, const char *name,
401 bfd *abfd, asection *section, bfd_vma address));
404 /* The linker builds link_order structures which tell the code how to
405 include input data in the output file. */
407 /* These are the types of link_order structures. */
409 enum bfd_link_order_type
411 bfd_undefined_link_order, /* Undefined. */
412 bfd_indirect_link_order, /* Built from a section. */
413 bfd_fill_link_order, /* Fill with a 16 bit constant. */
414 bfd_data_link_order, /* Set to explicit data. */
415 bfd_section_reloc_link_order, /* Relocate against a section. */
416 bfd_symbol_reloc_link_order /* Relocate against a symbol. */
419 /* This is the link_order structure itself. These form a chain
420 attached to the section whose contents they are describing. */
422 struct bfd_link_order
424 /* Next link_order in chain. */
425 struct bfd_link_order *next;
426 /* Type of link_order. */
427 enum bfd_link_order_type type;
428 /* Offset within output section. */
429 bfd_vma offset;
430 /* Size within output section. */
431 bfd_size_type size;
432 /* Type specific information. */
433 union
435 struct
437 /* Section to include. If this is used, then
438 section->output_section must be the section the
439 link_order is attached to, section->output_offset must
440 equal the link_order offset field, and section->_raw_size
441 must equal the link_order size field. Maybe these
442 restrictions should be relaxed someday. */
443 asection *section;
444 } indirect;
445 struct
447 /* Value to fill with. */
448 unsigned int value;
449 } fill;
450 struct
452 /* Data to put into file. The size field gives the number
453 of bytes which this field points to. */
454 bfd_byte *contents;
455 } data;
456 struct
458 /* Description of reloc to generate. Used for
459 bfd_section_reloc_link_order and
460 bfd_symbol_reloc_link_order. */
461 struct bfd_link_order_reloc *p;
462 } reloc;
463 } u;
466 /* A linker order of type bfd_section_reloc_link_order or
467 bfd_symbol_reloc_link_order means to create a reloc against a
468 section or symbol, respectively. This is used to implement -Ur to
469 generate relocs for the constructor tables. The
470 bfd_link_order_reloc structure describes the reloc that BFD should
471 create. It is similar to a arelent, but I didn't use arelent
472 because the linker does not know anything about most symbols, and
473 any asymbol structure it creates will be partially meaningless.
474 This information could logically be in the bfd_link_order struct,
475 but I didn't want to waste the space since these types of relocs
476 are relatively rare. */
478 struct bfd_link_order_reloc
480 /* Reloc type. */
481 bfd_reloc_code_real_type reloc;
483 union
485 /* For type bfd_section_reloc_link_order, this is the section
486 the reloc should be against. This must be a section in the
487 output BFD, not any of the input BFDs. */
488 asection *section;
489 /* For type bfd_symbol_reloc_link_order, this is the name of the
490 symbol the reloc should be against. */
491 const char *name;
492 } u;
494 /* Addend to use. The object file should contain zero. The BFD
495 backend is responsible for filling in the contents of the object
496 file correctly. For some object file formats (e.g., COFF) the
497 addend must be stored into in the object file, and for some
498 (e.g., SPARC a.out) it is kept in the reloc. */
499 bfd_vma addend;
502 /* Allocate a new link_order for a section. */
503 extern struct bfd_link_order *bfd_new_link_order PARAMS ((bfd *, asection *));
505 /* These structures are used to describe version information for the
506 ELF linker. These structures could be manipulated entirely inside
507 BFD, but it would be a pain. Instead, the regular linker sets up
508 these structures, and then passes them into BFD. */
510 /* Regular expressions for a version. */
512 struct bfd_elf_version_expr
514 /* Next regular expression for this version. */
515 struct bfd_elf_version_expr *next;
516 /* Regular expression. */
517 const char *pattern;
518 /* Matching function. */
519 int (*match) PARAMS((struct bfd_elf_version_expr *, const char *));
522 /* Version dependencies. */
524 struct bfd_elf_version_deps
526 /* Next dependency for this version. */
527 struct bfd_elf_version_deps *next;
528 /* The version which this version depends upon. */
529 struct bfd_elf_version_tree *version_needed;
532 /* A node in the version tree. */
534 struct bfd_elf_version_tree
536 /* Next version. */
537 struct bfd_elf_version_tree *next;
538 /* Name of this version. */
539 const char *name;
540 /* Version number. */
541 unsigned int vernum;
542 /* Regular expressions for global symbols in this version. */
543 struct bfd_elf_version_expr *globals;
544 /* Regular expressions for local symbols in this version. */
545 struct bfd_elf_version_expr *locals;
546 /* List of versions which this version depends upon. */
547 struct bfd_elf_version_deps *deps;
548 /* Index of the version name. This is used within BFD. */
549 unsigned int name_indx;
550 /* Whether this version tree was used. This is used within BFD. */
551 int used;
554 #endif