bfd/
[external/binutils.git] / bfd / syms.c
1 /* Generic symbol-table support for the BFD library.
2    Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
3    2000, 2001, 2002, 2003, 2004, 2007
4    Free Software Foundation, Inc.
5    Written by Cygnus Support.
6
7    This file is part of BFD, the Binary File Descriptor library.
8
9    This program is free software; you can redistribute it and/or modify
10    it under the terms of the GNU General Public License as published by
11    the Free Software Foundation; either version 3 of the License, or
12    (at your option) any later version.
13
14    This program is distributed in the hope that it will be useful,
15    but WITHOUT ANY WARRANTY; without even the implied warranty of
16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17    GNU General Public License for more details.
18
19    You should have received a copy of the GNU General Public License
20    along with this program; if not, write to the Free Software
21    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
22    MA 02110-1301, USA.  */
23
24 /*
25 SECTION
26         Symbols
27
28         BFD tries to maintain as much symbol information as it can when
29         it moves information from file to file. BFD passes information
30         to applications though the <<asymbol>> structure. When the
31         application requests the symbol table, BFD reads the table in
32         the native form and translates parts of it into the internal
33         format. To maintain more than the information passed to
34         applications, some targets keep some information ``behind the
35         scenes'' in a structure only the particular back end knows
36         about. For example, the coff back end keeps the original
37         symbol table structure as well as the canonical structure when
38         a BFD is read in. On output, the coff back end can reconstruct
39         the output symbol table so that no information is lost, even
40         information unique to coff which BFD doesn't know or
41         understand. If a coff symbol table were read, but were written
42         through an a.out back end, all the coff specific information
43         would be lost. The symbol table of a BFD
44         is not necessarily read in until a canonicalize request is
45         made. Then the BFD back end fills in a table provided by the
46         application with pointers to the canonical information.  To
47         output symbols, the application provides BFD with a table of
48         pointers to pointers to <<asymbol>>s. This allows applications
49         like the linker to output a symbol as it was read, since the ``behind
50         the scenes'' information will be still available.
51 @menu
52 @* Reading Symbols::
53 @* Writing Symbols::
54 @* Mini Symbols::
55 @* typedef asymbol::
56 @* symbol handling functions::
57 @end menu
58
59 INODE
60 Reading Symbols, Writing Symbols, Symbols, Symbols
61 SUBSECTION
62         Reading symbols
63
64         There are two stages to reading a symbol table from a BFD:
65         allocating storage, and the actual reading process. This is an
66         excerpt from an application which reads the symbol table:
67
68 |         long storage_needed;
69 |         asymbol **symbol_table;
70 |         long number_of_symbols;
71 |         long i;
72 |
73 |         storage_needed = bfd_get_symtab_upper_bound (abfd);
74 |
75 |         if (storage_needed < 0)
76 |           FAIL
77 |
78 |         if (storage_needed == 0)
79 |           return;
80 |         
81 |         symbol_table = xmalloc (storage_needed);
82 |           ...
83 |         number_of_symbols =
84 |            bfd_canonicalize_symtab (abfd, symbol_table);
85 |
86 |         if (number_of_symbols < 0)
87 |           FAIL
88 |
89 |         for (i = 0; i < number_of_symbols; i++)
90 |           process_symbol (symbol_table[i]);
91
92         All storage for the symbols themselves is in an objalloc
93         connected to the BFD; it is freed when the BFD is closed.
94
95 INODE
96 Writing Symbols, Mini Symbols, Reading Symbols, Symbols
97 SUBSECTION
98         Writing symbols
99
100         Writing of a symbol table is automatic when a BFD open for
101         writing is closed. The application attaches a vector of
102         pointers to pointers to symbols to the BFD being written, and
103         fills in the symbol count. The close and cleanup code reads
104         through the table provided and performs all the necessary
105         operations. The BFD output code must always be provided with an
106         ``owned'' symbol: one which has come from another BFD, or one
107         which has been created using <<bfd_make_empty_symbol>>.  Here is an
108         example showing the creation of a symbol table with only one element:
109
110 |       #include "bfd.h"
111 |       int main (void)
112 |       {
113 |         bfd *abfd;
114 |         asymbol *ptrs[2];
115 |         asymbol *new;
116 |
117 |         abfd = bfd_openw ("foo","a.out-sunos-big");
118 |         bfd_set_format (abfd, bfd_object);
119 |         new = bfd_make_empty_symbol (abfd);
120 |         new->name = "dummy_symbol";
121 |         new->section = bfd_make_section_old_way (abfd, ".text");
122 |         new->flags = BSF_GLOBAL;
123 |         new->value = 0x12345;
124 |
125 |         ptrs[0] = new;
126 |         ptrs[1] = 0;
127 |
128 |         bfd_set_symtab (abfd, ptrs, 1);
129 |         bfd_close (abfd);
130 |         return 0;
131 |       }
132 |
133 |       ./makesym
134 |       nm foo
135 |       00012345 A dummy_symbol
136
137         Many formats cannot represent arbitrary symbol information; for
138         instance, the <<a.out>> object format does not allow an
139         arbitrary number of sections. A symbol pointing to a section
140         which is not one  of <<.text>>, <<.data>> or <<.bss>> cannot
141         be described.
142
143 INODE
144 Mini Symbols, typedef asymbol, Writing Symbols, Symbols
145 SUBSECTION
146         Mini Symbols
147
148         Mini symbols provide read-only access to the symbol table.
149         They use less memory space, but require more time to access.
150         They can be useful for tools like nm or objdump, which may
151         have to handle symbol tables of extremely large executables.
152
153         The <<bfd_read_minisymbols>> function will read the symbols
154         into memory in an internal form.  It will return a <<void *>>
155         pointer to a block of memory, a symbol count, and the size of
156         each symbol.  The pointer is allocated using <<malloc>>, and
157         should be freed by the caller when it is no longer needed.
158
159         The function <<bfd_minisymbol_to_symbol>> will take a pointer
160         to a minisymbol, and a pointer to a structure returned by
161         <<bfd_make_empty_symbol>>, and return a <<asymbol>> structure.
162         The return value may or may not be the same as the value from
163         <<bfd_make_empty_symbol>> which was passed in.
164
165 */
166
167 /*
168 DOCDD
169 INODE
170 typedef asymbol, symbol handling functions, Mini Symbols, Symbols
171
172 */
173 /*
174 SUBSECTION
175         typedef asymbol
176
177         An <<asymbol>> has the form:
178
179 */
180
181 /*
182 CODE_FRAGMENT
183
184 .
185 .typedef struct bfd_symbol
186 .{
187 .  {* A pointer to the BFD which owns the symbol. This information
188 .     is necessary so that a back end can work out what additional
189 .     information (invisible to the application writer) is carried
190 .     with the symbol.
191 .
192 .     This field is *almost* redundant, since you can use section->owner
193 .     instead, except that some symbols point to the global sections
194 .     bfd_{abs,com,und}_section.  This could be fixed by making
195 .     these globals be per-bfd (or per-target-flavor).  FIXME.  *}
196 .  struct bfd *the_bfd; {* Use bfd_asymbol_bfd(sym) to access this field.  *}
197 .
198 .  {* The text of the symbol. The name is left alone, and not copied; the
199 .     application may not alter it.  *}
200 .  const char *name;
201 .
202 .  {* The value of the symbol.  This really should be a union of a
203 .     numeric value with a pointer, since some flags indicate that
204 .     a pointer to another symbol is stored here.  *}
205 .  symvalue value;
206 .
207 .  {* Attributes of a symbol.  *}
208 .#define BSF_NO_FLAGS    0x00
209 .
210 .  {* The symbol has local scope; <<static>> in <<C>>. The value
211 .     is the offset into the section of the data.  *}
212 .#define BSF_LOCAL      0x01
213 .
214 .  {* The symbol has global scope; initialized data in <<C>>. The
215 .     value is the offset into the section of the data.  *}
216 .#define BSF_GLOBAL     0x02
217 .
218 .  {* The symbol has global scope and is exported. The value is
219 .     the offset into the section of the data.  *}
220 .#define BSF_EXPORT     BSF_GLOBAL {* No real difference.  *}
221 .
222 .  {* A normal C symbol would be one of:
223 .     <<BSF_LOCAL>>, <<BSF_FORT_COMM>>,  <<BSF_UNDEFINED>> or
224 .     <<BSF_GLOBAL>>.  *}
225 .
226 .  {* The symbol is a debugging record. The value has an arbitrary
227 .     meaning, unless BSF_DEBUGGING_RELOC is also set.  *}
228 .#define BSF_DEBUGGING  0x08
229 .
230 .  {* The symbol denotes a function entry point.  Used in ELF,
231 .     perhaps others someday.  *}
232 .#define BSF_FUNCTION    0x10
233 .
234 .  {* Used by the linker.  *}
235 .#define BSF_KEEP        0x20
236 .#define BSF_KEEP_G      0x40
237 .
238 .  {* A weak global symbol, overridable without warnings by
239 .     a regular global symbol of the same name.  *}
240 .#define BSF_WEAK        0x80
241 .
242 .  {* This symbol was created to point to a section, e.g. ELF's
243 .     STT_SECTION symbols.  *}
244 .#define BSF_SECTION_SYM 0x100
245 .
246 .  {* The symbol used to be a common symbol, but now it is
247 .     allocated.  *}
248 .#define BSF_OLD_COMMON  0x200
249 .
250 .  {* The default value for common data.  *}
251 .#define BFD_FORT_COMM_DEFAULT_VALUE 0
252 .
253 .  {* In some files the type of a symbol sometimes alters its
254 .     location in an output file - ie in coff a <<ISFCN>> symbol
255 .     which is also <<C_EXT>> symbol appears where it was
256 .     declared and not at the end of a section.  This bit is set
257 .     by the target BFD part to convey this information.  *}
258 .#define BSF_NOT_AT_END    0x400
259 .
260 .  {* Signal that the symbol is the label of constructor section.  *}
261 .#define BSF_CONSTRUCTOR   0x800
262 .
263 .  {* Signal that the symbol is a warning symbol.  The name is a
264 .     warning.  The name of the next symbol is the one to warn about;
265 .     if a reference is made to a symbol with the same name as the next
266 .     symbol, a warning is issued by the linker.  *}
267 .#define BSF_WARNING       0x1000
268 .
269 .  {* Signal that the symbol is indirect.  This symbol is an indirect
270 .     pointer to the symbol with the same name as the next symbol.  *}
271 .#define BSF_INDIRECT      0x2000
272 .
273 .  {* BSF_FILE marks symbols that contain a file name.  This is used
274 .     for ELF STT_FILE symbols.  *}
275 .#define BSF_FILE          0x4000
276 .
277 .  {* Symbol is from dynamic linking information.  *}
278 .#define BSF_DYNAMIC       0x8000
279 .
280 .  {* The symbol denotes a data object.  Used in ELF, and perhaps
281 .     others someday.  *}
282 .#define BSF_OBJECT        0x10000
283 .
284 .  {* This symbol is a debugging symbol.  The value is the offset
285 .     into the section of the data.  BSF_DEBUGGING should be set
286 .     as well.  *}
287 .#define BSF_DEBUGGING_RELOC 0x20000
288 .
289 .  {* This symbol is thread local.  Used in ELF.  *}
290 .#define BSF_THREAD_LOCAL  0x40000
291 .
292 .  {* This symbol represents a complex relocation expression,
293 .     with the expression tree serialized in the symbol name.  *}
294 .#define BSF_RELC 0x80000
295 .
296 .  {* This symbol represents a signed complex relocation expression,
297 .     with the expression tree serialized in the symbol name.  *}
298 .#define BSF_SRELC 0x100000
299 .
300 .  {* This symbol was created by bfd_get_synthetic_symtab.  *}
301 .#define BSF_SYNTHETIC 0x200000
302 .
303 .  flagword flags;
304 .
305 .  {* A pointer to the section to which this symbol is
306 .     relative.  This will always be non NULL, there are special
307 .     sections for undefined and absolute symbols.  *}
308 .  struct bfd_section *section;
309 .
310 .  {* Back end special data.  *}
311 .  union
312 .    {
313 .      void *p;
314 .      bfd_vma i;
315 .    }
316 .  udata;
317 .}
318 .asymbol;
319 .
320 */
321
322 #include "sysdep.h"
323 #include "bfd.h"
324 #include "libbfd.h"
325 #include "safe-ctype.h"
326 #include "bfdlink.h"
327 #include "aout/stab_gnu.h"
328
329 /*
330 DOCDD
331 INODE
332 symbol handling functions,  , typedef asymbol, Symbols
333 SUBSECTION
334         Symbol handling functions
335 */
336
337 /*
338 FUNCTION
339         bfd_get_symtab_upper_bound
340
341 DESCRIPTION
342         Return the number of bytes required to store a vector of pointers
343         to <<asymbols>> for all the symbols in the BFD @var{abfd},
344         including a terminal NULL pointer. If there are no symbols in
345         the BFD, then return 0.  If an error occurs, return -1.
346
347 .#define bfd_get_symtab_upper_bound(abfd) \
348 .     BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
349 .
350 */
351
352 /*
353 FUNCTION
354         bfd_is_local_label
355
356 SYNOPSIS
357         bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym);
358
359 DESCRIPTION
360         Return TRUE if the given symbol @var{sym} in the BFD @var{abfd} is
361         a compiler generated local label, else return FALSE.
362 */
363
364 bfd_boolean
365 bfd_is_local_label (bfd *abfd, asymbol *sym)
366 {
367   /* The BSF_SECTION_SYM check is needed for IA-64, where every label that
368      starts with '.' is local.  This would accidentally catch section names
369      if we didn't reject them here.  */
370   if ((sym->flags & (BSF_GLOBAL | BSF_WEAK | BSF_FILE | BSF_SECTION_SYM)) != 0)
371     return FALSE;
372   if (sym->name == NULL)
373     return FALSE;
374   return bfd_is_local_label_name (abfd, sym->name);
375 }
376
377 /*
378 FUNCTION
379         bfd_is_local_label_name
380
381 SYNOPSIS
382         bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name);
383
384 DESCRIPTION
385         Return TRUE if a symbol with the name @var{name} in the BFD
386         @var{abfd} is a compiler generated local label, else return
387         FALSE.  This just checks whether the name has the form of a
388         local label.
389
390 .#define bfd_is_local_label_name(abfd, name) \
391 .  BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
392 .
393 */
394
395 /*
396 FUNCTION
397         bfd_is_target_special_symbol
398
399 SYNOPSIS
400         bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym);
401
402 DESCRIPTION
403         Return TRUE iff a symbol @var{sym} in the BFD @var{abfd} is something
404         special to the particular target represented by the BFD.  Such symbols
405         should normally not be mentioned to the user.
406
407 .#define bfd_is_target_special_symbol(abfd, sym) \
408 .  BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym))
409 .
410 */
411
412 /*
413 FUNCTION
414         bfd_canonicalize_symtab
415
416 DESCRIPTION
417         Read the symbols from the BFD @var{abfd}, and fills in
418         the vector @var{location} with pointers to the symbols and
419         a trailing NULL.
420         Return the actual number of symbol pointers, not
421         including the NULL.
422
423 .#define bfd_canonicalize_symtab(abfd, location) \
424 .  BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location))
425 .
426 */
427
428 /*
429 FUNCTION
430         bfd_set_symtab
431
432 SYNOPSIS
433         bfd_boolean bfd_set_symtab
434           (bfd *abfd, asymbol **location, unsigned int count);
435
436 DESCRIPTION
437         Arrange that when the output BFD @var{abfd} is closed,
438         the table @var{location} of @var{count} pointers to symbols
439         will be written.
440 */
441
442 bfd_boolean
443 bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int symcount)
444 {
445   if (abfd->format != bfd_object || bfd_read_p (abfd))
446     {
447       bfd_set_error (bfd_error_invalid_operation);
448       return FALSE;
449     }
450
451   bfd_get_outsymbols (abfd) = location;
452   bfd_get_symcount (abfd) = symcount;
453   return TRUE;
454 }
455
456 /*
457 FUNCTION
458         bfd_print_symbol_vandf
459
460 SYNOPSIS
461         void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol);
462
463 DESCRIPTION
464         Print the value and flags of the @var{symbol} supplied to the
465         stream @var{file}.
466 */
467 void
468 bfd_print_symbol_vandf (bfd *abfd, void *arg, asymbol *symbol)
469 {
470   FILE *file = arg;
471
472   flagword type = symbol->flags;
473
474   if (symbol->section != NULL)
475     bfd_fprintf_vma (abfd, file, symbol->value + symbol->section->vma);
476   else
477     bfd_fprintf_vma (abfd, file, symbol->value);
478
479   /* This presumes that a symbol can not be both BSF_DEBUGGING and
480      BSF_DYNAMIC, nor more than one of BSF_FUNCTION, BSF_FILE, and
481      BSF_OBJECT.  */
482   fprintf (file, " %c%c%c%c%c%c%c",
483            ((type & BSF_LOCAL)
484             ? (type & BSF_GLOBAL) ? '!' : 'l'
485             : (type & BSF_GLOBAL) ? 'g' : ' '),
486            (type & BSF_WEAK) ? 'w' : ' ',
487            (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
488            (type & BSF_WARNING) ? 'W' : ' ',
489            (type & BSF_INDIRECT) ? 'I' : ' ',
490            (type & BSF_DEBUGGING) ? 'd' : (type & BSF_DYNAMIC) ? 'D' : ' ',
491            ((type & BSF_FUNCTION)
492             ? 'F'
493             : ((type & BSF_FILE)
494                ? 'f'
495                : ((type & BSF_OBJECT) ? 'O' : ' '))));
496 }
497
498 /*
499 FUNCTION
500         bfd_make_empty_symbol
501
502 DESCRIPTION
503         Create a new <<asymbol>> structure for the BFD @var{abfd}
504         and return a pointer to it.
505
506         This routine is necessary because each back end has private
507         information surrounding the <<asymbol>>. Building your own
508         <<asymbol>> and pointing to it will not create the private
509         information, and will cause problems later on.
510
511 .#define bfd_make_empty_symbol(abfd) \
512 .  BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
513 .
514 */
515
516 /*
517 FUNCTION
518         _bfd_generic_make_empty_symbol
519
520 SYNOPSIS
521         asymbol *_bfd_generic_make_empty_symbol (bfd *);
522
523 DESCRIPTION
524         Create a new <<asymbol>> structure for the BFD @var{abfd}
525         and return a pointer to it.  Used by core file routines,
526         binary back-end and anywhere else where no private info
527         is needed.
528 */
529
530 asymbol *
531 _bfd_generic_make_empty_symbol (bfd *abfd)
532 {
533   bfd_size_type amt = sizeof (asymbol);
534   asymbol *new = bfd_zalloc (abfd, amt);
535   if (new)
536     new->the_bfd = abfd;
537   return new;
538 }
539
540 /*
541 FUNCTION
542         bfd_make_debug_symbol
543
544 DESCRIPTION
545         Create a new <<asymbol>> structure for the BFD @var{abfd},
546         to be used as a debugging symbol.  Further details of its use have
547         yet to be worked out.
548
549 .#define bfd_make_debug_symbol(abfd,ptr,size) \
550 .  BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
551 .
552 */
553
554 struct section_to_type
555 {
556   const char *section;
557   char type;
558 };
559
560 /* Map section names to POSIX/BSD single-character symbol types.
561    This table is probably incomplete.  It is sorted for convenience of
562    adding entries.  Since it is so short, a linear search is used.  */
563 static const struct section_to_type stt[] =
564 {
565   {".bss", 'b'},
566   {"code", 't'},                /* MRI .text */
567   {".data", 'd'},
568   {"*DEBUG*", 'N'},
569   {".debug", 'N'},              /* MSVC's .debug (non-standard debug syms) */
570   {".drectve", 'i'},            /* MSVC's .drective section */
571   {".edata", 'e'},              /* MSVC's .edata (export) section */
572   {".fini", 't'},               /* ELF fini section */
573   {".idata", 'i'},              /* MSVC's .idata (import) section */
574   {".init", 't'},               /* ELF init section */
575   {".pdata", 'p'},              /* MSVC's .pdata (stack unwind) section */
576   {".rdata", 'r'},              /* Read only data.  */
577   {".rodata", 'r'},             /* Read only data.  */
578   {".sbss", 's'},               /* Small BSS (uninitialized data).  */
579   {".scommon", 'c'},            /* Small common.  */
580   {".sdata", 'g'},              /* Small initialized data.  */
581   {".text", 't'},
582   {"vars", 'd'},                /* MRI .data */
583   {"zerovars", 'b'},            /* MRI .bss */
584   {0, 0}
585 };
586
587 /* Return the single-character symbol type corresponding to
588    section S, or '?' for an unknown COFF section.
589
590    Check for any leading string which matches, so .text5 returns
591    't' as well as .text */
592
593 static char
594 coff_section_type (const char *s)
595 {
596   const struct section_to_type *t;
597
598   for (t = &stt[0]; t->section; t++)
599     if (!strncmp (s, t->section, strlen (t->section)))
600       return t->type;
601
602   return '?';
603 }
604
605 /* Return the single-character symbol type corresponding to section
606    SECTION, or '?' for an unknown section.  This uses section flags to
607    identify sections.
608
609    FIXME These types are unhandled: c, i, e, p.  If we handled these also,
610    we could perhaps obsolete coff_section_type.  */
611
612 static char
613 decode_section_type (const struct bfd_section *section)
614 {
615   if (section->flags & SEC_CODE)
616     return 't';
617   if (section->flags & SEC_DATA)
618     {
619       if (section->flags & SEC_READONLY)
620         return 'r';
621       else if (section->flags & SEC_SMALL_DATA)
622         return 'g';
623       else
624         return 'd';
625     }
626   if ((section->flags & SEC_HAS_CONTENTS) == 0)
627     {
628       if (section->flags & SEC_SMALL_DATA)
629         return 's';
630       else
631         return 'b';
632     }
633   if (section->flags & SEC_DEBUGGING)
634     return 'N';
635   if ((section->flags & SEC_HAS_CONTENTS) && (section->flags & SEC_READONLY))
636     return 'n';
637
638   return '?';
639 }
640
641 /*
642 FUNCTION
643         bfd_decode_symclass
644
645 DESCRIPTION
646         Return a character corresponding to the symbol
647         class of @var{symbol}, or '?' for an unknown class.
648
649 SYNOPSIS
650         int bfd_decode_symclass (asymbol *symbol);
651 */
652 int
653 bfd_decode_symclass (asymbol *symbol)
654 {
655   char c;
656
657   if (symbol->section && bfd_is_com_section (symbol->section))
658     return 'C';
659   if (bfd_is_und_section (symbol->section))
660     {
661       if (symbol->flags & BSF_WEAK)
662         {
663           /* If weak, determine if it's specifically an object
664              or non-object weak.  */
665           if (symbol->flags & BSF_OBJECT)
666             return 'v';
667           else
668             return 'w';
669         }
670       else
671         return 'U';
672     }
673   if (bfd_is_ind_section (symbol->section))
674     return 'I';
675   if (symbol->flags & BSF_WEAK)
676     {
677       /* If weak, determine if it's specifically an object
678          or non-object weak.  */
679       if (symbol->flags & BSF_OBJECT)
680         return 'V';
681       else
682         return 'W';
683     }
684   if (!(symbol->flags & (BSF_GLOBAL | BSF_LOCAL)))
685     return '?';
686
687   if (bfd_is_abs_section (symbol->section))
688     c = 'a';
689   else if (symbol->section)
690     {
691       c = coff_section_type (symbol->section->name);
692       if (c == '?')
693         c = decode_section_type (symbol->section);
694     }
695   else
696     return '?';
697   if (symbol->flags & BSF_GLOBAL)
698     c = TOUPPER (c);
699   return c;
700
701   /* We don't have to handle these cases just yet, but we will soon:
702      N_SETV: 'v';
703      N_SETA: 'l';
704      N_SETT: 'x';
705      N_SETD: 'z';
706      N_SETB: 's';
707      N_INDR: 'i';
708      */
709 }
710
711 /*
712 FUNCTION
713         bfd_is_undefined_symclass
714
715 DESCRIPTION
716         Returns non-zero if the class symbol returned by
717         bfd_decode_symclass represents an undefined symbol.
718         Returns zero otherwise.
719
720 SYNOPSIS
721         bfd_boolean bfd_is_undefined_symclass (int symclass);
722 */
723
724 bfd_boolean
725 bfd_is_undefined_symclass (int symclass)
726 {
727   return symclass == 'U' || symclass == 'w' || symclass == 'v';
728 }
729
730 /*
731 FUNCTION
732         bfd_symbol_info
733
734 DESCRIPTION
735         Fill in the basic info about symbol that nm needs.
736         Additional info may be added by the back-ends after
737         calling this function.
738
739 SYNOPSIS
740         void bfd_symbol_info (asymbol *symbol, symbol_info *ret);
741 */
742
743 void
744 bfd_symbol_info (asymbol *symbol, symbol_info *ret)
745 {
746   ret->type = bfd_decode_symclass (symbol);
747
748   if (bfd_is_undefined_symclass (ret->type))
749     ret->value = 0;
750   else
751     ret->value = symbol->value + symbol->section->vma;
752
753   ret->name = symbol->name;
754 }
755
756 /*
757 FUNCTION
758         bfd_copy_private_symbol_data
759
760 SYNOPSIS
761         bfd_boolean bfd_copy_private_symbol_data
762           (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
763
764 DESCRIPTION
765         Copy private symbol information from @var{isym} in the BFD
766         @var{ibfd} to the symbol @var{osym} in the BFD @var{obfd}.
767         Return <<TRUE>> on success, <<FALSE>> on error.  Possible error
768         returns are:
769
770         o <<bfd_error_no_memory>> -
771         Not enough memory exists to create private data for @var{osec}.
772
773 .#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
774 .  BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
775 .            (ibfd, isymbol, obfd, osymbol))
776 .
777 */
778
779 /* The generic version of the function which returns mini symbols.
780    This is used when the backend does not provide a more efficient
781    version.  It just uses BFD asymbol structures as mini symbols.  */
782
783 long
784 _bfd_generic_read_minisymbols (bfd *abfd,
785                                bfd_boolean dynamic,
786                                void **minisymsp,
787                                unsigned int *sizep)
788 {
789   long storage;
790   asymbol **syms = NULL;
791   long symcount;
792
793   if (dynamic)
794     storage = bfd_get_dynamic_symtab_upper_bound (abfd);
795   else
796     storage = bfd_get_symtab_upper_bound (abfd);
797   if (storage < 0)
798     goto error_return;
799   if (storage == 0)
800     return 0;
801
802   syms = bfd_malloc (storage);
803   if (syms == NULL)
804     goto error_return;
805
806   if (dynamic)
807     symcount = bfd_canonicalize_dynamic_symtab (abfd, syms);
808   else
809     symcount = bfd_canonicalize_symtab (abfd, syms);
810   if (symcount < 0)
811     goto error_return;
812
813   *minisymsp = syms;
814   *sizep = sizeof (asymbol *);
815   return symcount;
816
817  error_return:
818   bfd_set_error (bfd_error_no_symbols);
819   if (syms != NULL)
820     free (syms);
821   return -1;
822 }
823
824 /* The generic version of the function which converts a minisymbol to
825    an asymbol.  We don't worry about the sym argument we are passed;
826    we just return the asymbol the minisymbol points to.  */
827
828 asymbol *
829 _bfd_generic_minisymbol_to_symbol (bfd *abfd ATTRIBUTE_UNUSED,
830                                    bfd_boolean dynamic ATTRIBUTE_UNUSED,
831                                    const void *minisym,
832                                    asymbol *sym ATTRIBUTE_UNUSED)
833 {
834   return *(asymbol **) minisym;
835 }
836
837 /* Look through stabs debugging information in .stab and .stabstr
838    sections to find the source file and line closest to a desired
839    location.  This is used by COFF and ELF targets.  It sets *pfound
840    to TRUE if it finds some information.  The *pinfo field is used to
841    pass cached information in and out of this routine; this first time
842    the routine is called for a BFD, *pinfo should be NULL.  The value
843    placed in *pinfo should be saved with the BFD, and passed back each
844    time this function is called.  */
845
846 /* We use a cache by default.  */
847
848 #define ENABLE_CACHING
849
850 /* We keep an array of indexentry structures to record where in the
851    stabs section we should look to find line number information for a
852    particular address.  */
853
854 struct indexentry
855 {
856   bfd_vma val;
857   bfd_byte *stab;
858   bfd_byte *str;
859   char *directory_name;
860   char *file_name;
861   char *function_name;
862 };
863
864 /* Compare two indexentry structures.  This is called via qsort.  */
865
866 static int
867 cmpindexentry (const void *a, const void *b)
868 {
869   const struct indexentry *contestantA = a;
870   const struct indexentry *contestantB = b;
871
872   if (contestantA->val < contestantB->val)
873     return -1;
874   else if (contestantA->val > contestantB->val)
875     return 1;
876   else
877     return 0;
878 }
879
880 /* A pointer to this structure is stored in *pinfo.  */
881
882 struct stab_find_info
883 {
884   /* The .stab section.  */
885   asection *stabsec;
886   /* The .stabstr section.  */
887   asection *strsec;
888   /* The contents of the .stab section.  */
889   bfd_byte *stabs;
890   /* The contents of the .stabstr section.  */
891   bfd_byte *strs;
892
893   /* A table that indexes stabs by memory address.  */
894   struct indexentry *indextable;
895   /* The number of entries in indextable.  */
896   int indextablesize;
897
898 #ifdef ENABLE_CACHING
899   /* Cached values to restart quickly.  */
900   struct indexentry *cached_indexentry;
901   bfd_vma cached_offset;
902   bfd_byte *cached_stab;
903   char *cached_file_name;
904 #endif
905
906   /* Saved ptr to malloc'ed filename.  */
907   char *filename;
908 };
909
910 bfd_boolean
911 _bfd_stab_section_find_nearest_line (bfd *abfd,
912                                      asymbol **symbols,
913                                      asection *section,
914                                      bfd_vma offset,
915                                      bfd_boolean *pfound,
916                                      const char **pfilename,
917                                      const char **pfnname,
918                                      unsigned int *pline,
919                                      void **pinfo)
920 {
921   struct stab_find_info *info;
922   bfd_size_type stabsize, strsize;
923   bfd_byte *stab, *str;
924   bfd_byte *last_stab = NULL;
925   bfd_size_type stroff;
926   struct indexentry *indexentry;
927   char *file_name;
928   char *directory_name;
929   int saw_fun;
930   bfd_boolean saw_line, saw_func;
931
932   *pfound = FALSE;
933   *pfilename = bfd_get_filename (abfd);
934   *pfnname = NULL;
935   *pline = 0;
936
937   /* Stabs entries use a 12 byte format:
938        4 byte string table index
939        1 byte stab type
940        1 byte stab other field
941        2 byte stab desc field
942        4 byte stab value
943      FIXME: This will have to change for a 64 bit object format.
944
945      The stabs symbols are divided into compilation units.  For the
946      first entry in each unit, the type of 0, the value is the length
947      of the string table for this unit, and the desc field is the
948      number of stabs symbols for this unit.  */
949
950 #define STRDXOFF (0)
951 #define TYPEOFF (4)
952 #define OTHEROFF (5)
953 #define DESCOFF (6)
954 #define VALOFF (8)
955 #define STABSIZE (12)
956
957   info = *pinfo;
958   if (info != NULL)
959     {
960       if (info->stabsec == NULL || info->strsec == NULL)
961         {
962           /* No stabs debugging information.  */
963           return TRUE;
964         }
965
966       stabsize = (info->stabsec->rawsize
967                   ? info->stabsec->rawsize
968                   : info->stabsec->size);
969       strsize = (info->strsec->rawsize
970                  ? info->strsec->rawsize
971                  : info->strsec->size);
972     }
973   else
974     {
975       long reloc_size, reloc_count;
976       arelent **reloc_vector;
977       int i;
978       char *name;
979       char *function_name;
980       bfd_size_type amt = sizeof *info;
981
982       info = bfd_zalloc (abfd, amt);
983       if (info == NULL)
984         return FALSE;
985
986       /* FIXME: When using the linker --split-by-file or
987          --split-by-reloc options, it is possible for the .stab and
988          .stabstr sections to be split.  We should handle that.  */
989
990       info->stabsec = bfd_get_section_by_name (abfd, ".stab");
991       info->strsec = bfd_get_section_by_name (abfd, ".stabstr");
992
993       if (info->stabsec == NULL || info->strsec == NULL)
994         {
995           /* Try SOM section names.  */
996           info->stabsec = bfd_get_section_by_name (abfd, "$GDB_SYMBOLS$");
997           info->strsec  = bfd_get_section_by_name (abfd, "$GDB_STRINGS$");
998   
999           if (info->stabsec == NULL || info->strsec == NULL)
1000             {
1001               /* No stabs debugging information.  Set *pinfo so that we
1002                  can return quickly in the info != NULL case above.  */
1003               *pinfo = info;
1004               return TRUE;
1005             }
1006         }
1007
1008       stabsize = (info->stabsec->rawsize
1009                   ? info->stabsec->rawsize
1010                   : info->stabsec->size);
1011       strsize = (info->strsec->rawsize
1012                  ? info->strsec->rawsize
1013                  : info->strsec->size);
1014
1015       info->stabs = bfd_alloc (abfd, stabsize);
1016       info->strs = bfd_alloc (abfd, strsize);
1017       if (info->stabs == NULL || info->strs == NULL)
1018         return FALSE;
1019
1020       if (! bfd_get_section_contents (abfd, info->stabsec, info->stabs,
1021                                       0, stabsize)
1022           || ! bfd_get_section_contents (abfd, info->strsec, info->strs,
1023                                          0, strsize))
1024         return FALSE;
1025
1026       /* If this is a relocatable object file, we have to relocate
1027          the entries in .stab.  This should always be simple 32 bit
1028          relocations against symbols defined in this object file, so
1029          this should be no big deal.  */
1030       reloc_size = bfd_get_reloc_upper_bound (abfd, info->stabsec);
1031       if (reloc_size < 0)
1032         return FALSE;
1033       reloc_vector = bfd_malloc (reloc_size);
1034       if (reloc_vector == NULL && reloc_size != 0)
1035         return FALSE;
1036       reloc_count = bfd_canonicalize_reloc (abfd, info->stabsec, reloc_vector,
1037                                             symbols);
1038       if (reloc_count < 0)
1039         {
1040           if (reloc_vector != NULL)
1041             free (reloc_vector);
1042           return FALSE;
1043         }
1044       if (reloc_count > 0)
1045         {
1046           arelent **pr;
1047
1048           for (pr = reloc_vector; *pr != NULL; pr++)
1049             {
1050               arelent *r;
1051               unsigned long val;
1052               asymbol *sym;
1053
1054               r = *pr;
1055               /* Ignore R_*_NONE relocs.  */
1056               if (r->howto->dst_mask == 0)
1057                 continue;
1058
1059               if (r->howto->rightshift != 0
1060                   || r->howto->size != 2
1061                   || r->howto->bitsize != 32
1062                   || r->howto->pc_relative
1063                   || r->howto->bitpos != 0
1064                   || r->howto->dst_mask != 0xffffffff)
1065                 {
1066                   (*_bfd_error_handler)
1067                     (_("Unsupported .stab relocation"));
1068                   bfd_set_error (bfd_error_invalid_operation);
1069                   if (reloc_vector != NULL)
1070                     free (reloc_vector);
1071                   return FALSE;
1072                 }
1073
1074               val = bfd_get_32 (abfd, info->stabs + r->address);
1075               val &= r->howto->src_mask;
1076               sym = *r->sym_ptr_ptr;
1077               val += sym->value + sym->section->vma + r->addend;
1078               bfd_put_32 (abfd, (bfd_vma) val, info->stabs + r->address);
1079             }
1080         }
1081
1082       if (reloc_vector != NULL)
1083         free (reloc_vector);
1084
1085       /* First time through this function, build a table matching
1086          function VM addresses to stabs, then sort based on starting
1087          VM address.  Do this in two passes: once to count how many
1088          table entries we'll need, and a second to actually build the
1089          table.  */
1090
1091       info->indextablesize = 0;
1092       saw_fun = 1;
1093       for (stab = info->stabs; stab < info->stabs + stabsize; stab += STABSIZE)
1094         {
1095           if (stab[TYPEOFF] == (bfd_byte) N_SO)
1096             {
1097               /* N_SO with null name indicates EOF */
1098               if (bfd_get_32 (abfd, stab + STRDXOFF) == 0)
1099                 continue;
1100
1101               /* if we did not see a function def, leave space for one.  */
1102               if (saw_fun == 0)
1103                 ++info->indextablesize;
1104
1105               saw_fun = 0;
1106
1107               /* two N_SO's in a row is a filename and directory. Skip */
1108               if (stab + STABSIZE < info->stabs + stabsize
1109                   && *(stab + STABSIZE + TYPEOFF) == (bfd_byte) N_SO)
1110                 {
1111                   stab += STABSIZE;
1112                 }
1113             }
1114           else if (stab[TYPEOFF] == (bfd_byte) N_FUN)
1115             {
1116               saw_fun = 1;
1117               ++info->indextablesize;
1118             }
1119         }
1120
1121       if (saw_fun == 0)
1122         ++info->indextablesize;
1123
1124       if (info->indextablesize == 0)
1125         return TRUE;
1126       ++info->indextablesize;
1127
1128       amt = info->indextablesize;
1129       amt *= sizeof (struct indexentry);
1130       info->indextable = bfd_alloc (abfd, amt);
1131       if (info->indextable == NULL)
1132         return FALSE;
1133
1134       file_name = NULL;
1135       directory_name = NULL;
1136       saw_fun = 1;
1137
1138       for (i = 0, stroff = 0, stab = info->stabs, str = info->strs;
1139            i < info->indextablesize && stab < info->stabs + stabsize;
1140            stab += STABSIZE)
1141         {
1142           switch (stab[TYPEOFF])
1143             {
1144             case 0:
1145               /* This is the first entry in a compilation unit.  */
1146               if ((bfd_size_type) ((info->strs + strsize) - str) < stroff)
1147                 break;
1148               str += stroff;
1149               stroff = bfd_get_32 (abfd, stab + VALOFF);
1150               break;
1151
1152             case N_SO:
1153               /* The main file name.  */
1154
1155               /* The following code creates a new indextable entry with
1156                  a NULL function name if there were no N_FUNs in a file.
1157                  Note that a N_SO without a file name is an EOF and
1158                  there could be 2 N_SO following it with the new filename
1159                  and directory.  */
1160               if (saw_fun == 0)
1161                 {
1162                   info->indextable[i].val = bfd_get_32 (abfd, last_stab + VALOFF);
1163                   info->indextable[i].stab = last_stab;
1164                   info->indextable[i].str = str;
1165                   info->indextable[i].directory_name = directory_name;
1166                   info->indextable[i].file_name = file_name;
1167                   info->indextable[i].function_name = NULL;
1168                   ++i;
1169                 }
1170               saw_fun = 0;
1171
1172               file_name = (char *) str + bfd_get_32 (abfd, stab + STRDXOFF);
1173               if (*file_name == '\0')
1174                 {
1175                   directory_name = NULL;
1176                   file_name = NULL;
1177                   saw_fun = 1;
1178                 }
1179               else
1180                 {
1181                   last_stab = stab;
1182                   if (stab + STABSIZE >= info->stabs + stabsize
1183                       || *(stab + STABSIZE + TYPEOFF) != (bfd_byte) N_SO)
1184                     {
1185                       directory_name = NULL;
1186                     }
1187                   else
1188                     {
1189                       /* Two consecutive N_SOs are a directory and a
1190                          file name.  */
1191                       stab += STABSIZE;
1192                       directory_name = file_name;
1193                       file_name = ((char *) str
1194                                    + bfd_get_32 (abfd, stab + STRDXOFF));
1195                     }
1196                 }
1197               break;
1198
1199             case N_SOL:
1200               /* The name of an include file.  */
1201               file_name = (char *) str + bfd_get_32 (abfd, stab + STRDXOFF);
1202               break;
1203
1204             case N_FUN:
1205               /* A function name.  */
1206               saw_fun = 1;
1207               name = (char *) str + bfd_get_32 (abfd, stab + STRDXOFF);
1208
1209               if (*name == '\0')
1210                 name = NULL;
1211
1212               function_name = name;
1213
1214               if (name == NULL)
1215                 continue;
1216
1217               info->indextable[i].val = bfd_get_32 (abfd, stab + VALOFF);
1218               info->indextable[i].stab = stab;
1219               info->indextable[i].str = str;
1220               info->indextable[i].directory_name = directory_name;
1221               info->indextable[i].file_name = file_name;
1222               info->indextable[i].function_name = function_name;
1223               ++i;
1224               break;
1225             }
1226         }
1227
1228       if (saw_fun == 0)
1229         {
1230           info->indextable[i].val = bfd_get_32 (abfd, last_stab + VALOFF);
1231           info->indextable[i].stab = last_stab;
1232           info->indextable[i].str = str;
1233           info->indextable[i].directory_name = directory_name;
1234           info->indextable[i].file_name = file_name;
1235           info->indextable[i].function_name = NULL;
1236           ++i;
1237         }
1238
1239       info->indextable[i].val = (bfd_vma) -1;
1240       info->indextable[i].stab = info->stabs + stabsize;
1241       info->indextable[i].str = str;
1242       info->indextable[i].directory_name = NULL;
1243       info->indextable[i].file_name = NULL;
1244       info->indextable[i].function_name = NULL;
1245       ++i;
1246
1247       info->indextablesize = i;
1248       qsort (info->indextable, (size_t) i, sizeof (struct indexentry),
1249              cmpindexentry);
1250
1251       *pinfo = info;
1252     }
1253
1254   /* We are passed a section relative offset.  The offsets in the
1255      stabs information are absolute.  */
1256   offset += bfd_get_section_vma (abfd, section);
1257
1258 #ifdef ENABLE_CACHING
1259   if (info->cached_indexentry != NULL
1260       && offset >= info->cached_offset
1261       && offset < (info->cached_indexentry + 1)->val)
1262     {
1263       stab = info->cached_stab;
1264       indexentry = info->cached_indexentry;
1265       file_name = info->cached_file_name;
1266     }
1267   else
1268 #endif
1269     {
1270       long low, high;
1271       long mid = -1;
1272
1273       /* Cache non-existent or invalid.  Do binary search on
1274          indextable.  */
1275       indexentry = NULL;
1276
1277       low = 0;
1278       high = info->indextablesize - 1;
1279       while (low != high)
1280         {
1281           mid = (high + low) / 2;
1282           if (offset >= info->indextable[mid].val
1283               && offset < info->indextable[mid + 1].val)
1284             {
1285               indexentry = &info->indextable[mid];
1286               break;
1287             }
1288
1289           if (info->indextable[mid].val > offset)
1290             high = mid;
1291           else
1292             low = mid + 1;
1293         }
1294
1295       if (indexentry == NULL)
1296         return TRUE;
1297
1298       stab = indexentry->stab + STABSIZE;
1299       file_name = indexentry->file_name;
1300     }
1301
1302   directory_name = indexentry->directory_name;
1303   str = indexentry->str;
1304
1305   saw_line = FALSE;
1306   saw_func = FALSE;
1307   for (; stab < (indexentry+1)->stab; stab += STABSIZE)
1308     {
1309       bfd_boolean done;
1310       bfd_vma val;
1311
1312       done = FALSE;
1313
1314       switch (stab[TYPEOFF])
1315         {
1316         case N_SOL:
1317           /* The name of an include file.  */
1318           val = bfd_get_32 (abfd, stab + VALOFF);
1319           if (val <= offset)
1320             {
1321               file_name = (char *) str + bfd_get_32 (abfd, stab + STRDXOFF);
1322               *pline = 0;
1323             }
1324           break;
1325
1326         case N_SLINE:
1327         case N_DSLINE:
1328         case N_BSLINE:
1329           /* A line number.  If the function was specified, then the value
1330              is relative to the start of the function.  Otherwise, the
1331              value is an absolute address.  */
1332           val = ((indexentry->function_name ? indexentry->val : 0)
1333                  + bfd_get_32 (abfd, stab + VALOFF));
1334           /* If this line starts before our desired offset, or if it's
1335              the first line we've been able to find, use it.  The
1336              !saw_line check works around a bug in GCC 2.95.3, which emits
1337              the first N_SLINE late.  */
1338           if (!saw_line || val <= offset)
1339             {
1340               *pline = bfd_get_16 (abfd, stab + DESCOFF);
1341
1342 #ifdef ENABLE_CACHING
1343               info->cached_stab = stab;
1344               info->cached_offset = val;
1345               info->cached_file_name = file_name;
1346               info->cached_indexentry = indexentry;
1347 #endif
1348             }
1349           if (val > offset)
1350             done = TRUE;
1351           saw_line = TRUE;
1352           break;
1353
1354         case N_FUN:
1355         case N_SO:
1356           if (saw_func || saw_line)
1357             done = TRUE;
1358           saw_func = TRUE;
1359           break;
1360         }
1361
1362       if (done)
1363         break;
1364     }
1365
1366   *pfound = TRUE;
1367
1368   if (file_name == NULL || IS_ABSOLUTE_PATH (file_name)
1369       || directory_name == NULL)
1370     *pfilename = file_name;
1371   else
1372     {
1373       size_t dirlen;
1374
1375       dirlen = strlen (directory_name);
1376       if (info->filename == NULL
1377           || strncmp (info->filename, directory_name, dirlen) != 0
1378           || strcmp (info->filename + dirlen, file_name) != 0)
1379         {
1380           size_t len;
1381
1382           if (info->filename != NULL)
1383             free (info->filename);
1384           len = strlen (file_name) + 1;
1385           info->filename = bfd_malloc (dirlen + len);
1386           if (info->filename == NULL)
1387             return FALSE;
1388           memcpy (info->filename, directory_name, dirlen);
1389           memcpy (info->filename + dirlen, file_name, len);
1390         }
1391
1392       *pfilename = info->filename;
1393     }
1394
1395   if (indexentry->function_name != NULL)
1396     {
1397       char *s;
1398
1399       /* This will typically be something like main:F(0,1), so we want
1400          to clobber the colon.  It's OK to change the name, since the
1401          string is in our own local storage anyhow.  */
1402       s = strchr (indexentry->function_name, ':');
1403       if (s != NULL)
1404         *s = '\0';
1405
1406       *pfnname = indexentry->function_name;
1407     }
1408
1409   return TRUE;
1410 }