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 **) malloc (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 Aointer 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 "sysdep.h"
 267 #include "bfd.h"
 268 #include "libbfd.h"
 269
 270 /*doc*
 271 @node symbol handling functions, Symbols, typedef asymbol, Symbols
 272 @subsection Symbol Handling Functions
 273
 274 */
 275
 276 /*proto* get_symtab_upper_bound
 277 Returns the number of bytes required in a vector of pointers to
 278 @code{asymbols} for all the symbols in the supplied BFD, including a
 279 terminal NULL pointer. If there are no symbols in the BFD, then 0 is
 280 returned.
 281 *+
 282 #define get_symtab_upper_bound(abfd) \
 283      BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
 284 *-
 285
 286 */
 287
 288 /*proto* bfd_canonicalize_symtab
 289 Supplied a BFD and a pointer to an uninitialized vector of pointers.
 290 This reads in the symbols from the BFD, and fills in the table with
 291 pointers to the symbols, and a trailing NULL. The routine returns the
 292 actual number of symbol pointers not including the NULL.
 293
 294 *+
 295 #define bfd_canonicalize_symtab(abfd, location) \
 296      BFD_SEND (abfd, _bfd_canonicalize_symtab,\
 297                   (abfd, location))
 298
 299 *-
 300 */
 301
 302
 303 /*proto* bfd_set_symtab
 304 Provided a table of pointers to to symbols and a count, writes to the
 305 output BFD the symbols when closed.
 306
 307 *; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int ));
 308 */
 309
 310 boolean
 311 bfd_set_symtab (abfd, location, symcount)
 312      bfd *abfd;
 313      asymbol **location;
 314      unsigned int symcount;
 315 {
 316   if ((abfd->format != bfd_object) || (bfd_read_p (abfd))) {
 317     bfd_error = invalid_operation;
 318     return false;
 319   }
 320
 321   bfd_get_outsymbols (abfd) = location;
 322   bfd_get_symcount (abfd) = symcount;
 323   return true;
 324 }
 325
 326 /*proto* bfd_print_symbol_vandf
 327 Prints the value and flags of the symbol supplied to the stream file.
 328
 329 *; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol));
 330 */
 331 void
 332 DEFUN(bfd_print_symbol_vandf,(file, symbol),
 333 PTR file AND
 334 asymbol *symbol)
 335 {
 336   flagword type = symbol->flags;
 337   if (symbol->section != (asection *)NULL)
 338       {
 339         fprintf_vma(file, symbol->value+symbol->section->vma);
 340       }
 341   else
 342       {
 343         fprintf_vma(file, symbol->value);
 344       }
 345   fprintf(file," %c%c%c%c%c%c%c%c%c%c",
 346           (type & BSF_LOCAL)  ? 'l':' ',
 347           (type & BSF_GLOBAL) ? 'g' : ' ',
 348           (type & BSF_IMPORT) ? 'i' : ' ',
 349           (type & BSF_EXPORT) ? 'e' : ' ',
 350           (type & BSF_UNDEFINED) ? 'u' : ' ',
 351           (type & BSF_FORT_COMM) ? 'c' : ' ',
 352           (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
 353           (type & BSF_WARNING) ? 'W' : ' ',
 354           (type & BSF_INDIRECT) ? 'I' : ' ',
 355           (type & BSF_DEBUGGING) ? 'd' :' ');
 356
 357 }
 358
 359
 360 /*proto*  bfd_make_empty_symbol
 361 This function creates a new @code{asymbol} structure for the BFD, and
 362 returns a pointer to it.
 363
 364 This routine is necessary, since each back end has private information
 365 surrounding the @code{asymbol}. Building your own @code{asymbol} and
 366 pointing to it will not create the private information, and will cause
 367 problems later on.
 368 *+
 369 #define bfd_make_empty_symbol(abfd) \
 370      BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
 371 *-
 372 */