section.texi

gdb-6.0 linux 下的调试工具

  /* If an input section, a pointer to a vector of relocation
     records for the data in this section.  */
  struct reloc_cache_entry *relocation;

  /* If an output section, a pointer to a vector of pointers to
     relocation records for the data in this section.  */
  struct reloc_cache_entry **orelocation;

  /* The number of relocation records in one of the above.  */
  unsigned reloc_count;

  /* Information below is back end specific - and not always used
     or updated.  */

  /* File position of section data.  */
  file_ptr filepos;

  /* File position of relocation info.  */
  file_ptr rel_filepos;

  /* File position of line data.  */
  file_ptr line_filepos;

  /* Pointer to data for applications.  */
  PTR userdata;

  /* If the SEC_IN_MEMORY flag is set, this points to the actual
     contents.  */
  unsigned char *contents;

  /* Attached line number information.  */
  alent *lineno;

  /* Number of line number records.  */
  unsigned int lineno_count;

  /* Entity size for merging purposes.  */
  unsigned int entsize;

  /* Optional information about a COMDAT entry; NULL if not COMDAT.  */
  struct bfd_comdat_info *comdat;

  /* Points to the kept section if this section is a link-once section,
     and is discarded.  */
  struct sec *kept_section;

  /* When a section is being output, this value changes as more
     linenumbers are written out.  */
  file_ptr moving_line_filepos;

  /* What the section number is in the target world.  */
  int target_index;

  PTR used_by_bfd;

  /* If this is a constructor section then here is a list of the
     relocations created to relocate items within it.  */
  struct relent_chain *constructor_chain;

  /* The BFD which owns the section.  */
  bfd *owner;

  /* A symbol which points at this section only.  */
  struct symbol_cache_entry *symbol;
  struct symbol_cache_entry **symbol_ptr_ptr;

  struct bfd_link_order *link_order_head;
  struct bfd_link_order *link_order_tail;
@} asection;

/* These sections are global, and are managed by BFD.  The application
   and target back end are not permitted to change the values in
   these sections.  New code should use the section_ptr macros rather
   than referring directly to the const sections.  The const sections
   may eventually vanish.  */
#define BFD_ABS_SECTION_NAME "*ABS*"
#define BFD_UND_SECTION_NAME "*UND*"
#define BFD_COM_SECTION_NAME "*COM*"
#define BFD_IND_SECTION_NAME "*IND*"

/* The absolute section.  */
extern const asection bfd_abs_section;
#define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
/* Pointer to the undefined section.  */
extern const asection bfd_und_section;
#define bfd_und_section_ptr ((asection *) &bfd_und_section)
#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
/* Pointer to the common section.  */
extern const asection bfd_com_section;
#define bfd_com_section_ptr ((asection *) &bfd_com_section)
/* Pointer to the indirect section.  */
extern const asection bfd_ind_section;
#define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)

#define bfd_is_const_section(SEC)              \
 (   ((SEC) == bfd_abs_section_ptr)            \
  || ((SEC) == bfd_und_section_ptr)            \
  || ((SEC) == bfd_com_section_ptr)            \
  || ((SEC) == bfd_ind_section_ptr))

extern const struct symbol_cache_entry * const bfd_abs_symbol;
extern const struct symbol_cache_entry * const bfd_com_symbol;
extern const struct symbol_cache_entry * const bfd_und_symbol;
extern const struct symbol_cache_entry * const bfd_ind_symbol;
#define bfd_get_section_size_before_reloc(section) \
     ((section)->reloc_done ? (abort (), (bfd_size_type) 1) \
                            : (section)->_raw_size)
#define bfd_get_section_size_after_reloc(section) \
     ((section)->reloc_done ? (section)->_cooked_size \
                            : (abort (), (bfd_size_type) 1))

/* Macros to handle insertion and deletion of a bfd's sections.  These
   only handle the list pointers, ie. do not adjust section_count,
   target_index etc.  */
#define bfd_section_list_remove(ABFD, PS) \
  do                                                   \
    @{                                                  \
      asection **_ps = PS;                             \
      asection *_s = *_ps;                             \
      *_ps = _s->next;                                 \
      if (_s->next == NULL)                            \
        (ABFD)->section_tail = _ps;                    \
    @}                                                  \
  while (0)
#define bfd_section_list_insert(ABFD, PS, S) \
  do                                                   \
    @{                                                  \
      asection **_ps = PS;                             \
      asection *_s = S;                                \
      _s->next = *_ps;                                 \
      *_ps = _s;                                       \
      if (_s->next == NULL)                            \
        (ABFD)->section_tail = &_s->next;              \
    @}                                                  \
  while (0)

@end example

@node section prototypes,  , typedef asection, Sections
@subsection Section prototypes
These are the functions exported by the section handling part of BFD.

@findex bfd_section_list_clear
@subsubsection @code{bfd_section_list_clear}
@strong{Synopsis}
@example
void bfd_section_list_clear (bfd *);
@end example
@strong{Description}@*
Clears the section list, and also resets the section count and
hash table entries.

@findex bfd_get_section_by_name
@subsubsection @code{bfd_get_section_by_name}
@strong{Synopsis}
@example
asection *bfd_get_section_by_name(bfd *abfd, const char *name);
@end example
@strong{Description}@*
Run through @var{abfd} and return the one of the
@code{asection}s whose name matches @var{name}, otherwise @code{NULL}.
@xref{Sections}, for more information.

This should only be used in special cases; the normal way to process
all sections of a given name is to use @code{bfd_map_over_sections} and
@code{strcmp} on the name (or better yet, base it on the section flags
or something else) for each section.

@findex bfd_get_unique_section_name
@subsubsection @code{bfd_get_unique_section_name}
@strong{Synopsis}
@example
char *bfd_get_unique_section_name(bfd *abfd,
    const char *templat,
    int *count);
@end example
@strong{Description}@*
Invent a section name that is unique in @var{abfd} by tacking
a dot and a digit suffix onto the original @var{templat}.  If
@var{count} is non-NULL, then it specifies the first number
tried as a suffix to generate a unique name.  The value
pointed to by @var{count} will be incremented in this case.

@findex bfd_make_section_old_way
@subsubsection @code{bfd_make_section_old_way}
@strong{Synopsis}
@example
asection *bfd_make_section_old_way(bfd *abfd, const char *name);
@end example
@strong{Description}@*
Create a new empty section called @var{name}
and attach it to the end of the chain of sections for the
BFD @var{abfd}. An attempt to create a section with a name which
is already in use returns its pointer without changing the
section chain.

It has the funny name since this is the way it used to be
before it was rewritten....

Possible errors are:
@itemize @bullet

@item
@code{bfd_error_invalid_operation} -
If output has already started for this BFD.
@item
@code{bfd_error_no_memory} -
If memory allocation fails.
@end itemize

@findex bfd_make_section_anyway
@subsubsection @code{bfd_make_section_anyway}
@strong{Synopsis}
@example
asection *bfd_make_section_anyway(bfd *abfd, const char *name);
@end example
@strong{Description}@*
Create a new empty section called @var{name} and attach it to the end of
the chain of sections for @var{abfd}.  Create a new section even if there
is already a section with that name.

Return @code{NULL} and set @code{bfd_error} on error; possible errors are:
@itemize @bullet

@item
@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}.
@item
@code{bfd_error_no_memory} - If memory allocation fails.
@end itemize

@findex bfd_make_section
@subsubsection @code{bfd_make_section}
@strong{Synopsis}
@example
asection *bfd_make_section(bfd *, const char *name);
@end example
@strong{Description}@*
Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling
bfd_set_error ()) without changing the section chain if there is already a
section named @var{name}.  If there is an error, return @code{NULL} and set
@code{bfd_error}.

@findex bfd_set_section_flags
@subsubsection @code{bfd_set_section_flags}
@strong{Synopsis}
@example
bfd_boolean bfd_set_section_flags (bfd *abfd, asection *sec, flagword flags);
@end example
@strong{Description}@*
Set the attributes of the section @var{sec} in the BFD
@var{abfd} to the value @var{flags}. Return @code{TRUE} on success,
@code{FALSE} on error. Possible error returns are:

@itemize @bullet

@item
@code{bfd_error_invalid_operation} -
The section cannot have one or more of the attributes
requested. For example, a .bss section in @code{a.out} may not
have the @code{SEC_HAS_CONTENTS} field set.
@end itemize

@findex bfd_map_over_sections
@subsubsection @code{bfd_map_over_sections}
@strong{Synopsis}
@example
void bfd_map_over_sections(bfd *abfd,
    void (*func) (bfd *abfd,
    asection *sect,
    PTR obj),
    PTR obj);
@end example
@strong{Description}@*
Call the provided function @var{func} for each section
attached to the BFD @var{abfd}, passing @var{obj} as an
argument. The function will be called as if by

@example
       func(abfd, the_section, obj);
@end example

This is the prefered method for iterating over sections; an
alternative would be to use a loop:

@example
          section *p;
          for (p = abfd->sections; p != NULL; p = p->next)
             func(abfd, p, ...)
@end example

@findex bfd_set_section_size
@subsubsection @code{bfd_set_section_size}
@strong{Synopsis}
@example
bfd_boolean bfd_set_section_size (bfd *abfd, asection *sec, bfd_size_type val);
@end example
@strong{Description}@*
Set @var{sec} to the size @var{val}. If the operation is
ok, then @code{TRUE} is returned, else @code{FALSE}.

Possible error returns:
@itemize @bullet

@item
@code{bfd_error_invalid_operation} -
Writing has started to the BFD, so setting the size is invalid.
@end itemize

@findex bfd_set_section_contents
@subsubsection @code{bfd_set_section_contents}
@strong{Synopsis}
@example
bfd_boolean bfd_set_section_contents (bfd *abfd, asection *section,
    PTR data, file_ptr offset,
    bfd_size_type count);
@end example
@strong{Description}@*
Sets the contents of the section @var{section} in BFD
@var{abfd} to the data starting in memory at @var{data}. The
data is written to the output section starting at offset
@var{offset} for @var{count} octets.

Normally @code{TRUE} is returned, else @code{FALSE}. Possible error
returns are:
@itemize @bullet

@item
@code{bfd_error_no_contents} -
The output section does not have the @code{SEC_HAS_CONTENTS}
attribute, so nothing can be written to it.
@item
and some more too
@end itemize
This routine is front end to the back end function
@code{_bfd_set_section_contents}.

@findex bfd_get_section_contents
@subsubsection @code{bfd_get_section_contents}
@strong{Synopsis}
@example
bfd_boolean bfd_get_section_contents (bfd *abfd, asection *section,
    PTR location, file_ptr offset,
    bfd_size_type count);
@end example
@strong{Description}@*
Read data from @var{section} in BFD @var{abfd}
into memory starting at @var{location}. The data is read at an
offset of @var{offset} from the start of the input section,
and is read for @var{count} bytes.

If the contents of a constructor with the @code{SEC_CONSTRUCTOR}
flag set are requested or if the section does not have the
@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled
with zeroes. If no errors occur, @code{TRUE} is returned, else
@code{FALSE}.

@findex bfd_copy_private_section_data
@subsubsection @code{bfd_copy_private_section_data}
@strong{Synopsis}
@example
bfd_boolean bfd_copy_private_section_data (bfd *ibfd, asection *isec,
    bfd *obfd, asection *osec);
@end example
@strong{Description}@*
Copy private section information from @var{isec} in the BFD
@var{ibfd} to the section @var{osec} 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_section_data(ibfd, isection, obfd, osection) \
     BFD_SEND (obfd, _bfd_copy_private_section_data, \
               (ibfd, isection, obfd, osection))
@end example

@findex _bfd_strip_section_from_output
@subsubsection @code{_bfd_strip_section_from_output}
@strong{Synopsis}
@example
void _bfd_strip_section_from_output
   (struct bfd_link_info *info, asection *section);
@end example
@strong{Description}@*
Remove @var{section} from the output.  If the output section
becomes empty, remove it from the output bfd.

This function won't actually do anything except twiddle flags
if called too late in the linking process, when it's not safe
to remove sections.

@findex bfd_generic_discard_group
@subsubsection @code{bfd_generic_discard_group}
@strong{Synopsis}
@example
bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);
@end example
@strong{Description}@*
Remove all members of @var{group} from the output.