Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(4569)

Unified Diff: bfd/doc/syms.texi

Issue 124383005: GDB 7.6.50 (Closed) Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream
Patch Set: Created 6 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « bfd/doc/section.texi ('k') | bfd/doc/targets.texi » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: bfd/doc/syms.texi
diff --git a/bfd/doc/syms.texi b/bfd/doc/syms.texi
deleted file mode 100644
index 3d6638063e4a9072d4b17d751b2f32f2ff759cf4..0000000000000000000000000000000000000000
--- a/bfd/doc/syms.texi
+++ /dev/null
@@ -1,480 +0,0 @@
-@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
-
« no previous file with comments | « bfd/doc/section.texi ('k') | bfd/doc/targets.texi » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698