bfd: section prototypes
2.6.5 Section prototypes
------------------------
These are the functions exported by the section handling part of BFD.
2.6.5.1 'bfd_section_list_clear'
................................
*Synopsis*
void bfd_section_list_clear (bfd *);
*Description*
Clears the section list, and also resets the section count and hash
table entries.
2.6.5.2 'bfd_get_section_by_name'
.................................
*Synopsis*
asection *bfd_get_section_by_name (bfd *abfd, const char *name);
*Description*
Return the most recently created section attached to ABFD named NAME.
Return NULL if no such section exists.
2.6.5.3 'bfd_get_next_section_by_name'
......................................
*Synopsis*
asection *bfd_get_next_section_by_name (bfd *ibfd, asection *sec);
*Description*
Given SEC is a section returned by 'bfd_get_section_by_name', return the
next most recently created section attached to the same BFD with the
same name, or if no such section exists in the same BFD and IBFD is
non-NULL, the next section with the same name in any input BFD following
IBFD. Return NULL on finding no section.
2.6.5.4 'bfd_get_linker_section'
................................
*Synopsis*
asection *bfd_get_linker_section (bfd *abfd, const char *name);
*Description*
Return the linker created section attached to ABFD named NAME. Return
NULL if no such section exists.
2.6.5.5 'bfd_get_section_by_name_if'
....................................
*Synopsis*
asection *bfd_get_section_by_name_if
(bfd *abfd,
const char *name,
bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj),
void *obj);
*Description*
Call the provided function FUNC for each section attached to the BFD
ABFD whose name matches NAME, passing OBJ as an argument. The function
will be called as if by
func (abfd, the_section, obj);
It returns the first section for which FUNC returns true, otherwise
'NULL'.
2.6.5.6 'bfd_get_unique_section_name'
.....................................
*Synopsis*
char *bfd_get_unique_section_name
(bfd *abfd, const char *templat, int *count);
*Description*
Invent a section name that is unique in ABFD by tacking a dot and a
digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it
specifies the first number tried as a suffix to generate a unique name.
The value pointed to by COUNT will be incremented in this case.
2.6.5.7 'bfd_make_section_old_way'
..................................
*Synopsis*
asection *bfd_make_section_old_way (bfd *abfd, const char *name);
*Description*
Create a new empty section called NAME and attach it to the end of the
chain of sections for the BFD 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:
* 'bfd_error_invalid_operation' - If output has already started for
this BFD.
* 'bfd_error_no_memory' - If memory allocation fails.
2.6.5.8 'bfd_make_section_anyway_with_flags'
............................................
*Synopsis*
asection *bfd_make_section_anyway_with_flags
(bfd *abfd, const char *name, flagword flags);
*Description*
Create a new empty section called NAME and attach it to the end of the
chain of sections for ABFD. Create a new section even if there is
already a section with that name. Also set the attributes of the new
section to the value FLAGS.
Return 'NULL' and set 'bfd_error' on error; possible errors are:
* 'bfd_error_invalid_operation' - If output has already started for
ABFD.
* 'bfd_error_no_memory' - If memory allocation fails.
2.6.5.9 'bfd_make_section_anyway'
.................................
*Synopsis*
asection *bfd_make_section_anyway (bfd *abfd, const char *name);
*Description*
Create a new empty section called NAME and attach it to the end of the
chain of sections for ABFD. Create a new section even if there is
already a section with that name.
Return 'NULL' and set 'bfd_error' on error; possible errors are:
* 'bfd_error_invalid_operation' - If output has already started for
ABFD.
* 'bfd_error_no_memory' - If memory allocation fails.
2.6.5.10 'bfd_make_section_with_flags'
......................................
*Synopsis*
asection *bfd_make_section_with_flags
(bfd *, const char *name, flagword flags);
*Description*
Like 'bfd_make_section_anyway', but return 'NULL' (without calling
bfd_set_error ()) without changing the section chain if there is already
a section named NAME. Also set the attributes of the new section to the
value FLAGS. If there is an error, return 'NULL' and set 'bfd_error'.
2.6.5.11 'bfd_make_section'
...........................
*Synopsis*
asection *bfd_make_section (bfd *, const char *name);
*Description*
Like 'bfd_make_section_anyway', but return 'NULL' (without calling
bfd_set_error ()) without changing the section chain if there is already
a section named NAME. If there is an error, return 'NULL' and set
'bfd_error'.
2.6.5.12 'bfd_set_section_flags'
................................
*Synopsis*
bfd_boolean bfd_set_section_flags
(bfd *abfd, asection *sec, flagword flags);
*Description*
Set the attributes of the section SEC in the BFD ABFD to the value
FLAGS. Return 'TRUE' on success, 'FALSE' on error. Possible error
returns are:
* 'bfd_error_invalid_operation' - The section cannot have one or more
of the attributes requested. For example, a .bss section in
'a.out' may not have the 'SEC_HAS_CONTENTS' field set.
2.6.5.13 'bfd_rename_section'
.............................
*Synopsis*
void bfd_rename_section
(bfd *abfd, asection *sec, const char *newname);
*Description*
Rename section SEC in ABFD to NEWNAME.
2.6.5.14 'bfd_map_over_sections'
................................
*Synopsis*
void bfd_map_over_sections
(bfd *abfd,
void (*func) (bfd *abfd, asection *sect, void *obj),
void *obj);
*Description*
Call the provided function FUNC for each section attached to the BFD
ABFD, passing OBJ as an argument. The function will be called as if by
func (abfd, the_section, obj);
This is the preferred method for iterating over sections; an
alternative would be to use a loop:
asection *p;
for (p = abfd->sections; p != NULL; p = p->next)
func (abfd, p, ...)
2.6.5.15 'bfd_sections_find_if'
...............................
*Synopsis*
asection *bfd_sections_find_if
(bfd *abfd,
bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj),
void *obj);
*Description*
Call the provided function OPERATION for each section attached to the
BFD ABFD, passing OBJ as an argument. The function will be called as if
by
operation (abfd, the_section, obj);
It returns the first section for which OPERATION returns true.
2.6.5.16 'bfd_set_section_size'
...............................
*Synopsis*
bfd_boolean bfd_set_section_size
(bfd *abfd, asection *sec, bfd_size_type val);
*Description*
Set SEC to the size VAL. If the operation is ok, then 'TRUE' is
returned, else 'FALSE'.
Possible error returns:
* 'bfd_error_invalid_operation' - Writing has started to the BFD, so
setting the size is invalid.
2.6.5.17 'bfd_set_section_contents'
...................................
*Synopsis*
bfd_boolean bfd_set_section_contents
(bfd *abfd, asection *section, const void *data,
file_ptr offset, bfd_size_type count);
*Description*
Sets the contents of the section SECTION in BFD ABFD to the data
starting in memory at LOCATION. The data is written to the output
section starting at offset OFFSET for COUNT octets.
Normally 'TRUE' is returned, but 'FALSE' is returned if there was an
error. Possible error returns are:
* 'bfd_error_no_contents' - The output section does not have the
'SEC_HAS_CONTENTS' attribute, so nothing can be written to it.
* 'bfd_error_bad_value' - The section is unable to contain all of the
data.
* 'bfd_error_invalid_operation' - The BFD is not writeable.
* and some more too.
This routine is front end to the back end function
'_bfd_set_section_contents'.
2.6.5.18 'bfd_get_section_contents'
...................................
*Synopsis*
bfd_boolean bfd_get_section_contents
(bfd *abfd, asection *section, void *location, file_ptr offset,
bfd_size_type count);
*Description*
Read data from SECTION in BFD ABFD into memory starting at LOCATION.
The data is read at an offset of OFFSET from the start of the input
section, and is read for COUNT bytes.
If the contents of a constructor with the 'SEC_CONSTRUCTOR' flag set
are requested or if the section does not have the 'SEC_HAS_CONTENTS'
flag set, then the LOCATION is filled with zeroes. If no errors occur,
'TRUE' is returned, else 'FALSE'.
2.6.5.19 'bfd_malloc_and_get_section'
.....................................
*Synopsis*
bfd_boolean bfd_malloc_and_get_section
(bfd *abfd, asection *section, bfd_byte **buf);
*Description*
Read all data from SECTION in BFD ABFD into a buffer, *BUF, malloc'd by
this function.
2.6.5.20 'bfd_copy_private_section_data'
........................................
*Synopsis*
bfd_boolean bfd_copy_private_section_data
(bfd *ibfd, asection *isec, bfd *obfd, asection *osec);
*Description*
Copy private section information from ISEC in the BFD IBFD to the
section OSEC in the BFD OBFD. Return 'TRUE' on success, 'FALSE' on
error. Possible error returns are:
* 'bfd_error_no_memory' - Not enough memory exists to create private
data for OSEC.
#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
BFD_SEND (obfd, _bfd_copy_private_section_data, \
(ibfd, isection, obfd, osection))
2.6.5.21 'bfd_generic_is_group_section'
.......................................
*Synopsis*
bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec);
*Description*
Returns TRUE if SEC is a member of a group.
2.6.5.22 'bfd_generic_discard_group'
....................................
*Synopsis*
bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);
*Description*
Remove all members of GROUP from the output.