section prototypes - Untitled
Description: Untitled

Previous: typedef asection, Up: Sections

#### 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
Run through abfd and return the one of the `asection`s whose name matches name, otherwise `NULL`. See 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 `bfd_map_over_sections` and `strcmp` on the name (or better yet, base it on the section flags or something else) for each section.

##### 2.6.5.3 `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.4 `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.5 `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.6 `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.7 `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.8 `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.9 `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.10 `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.11 `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.12 `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:

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

##### 2.6.5.13 `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.14 `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.15 `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 data. The data is written to the output section starting at offset offset for count octets.

Normally `TRUE` is returned, else `FALSE`. 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.
- and some more too

This routine is front end to the back end function `_bfd_set_section_contents`.

##### 2.6.5.16 `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.17 `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.18 `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.19 `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.20 `bfd_generic_discard_group`

Synopsis

         bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);

Description
Remove all members of group from the output.