| @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 = 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 "sysdep.h" |
| #include "bfd.h" |
| int main (void) |
| @{ |
| 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] = 0; |
| |
| bfd_set_symtab (abfd, ptrs, 1); |
| bfd_close (abfd); |
| return 0; |
| @} |
| |
| ./makesym |
| nm foo |
| 00012345 A dummy_symbol |
| @end example |
| |
| Many formats cannot represent arbitrary symbol information; for |
| instance, the @code{a.out} object format does not allow an |
| arbitrary 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 bfd_symbol |
| @{ |
| /* 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 (1 << 0) |
| |
| /* The symbol has global scope; initialized data in @code{C}. The |
| value is the offset into the section of the data. */ |
| #define BSF_GLOBAL (1 << 1) |
| |
| /* 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_COMMON}, @code{BSF_UNDEFINED} or |
| @code{BSF_GLOBAL}. */ |
| |
| /* The symbol is a debugging record. The value has an arbitrary |
| meaning, unless BSF_DEBUGGING_RELOC is also set. */ |
| #define BSF_DEBUGGING (1 << 2) |
| |
| /* The symbol denotes a function entry point. Used in ELF, |
| perhaps others someday. */ |
| #define BSF_FUNCTION (1 << 3) |
| |
| /* Used by the linker. */ |
| #define BSF_KEEP (1 << 5) |
| #define BSF_KEEP_G (1 << 6) |
| |
| /* A weak global symbol, overridable without warnings by |
| a regular global symbol of the same name. */ |
| #define BSF_WEAK (1 << 7) |
| |
| /* This symbol was created to point to a section, e.g. ELF's |
| STT_SECTION symbols. */ |
| #define BSF_SECTION_SYM (1 << 8) |
| |
| /* The symbol used to be a common symbol, but now it is |
| allocated. */ |
| #define BSF_OLD_COMMON (1 << 9) |
| |
| /* 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 (1 << 10) |
| |
| /* Signal that the symbol is the label of constructor section. */ |
| #define BSF_CONSTRUCTOR (1 << 11) |
| |
| /* 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 (1 << 12) |
| |
| /* 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 (1 << 13) |
| |
| /* BSF_FILE marks symbols that contain a file name. This is used |
| for ELF STT_FILE symbols. */ |
| #define BSF_FILE (1 << 14) |
| |
| /* Symbol is from dynamic linking information. */ |
| #define BSF_DYNAMIC (1 << 15) |
| |
| /* The symbol denotes a data object. Used in ELF, and perhaps |
| others someday. */ |
| #define BSF_OBJECT (1 << 16) |
| |
| /* 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 (1 << 17) |
| |
| /* This symbol is thread local. Used in ELF. */ |
| #define BSF_THREAD_LOCAL (1 << 18) |
| |
| /* This symbol represents a complex relocation expression, |
| with the expression tree serialized in the symbol name. */ |
| #define BSF_RELC (1 << 19) |
| |
| /* This symbol represents a signed complex relocation expression, |
| with the expression tree serialized in the symbol name. */ |
| #define BSF_SRELC (1 << 20) |
| |
| /* This symbol was created by bfd_get_synthetic_symtab. */ |
| #define BSF_SYNTHETIC (1 << 21) |
| |
| /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT. |
| The dynamic linker will compute the value of this symbol by |
| calling the function that it points to. BSF_FUNCTION must |
| also be also set. */ |
| #define BSF_GNU_INDIRECT_FUNCTION (1 << 22) |
| /* This symbol is a globally unique data object. The dynamic linker |
| will make sure that in the entire process there is just one symbol |
| with this name and type in use. BSF_OBJECT must also be set. */ |
| #define BSF_GNU_UNIQUE (1 << 23) |
| |
| 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 bfd_section *section; |
| |
| /* Back end special data. */ |
| union |
| @{ |
| void *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 |
| bfd_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 |
| bfd_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_is_target_special_symbol |
| @subsubsection @code{bfd_is_target_special_symbol} |
| @strong{Synopsis} |
| @example |
| bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym); |
| @end example |
| @strong{Description}@* |
| Return TRUE iff a symbol @var{sym} in the BFD @var{abfd} is something |
| special to the particular target represented by the BFD. Such symbols |
| should normally not be mentioned to the user. |
| @example |
| #define bfd_is_target_special_symbol(abfd, sym) \ |
| BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) |
| |
| @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 |
| bfd_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, void *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 |
| bfd_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 |
| bfd_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 |
| |