442 lines
15 KiB
Plaintext
442 lines
15 KiB
Plaintext
@section Symbols
|
|
BFD tries to maintain as much symbol information as it can when
|
|
it moves information from file to file. BFD passes information
|
|
to applications though the @code{asymbol} structure. When the
|
|
application requests the symbol table, BFD reads the table in
|
|
the native form and translates parts of it into the internal
|
|
format. To maintain more than the information passed to
|
|
applications, some targets keep some information ``behind the
|
|
scenes'' in a structure only the particular back end knows
|
|
about. For example, the coff back end keeps the original
|
|
symbol table structure as well as the canonical structure when
|
|
a BFD is read in. On output, the coff back end can reconstruct
|
|
the output symbol table so that no information is lost, even
|
|
information unique to coff which BFD doesn't know or
|
|
understand. If a coff symbol table were read, but were written
|
|
through an a.out back end, all the coff specific information
|
|
would be lost. The symbol table of a BFD
|
|
is not necessarily read in until a canonicalize request is
|
|
made. Then the BFD back end fills in a table provided by the
|
|
application with pointers to the canonical information. To
|
|
output symbols, the application provides BFD with a table of
|
|
pointers to pointers to @code{asymbol}s. This allows applications
|
|
like the linker to output a symbol as it was read, since the ``behind
|
|
the scenes'' information will be still available.
|
|
@menu
|
|
* Reading Symbols::
|
|
* Writing Symbols::
|
|
* Mini Symbols::
|
|
* typedef asymbol::
|
|
* symbol handling functions::
|
|
@end menu
|
|
|
|
@node Reading Symbols, Writing Symbols, Symbols, Symbols
|
|
@subsection Reading symbols
|
|
There are two stages to reading a symbol table from a BFD:
|
|
allocating storage, and the actual reading process. This is an
|
|
excerpt from an application which reads the symbol table:
|
|
|
|
@example
|
|
long storage_needed;
|
|
asymbol **symbol_table;
|
|
long number_of_symbols;
|
|
long i;
|
|
|
|
storage_needed = bfd_get_symtab_upper_bound (abfd);
|
|
|
|
if (storage_needed < 0)
|
|
FAIL
|
|
|
|
if (storage_needed == 0) @{
|
|
return ;
|
|
@}
|
|
symbol_table = (asymbol **) xmalloc (storage_needed);
|
|
...
|
|
number_of_symbols =
|
|
bfd_canonicalize_symtab (abfd, symbol_table);
|
|
|
|
if (number_of_symbols < 0)
|
|
FAIL
|
|
|
|
for (i = 0; i < number_of_symbols; i++) @{
|
|
process_symbol (symbol_table[i]);
|
|
@}
|
|
@end example
|
|
|
|
All storage for the symbols themselves is in an objalloc
|
|
connected to the BFD; it is freed when the BFD is closed.
|
|
|
|
@node Writing Symbols, Mini Symbols, Reading Symbols, Symbols
|
|
@subsection Writing symbols
|
|
Writing of a symbol table is automatic when a BFD open for
|
|
writing is closed. The application attaches a vector of
|
|
pointers to pointers to symbols to the BFD being written, and
|
|
fills in the symbol count. The close and cleanup code reads
|
|
through the table provided and performs all the necessary
|
|
operations. The BFD output code must always be provided with an
|
|
``owned'' symbol: one which has come from another BFD, or one
|
|
which has been created using @code{bfd_make_empty_symbol}. Here is an
|
|
example showing the creation of a symbol table with only one element:
|
|
|
|
@example
|
|
#include "bfd.h"
|
|
main()
|
|
@{
|
|
bfd *abfd;
|
|
asymbol *ptrs[2];
|
|
asymbol *new;
|
|
|
|
abfd = bfd_openw("foo","a.out-sunos-big");
|
|
bfd_set_format(abfd, bfd_object);
|
|
new = bfd_make_empty_symbol(abfd);
|
|
new->name = "dummy_symbol";
|
|
new->section = bfd_make_section_old_way(abfd, ".text");
|
|
new->flags = BSF_GLOBAL;
|
|
new->value = 0x12345;
|
|
|
|
ptrs[0] = new;
|
|
ptrs[1] = (asymbol *)0;
|
|
|
|
bfd_set_symtab(abfd, ptrs, 1);
|
|
bfd_close(abfd);
|
|
@}
|
|
|
|
./makesym
|
|
nm foo
|
|
00012345 A dummy_symbol
|
|
@end example
|
|
|
|
Many formats cannot represent arbitary symbol information; for
|
|
instance, the @code{a.out} object format does not allow an
|
|
arbitary number of sections. A symbol pointing to a section
|
|
which is not one of @code{.text}, @code{.data} or @code{.bss} cannot
|
|
be described.
|
|
|
|
@node Mini Symbols, typedef asymbol, Writing Symbols, Symbols
|
|
@subsection Mini Symbols
|
|
Mini symbols provide read-only access to the symbol table.
|
|
They use less memory space, but require more time to access.
|
|
They can be useful for tools like nm or objdump, which may
|
|
have to handle symbol tables of extremely large executables.
|
|
|
|
The @code{bfd_read_minisymbols} function will read the symbols
|
|
into memory in an internal form. It will return a @code{void *}
|
|
pointer to a block of memory, a symbol count, and the size of
|
|
each symbol. The pointer is allocated using @code{malloc}, and
|
|
should be freed by the caller when it is no longer needed.
|
|
|
|
The function @code{bfd_minisymbol_to_symbol} will take a pointer
|
|
to a minisymbol, and a pointer to a structure returned by
|
|
@code{bfd_make_empty_symbol}, and return a @code{asymbol} structure.
|
|
The return value may or may not be the same as the value from
|
|
@code{bfd_make_empty_symbol} which was passed in.
|
|
|
|
|
|
@node typedef asymbol, symbol handling functions, Mini Symbols, Symbols
|
|
@subsection typedef asymbol
|
|
An @code{asymbol} has the form:
|
|
|
|
|
|
@example
|
|
|
|
typedef struct symbol_cache_entry
|
|
@{
|
|
/* A pointer to the BFD which owns the symbol. This information
|
|
is necessary so that a back end can work out what additional
|
|
information (invisible to the application writer) is carried
|
|
with the symbol.
|
|
|
|
This field is *almost* redundant, since you can use section->owner
|
|
instead, except that some symbols point to the global sections
|
|
bfd_@{abs,com,und@}_section. This could be fixed by making
|
|
these globals be per-bfd (or per-target-flavor). FIXME. */
|
|
struct _bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */
|
|
|
|
/* The text of the symbol. The name is left alone, and not copied; the
|
|
application may not alter it. */
|
|
const char *name;
|
|
|
|
/* The value of the symbol. This really should be a union of a
|
|
numeric value with a pointer, since some flags indicate that
|
|
a pointer to another symbol is stored here. */
|
|
symvalue value;
|
|
|
|
/* Attributes of a symbol. */
|
|
#define BSF_NO_FLAGS 0x00
|
|
|
|
/* The symbol has local scope; @code{static} in @code{C}. The value
|
|
is the offset into the section of the data. */
|
|
#define BSF_LOCAL 0x01
|
|
|
|
/* The symbol has global scope; initialized data in @code{C}. The
|
|
value is the offset into the section of the data. */
|
|
#define BSF_GLOBAL 0x02
|
|
|
|
/* The symbol has global scope and is exported. The value is
|
|
the offset into the section of the data. */
|
|
#define BSF_EXPORT BSF_GLOBAL /* No real difference. */
|
|
|
|
/* A normal C symbol would be one of:
|
|
@code{BSF_LOCAL}, @code{BSF_FORT_COMM}, @code{BSF_UNDEFINED} or
|
|
@code{BSF_GLOBAL}. */
|
|
|
|
/* The symbol is a debugging record. The value has an arbitary
|
|
meaning, unless BSF_DEBUGGING_RELOC is also set. */
|
|
#define BSF_DEBUGGING 0x08
|
|
|
|
/* The symbol denotes a function entry point. Used in ELF,
|
|
perhaps others someday. */
|
|
#define BSF_FUNCTION 0x10
|
|
|
|
/* Used by the linker. */
|
|
#define BSF_KEEP 0x20
|
|
#define BSF_KEEP_G 0x40
|
|
|
|
/* A weak global symbol, overridable without warnings by
|
|
a regular global symbol of the same name. */
|
|
#define BSF_WEAK 0x80
|
|
|
|
/* This symbol was created to point to a section, e.g. ELF's
|
|
STT_SECTION symbols. */
|
|
#define BSF_SECTION_SYM 0x100
|
|
|
|
/* The symbol used to be a common symbol, but now it is
|
|
allocated. */
|
|
#define BSF_OLD_COMMON 0x200
|
|
|
|
/* The default value for common data. */
|
|
#define BFD_FORT_COMM_DEFAULT_VALUE 0
|
|
|
|
/* In some files the type of a symbol sometimes alters its
|
|
location in an output file - ie in coff a @code{ISFCN} symbol
|
|
which is also @code{C_EXT} symbol appears where it was
|
|
declared and not at the end of a section. This bit is set
|
|
by the target BFD part to convey this information. */
|
|
#define BSF_NOT_AT_END 0x400
|
|
|
|
/* Signal that the symbol is the label of constructor section. */
|
|
#define BSF_CONSTRUCTOR 0x800
|
|
|
|
/* Signal that the symbol is a warning symbol. The name is a
|
|
warning. The name of the next symbol is the one to warn about;
|
|
if a reference is made to a symbol with the same name as the next
|
|
symbol, a warning is issued by the linker. */
|
|
#define BSF_WARNING 0x1000
|
|
|
|
/* Signal that the symbol is indirect. This symbol is an indirect
|
|
pointer to the symbol with the same name as the next symbol. */
|
|
#define BSF_INDIRECT 0x2000
|
|
|
|
/* BSF_FILE marks symbols that contain a file name. This is used
|
|
for ELF STT_FILE symbols. */
|
|
#define BSF_FILE 0x4000
|
|
|
|
/* Symbol is from dynamic linking information. */
|
|
#define BSF_DYNAMIC 0x8000
|
|
|
|
/* The symbol denotes a data object. Used in ELF, and perhaps
|
|
others someday. */
|
|
#define BSF_OBJECT 0x10000
|
|
|
|
/* This symbol is a debugging symbol. The value is the offset
|
|
into the section of the data. BSF_DEBUGGING should be set
|
|
as well. */
|
|
#define BSF_DEBUGGING_RELOC 0x20000
|
|
|
|
flagword flags;
|
|
|
|
/* A pointer to the section to which this symbol is
|
|
relative. This will always be non NULL, there are special
|
|
sections for undefined and absolute symbols. */
|
|
struct sec *section;
|
|
|
|
/* Back end special data. */
|
|
union
|
|
@{
|
|
PTR p;
|
|
bfd_vma i;
|
|
@}
|
|
udata;
|
|
@}
|
|
asymbol;
|
|
|
|
@end example
|
|
|
|
@node symbol handling functions, , typedef asymbol, Symbols
|
|
@subsection Symbol handling functions
|
|
|
|
|
|
@findex bfd_get_symtab_upper_bound
|
|
@subsubsection @code{bfd_get_symtab_upper_bound}
|
|
@strong{Description}@*
|
|
Return the number of bytes required to store a vector of pointers
|
|
to @code{asymbols} for all the symbols in the BFD @var{abfd},
|
|
including a terminal NULL pointer. If there are no symbols in
|
|
the BFD, then return 0. If an error occurs, return -1.
|
|
@example
|
|
#define bfd_get_symtab_upper_bound(abfd) \
|
|
BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
|
|
|
|
@end example
|
|
|
|
@findex bfd_is_local_label
|
|
@subsubsection @code{bfd_is_local_label}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_is_local_label(bfd *abfd, asymbol *sym);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return true if the given symbol @var{sym} in the BFD @var{abfd} is
|
|
a compiler generated local label, else return false.
|
|
|
|
@findex bfd_is_local_label_name
|
|
@subsubsection @code{bfd_is_local_label_name}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_is_local_label_name(bfd *abfd, const char *name);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return true if a symbol with the name @var{name} in the BFD
|
|
@var{abfd} is a compiler generated local label, else return
|
|
false. This just checks whether the name has the form of a
|
|
local label.
|
|
@example
|
|
#define bfd_is_local_label_name(abfd, name) \
|
|
BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
|
|
|
|
@end example
|
|
|
|
@findex bfd_canonicalize_symtab
|
|
@subsubsection @code{bfd_canonicalize_symtab}
|
|
@strong{Description}@*
|
|
Read the symbols from the BFD @var{abfd}, and fills in
|
|
the vector @var{location} with pointers to the symbols and
|
|
a trailing NULL.
|
|
Return the actual number of symbol pointers, not
|
|
including the NULL.
|
|
@example
|
|
#define bfd_canonicalize_symtab(abfd, location) \
|
|
BFD_SEND (abfd, _bfd_canonicalize_symtab,\
|
|
(abfd, location))
|
|
|
|
@end example
|
|
|
|
@findex bfd_set_symtab
|
|
@subsubsection @code{bfd_set_symtab}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int count);
|
|
@end example
|
|
@strong{Description}@*
|
|
Arrange that when the output BFD @var{abfd} is closed,
|
|
the table @var{location} of @var{count} pointers to symbols
|
|
will be written.
|
|
|
|
@findex bfd_print_symbol_vandf
|
|
@subsubsection @code{bfd_print_symbol_vandf}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_print_symbol_vandf(bfd *abfd, PTR file, asymbol *symbol);
|
|
@end example
|
|
@strong{Description}@*
|
|
Print the value and flags of the @var{symbol} supplied to the
|
|
stream @var{file}.
|
|
|
|
@findex bfd_make_empty_symbol
|
|
@subsubsection @code{bfd_make_empty_symbol}
|
|
@strong{Description}@*
|
|
Create a new @code{asymbol} structure for the BFD @var{abfd}
|
|
and return a pointer to it.
|
|
|
|
This routine is necessary because each back end has private
|
|
information surrounding the @code{asymbol}. Building your own
|
|
@code{asymbol} and pointing to it will not create the private
|
|
information, and will cause problems later on.
|
|
@example
|
|
#define bfd_make_empty_symbol(abfd) \
|
|
BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
|
|
|
|
@end example
|
|
|
|
@findex _bfd_generic_make_empty_symbol
|
|
@subsubsection @code{_bfd_generic_make_empty_symbol}
|
|
@strong{Synopsis}
|
|
@example
|
|
asymbol *_bfd_generic_make_empty_symbol (bfd *);
|
|
@end example
|
|
@strong{Description}@*
|
|
Create a new @code{asymbol} structure for the BFD @var{abfd}
|
|
and return a pointer to it. Used by core file routines,
|
|
binary back-end and anywhere else where no private info
|
|
is needed.
|
|
|
|
@findex bfd_make_debug_symbol
|
|
@subsubsection @code{bfd_make_debug_symbol}
|
|
@strong{Description}@*
|
|
Create a new @code{asymbol} structure for the BFD @var{abfd},
|
|
to be used as a debugging symbol. Further details of its use have
|
|
yet to be worked out.
|
|
@example
|
|
#define bfd_make_debug_symbol(abfd,ptr,size) \
|
|
BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
|
|
|
|
@end example
|
|
|
|
@findex bfd_decode_symclass
|
|
@subsubsection @code{bfd_decode_symclass}
|
|
@strong{Description}@*
|
|
Return a character corresponding to the symbol
|
|
class of @var{symbol}, or '?' for an unknown class.
|
|
|
|
@strong{Synopsis}
|
|
@example
|
|
int bfd_decode_symclass(asymbol *symbol);
|
|
@end example
|
|
@findex bfd_is_undefined_symclass
|
|
@subsubsection @code{bfd_is_undefined_symclass}
|
|
@strong{Description}@*
|
|
Returns non-zero if the class symbol returned by
|
|
bfd_decode_symclass represents an undefined symbol.
|
|
Returns zero otherwise.
|
|
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_is_undefined_symclass (int symclass);
|
|
@end example
|
|
@findex bfd_symbol_info
|
|
@subsubsection @code{bfd_symbol_info}
|
|
@strong{Description}@*
|
|
Fill in the basic info about symbol that nm needs.
|
|
Additional info may be added by the back-ends after
|
|
calling this function.
|
|
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_symbol_info(asymbol *symbol, symbol_info *ret);
|
|
@end example
|
|
@findex bfd_copy_private_symbol_data
|
|
@subsubsection @code{bfd_copy_private_symbol_data}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_copy_private_symbol_data(bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
|
|
@end example
|
|
@strong{Description}@*
|
|
Copy private symbol information from @var{isym} in the BFD
|
|
@var{ibfd} to the symbol @var{osym} in the BFD @var{obfd}.
|
|
Return @code{true} on success, @code{false} on error. Possible error
|
|
returns are:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{bfd_error_no_memory} -
|
|
Not enough memory exists to create private data for @var{osec}.
|
|
@end itemize
|
|
@example
|
|
#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
|
|
BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
|
|
(ibfd, isymbol, obfd, osymbol))
|
|
|
|
@end example
|
|
|