1 /* Generic symbol-table support for the BFD library.
2 Copyright (C) 1990-1991 Free Software Foundation, Inc.
3 Written by 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., 675 Mass Ave, Cambridge, MA 02139, USA. */
26 BFD trys to maintain as much symbol information as it can when
27 it moves information from file to file. BFD passes information
28 to applications though the <<asymbol>> structure. When the
29 applicationrequests the symbol table, BFD reads the table in
30 the native form and translates parts of it into the internal
31 format. To maintain more than the infomation passed to
32 applications some targets keep some information 'behind the
33 sceans', in a structure only the particular back end knows
34 about. For example, the coff back end keeps the original
35 symbol table structure as well as the canonical structure when
36 a BFD is read in. On output, the coff back end can reconstruct
37 the output symbol table so that no information is lost, even
38 information unique to coff which BFD doesn't know or
39 understand. If a coff symbol table was read, but was written
40 through an a.out back end, all the coff specific information
41 would be lost. (.. until BFD 2 :). The symbol table of a BFD
42 is not necessarily read in until a canonicalize request is
43 made. Then the BFD back end fills in a table provided by the
44 application with pointers to the canonical information. To
45 output symbols, the application provides BFD with a table of
46 pointers to pointers to <<asymbol>>s. This allows applications
47 like the linker to output a symbol as read, since the 'behind
48 the sceens' information will be still available.
53 * symbol handling functions::
56 @node Reading Symbols, Writing Symbols, Symbols, Symbols
61 There are two stages to reading a symbol table from a BFD;
62 allocating storage, and the actual reading process. This is an
63 excerpt from an appliction which reads the symbol table:
67 unsigned int storage_needed;
68 asymbol **symbol_table;
69 unsigned int number_of_symbols;
72 storage_needed = get_symtab_upper_bound (abfd);
74 if (storage_needed == 0) {
77 symbol_table = (asymbol **) bfd_xmalloc (storage_needed);
80 bfd_canonicalize_symtab (abfd, symbol_table);
82 for (i = 0; i < number_of_symbols; i++) {
83 process_symbol (symbol_table[i]);
88 All storage for the symbols themselves is in an obstack
89 connected to the BFD, and is freed when the BFD is closed.
92 @node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
97 Writing of a symbol table is automatic when a BFD open for
98 writing is closed. The application attaches a vector of
99 pointers to pointers to symbols to the BFD being written, and
100 fills in the symbol count. The close and cleanup code reads
101 through the table provided and performs all the necessary
102 operations. The outputing code must always be provided with an
103 'owned' symbol; one which has come from another BFD, or one
104 which has been created using <<bfd_make_empty_symbol>>. An
105 example showing the creation of a symbol table with only one element:
115 abfd = bfd_openw("foo","a.out-sunos-big");
116 bfd_set_format(abfd, bfd_object);
117 new = bfd_make_empty_symbol(abfd);
118 new->name = "dummy_symbol";
119 new->section = (asection *)0;
120 new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
121 new->value = 0x12345;
124 ptrs[1] = (asymbol *)0;
126 bfd_set_symtab(abfd, ptrs, 1);
132 00012345 A dummy_symbol
136 Many formats cannot represent arbitary symbol information; for
137 instance the <<a.out>> object format does not allow an
138 arbitary number of sections. A symbol pointing to a section
139 which is not one of <<.text>>, <<.data>> or <<.bss>> cannot
146 @node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
154 An <<asymbol>> has the form:
156 .typedef struct symbol_cache_entry
158 A pointer to the BFD which owns the symbol. This information
159 is necessary so that a back end can work out what additional
160 (invisible to the application writer) information is carried
163 . struct _bfd *the_bfd;
165 The text of the symbol. The name is left alone, and not copied - the
166 application may not alter it.
170 The value of the symbol.
174 Attributes of a symbol:
176 .#define BSF_NO_FLAGS 0x00
178 The symbol has local scope; <<static>> in <<C>>. The value is
179 the offset into the section of the data.
181 .#define BSF_LOCAL 0x01
183 The symbol has global scope; initialized data in <<C>>. The value
184 is the offset into the section of the data.
186 .#define BSF_GLOBAL 0x02
190 .#define BSF_IMPORT 0x04
192 The symbol has global scope, and is exported. The value is the offset
193 into the section of the data.
195 .#define BSF_EXPORT 0x08
197 The symbol is undefined. <<extern>> in <<C>>. The value has no meaning.
199 .#define BSF_UNDEFINED 0x10
201 The symbol is common, initialized to zero; default in <<C>>. The
202 value is the size of the object in bytes.
204 .#define BSF_FORT_COMM 0x20
206 A normal <<C>> symbol would be one of:
207 <<BSF_LOCAL>>, <<BSF_FORT_COMM>>, <<BSF_UNDEFINED>> or <<BSF_EXPORT|BSD_GLOBAL>>
209 The symbol is a debugging record. The value has an arbitary meaning.
211 .#define BSF_DEBUGGING 0x40
213 The symbol has no section attached, any value is the actual value and
214 is not a relative offset to a section.
216 .#define BSF_ABSOLUTE 0x80
220 .#define BSF_KEEP 0x10000
221 .#define BSF_KEEP_G 0x80000
225 .#define BSF_WEAK 0x100000
226 .#define BSF_CTOR 0x200000
227 .#define BSF_FAKE 0x400000
229 The symbol used to be a common symbol, but now it is allocated.
231 .#define BSF_OLD_COMMON 0x800000
233 The default value for common data.
235 .#define BFD_FORT_COMM_DEFAULT_VALUE 0
237 In some files the type of a symbol sometimes alters its location
238 in an output file - ie in coff a <<ISFCN>> symbol which is also <<C_EXT>>
239 symbol appears where it was declared and not at the end of a section.
240 This bit is set by the target BFD part to convey this information.
242 .#define BSF_NOT_AT_END 0x40000
244 Signal that the symbol is the label of constructor section.
246 .#define BSF_CONSTRUCTOR 0x1000000
248 Signal that the symbol is a warning symbol. If the symbol is a warning
249 symbol, then the value field (I know this is tacky) will point to the
250 asymbol which when referenced will cause the warning.
252 .#define BSF_WARNING 0x2000000
254 Signal that the symbol is indirect. The value of the symbol is a
255 pointer to an undefined asymbol which contains the name to use
258 .#define BSF_INDIRECT 0x4000000
262 A pointer to the section to which this symbol is relative, or 0 if the
263 symbol is absolute or undefined. Note that it is not sufficient to set
264 this location to 0 to mark a symbol as absolute - the flag
265 <<BSF_ABSOLUTE>> must be set also.
267 . struct sec *section;
269 Back end special data. This is being phased out in favour of making
280 #include "stab.gnu.h"
283 @node symbol handling functions, , typedef asymbol, Symbols
285 Symbol Handling Functions
291 get_symtab_upper_bound
294 Returns the number of bytes required in a vector of pointers
295 to <<asymbols>> for all the symbols in the supplied BFD,
296 including a terminal NULL pointer. If there are no symbols in
297 the BFD, then 0 is returned.
299 .#define get_symtab_upper_bound(abfd) \
300 . BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
306 bfd_canonicalize_symtab
309 Supplied a BFD and a pointer to an uninitialized vector of
310 pointers. This reads in the symbols from the BFD, and fills in
311 the table with pointers to the symbols, and a trailing NULL.
312 The routine returns the actual number of symbol pointers not
316 .#define bfd_canonicalize_symtab(abfd, location) \
317 . BFD_SEND (abfd, _bfd_canonicalize_symtab,\
328 Provided a table of pointers to symbols and a count, writes to
329 the output BFD the symbols when closed.
332 boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );
336 bfd_set_symtab (abfd, location, symcount)
339 unsigned int symcount;
341 if ((abfd->format != bfd_object) || (bfd_read_p (abfd))) {
342 bfd_error = invalid_operation;
346 bfd_get_outsymbols (abfd) = location;
347 bfd_get_symcount (abfd) = symcount;
353 bfd_print_symbol_vandf
356 Prints the value and flags of the symbol supplied to the stream file.
359 void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
362 DEFUN(bfd_print_symbol_vandf,(file, symbol),
366 flagword type = symbol->flags;
367 if (symbol->section != (asection *)NULL)
369 fprintf_vma(file, symbol->value+symbol->section->vma);
373 fprintf_vma(file, symbol->value);
375 fprintf(file," %c%c%c%c%c%c%c%c%c%c",
376 (type & BSF_LOCAL) ? 'l':' ',
377 (type & BSF_GLOBAL) ? 'g' : ' ',
378 (type & BSF_IMPORT) ? 'i' : ' ',
379 (type & BSF_EXPORT) ? 'e' : ' ',
380 (type & BSF_UNDEFINED) ? 'u' : ' ',
381 (type & BSF_FORT_COMM) ? 'c' : ' ',
382 (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
383 (type & BSF_WARNING) ? 'W' : ' ',
384 (type & BSF_INDIRECT) ? 'I' : ' ',
385 (type & BSF_DEBUGGING) ? 'd' :' ');
392 bfd_make_empty_symbol
395 This function creates a new <<asymbol>> structure for the BFD,
396 and returns a pointer to it.
398 This routine is necessary, since each back end has private
399 information surrounding the <<asymbol>>. Building your own
400 <<asymbol>> and pointing to it will not create the private
401 information, and will cause problems later on.
403 .#define bfd_make_empty_symbol(abfd) \
404 . BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
412 Return a lower-case character corresponding to the symbol
416 int bfd_decode_symclass(asymbol *symbol);
419 DEFUN(bfd_decode_symclass,(symbol),
422 flagword flags = symbol->flags;
424 if (flags & BSF_FORT_COMM) return 'C';
425 if (flags & BSF_UNDEFINED) return 'U';
426 if (flags & BSF_ABSOLUTE)
427 return (flags & BSF_GLOBAL) ? 'A' : 'a';
429 if ( flags & (BSF_GLOBAL|BSF_LOCAL) ) {
430 if (symbol->section == (asection *)NULL)
432 else if ( !strcmp(symbol->section->name, ".text") )
433 return (flags & BSF_GLOBAL) ? 'T' : 't';
434 else if ( !strcmp(symbol->section->name, ".data") )
435 return (flags & BSF_GLOBAL) ? 'D' : 'd';
436 else if ( !strcmp(symbol->section->name, ".bss") )
437 return (flags & BSF_GLOBAL) ? 'B' : 'b';
439 return (flags & BSF_GLOBAL) ? 'O' : 'o';
442 /* We don't have to handle these cases just yet, but we will soon: