diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/section.texi')
| -rw-r--r-- | contrib/binutils/bfd/doc/section.texi | 439 |
1 files changed, 238 insertions, 201 deletions
diff --git a/contrib/binutils/bfd/doc/section.texi b/contrib/binutils/bfd/doc/section.texi index 2569590..4b0ec017 100644 --- a/contrib/binutils/bfd/doc/section.texi +++ b/contrib/binutils/bfd/doc/section.texi @@ -107,10 +107,10 @@ Here is the section structure: @example - /* This structure is used for a comdat section, as in PE. A comdat - section is associated with a particular symbol. When the linker - sees a comdat section, it keeps only one of the sections with a - given name and associated with a given symbol. */ +/* This structure is used for a comdat section, as in PE. A comdat + section is associated with a particular symbol. When the linker + sees a comdat section, it keeps only one of the sections with a + given name and associated with a given symbol. */ struct bfd_comdat_info @{ @@ -122,340 +122,362 @@ struct bfd_comdat_info specific code; it is not an index into the list returned by bfd_canonicalize_symtab. */ long symbol; - - /* If this section is being discarded, the linker uses this field - to point to the input section which is being kept. */ - struct sec *sec; @}; typedef struct sec @{ - /* The name of the section; the name isn't a copy, the pointer is - the same as that passed to bfd_make_section. */ + /* The name of the section; the name isn't a copy, the pointer is + the same as that passed to bfd_make_section. */ + + const char *name; + + /* A unique sequence number. */ - CONST char *name; + int id; - /* Which section is it; 0..nth. */ + /* Which section is it; 0..nth. */ - int index; + int index; - /* The next section in the list belonging to the BFD, or NULL. */ + /* The next section in the list belonging to the BFD, or NULL. */ - struct sec *next; + struct sec *next; - /* The field flags contains attributes of the section. Some - flags are read in from the object file, and some are - synthesized from other information. */ + /* The field flags contains attributes of the section. Some + flags are read in from the object file, and some are + synthesized from other information. */ - flagword flags; + flagword flags; #define SEC_NO_FLAGS 0x000 - /* Tells the OS to allocate space for this section when loading. - This is clear for a section containing debug information - only. */ + /* Tells the OS to allocate space for this section when loading. + This is clear for a section containing debug information only. */ #define SEC_ALLOC 0x001 - /* Tells the OS to load the section from the file when loading. - This is clear for a .bss section. */ + /* Tells the OS to load the section from the file when loading. + This is clear for a .bss section. */ #define SEC_LOAD 0x002 - /* The section contains data still to be relocated, so there is - some relocation information too. */ + /* The section contains data still to be relocated, so there is + some relocation information too. */ #define SEC_RELOC 0x004 #if 0 /* Obsolete ? */ #define SEC_BALIGN 0x008 #endif - /* A signal to the OS that the section contains read only - data. */ + /* A signal to the OS that the section contains read only data. */ #define SEC_READONLY 0x010 - /* The section contains code only. */ + /* The section contains code only. */ #define SEC_CODE 0x020 - /* The section contains data only. */ + /* The section contains data only. */ #define SEC_DATA 0x040 - /* The section will reside in ROM. */ + /* The section will reside in ROM. */ #define SEC_ROM 0x080 - /* The section contains constructor information. This section - type is used by the linker to create lists of constructors and - destructors used by @code{g++}. When a back end sees a symbol - which should be used in a constructor list, it creates a new - section for the type of name (e.g., @code{__CTOR_LIST__}), attaches - the symbol to it, and builds a relocation. To build the lists - of constructors, all the linker has to do is catenate all the - sections called @code{__CTOR_LIST__} and relocate the data - contained within - exactly the operations it would peform on - standard data. */ + /* The section contains constructor information. This section + type is used by the linker to create lists of constructors and + destructors used by @code{g++}. When a back end sees a symbol + which should be used in a constructor list, it creates a new + section for the type of name (e.g., @code{__CTOR_LIST__}), attaches + the symbol to it, and builds a relocation. To build the lists + of constructors, all the linker has to do is catenate all the + sections called @code{__CTOR_LIST__} and relocate the data + contained within - exactly the operations it would peform on + standard data. */ #define SEC_CONSTRUCTOR 0x100 - /* The section is a constructor, and should be placed at the - end of the text, data, or bss section(?). */ + /* The section is a constructor, and should be placed at the + end of the text, data, or bss section(?). */ #define SEC_CONSTRUCTOR_TEXT 0x1100 #define SEC_CONSTRUCTOR_DATA 0x2100 #define SEC_CONSTRUCTOR_BSS 0x3100 - /* The section has contents - a data section could be - @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be - @code{SEC_HAS_CONTENTS} */ + /* The section has contents - a data section could be + @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be + @code{SEC_HAS_CONTENTS} */ #define SEC_HAS_CONTENTS 0x200 - /* An instruction to the linker to not output the section - even if it has information which would normally be written. */ + /* An instruction to the linker to not output the section + even if it has information which would normally be written. */ #define SEC_NEVER_LOAD 0x400 - /* The section is a COFF shared library section. This flag is - only for the linker. If this type of section appears in - the input file, the linker must copy it to the output file - without changing the vma or size. FIXME: Although this - was originally intended to be general, it really is COFF - specific (and the flag was renamed to indicate this). It - might be cleaner to have some more general mechanism to - allow the back end to control what the linker does with - sections. */ + /* The section is a COFF shared library section. This flag is + only for the linker. If this type of section appears in + the input file, the linker must copy it to the output file + without changing the vma or size. FIXME: Although this + was originally intended to be general, it really is COFF + specific (and the flag was renamed to indicate this). It + might be cleaner to have some more general mechanism to + allow the back end to control what the linker does with + sections. */ #define SEC_COFF_SHARED_LIBRARY 0x800 - /* The section contains common symbols (symbols may be defined - multiple times, the value of a symbol is the amount of - space it requires, and the largest symbol value is the one - used). Most targets have exactly one of these (which we - translate to bfd_com_section_ptr), but ECOFF has two. */ + /* The section has GOT references. This flag is only for the + linker, and is currently only used by the elf32-hppa back end. + It will be set if global offset table references were detected + in this section, which indicate to the linker that the section + contains PIC code, and must be handled specially when doing a + static link. */ +#define SEC_HAS_GOT_REF 0x4000 + + /* The section contains common symbols (symbols may be defined + multiple times, the value of a symbol is the amount of + space it requires, and the largest symbol value is the one + used). Most targets have exactly one of these (which we + translate to bfd_com_section_ptr), but ECOFF has two. */ #define SEC_IS_COMMON 0x8000 - /* The section contains only debugging information. For - example, this is set for ELF .debug and .stab sections. - strip tests this flag to see if a section can be - discarded. */ + /* The section contains only debugging information. For + example, this is set for ELF .debug and .stab sections. + strip tests this flag to see if a section can be + discarded. */ #define SEC_DEBUGGING 0x10000 - /* The contents of this section are held in memory pointed to - by the contents field. This is checked by - bfd_get_section_contents, and the data is retrieved from - memory if appropriate. */ + /* The contents of this section are held in memory pointed to + by the contents field. This is checked by bfd_get_section_contents, + and the data is retrieved from memory if appropriate. */ #define SEC_IN_MEMORY 0x20000 - /* The contents of this section are to be excluded by the - linker for executable and shared objects unless those - objects are to be further relocated. */ + /* The contents of this section are to be excluded by the + linker for executable and shared objects unless those + objects are to be further relocated. */ #define SEC_EXCLUDE 0x40000 - /* The contents of this section are to be sorted by the - based on the address specified in the associated symbol - table. */ + /* The contents of this section are to be sorted by the + based on the address specified in the associated symbol + table. */ #define SEC_SORT_ENTRIES 0x80000 - /* When linking, duplicate sections of the same name should be - discarded, rather than being combined into a single section as - is usually done. This is similar to how common symbols are - handled. See SEC_LINK_DUPLICATES below. */ + /* When linking, duplicate sections of the same name should be + discarded, rather than being combined into a single section as + is usually done. This is similar to how common symbols are + handled. See SEC_LINK_DUPLICATES below. */ #define SEC_LINK_ONCE 0x100000 - /* If SEC_LINK_ONCE is set, this bitfield describes how the linker - should handle duplicate sections. */ + /* If SEC_LINK_ONCE is set, this bitfield describes how the linker + should handle duplicate sections. */ #define SEC_LINK_DUPLICATES 0x600000 - /* This value for SEC_LINK_DUPLICATES means that duplicate - sections with the same name should simply be discarded. */ + /* This value for SEC_LINK_DUPLICATES means that duplicate + sections with the same name should simply be discarded. */ #define SEC_LINK_DUPLICATES_DISCARD 0x0 - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if there are any duplicate sections, although - it should still only link one copy. */ + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if there are any duplicate sections, although + it should still only link one copy. */ #define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000 - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections are a different size. */ + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections are a different size. */ #define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000 - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections contain different - contents. */ + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections contain different + contents. */ #define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000 - /* This section was created by the linker as part of dynamic - relocation or other arcane processing. It is skipped when - going through the first-pass output, trusting that someone - else up the line will take care of it later. */ + /* This section was created by the linker as part of dynamic + relocation or other arcane processing. It is skipped when + going through the first-pass output, trusting that someone + else up the line will take care of it later. */ #define SEC_LINKER_CREATED 0x800000 - /* This section should not be subject to garbage collection. */ + /* This section should not be subject to garbage collection. */ #define SEC_KEEP 0x1000000 - /* This section contains "short" data, and should be placed - "near" the GP. */ + /* This section contains "short" data, and should be placed + "near" the GP. */ #define SEC_SMALL_DATA 0x2000000 - /* This section contains data which may be shared with other - executables or shared objects. */ + /* This section contains data which may be shared with other + executables or shared objects. */ #define SEC_SHARED 0x4000000 - /* End of section flags. */ + /* When a section with this flag is being linked, then if the size of + the input section is less than a page, it should not cross a page + boundary. If the size of the input section is one page or more, it + should be aligned on a page boundary. */ +#define SEC_BLOCK 0x8000000 + + /* Conditionally link this section; do not link if there are no + references found to any symbol in the section. */ +#define SEC_CLINK 0x10000000 + + /* End of section flags. */ + + /* Some internal packed boolean fields. */ - /* Some internal packed boolean fields. */ + /* See the vma field. */ + unsigned int user_set_vma : 1; - /* See the vma field. */ - unsigned int user_set_vma : 1; + /* Whether relocations have been processed. */ + unsigned int reloc_done : 1; - /* Whether relocations have been processed. */ - unsigned int reloc_done : 1; + /* A mark flag used by some of the linker backends. */ + unsigned int linker_mark : 1; - /* A mark flag used by some of the linker backends. */ - unsigned int linker_mark : 1; + /* A mark flag used by some linker backends for garbage collection. */ + unsigned int gc_mark : 1; - /* A mark flag used by some linker backends for garbage collection. */ - unsigned int gc_mark : 1; + /* Used by the ELF code to mark sections which have been allocated to segments. */ + unsigned int segment_mark : 1; - /* End of internal packed boolean fields. */ + /* End of internal packed boolean fields. */ - /* The virtual memory address of the section - where it will be - at run time. The symbols are relocated against this. The - user_set_vma flag is maintained by bfd; if it's not set, the - backend can assign addresses (for example, in @code{a.out}, where - the default address for @code{.data} is dependent on the specific - target and various flags). */ + /* The virtual memory address of the section - where it will be + at run time. The symbols are relocated against this. The + user_set_vma flag is maintained by bfd; if it's not set, the + backend can assign addresses (for example, in @code{a.out}, where + the default address for @code{.data} is dependent on the specific + target and various flags). */ - bfd_vma vma; + bfd_vma vma; - /* The load address of the section - where it would be in a - rom image; really only used for writing section header - information. */ + /* The load address of the section - where it would be in a + rom image; really only used for writing section header + information. */ - bfd_vma lma; + bfd_vma lma; - /* The size of the section in octets, as it will be output. - Contains a value even if the section has no contents (e.g., the - size of @code{.bss}). This will be filled in after relocation. */ + /* The size of the section in octets, as it will be output. + Contains a value even if the section has no contents (e.g., the + size of @code{.bss}). This will be filled in after relocation. */ - bfd_size_type _cooked_size; + bfd_size_type _cooked_size; - /* The original size on disk of the section, in octets. Normally this - value is the same as the size, but if some relaxing has - been done, then this value will be bigger. */ + /* The original size on disk of the section, in octets. Normally this + value is the same as the size, but if some relaxing has + been done, then this value will be bigger. */ - bfd_size_type _raw_size; + bfd_size_type _raw_size; - /* If this section is going to be output, then this value is the - offset in *bytes* into the output section of the first byte in the - input section (byte ==> smallest addressable unit on the - target). In most cases, if this was going to start at the - 100th octet (8-bit quantity) in the output section, this value - would be 100. However, if the target byte size is 16 bits - (bfd_octets_per_byte is "2"), this value would be 50. */ + /* If this section is going to be output, then this value is the + offset in *bytes* into the output section of the first byte in the + input section (byte ==> smallest addressable unit on the + target). In most cases, if this was going to start at the + 100th octet (8-bit quantity) in the output section, this value + would be 100. However, if the target byte size is 16 bits + (bfd_octets_per_byte is "2"), this value would be 50. */ - bfd_vma output_offset; + bfd_vma output_offset; - /* The output section through which to map on output. */ + /* The output section through which to map on output. */ - struct sec *output_section; + struct sec *output_section; - /* The alignment requirement of the section, as an exponent of 2 - - e.g., 3 aligns to 2^3 (or 8). */ + /* The alignment requirement of the section, as an exponent of 2 - + e.g., 3 aligns to 2^3 (or 8). */ - unsigned int alignment_power; + unsigned int alignment_power; - /* If an input section, a pointer to a vector of relocation - records for the data in this section. */ + /* If an input section, a pointer to a vector of relocation + records for the data in this section. */ - struct reloc_cache_entry *relocation; + 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. */ + /* 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; + struct reloc_cache_entry **orelocation; - /* The number of relocation records in one of the above */ + /* The number of relocation records in one of the above */ - unsigned reloc_count; + unsigned reloc_count; - /* Information below is back end specific - and not always used - or updated. */ + /* Information below is back end specific - and not always used + or updated. */ - /* File position of section data */ + /* File position of section data. */ - file_ptr filepos; + file_ptr filepos; - /* File position of relocation info */ + /* File position of relocation info. */ - file_ptr rel_filepos; + file_ptr rel_filepos; - /* File position of line data */ + /* File position of line data. */ - file_ptr line_filepos; + file_ptr line_filepos; - /* Pointer to data for applications */ + /* Pointer to data for applications. */ - PTR userdata; + PTR userdata; - /* If the SEC_IN_MEMORY flag is set, this points to the actual - contents. */ - unsigned char *contents; + /* If the SEC_IN_MEMORY flag is set, this points to the actual + contents. */ + unsigned char *contents; - /* Attached line number information */ + /* Attached line number information. */ - alent *lineno; + alent *lineno; - /* Number of line number records */ + /* Number of line number records. */ - unsigned int lineno_count; + unsigned int lineno_count; - /* Optional information about a COMDAT entry; NULL if not COMDAT */ + /* Optional information about a COMDAT entry; NULL if not COMDAT. */ - struct bfd_comdat_info *comdat; + struct bfd_comdat_info *comdat; - /* When a section is being output, this value changes as more - linenumbers are written out */ + /* Points to the kept section if this section is a link-once section, + and is discarded. */ + struct sec *kept_section; - file_ptr moving_line_filepos; + /* When a section is being output, this value changes as more + linenumbers are written out. */ - /* What the section number is in the target world */ + file_ptr moving_line_filepos; - int target_index; + /* What the section number is in the target world. */ - PTR used_by_bfd; + int target_index; - /* If this is a constructor section then here is a list of the - relocations created to relocate items within it. */ + PTR used_by_bfd; - struct relent_chain *constructor_chain; + /* If this is a constructor section then here is a list of the + relocations created to relocate items within it. */ - /* The BFD which owns the section. */ + struct relent_chain *constructor_chain; - bfd *owner; + /* The BFD which owns the section. */ - /* A symbol which points at this section only */ - struct symbol_cache_entry *symbol; - struct symbol_cache_entry **symbol_ptr_ptr; + bfd *owner; - struct bfd_link_order *link_order_head; - struct bfd_link_order *link_order_tail; + /* 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. */ +/* 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 */ +/* 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 */ +/* 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 */ +/* 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 */ +/* 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) @@ -480,7 +502,7 @@ These are the functions exported by the section handling part of BFD. @subsubsection @code{bfd_get_section_by_name} @strong{Synopsis} @example -asection *bfd_get_section_by_name(bfd *abfd, CONST char *name); +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 @@ -492,11 +514,26 @@ 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); +asection *bfd_make_section_old_way(bfd *abfd, const char *name); @end example @strong{Description}@* Create a new empty section called @var{name} @@ -523,7 +560,7 @@ If memory allocation fails. @subsubsection @code{bfd_make_section_anyway} @strong{Synopsis} @example -asection *bfd_make_section_anyway(bfd *abfd, CONST char *name); +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 @@ -543,7 +580,7 @@ Return @code{NULL} and set @code{bfd_error} on error; possible errors are: @subsubsection @code{bfd_make_section} @strong{Synopsis} @example -asection *bfd_make_section(bfd *, CONST char *name); +asection *bfd_make_section(bfd *, const char *name); @end example @strong{Description}@* Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling @@ -576,7 +613,7 @@ have the @code{SEC_HAS_CONTENTS} field set. @strong{Synopsis} @example void bfd_map_over_sections(bfd *abfd, - void (*func)(bfd *abfd, + void (*func) (bfd *abfd, asection *sect, PTR obj), PTR obj); |
