1 Info file bfdinfo, produced by Makeinfo, -*- Text -*- from input file
4 This file documents the BFD library.
6 Copyright (C) 1991 Free Software Foundation, Inc.
8 Permission is granted to make and distribute verbatim copies of
9 this manual provided the copyright notice and this permission notice
10 are preserved on all copies.
12 Permission is granted to copy and distribute modified versions of
13 this manual under the conditions for verbatim copying, subject to the
14 terms of the GNU General Public License, which includes the provision
15 that the entire resulting derived work is distributed under the terms
16 of a permission notice identical to this one.
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
23 File: bfdinfo, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
25 This file documents the binary file descriptor library libbfd.
29 * Overview:: Overview of BFD
30 * History:: History of BFD
46 * Opening and Closing::
55 File: bfdinfo, Node: Overview, Next: History, Prev: Top, Up: Top
60 Simply put, BFD is a package which allows applications to use the
61 same routines to operate on object files whatever the object file
62 format. A different object file format can be supported simply by
63 creating a new BFD back end and adding it to the library.
65 BFD is split into two parts; the front end and the many back ends.
67 * memory, and various canonical data structures. The front end also
68 decides which back end to use, and when to call back end routines.
70 * end provides a set of calls which the BFD front end can use to
71 maintain its canonical form. The back ends also may keep around
72 information for their own use, for greater efficiency.
75 File: bfdinfo, Node: History, Next: How It Works, Prev: Overview, Up: Top
80 One spur behind BFD was the desire, on the part of the GNU 960 team
81 at Intel Oregon, for interoperability of applications on their COFF and
82 b.out file formats. Cygnus was providing GNU support for the team, and
83 Cygnus was contracted to provide the required functionality.
85 The name came from a conversation David Wallace was having with
86 Richard Stallman about the library: RMS said that it would be quite
87 hard--David said "BFD". Stallman was right, but the name stuck.
89 At the same time, Ready Systems wanted much the same thing, but for
90 different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
93 BFD was first implemented by Steve Chamberlain (steve@cygnus.com),
94 John Gilmore (gnu@cygnus.com), K. Richard Pixley (rich@cygnus.com) and
95 David Wallace (gumby@cygnus.com) at Cygnus Support in Palo Alto,
99 File: bfdinfo, Node: How It Works, Next: History, Prev: Porting, Up: Top
104 To use the library, include `bfd.h' and link with `libbfd.a'.
106 BFD provides a common interface to the parts of an object file for
107 a calling application.
109 When an application sucessfully opens a target file (object,
110 archive or whatever) a pointer to an internal structure is returned.
111 This pointer points to a structure called `bfd', described in
112 `include/bfd.h'. Our convention is to call this pointer a BFD, and
113 instances of it within code `abfd'. All operations on the target
114 object file are applied as methods to the BFD. The mapping is defined
115 within `bfd.h' in a set of macros, all beginning `bfd'_.
117 For example, this sequence would do what you would probably expect:
118 return the number of sections in an object file attached to a BFD
124 unsigned int number_of_sections(abfd)
127 return bfd_count_sections(abfd);
132 The abstraction used within BFD is that an object file has a header,
133 a number of sections containing raw data, a set of relocations, and
134 some symbol information. Also, BFDs opened for archives have the
135 additional attribute of an index and contain subordinate BFDs. This
136 approach is fine for a.out and coff, but loses efficiency when applied
137 to formats such as S-records and IEEE-695.
139 What BFD Version 1 Can Do
140 =========================
142 As different information from the the object files is required, BFD
143 reads from different sections of the file and processes them. For
144 example a very common operation for the linker is processing symbol
145 tables. Each BFD back end provides a routine for converting between
146 the object file's representation of symbols and an internal canonical
147 format. When the linker asks for the symbol table of an object file,
148 it calls through the memory pointer to the relevant BFD back end
149 routine which reads and converts the table into a canonical form. The
150 linker then operates upon the canonical form. When the link is
151 finished and the linker writes the output file's symbol table, another
152 BFD back end routine is called which takes the newly created symbol
153 table and converts it into the chosen output format.
156 File: bfdinfo, Node: BFD information loss, Next: Mechanism, Prev: BFD outline, Up: BFD
161 *Some information is lost due to the nature of the file format.*
162 The output targets supported by BFD do not provide identical
163 facilities, and information which may be described in one form has
164 nowhere to go in another format. One example of this is alignment
165 information in `b.out'. There is nowhere in an `a.out' format file to
166 store alignment information on the contained data, so when a file is
167 linked from `b.out' and an `a.out' image is produced, alignment
168 information will not propagate to the output file. (The linker will
169 still use the alignment information internally, so the link is
170 performed correctly).
172 Another example is COFF section names. COFF files may contain an
173 unlimited number of sections, each one with a textual section name. If
174 the target of the link is a format which does not have many sections
175 (eg `a.out') or has sections without names (eg the Oasys format) the
176 link cannot be done simply. You can circumvent this problem by
177 describing the desired input-to-output section mapping with the linker
180 *Information can be lost during canonicalization.* The BFD internal
181 canonical form of the external formats is not exhaustive; there are
182 structures in input formats for which there is no direct
183 representation internally. This means that the BFD back ends cannot
184 maintain all possible data richness through the transformation between
185 external to internal and back to external formats.
187 This limitation is only a problem when an application reads one
188 format and writes another. Each BFD back end is responsible for
189 maintaining as much data as possible, and the internal BFD canonical
190 form has structures which are opaque to the BFD core, and exported
191 only to the back ends. When a file is read in one format, the
192 canonical form is generated for BFD and the application. At the same
193 time, the back end saves away any information which may otherwise be
194 lost. If the data is then written back in the same format, the back
195 end routine will be able to use the canonical form provided by the BFD
196 core as well as the information it prepared earlier. Since there is a
197 great deal of commonality between back ends, this mechanism is very
198 useful. There is no information lost for this reason when linking or
199 copying big endian COFF to little endian COFF, or `a.out' to `b.out'.
200 When a mixture of formats is linked, the information is only lost from
201 the files whose format differs from the destination.
204 File: bfdinfo, Node: Mechanism, Prev: BFD information loss, Up: BFD
209 The greatest potential for loss of information is when there is
210 least overlap between the information provided by the source format,
211 that stored by the canonical format, and the information needed by the
212 destination format. A brief description of the canonical form may help
213 you appreciate what kinds of data you can count on preserving across
217 Information on target machine architecture, particular
218 implementation and format type are stored on a per-file basis.
219 Other information includes a demand pageable bit and a write
220 protected bit. Note that information like Unix magic numbers is
221 not stored here--only the magic numbers' meaning, so a `ZMAGIC'
222 file would have both the demand pageable bit and the write
223 protected text bit set. The byte order of the target is stored
224 on a per-file basis, so that big- and little-endian object files
225 may be linked with one another.
228 Each section in the input file contains the name of the section,
229 the original address in the object file, various flags, size and
230 alignment information and pointers into other BFD data structures.
233 Each symbol contains a pointer to the object file which originally
234 defined it, its name, its value, and various flag bits. When a
235 BFD back end reads in a symbol table, the back end relocates all
236 symbols to make them relative to the base of the section where
237 they were defined. This ensures that each symbol points to its
238 containing section. Each symbol also has a varying amount of
239 hidden data to contain private data for the BFD back end. Since
240 the symbol points to the original file, the private data format
241 for that symbol is accessible. `gld' can operate on a collection
242 of symbols of wildly different formats without problems.
244 Normal global and simple local symbols are maintained on output,
245 so an output file (no matter its format) will retain symbols
246 pointing to functions and to global, static, and common
247 variables. Some symbol information is not worth retaining; in
248 `a.out' type information is stored in the symbol table as long
249 symbol names. This information would be useless to most COFF
250 debuggers; the linker has command line switches to allow users to
253 There is one word of type information within the symbol, so if the
254 format supports symbol type information within symbols (for
255 example COFF, IEEE, Oasys) and the type is simple enough to fit
256 within one word (nearly everything but aggregates) the
257 information will be preserved.
260 Each canonical BFD relocation record contains a pointer to the
261 symbol to relocate to, the offset of the data to relocate, the
262 section the data is in and a pointer to a relocation type
263 descriptor. Relocation is performed effectively by message
264 passing through the relocation type descriptor and symbol
265 pointer. It allows relocations to be performed on output data
266 using a relocation method only available in one of the input
267 formats. For instance, Oasys provides a byte relocation format.
268 A relocation record requesting this relocation type would point
269 indirectly to a routine to perform this, so the relocation may be
270 performed on a byte being written to a COFF file, even though 68k
271 COFF has no such relocation type.
274 Object formats can contain, for debugging purposes, some form of
275 mapping between symbols, source line numbers, and addresses in
276 the output file. These addresses have to be relocated along with
277 the symbol information. Each symbol with an associated list of
278 line number records points to the first record of the list. The
279 head of a line number list consists of a pointer to the symbol,
280 which allows divination of the address of the function whose line
281 number is being described. The rest of the list is made up of
282 pairs: offsets into the section and line numbers. Any format
283 which can simply derive this information can pass it successfully
284 between formats (COFF, IEEE and Oasys).
287 File: bfdinfo, Node: BFD front end, Next: BFD back end, Prev: Mechanism, Up: Top
295 Pointers to bfd structs are the cornerstone of any application using
296 `libbfd'. References though the BFD and to data in the BFD give the
297 entire BFD functionality.
299 Here is the BFD struct itself. This contains the major data about
300 the file, and contains pointers to the rest of the data.
305 The filename the application opened the BFD with.
307 CONST char *filename;
309 A pointer to the target jump table.
311 struct bfd_target *xvec;
313 To avoid dragging too many header files into every file that
314 includes `bfd.h', IOSTREAM has been declared as a "char *", and MTIME
315 as a "long". Their correct types, to which they are cast when used,
316 are "FILE *" and "time_t".
318 The iostream is the result of an fopen on the filename.
322 Is the file being cached *Note File Caching::.
326 Marks whether there was a default target specified when the BFD was
327 opened. This is used to select what matching algorithm to use to chose
330 boolean target_defaulted;
332 The caching routines use these to maintain a least-recently-used
333 list of BFDs (*note File Caching::.).
335 struct _bfd *lru_prev, *lru_next;
337 When a file is closed by the caching routines, BFD retains state
338 information on the file here:
352 Reserved for an unimplemented file locking extension.
356 The format which belongs to the BFD.
360 The direction the BFD was opened with
362 enum bfd_direction {no_direction = 0,
365 both_direction = 3} direction;
367 Format_specific flags
371 Currently my_archive is tested before adding origin to anything. I
372 believe that this can become always an add of origin, with origin set
373 to 0 for non archive files.
377 Remember when output has begun, to stop strange things happening.
379 boolean output_has_begun;
381 Pointer to linked list of sections
383 struct sec *sections;
385 The number of sections
387 unsigned int section_count;
389 Stuff only useful for object files: The start address.
391 bfd_vma start_address;
393 Used for input and output
395 unsigned int symcount;
397 Symbol table for output BFD
399 struct symbol_cache_entry **outsymbols;
401 Architecture of object machine, eg m68k
403 enum bfd_architecture obj_arch;
405 Particular machine within arch, e.g. 68010
407 unsigned long obj_machine;
409 Stuff only useful for archives:
412 struct _bfd *my_archive;
414 struct _bfd *archive_head;
417 Used by the back end to hold private data.
421 Used by the application to hold private data
425 Where all the allocated stuff under this BFD goes (*note Memory
428 struct obstack memory;
431 `bfd_set_start_address'
432 .......................
434 Marks the entry point of an output BFD. Returns `true' on success,
437 boolean bfd_set_start_address(bfd *, bfd_vma);
442 Return cached file modification time (e.g. as read from archive
443 header for archive members, or from file system if we have been called
444 before); else determine modify time, cache it, and return it.
446 long bfd_get_mtime(bfd *);
453 #define bfd_sizeof_headers(abfd, reloc) \
454 BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
456 #define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
457 BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
459 #define bfd_debug_info_start(abfd) \
460 BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
462 #define bfd_debug_info_end(abfd) \
463 BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
465 #define bfd_debug_info_accumulate(abfd, section) \
466 BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
468 #define bfd_stat_arch_elt(abfd, stat) \
469 BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
471 #define bfd_coff_swap_aux_in(a,e,t,c,i) \
472 BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
474 #define bfd_coff_swap_sym_in(a,e,i) \
475 BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
477 #define bfd_coff_swap_lineno_in(a,e,i) \
478 BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
483 File: bfdinfo, Node: Memory Usage, Next: Sections, Prev: bfd, Up: Top
488 BFD keeps all its internal structures in obstacks. There is one
489 obstack per open BFD file, into which the current state is stored.
490 When a BFD is closed, the obstack is deleted, and so everything which
491 has been allocated by libbfd for the closing file will be thrown away.
493 BFD will not free anything created by an application, but pointers
494 into `bfd' structures will be invalidated on a `bfd_close'; for
495 example, after a `bfd_close' the vector passed to
496 `bfd_canonicalize_symtab' will still be around, since it has been
497 allocated by the application, but the data that it pointed to will be
500 The general rule is not to close a BFD until all operations
501 dependent upon data from the BFD have been completed, or all the data
502 from within the file has been copied. To help with the management of
503 memory, there is a function (`bfd_alloc_size') which returns the
504 number of bytes in obstacks associated with the supplied BFD. This
505 could be used to select the greediest open BFD, close it to reclaim
506 the memory, perform some operation and reopen the BFD again, to get a
507 fresh copy of the data structures.
510 File: bfdinfo, Node: Sections, Next: Symbols, Prev: Memory Usage, Up: Top
515 Sections are supported in BFD in `section.c'.
517 The raw data contained within a BFD is maintained through the
518 section abstraction. A single BFD may have any number of sections,
519 and keeps hold of them by pointing to the first, each one points to
520 the next in the list.
527 * section prototypes::
530 File: bfdinfo, Node: Section Input, Next: Section Output, Up: Sections
535 When a BFD is opened for reading, the section structures are created
536 and attached to the BFD.
538 Each section has a name which describes the section in the outside
539 world - for example, `a.out' would contain at least three sections,
540 called `.text', `.data' and `.bss'.
542 Sometimes a BFD will contain more than the 'natural' number of
543 sections. A back end may attach other sections containing constructor
544 data, or an application may add a section (using bfd_make_section) to
545 the sections attached to an already open BFD. For example, the linker
546 creates a supernumary section `COMMON' for each input file's BFD to
547 hold information about common storage.
549 The raw data is not necessarily read in at the same time as the
550 section descriptor is created. Some targets may leave the data in
551 place until a `bfd_get_section_contents' call is made. Other back ends
552 may read in all the data at once - For example; an S-record file has
553 to be read once to determine the size of the data. An IEEE-695 file
554 doesn't contain raw data in sections, but data and relocation
555 expressions intermixed, so the data area has to be parsed to get out
556 the data and relocations.
559 File: bfdinfo, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
564 To write a new object style BFD, the various sections to be written
565 have to be created. They are attached to the BFD in the same way as
566 input sections, data is written to the sections using
567 `bfd_set_section_contents'.
569 The linker uses the fields `output_section' and `output_offset' to
570 create an output file.
572 The data to be written comes from input sections attached to the
573 output sections. The output section structure can be considered a
574 filter for the input section, the output section determines the vma of
575 the output data and the name, but the input section determines the
576 offset into the output section of the data to be written.
578 Eg to create a section "O", starting at 0x100, 0x123 long,
579 containing two subsections, "A" at offset 0x0 (ie at vma 0x100) and
580 "B" at offset 0x20 (ie at vma 0x120) the structures would look like:
587 output_section -----------> section name "O"
589 section name "B" | size 0x123
592 output_section --------|
597 File: bfdinfo, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
602 The shape of a section struct:
606 The name of the section, the name isn't a copy, the pointer is the
607 same as that passed to bfd_make_section.
611 The next section in the list belonging to the BFD, or NULL.
615 The field flags contains attributes of the section. Some of these
616 flags are read in from the object file, and some are synthesized from
621 #define SEC_NO_FLAGS 0x000
623 Tells the OS to allocate space for this section when loaded. This
624 would clear for a section containing debug information only.
626 #define SEC_ALLOC 0x001
628 Tells the OS to load the section from the file when loading. This
629 would be clear for a .bss section
631 #define SEC_LOAD 0x002
633 The section contains data still to be relocated, so there will be
634 some relocation information too.
636 #define SEC_RELOC 0x004
640 #define SEC_BALIGN 0x008
642 A signal to the OS that the section contains read only data.
644 #define SEC_READONLY 0x010
646 The section contains code only.
648 #define SEC_CODE 0x020
650 The section contains data only.
652 #define SEC_DATA 0x040
654 The section will reside in ROM.
656 #define SEC_ROM 0x080
658 The section contains constructor information. This section type is
659 used by the linker to create lists of constructors and destructors
660 used by `g++'. When a back end sees a symbol which should be used in a
661 constructor list, it creates a new section for the type of name (eg
662 `__CTOR_LIST__'), attaches the symbol to it and builds a relocation.
663 To build the lists of constructors, all the linker has to to is
664 catenate all the sections called `__CTOR_LIST__' and relocte the data
665 contained within - exactly the operations it would peform on standard
668 #define SEC_CONSTRUCTOR 0x100
670 The section is a constuctor, and should be placed at the end of the
673 #define SEC_CONSTRUCTOR_TEXT 0x1100
675 #define SEC_CONSTRUCTOR_DATA 0x2100
677 #define SEC_CONSTRUCTOR_BSS 0x3100
679 The section has contents - a bss section could be `SEC_ALLOC' |
680 `SEC_HAS_CONTENTS', a debug section could be `SEC_HAS_CONTENTS'
682 #define SEC_HAS_CONTENTS 0x200
684 An instruction to the linker not to output sections containing this
685 flag even if they have information which would normally be written.
687 #define SEC_NEVER_LOAD 0x400
689 The base address of the section in the address space of the target.
693 The size of the section in bytes of the loaded section. This
694 contains a value even if the section has no contents (eg, the size of
699 If this section is going to be output, then this value is the
700 offset into the output section of the first byte in the input section.
701 Eg, if this was going to start at the 100th byte in the output
702 section, this value would be 100.
704 bfd_vma output_offset;
706 The output section through which to map on output.
708 struct sec *output_section;
710 The alignment requirement of the section, as an exponent - eg 3
713 unsigned int alignment_power;
715 If an input section, a pointer to a vector of relocation records for
716 the data in this section.
718 struct reloc_cache_entry *relocation;
720 If an output section, a pointer to a vector of pointers to
721 relocation records for the data in this section.
723 struct reloc_cache_entry **orelocation;
725 The number of relocation records in one of the above
727 unsigned reloc_count;
729 Which section is it 0..nth
733 Information below is back end specific - and not always used or
736 File position of section data
740 File position of relocation info
742 file_ptr rel_filepos;
744 File position of line data
746 file_ptr line_filepos;
748 Pointer to data for applications
752 struct lang_output_section *otheruserdata;
754 Attached line number information
758 Number of line number records
760 unsigned int lineno_count;
762 When a section is being output, this value changes as more
763 linenumbers are written out
765 file_ptr moving_line_filepos;
767 what the section number is in the target world
769 unsigned int target_index;
773 If this is a constructor section then here is a list of the
774 relocations created to relocate items within it.
776 struct relent_chain *constructor_chain;
778 The BFD which owns the section.
785 File: bfdinfo, Node: section prototypes, Next: Section, Prev: typedef section, Up: Sections
790 `bfd_get_section_by_name'
791 .........................
793 Runs through the provided ABFD and returns the `asection' who's
794 name matches that provided, otherwise NULL. *Note Sections::, for more
797 asection * bfd_get_section_by_name(bfd *abfd, CONST char *name);
802 This function creates a new empty section called NAME and attaches
803 it to the end of the chain of sections for the BFD supplied. An
804 attempt to create a section with a name which is already in use,
805 returns the old section by that name instead.
810 If output has already started for this BFD.
813 If obstack alloc fails.
815 asection * bfd_make_section(bfd *, CONST char *name);
817 `bfd_set_section_flags'
818 .......................
820 Attempts to set the attributes of the section named in the BFD
821 supplied to the value. Returns true on success, false on error.
822 Possible error returns are:
825 The section cannot have one or more of the attributes requested.
826 For example, a .bss section in `a.out' may not have the
827 `SEC_HAS_CONTENTS' field set.
829 boolean bfd_set_section_flags(bfd *, asection *, flagword);
831 `bfd_map_over_sections'
832 .......................
834 Calls the provided function FUNC for each section attached to the
835 BFD ABFD, passing OBJ as an argument. The function will be called as
838 func(abfd, the_section, obj);
840 void bfd_map_over_sections(bfd *abfd, void (*func)(), PTR obj);
842 This is the prefered method for iterating over sections, an
843 alternative would be to use a loop:
846 for (p = abfd->sections; p != NULL; p = p->next)
849 `bfd_set_section_size'
850 ......................
852 Sets SECTION to the size VAL. If the operation is ok, then `true'
853 is returned, else `false'.
855 Possible error returns:
858 Writing has started to the BFD, so setting the size is invalid
860 boolean bfd_set_section_size(bfd *, asection *, bfd_size_type val);
862 `bfd_set_section_contents'
863 ..........................
865 Sets the contents of the section SECTION in BFD ABFD to the data
866 starting in memory at DATA. The data is written to the output section
867 starting at offset OFFSET for COUNT bytes.
869 Normally `true' is returned, else `false'. Possible error returns
873 The output section does not have the `SEC_HAS_CONTENTS'
874 attribute, so nothing can be written to it.
877 This routine is front end to the back end function
878 `_bfd_set_section_contents'.
880 boolean bfd_set_section_contents(bfd *abfd,
884 bfd_size_type count);
886 `bfd_get_section_contents'
887 ..........................
889 This function reads data from SECTION in BFD ABFD into memory
890 starting at LOCATION. The data is read at an offset of OFFSET from the
891 start of the input section, and is read for COUNT bytes.
893 If the contents of a constuctor with the `SEC_CONSTUCTOR' flag set
894 are requested, then the LOCATION is filled with zeroes.
896 If no errors occur, `true' is returned, else `false'. Possible
900 boolean bfd_get_section_contents(bfd *abfd, asection *section, PTR location,
901 file_ptr offset, bfd_size_type count);
904 File: bfdinfo, Node: Symbols, Next: Archives, Prev: Sections, Up: To
909 BFD trys to maintain as much symbol information as it can when it
910 moves information from file to file. BFD passes information to
911 applications though the `asymbol' structure. When the application
912 requests the symbol table, BFD reads the table in the native form and
913 translates parts of it into the internal format. To maintain more than
914 the infomation passed to applications some targets keep some
915 information 'behind the sceans', in a structure only the particular
916 back end knows about. For example, the coff back end keeps the
917 original symbol table structure as well as the canonical structure
918 when a BFD is read in. On output, the coff back end can reconstruct
919 the output symbol table so that no information is lost, even
920 information unique to coff which BFD doesn't know or understand. If a
921 coff symbol table was read, but was written through an a.out back end,
922 all the coff specific information would be lost. (.. until BFD 2 :).
924 The symbol table of a BFD is not necessarily read in until a
925 canonicalize request is made. Then the BFD back end fills in a table
926 provided by the application with pointers to the canonical information.
928 To output symbols, the application provides BFD with a table of
929 pointers to pointers to `asymbol's. This allows applications like the
930 linker to output a symbol as read, since the 'behind the sceens'
931 information will be still available.
938 * symbol handling functions::
941 File: bfdinfo, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
946 There are two stages to reading a symbol table from a BFD;
947 allocating storage, and the actual reading process. This is an excerpt
948 from an appliction which reads the symbol table:
951 unsigned int storage_needed;
952 asymbol **symbol_table;
953 unsigned int number_of_symbols;
956 storage_needed = get_symtab_upper_bound (abfd);
958 if (storage_needed == 0) {
961 symbol_table = (asymbol **) malloc (storage_needed);
964 bfd_canonicalize_symtab (abfd, symbol_table);
966 for (i = 0; i < number_of_symbols; i++) {
967 process_symbol (symbol_table[i]);
972 All storage for the symbols themselves is in an obstack connected to
973 the BFD, and is freed when the BFD is closed.
976 File: bfdinfo, Node: Writing Symbols, Next: typedef asymbol, Prev: Reading Symbols, Up: Symbols
981 Writing of a symbol table is automatic when a BFD open for writing
982 is closed. The application attaches a vector of pointers to pointers
983 to symbols to the BFD being written, and fills in the symbol count.
984 The close and cleanup code reads through the table provided and
985 performs all the necessary operations. The outputing code must always
986 be provided with an 'owned' symbol; one which has come from another
987 BFD, or one which has been created using `bfd_make_empty_symbol'.
989 An example showing the creation of a symbol table with only one
1000 abfd = bfd_openw("foo","a.out-sunos-big");
1001 bfd_set_format(abfd, bfd_object);
1002 new = bfd_make_empty_symbol(abfd);
1003 new->name = "dummy_symbol";
1004 new->section = (asection *)0;
1005 new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
1006 new->value = 0x12345;
1009 ptrs[1] = (asymbol *)0;
1011 bfd_set_symtab(abfd, ptrs, 1);
1017 00012345 A dummy_symbol
1021 Many formats cannot represent arbitary symbol information; for
1022 instance the `a.out' object format does not allow an arbitary number
1023 of sections. A symbol pointing to a section which is not one of
1024 `.text', `.data' or `.bss' cannot be described.
1027 File: bfdinfo, Node: typedef asymbol, Next: symbol handling functions, Prev: Writing Symbols, Up: Symbols
1032 An `asymbol' has the form:
1034 typedef struct symbol_cache_entry
1037 A pointer to the BFD which owns the symbol. This information is
1038 necessary so that a back end can work out what additional (invisible to
1039 the application writer) information is carried with the symbol.
1041 struct _bfd *the_bfd;
1043 The text of the symbol. The name is left alone, and not copied - the
1044 application may not alter it.
1048 The value of the symbol.
1052 Attributes of a symbol:
1054 #define BSF_NO_FLAGS 0x00
1056 The symbol has local scope; `static' in `C'. The value is the
1057 offset into the section of the data.
1059 #define BSF_LOCAL 0x01
1061 The symbol has global scope; initialized data in `C'. The value is
1062 the offset into the section of the data.
1064 #define BSF_GLOBAL 0x02
1068 #define BSF_IMPORT 0x04
1070 The symbol has global scope, and is exported. The value is the
1071 offset into the section of the data.
1073 #define BSF_EXPORT 0x08
1075 The symbol is undefined. `extern' in `C'. The value has no meaning.
1077 #define BSF_UNDEFINED 0x10
1079 The symbol is common, initialized to zero; default in `C'. The
1080 value is the size of the object in bytes.
1082 #define BSF_FORT_COMM 0x20
1084 A normal `C' symbol would be one of: `BSF_LOCAL', `BSF_FORT_COMM',
1085 `BSF_UNDEFINED' or `BSF_EXPORT|BSD_GLOBAL'
1087 The symbol is a debugging record. The value has an arbitary meaning.
1089 #define BSF_DEBUGGING 0x40
1091 The symbol has no section attached, any value is the actual value
1092 and is not a relative offset to a section.
1094 #define BSF_ABSOLUTE 0x80
1098 #define BSF_KEEP 0x10000
1099 #define BSF_KEEP_G 0x80000
1103 #define BSF_WEAK 0x100000
1104 #define BSF_CTOR 0x200000
1105 #define BSF_FAKE 0x400000
1107 The symbol used to be a common symbol, but now it is allocated.
1109 #define BSF_OLD_COMMON 0x800000
1111 The default value for common data.
1113 #define BFD_FORT_COMM_DEFAULT_VALUE 0
1115 In some files the type of a symbol sometimes alters its location in
1116 an output file - ie in coff a `ISFCN' symbol which is also `C_EXT'
1117 symbol appears where it was declared and not at the end of a section.
1118 This bit is set by the target BFD part to convey this information.
1120 #define BSF_NOT_AT_END 0x40000
1122 Signal that the symbol is the label of constructor section.
1124 #define BSF_CONSTRUCTOR 0x1000000
1126 Signal that the symbol is a warning symbol. If the symbol is a
1127 warning symbol, then the value field (I know this is tacky) will point
1128 to the asymbol which when referenced will cause the warning.
1130 #define BSF_WARNING 0x2000000
1132 Signal that the symbol is indirect. The value of the symbol is a
1133 pointer to an undefined asymbol which contains the name to use instead.
1135 #define BSF_INDIRECT 0x4000000
1139 A pointer to the section to which this symbol is relative, or 0 if
1140 the symbol is absolute or undefined. Note that it is not sufficient to
1141 set this location to 0 to mark a symbol as absolute - the flag
1142 `BSF_ABSOLUTE' must be set also.
1144 struct sec *section;
1146 Back end special data. This is being phased out in favour of making
1153 File: bfdinfo, Node: symbol handling functions, Next: Symbols, Prev: typedef asymbol, Up: Symbols
1155 Symbol Handling Functions
1156 -------------------------
1158 `get_symtab_upper_bound'
1159 ........................
1161 Returns the number of bytes required in a vector of pointers to
1162 `asymbols' for all the symbols in the supplied BFD, including a
1163 terminal NULL pointer. If there are no symbols in the BFD, then 0 is
1167 #define get_symtab_upper_bound(abfd) \
1168 BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
1172 `bfd_canonicalize_symtab'
1173 .........................
1175 Supplied a BFD and a pointer to an uninitialized vector of pointers.
1176 This reads in the symbols from the BFD, and fills in the table with
1177 pointers to the symbols, and a trailing NULL. The routine returns the
1178 actual number of symbol pointers not including the NULL.
1181 #define bfd_canonicalize_symtab(abfd, location) \
1182 BFD_SEND (abfd, _bfd_canonicalize_symtab,\
1190 Provided a table of pointers to to symbols and a count, writes to
1191 the output BFD the symbols when closed.
1193 boolean bfd_set_symtab(bfd *, asymbol **, unsigned int );
1195 `bfd_print_symbol_vandf'
1196 ........................
1198 Prints the value and flags of the symbol supplied to the stream
1201 void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
1203 `bfd_make_empty_symbol'
1204 .......................
1206 This function creates a new `asymbol' structure for the BFD, and
1207 returns a pointer to it.
1209 This routine is necessary, since each back end has private
1210 information surrounding the `asymbol'. Building your own `asymbol' and
1211 pointing to it will not create the private information, and will cause
1215 #define bfd_make_empty_symbol(abfd) \
1216 BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
1221 File: bfdinfo, Node: Archives, Next: Formats, Prev: Symbols, Up: Top
1226 Gumby, you promised to write this bit...
1228 Archives are supported in BFD in `archive.c'.
1230 An archive is represented internally just like another BFD, with a
1231 pointer to a chain of contained BFDs. Archives can be created by
1232 opening BFDs, linking them together and attaching them as children to
1233 another BFD and then closing the parent BFD.
1235 `bfd_get_next_mapent'
1236 .....................
1240 symindex bfd_get_next_mapent(bfd *, symindex, carsym **);
1242 `bfd_set_archive_head'
1243 ......................
1245 Used whilst processing archives. Sets the head of the chain of BFDs
1246 contained in an archive to NEW_HEAD. (see chapter on archives)
1248 boolean bfd_set_archive_head(bfd *output, bfd *new_head);
1250 `bfd_get_elt_at_index'
1251 ......................
1253 Return the sub bfd contained within the archive at archive index n.
1255 bfd * bfd_get_elt_at_index(bfd *, int);
1257 `bfd_openr_next_archived_file'
1258 ..............................
1260 Initially provided a BFD containing an archive and NULL, opens a BFD
1261 on the first contained element and returns that. Subsequent calls to
1262 bfd_openr_next_archived_file should pass the archive and the previous
1263 return value to return a created BFD to the next contained element.
1264 NULL is returned when there are no more.
1266 bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
1269 File: bfdinfo, Node: Formats, Next: Relocations, Prev: Archives, Up: Top
1274 A format is a BFD concept of high level file contents. The formats
1275 supported by BFD are:
1278 The BFD may contain data, symbols, relocations and debug info.
projects / deliverable / binutils-gdb.git / blob