bfd/syms.c

   1 /* Generic symbol-table support for the BFD library.
   2    Copyright (C) 1990-1991 Free Software Foundation, Inc.
   3    Written by Cygnus Support.
   4
   5 This file is part of BFD, the Binary File Descriptor library.
   6
   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.
  11
  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.
  16
  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.  */
  20
  21 /*doc*
  22 @section Symbols
  23 BFD trys to maintain as much symbol information as it can when it
  24 moves information from file to file. BFD passes information to
  25 applications though the @code{asymbol} structure. When the application
  26 requests the symbol table, BFD reads the table in the native form and
  27 translates parts of it into the internal format. To maintain more than
  28 the infomation passed to applications some targets keep
  29 some information 'behind the sceans', in a structure only the
  30 particular back end knows about. For example, the coff back end keeps
  31 the original symbol table structure as well as the canonical structure
  32 when a BFD is read in. On output, the coff back end can reconstruct
  33 the output symbol table so that no information is lost, even
  34 information unique to coff which BFD doesn't know or understand. If a
  35 coff symbol table was read, but was written through an a.out back end,
  36 all the coff specific information would be lost. (.. until BFD 2 :).
  37
  38 The symbol table of a BFD is not necessarily read in until a
  39 canonicalize request is made. Then the BFD back end fills in a table
  40 provided by the application with pointers to the canonical
  41 information.
  42
  43 To output symbols, the application provides BFD with a table of
  44 pointers to pointers to @code{asymbol}s. This allows applications like
  45 the linker to output a symbol as read, since the 'behind the sceens'
  46 information will be still available.
  47
  48 @menu
  49 * Reading Symbols::
  50 * Writing Symbols::
  51 * typedef asymbol::
  52 * symbol handling functions::
  53 @end menu
  54
  55 @node Reading Symbols, Writing Symbols, Symbols, Symbols
  56 @subsection Reading Symbols
  57 There are two stages to reading a symbol table from a BFD; allocating
  58 storage, and the actual reading process. This is an excerpt from an
  59 appliction which reads the symbol table:
  60
  61 *+
  62   unsigned int storage_needed;
  63   asymbol **symbol_table;
  64   unsigned int number_of_symbols;
  65   unsigned int i;
  66
  67   storage_needed = get_symtab_upper_bound (abfd);
  68
  69   if (storage_needed == 0) {
  70      return ;
  71   }
  72   symbol_table = (asymbol **) bfd_xmalloc (storage_needed);
  73     ...
  74   number_of_symbols =
  75      bfd_canonicalize_symtab (abfd, symbol_table);
  76
  77   for (i = 0; i < number_of_symbols; i++) {
  78      process_symbol (symbol_table[i]);
  79   }
  80 *-
  81
  82 All storage for the symbols themselves is in an obstack connected to
  83 the BFD, and is freed when the BFD is closed.
  84
  85 @node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
  86 @subsection Writing Symbols
  87 Writing of a symbol table is automatic when a BFD open for writing
  88 is closed. The application attaches a vector of pointers to pointers to symbols
  89 to the BFD being written, and fills in the symbol count. The close and
  90 cleanup code reads through the table provided and performs all the
  91 necessary operations. The outputing code must always be provided with
  92 an 'owned' symbol; one which has come from another BFD, or one which
  93 has been created using @code{bfd_make_empty_symbol}.
  94
  95 An example showing the creation of a symbol table with only one
  96 element:
  97
  98 *+
  99 #include "bfd.h"
 100 main()
 101 {
 102   bfd *abfd;
 103   asymbol *ptrs[2];
 104   asymbol *new;
 105
 106   abfd = bfd_openw("foo","a.out-sunos-big");
 107   bfd_set_format(abfd, bfd_object);
 108   new = bfd_make_empty_symbol(abfd);
 109   new->name = "dummy_symbol";
 110   new->section = (asection *)0;
 111   new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
 112   new->value = 0x12345;
 113
 114   ptrs[0] = new;
 115   ptrs[1] = (asymbol *)0;
 116
 117   bfd_set_symtab(abfd, ptrs, 1);
 118   bfd_close(abfd);
 119 }
 120
 121 ./makesym
 122 nm foo
 123 00012345 A dummy_symbol
 124
 125
 126 *-
 127
 128 Many formats cannot represent arbitary symbol information; for
 129 instance the @code{a.out} object format does not allow an arbitary
 130 number of sections. A symbol pointing to a section which is not one of
 131 @code{.text}, @code{.data} or @code{.bss} cannot be described.
 132 */
 133
 134
 135 /*doc*
 136 @node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
 137
 138 */
 139 /*proto*
 140 @subsection typedef asymbol
 141 An @code{asymbol} has the form:
 142
 143 *+++
 144
 145 $typedef struct symbol_cache_entry
 146 ${
 147 A pointer to the BFD which owns the symbol. This information is
 148 necessary so that a back end can work out what additional (invisible to
 149 the application writer) information is carried with the symbol.
 150
 151 $  struct _bfd *the_bfd;
 152
 153 The text of the symbol. The name is left alone, and not copied - the
 154 application may not alter it.
 155
 156 $   CONST char *name;
 157
 158 The value of the symbol.
 159
 160 $   symvalue value;
 161
 162 Attributes of a symbol:
 163
 164 $#define BSF_NO_FLAGS    0x00
 165
 166 The symbol has local scope; @code{static} in @code{C}. The value is
 167 the offset into the section of the data.
 168
 169 $#define BSF_LOCAL      0x01
 170
 171 The symbol has global scope; initialized data in @code{C}. The value
 172 is the offset into the section of the data.
 173
 174 $#define BSF_GLOBAL     0x02
 175
 176 Obsolete
 177
 178 $#define BSF_IMPORT     0x04
 179
 180 The symbol has global scope, and is exported. The value is the offset
 181 into the section of the data.
 182
 183 $#define BSF_EXPORT     0x08
 184
 185 The symbol is undefined. @code{extern} in @code{C}. The value has no meaning.
 186
 187 $#define BSF_UNDEFINED  0x10
 188
 189 The symbol is common, initialized to zero; default in @code{C}. The
 190 value is the size of the object in bytes.
 191
 192 $#define BSF_FORT_COMM  0x20
 193
 194 A normal @code{C} symbol would be one of:
 195 @code{BSF_LOCAL}, @code{BSF_FORT_COMM},  @code{BSF_UNDEFINED} or @code{BSF_EXPORT|BSD_GLOBAL}
 196
 197 The symbol is a debugging record. The value has an arbitary meaning.
 198
 199 $#define BSF_DEBUGGING  0x40
 200
 201 The symbol has no section attached, any value is the actual value and
 202 is not a relative offset to a section.
 203
 204 $#define BSF_ABSOLUTE   0x80
 205
 206 Used by the linker
 207
 208 $#define BSF_KEEP        0x10000
 209 $#define BSF_KEEP_G      0x80000
 210
 211 Unused
 212
 213 $#define BSF_WEAK        0x100000
 214 $#define BSF_CTOR        0x200000
 215 $#define BSF_FAKE        0x400000
 216
 217 The symbol used to be a common symbol, but now it is allocated.
 218
 219 $#define BSF_OLD_COMMON  0x800000
 220
 221 The default value for common data.
 222
 223 $#define BFD_FORT_COMM_DEFAULT_VALUE 0
 224
 225 In some files the type of a symbol sometimes alters its location
 226 in an output file - ie in coff a @code{ISFCN} symbol which is also @code{C_EXT}
 227 symbol appears where it was declared and not at the end of a section.
 228 This bit is set by the target BFD part to convey this information.
 229
 230 $#define BSF_NOT_AT_END    0x40000
 231
 232 Signal that the symbol is the label of constructor section.
 233
 234 $#define BSF_CONSTRUCTOR   0x1000000
 235
 236 Signal that the symbol is a warning symbol. If the symbol is a warning
 237 symbol, then the value field (I know this is tacky) will point to the
 238 asymbol which when referenced will cause the warning.
 239
 240 $#define BSF_WARNING       0x2000000
 241
 242 Signal that the symbol is indirect. The value of the symbol is a
 243 pointer to an undefined asymbol which contains the name to use
 244 instead.
 245
 246 $#define BSF_INDIRECT     0x4000000
 247
 248 $  flagword flags;
 249
 250 A pointer to the section to which this symbol is relative, or 0 if the
 251 symbol is absolute or undefined. Note that it is not sufficient to set
 252 this location to 0 to mark a symbol as absolute - the flag
 253 @code{BSF_ABSOLUTE} must be set also.
 254
 255 $  struct sec *section;
 256
 257 Back end special data. This is being phased out in favour of making
 258 this a union.
 259
 260 $  PTR udata;
 261 $} asymbol;
 262 *---
 263
 264 */
 265
 266 #include "bfd.h"
 267 #include "sysdep.h"
 268 #include "libbfd.h"
 269 #include "stab.gnu.h"
 270
 271 /*doc*
 272 @node symbol handling functions,  , typedef asymbol, Symbols
 273 @subsection Symbol Handling Functions
 274
 275 */
 276
 277 /*proto* get_symtab_upper_bound
 278 Returns the number of bytes required in a vector of pointers to
 279 @code{asymbols} for all the symbols in the supplied BFD, including a
 280 terminal NULL pointer. If there are no symbols in the BFD, then 0 is
 281 returned.
 282 *+
 283 #define get_symtab_upper_bound(abfd) \
 284      BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
 285 *-
 286
 287 */
 288
 289 /*proto* bfd_canonicalize_symtab
 290 Supplied a BFD and a pointer to an uninitialized vector of pointers.
 291 This reads in the symbols from the BFD, and fills in the table with
 292 pointers to the symbols, and a trailing NULL. The routine returns the
 293 actual number of symbol pointers not including the NULL.
 294
 295 *+
 296 #define bfd_canonicalize_symtab(abfd, location) \
 297      BFD_SEND (abfd, _bfd_canonicalize_symtab,\
 298                   (abfd, location))
 299
 300 *-
 301 */
 302
 303
 304 /*proto* bfd_set_symtab
 305 Provided a table of pointers to symbols and a count, writes to the
 306 output BFD the symbols when closed.
 307
 308 *; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int ));
 309 */
 310
 311 boolean
 312 bfd_set_symtab (abfd, location, symcount)
 313      bfd *abfd;
 314      asymbol **location;
 315      unsigned int symcount;
 316 {
 317   if ((abfd->format != bfd_object) || (bfd_read_p (abfd))) {
 318     bfd_error = invalid_operation;
 319     return false;
 320   }
 321
 322   bfd_get_outsymbols (abfd) = location;
 323   bfd_get_symcount (abfd) = symcount;
 324   return true;
 325 }
 326
 327 /*proto* bfd_print_symbol_vandf
 328 Prints the value and flags of the symbol supplied to the stream file.
 329
 330 *; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol));
 331 */
 332 void
 333 DEFUN(bfd_print_symbol_vandf,(file, symbol),
 334 PTR file AND
 335 asymbol *symbol)
 336 {
 337   flagword type = symbol->flags;
 338   if (symbol->section != (asection *)NULL)
 339       {
 340         fprintf_vma(file, symbol->value+symbol->section->vma);
 341       }
 342   else
 343       {
 344         fprintf_vma(file, symbol->value);
 345       }
 346   fprintf(file," %c%c%c%c%c%c%c%c%c%c",
 347           (type & BSF_LOCAL)  ? 'l':' ',
 348           (type & BSF_GLOBAL) ? 'g' : ' ',
 349           (type & BSF_IMPORT) ? 'i' : ' ',
 350           (type & BSF_EXPORT) ? 'e' : ' ',
 351           (type & BSF_UNDEFINED) ? 'u' : ' ',
 352           (type & BSF_FORT_COMM) ? 'c' : ' ',
 353           (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
 354           (type & BSF_WARNING) ? 'W' : ' ',
 355           (type & BSF_INDIRECT) ? 'I' : ' ',
 356           (type & BSF_DEBUGGING) ? 'd' :' ');
 357
 358 }
 359
 360
 361 /*proto*  bfd_make_empty_symbol
 362 This function creates a new @code{asymbol} structure for the BFD, and
 363 returns a pointer to it.
 364
 365 This routine is necessary, since each back end has private information
 366 surrounding the @code{asymbol}. Building your own @code{asymbol} and
 367 pointing to it will not create the private information, and will cause
 368 problems later on.
 369 *+
 370 #define bfd_make_empty_symbol(abfd) \
 371      BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
 372 *-
 373 */
 374
 375 /*proto* bfd_decode_symclass
 376 Return a lower-case character corresponding to the symbol class of symbol.
 377
 378 *; PROTO(int, bfd_decode_symclass, (asymbol *symbol));
 379 */
 380 int
 381 DEFUN(bfd_decode_symclass,(symbol),
 382 asymbol *symbol)
 383 {
 384   flagword flags = symbol->flags;
 385
 386 #if 0
 387   if ((symbol->value == 0) && (symbol->section != NULL))
 388     /* Huh?  All section names don't begin with "." */
 389     return (symbol->section->name)[1];
 390 #endif
 391
 392   if (flags & BSF_FORT_COMM) return 'C';
 393   if (flags & BSF_UNDEFINED) return 'U';
 394   if (flags & BSF_ABSOLUTE)  return 'a';
 395
 396
 397    if ( flags & (BSF_GLOBAL|BSF_LOCAL) ) {
 398      if (symbol->section == (asection *)NULL)
 399        return '*';
 400      else if ( !strcmp(symbol->section->name, ".text") )
 401        return (flags & BSF_GLOBAL) ? 'T' : 't';
 402      else if ( !strcmp(symbol->section->name, ".data") )
 403        return (flags & BSF_GLOBAL) ? 'D' : 'd';
 404      else if ( !strcmp(symbol->section->name, ".bss") )
 405        return (flags & BSF_GLOBAL) ? 'B' : 'b';
 406      else
 407        return (flags & BSF_GLOBAL) ? 'O' : 'o';
 408     }
 409
 410   /* We don't have to handle these cases just yet, but we will soon:
 411      N_SETV: 'v';
 412      N_SETA: 'l';
 413      N_SETT: 'x';
 414      N_SETD: 'z';
 415      N_SETB: 's';
 416      N_INDR: 'i';
 417      */
 418
 419   return '?';
 420 }
 421
 422 /* Create a table of debugging stab-codes and corresponding names.  */
 423
 424 #define __define_stab(NAME, CODE, STRING) {NAME, STRING},
 425 struct {enum __stab_debug_code code; char *string;} bfd_stab_names[]
 426   = {
 427 #include "stab.def"
 428     };
 429 #undef __define_stab
 430
 431 /*proto* bfd_stab_name
 432 Returns a string for the stab with the given code, or NULL if not found.
 433
 434 *; PROTO(char *, bfd_stab_name, (int code));
 435 */
 436 char *
 437 DEFUN(bfd_stab_name,(code),
 438 int code)
 439 {
 440   register int i;
 441   for (i = sizeof(bfd_stab_names) / sizeof(bfd_stab_names[0]) - 1; i >= 0; i--)
 442     if (bfd_stab_names[i].code == (enum __stab_debug_code) code)
 443       return bfd_stab_names[i].string;
 444   return NULL;
 445 }