diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/section.texi')
| -rw-r--r-- | contrib/binutils/bfd/doc/section.texi | 650 |
1 files changed, 0 insertions, 650 deletions
diff --git a/contrib/binutils/bfd/doc/section.texi b/contrib/binutils/bfd/doc/section.texi deleted file mode 100644 index 24625c2c57b1..000000000000 --- a/contrib/binutils/bfd/doc/section.texi +++ /dev/null @@ -1,650 +0,0 @@ -@section Sections -The raw data contained within a BFD is maintained through the -section abstraction. A single BFD may have any number of -sections. It keeps hold of them by pointing to the first; -each one points to the next in the list. - -Sections are supported in BFD in @code{section.c}. - -@menu -* Section Input:: -* Section Output:: -* typedef asection:: -* section prototypes:: -@end menu - -@node Section Input, Section Output, Sections, Sections -@subsection Section input -When a BFD is opened for reading, the section structures are -created and attached to the BFD. - -Each section has a name which describes the section in the -outside world---for example, @code{a.out} would contain at least -three sections, called @code{.text}, @code{.data} and @code{.bss}. - -Names need not be unique; for example a COFF file may have several -sections named @code{.data}. - -Sometimes a BFD will contain more than the ``natural'' number of -sections. A back end may attach other sections containing -constructor data, or an application may add a section (using -@code{bfd_make_section}) to the sections attached to an already open -BFD. For example, the linker creates an extra section -@code{COMMON} for each input file's BFD to hold information about -common storage. - -The raw data is not necessarily read in when -the section descriptor is created. Some targets may leave the -data in place until a @code{bfd_get_section_contents} call is -made. Other back ends may read in all the data at once. For -example, an S-record file has to be read once to determine the -size of the data. An IEEE-695 file doesn't contain raw data in -sections, but data and relocation expressions intermixed, so -the data area has to be parsed to get out the data and -relocations. - -@node Section Output, typedef asection, Section Input, Sections -@subsection Section output -To write a new object style BFD, the various sections to be -written have to be created. They are attached to the BFD in -the same way as input sections; data is written to the -sections using @code{bfd_set_section_contents}. - -Any program that creates or combines sections (e.g., the assembler -and linker) must use the @code{asection} fields @code{output_section} and -@code{output_offset} to indicate the file sections to which each -section must be written. (If the section is being created from -scratch, @code{output_section} should probably point to the section -itself and @code{output_offset} should probably be zero.) - -The data to be written comes from input sections attached -(via @code{output_section} pointers) to -the output sections. The output section structure can be -considered a filter for the input section: the output section -determines the vma of the output data and the name, but the -input section determines the offset into the output section of -the data to be written. - -E.g., to create a section "O", starting at 0x100, 0x123 long, -containing two subsections, "A" at offset 0x0 (i.e., at vma -0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection} -structures would look like: - -@example - section name "A" - output_offset 0x00 - size 0x20 - output_section -----------> section name "O" - | vma 0x100 - section name "B" | size 0x123 - output_offset 0x20 | - size 0x103 | - output_section --------| -@end example - -@subsection Link orders -The data within a section is stored in a @dfn{link_order}. -These are much like the fixups in @code{gas}. The link_order -abstraction allows a section to grow and shrink within itself. - -A link_order knows how big it is, and which is the next -link_order and where the raw data for it is; it also points to -a list of relocations which apply to it. - -The link_order is used by the linker to perform relaxing on -final code. The compiler creates code which is as big as -necessary to make it work without relaxing, and the user can -select whether to relax. Sometimes relaxing takes a lot of -time. The linker runs around the relocations to see if any -are attached to data which can be shrunk, if so it does it on -a link_order by link_order basis. - - -@node typedef asection, section prototypes, Section Output, Sections -@subsection typedef asection -Here is the section structure: - - -@example - -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. */ - - CONST char *name; - - /* Which section is it; 0..nth. */ - - int index; - - /* The next section in the list belonging to the BFD, or NULL. */ - - 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. */ - - 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. */ -#define SEC_ALLOC 0x001 - - /* 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. */ -#define SEC_RELOC 0x004 - -#if 0 /* Obsolete ? */ -#define SEC_BALIGN 0x008 -#endif - - /* A signal to the OS that the section contains read only - data. */ -#define SEC_READONLY 0x010 - - /* The section contains code only. */ -#define SEC_CODE 0x020 - - /* The section contains data only. */ -#define SEC_DATA 0x040 - - /* 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. */ -#define SEC_CONSTRUCTOR 0x100 - - /* The section is a constuctor, 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} */ -#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. */ -#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. */ -#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. */ -#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. */ -#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. */ -#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. */ -#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. */ -#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. */ -#define SEC_LINK_ONCE 0x100000 - - /* 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. */ -#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. */ -#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. */ -#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. */ -#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. */ -#define SEC_LINKER_CREATED 0x800000 - - /* End of section flags. */ - - /* Some internal packed boolean fields. */ - - /* See the vma field. */ - unsigned int user_set_vma : 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; - - /* 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). */ - - 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. */ - - bfd_vma lma; - - /* The size of the section in bytes, 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; - - /* The original size on disk of the section, in bytes. 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; - - /* If this section is going to be output, then this value is the - offset into the output section of the first byte in the input - section. E.g., if this was going to start at the 100th byte in - the output section, this value would be 100. */ - - bfd_vma output_offset; - - /* The output section through which to map on output. */ - - struct sec *output_section; - - /* The alignment requirement of the section, as an exponent of 2 - - e.g., 3 aligns to 2^3 (or 8). */ - - unsigned int alignment_power; - - /* 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; - - /* 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) - -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(),1): (section)->_raw_size) -#define bfd_get_section_size_after_reloc(section) \ - ((section->reloc_done) ? (section)->_cooked_size: (abort(),1)) -@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_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_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 -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 -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 -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} bytes. - -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 -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 -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 - |