section.texi

这个是LINUX下的GDB调度工具的源码

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

  /* Points to the kept section if this section is a link-once section,
     and is discarded.  */
  struct bfd_section *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;

  void *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 bfd_symbol *symbol;
  struct bfd_symbol **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 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 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 asection bfd_com_section;
#define bfd_com_section_ptr ((asection *) &bfd_com_section)
/* Pointer to the indirect section.  */
extern 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 bfd_symbol * const bfd_abs_symbol;
extern const struct bfd_symbol * const bfd_com_symbol;
extern const struct bfd_symbol * const bfd_und_symbol;
extern const struct bfd_symbol * const bfd_ind_symbol;

/* 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_section_by_name_if
@subsubsection @code{bfd_get_section_by_name_if}
@strong{Synopsis}
@example
asection *bfd_get_section_by_name_if
   (bfd *abfd,
    const char *name,
    bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj),
    void *obj);
@end example
@strong{Description}@*
Call the provided function @var{func} for each section
attached to the BFD @var{abfd} whose name matches @var{name},
passing @var{obj} as an argument. The function will be called
as if by

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

It returns the first section for which @var{func} returns true,
otherwise @code{NULL}.

@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, void *obj),
    void *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 preferred 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_sections_find_if
@subsubsection @code{bfd_sections_find_if}
@strong{Synopsis}
@example
asection *bfd_sections_find_if
   (bfd *abfd,
    bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj),
    void *obj);
@end example
@strong{Description}@*
Call the provided function @var{operation} for each section
attached to the BFD @var{abfd}, passing @var{obj} as an
argument. The function will be called as if by

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

It returns the first section for which @var{operation} returns true.

@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, const void *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, void *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_malloc_and_get_section
@subsubsection @code{bfd_malloc_and_get_section}
@strong{Synopsis}
@example
bfd_boolean bfd_malloc_and_get_section
   (bfd *abfd, asection *section, bfd_byte **buf);
@end example
@strong{Description}@*
Read all data from @var{section} in BFD @var{abfd}
into a buffer, *@var{buf}, malloc'd by this function.

@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_is_group_section
@subsubsection @code{bfd_generic_is_group_section}
@strong{Synopsis}
@example
bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec);
@end example
@strong{Description}@*
Returns TRUE if @var{sec} is a member of a group.

@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.