diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/syms.texi')
| -rw-r--r-- | contrib/binutils/bfd/doc/syms.texi | 231 |
1 files changed, 116 insertions, 115 deletions
diff --git a/contrib/binutils/bfd/doc/syms.texi b/contrib/binutils/bfd/doc/syms.texi index 034f086..48593f4 100644 --- a/contrib/binutils/bfd/doc/syms.texi +++ b/contrib/binutils/bfd/doc/syms.texi @@ -29,7 +29,7 @@ the scenes'' information will be still available. * 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: @@ -37,35 +37,35 @@ 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; + long storage_needed; + asymbol **symbol_table; + long number_of_symbols; + long i; - storage_needed = bfd_get_symtab_upper_bound (abfd); + 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 (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]); - @} + 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 @@ -79,31 +79,31 @@ 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 + #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 @@ -111,7 +111,7 @@ 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. @@ -130,124 +130,125 @@ 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. + /* 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. */ + 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. */ + /* 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 + /* 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: */ + /* 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 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; 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 */ + /* 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} */ + /* 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. */ -#define BSF_DEBUGGING 0x08 + /* The symbol is a debugging record. The value has an arbitary + meaning. */ +#define BSF_DEBUGGING 0x08 - /* The symbol denotes a function entry point. Used in ELF, - perhaps others someday. */ + /* The symbol denotes a function entry point. Used in ELF, + perhaps others someday. */ #define BSF_FUNCTION 0x10 - /* Used by the linker. */ + /* 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. */ + /* 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. */ + STT_SECTION symbols. */ #define BSF_SECTION_SYM 0x100 - /* The symbol used to be a common symbol, but now it is - allocated. */ + /* The symbol used to be a common symbol, but now it is + allocated. */ #define BSF_OLD_COMMON 0x200 - /* The default value for common data. */ + /* 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. */ + /* 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. */ + /* 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. */ + /* 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. */ + /* 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. */ + /* 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 + /* 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 +#define BSF_OBJECT 0x10000 flagword flags; - /* A pointer to the section to which this symbol is - relative. This will always be non NULL, there are special + /* 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. */ + /* Back end special data. */ union @{ PTR p; @@ -260,7 +261,7 @@ typedef struct symbol_cache_entry @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}@* @@ -272,7 +273,7 @@ the BFD, then return 0. If an error occurs, return -1. #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} @@ -282,7 +283,7 @@ boolean bfd_is_local_label(bfd *abfd, asymbol *sym); @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} @@ -298,7 +299,7 @@ local label. #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}@* @@ -312,7 +313,7 @@ including the NULL. BFD_SEND (abfd, _bfd_canonicalize_symtab,\ (abfd, location)) @end example -@* + @findex bfd_set_symtab @subsubsection @code{bfd_set_symtab} @strong{Synopsis} @@ -323,7 +324,7 @@ boolean bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int count); 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} @@ -333,7 +334,7 @@ void bfd_print_symbol_vandf(PTR file, asymbol *symbol); @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}@* @@ -348,7 +349,7 @@ information, and will cause problems later on. #define bfd_make_empty_symbol(abfd) \ BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) @end example -@* + @findex bfd_make_debug_symbol @subsubsection @code{bfd_make_debug_symbol} @strong{Description}@* @@ -359,13 +360,13 @@ yet to be worked out. #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); @@ -376,7 +377,7 @@ int bfd_decode_symclass(asymbol *symbol); 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); @@ -402,6 +403,6 @@ Not enough memory exists to create private data for @var{osec}. @example #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ - (ibfd, isymbol, obfd, osymbol)) + (ibfd, isymbol, obfd, osymbol)) @end example -@* + |
