1fddef416Sniklas@section Sections 2fddef416SniklasThe raw data contained within a BFD is maintained through the 3fddef416Sniklassection abstraction. A single BFD may have any number of 4fddef416Sniklassections. It keeps hold of them by pointing to the first; 5fddef416Sniklaseach one points to the next in the list. 6fddef416Sniklas 7fddef416SniklasSections are supported in BFD in @code{section.c}. 8fddef416Sniklas 9fddef416Sniklas@menu 10fddef416Sniklas* Section Input:: 11fddef416Sniklas* Section Output:: 12fddef416Sniklas* typedef asection:: 13fddef416Sniklas* section prototypes:: 14fddef416Sniklas@end menu 15f7cc78ecSespie 16fddef416Sniklas@node Section Input, Section Output, Sections, Sections 17fddef416Sniklas@subsection Section input 18fddef416SniklasWhen a BFD is opened for reading, the section structures are 19fddef416Sniklascreated and attached to the BFD. 20fddef416Sniklas 21fddef416SniklasEach section has a name which describes the section in the 22fddef416Sniklasoutside world---for example, @code{a.out} would contain at least 23fddef416Sniklasthree sections, called @code{.text}, @code{.data} and @code{.bss}. 24fddef416Sniklas 25fddef416SniklasNames need not be unique; for example a COFF file may have several 26fddef416Sniklassections named @code{.data}. 27fddef416Sniklas 28fddef416SniklasSometimes a BFD will contain more than the ``natural'' number of 29fddef416Sniklassections. A back end may attach other sections containing 30fddef416Sniklasconstructor data, or an application may add a section (using 31fddef416Sniklas@code{bfd_make_section}) to the sections attached to an already open 32fddef416SniklasBFD. For example, the linker creates an extra section 33fddef416Sniklas@code{COMMON} for each input file's BFD to hold information about 34fddef416Sniklascommon storage. 35fddef416Sniklas 36fddef416SniklasThe raw data is not necessarily read in when 37fddef416Sniklasthe section descriptor is created. Some targets may leave the 38fddef416Sniklasdata in place until a @code{bfd_get_section_contents} call is 39fddef416Sniklasmade. Other back ends may read in all the data at once. For 40fddef416Sniklasexample, an S-record file has to be read once to determine the 41fddef416Sniklassize of the data. An IEEE-695 file doesn't contain raw data in 42fddef416Sniklassections, but data and relocation expressions intermixed, so 43fddef416Sniklasthe data area has to be parsed to get out the data and 44fddef416Sniklasrelocations. 45f7cc78ecSespie 46fddef416Sniklas@node Section Output, typedef asection, Section Input, Sections 47fddef416Sniklas@subsection Section output 48fddef416SniklasTo write a new object style BFD, the various sections to be 49fddef416Sniklaswritten have to be created. They are attached to the BFD in 50fddef416Sniklasthe same way as input sections; data is written to the 51fddef416Sniklassections using @code{bfd_set_section_contents}. 52fddef416Sniklas 53fddef416SniklasAny program that creates or combines sections (e.g., the assembler 54fddef416Sniklasand linker) must use the @code{asection} fields @code{output_section} and 55fddef416Sniklas@code{output_offset} to indicate the file sections to which each 56fddef416Sniklassection must be written. (If the section is being created from 57fddef416Sniklasscratch, @code{output_section} should probably point to the section 58fddef416Sniklasitself and @code{output_offset} should probably be zero.) 59fddef416Sniklas 60fddef416SniklasThe data to be written comes from input sections attached 61fddef416Sniklas(via @code{output_section} pointers) to 62fddef416Sniklasthe output sections. The output section structure can be 63fddef416Sniklasconsidered a filter for the input section: the output section 64fddef416Sniklasdetermines the vma of the output data and the name, but the 65fddef416Sniklasinput section determines the offset into the output section of 66fddef416Sniklasthe data to be written. 67fddef416Sniklas 68fddef416SniklasE.g., to create a section "O", starting at 0x100, 0x123 long, 69fddef416Sniklascontaining two subsections, "A" at offset 0x0 (i.e., at vma 70fddef416Sniklas0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection} 71fddef416Sniklasstructures would look like: 72fddef416Sniklas 73fddef416Sniklas@example 74fddef416Sniklas section name "A" 75fddef416Sniklas output_offset 0x00 76fddef416Sniklas size 0x20 77fddef416Sniklas output_section -----------> section name "O" 78fddef416Sniklas | vma 0x100 79fddef416Sniklas section name "B" | size 0x123 80fddef416Sniklas output_offset 0x20 | 81fddef416Sniklas size 0x103 | 82fddef416Sniklas output_section --------| 83fddef416Sniklas@end example 84f7cc78ecSespie 85fddef416Sniklas@subsection Link orders 86fddef416SniklasThe data within a section is stored in a @dfn{link_order}. 87fddef416SniklasThese are much like the fixups in @code{gas}. The link_order 88fddef416Sniklasabstraction allows a section to grow and shrink within itself. 89fddef416Sniklas 90fddef416SniklasA link_order knows how big it is, and which is the next 91fddef416Sniklaslink_order and where the raw data for it is; it also points to 92fddef416Sniklasa list of relocations which apply to it. 93fddef416Sniklas 94fddef416SniklasThe link_order is used by the linker to perform relaxing on 95fddef416Sniklasfinal code. The compiler creates code which is as big as 96fddef416Sniklasnecessary to make it work without relaxing, and the user can 97fddef416Sniklasselect whether to relax. Sometimes relaxing takes a lot of 98fddef416Sniklastime. The linker runs around the relocations to see if any 99fddef416Sniklasare attached to data which can be shrunk, if so it does it on 100fddef416Sniklasa link_order by link_order basis. 101f7cc78ecSespie 102fddef416Sniklas 103fddef416Sniklas@node typedef asection, section prototypes, Section Output, Sections 104fddef416Sniklas@subsection typedef asection 105fddef416SniklasHere is the section structure: 106f7cc78ecSespie 107f7cc78ecSespie 108fddef416Sniklas@example 109f7cc78ecSespie 110f7cc78ecSespie/* This structure is used for a comdat section, as in PE. A comdat 111f7cc78ecSespie section is associated with a particular symbol. When the linker 112f7cc78ecSespie sees a comdat section, it keeps only one of the sections with a 113f7cc78ecSespie given name and associated with a given symbol. */ 114f7cc78ecSespie 115f7cc78ecSespiestruct bfd_comdat_info 116f7cc78ecSespie@{ 117f7cc78ecSespie /* The name of the symbol associated with a comdat section. */ 118f7cc78ecSespie const char *name; 119f7cc78ecSespie 120f7cc78ecSespie /* The local symbol table index of the symbol associated with a 121f7cc78ecSespie comdat section. This is only meaningful to the object file format 122f7cc78ecSespie specific code; it is not an index into the list returned by 123f7cc78ecSespie bfd_canonicalize_symtab. */ 124f7cc78ecSespie long symbol; 125f7cc78ecSespie@}; 126f7cc78ecSespie 127*cf2f2c56Smiodtypedef struct bfd_section 128fddef416Sniklas@{ 129fddef416Sniklas /* The name of the section; the name isn't a copy, the pointer is 130fddef416Sniklas the same as that passed to bfd_make_section. */ 1315f210c2aSfgsch const char *name; 1325f210c2aSfgsch 1335f210c2aSfgsch /* A unique sequence number. */ 1345f210c2aSfgsch int id; 135fddef416Sniklas 136d2201f2fSdrahn /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ 137fddef416Sniklas int index; 138fddef416Sniklas 139fddef416Sniklas /* The next section in the list belonging to the BFD, or NULL. */ 140*cf2f2c56Smiod struct bfd_section *next; 141fddef416Sniklas 142fddef416Sniklas /* The field flags contains attributes of the section. Some 143fddef416Sniklas flags are read in from the object file, and some are 144fddef416Sniklas synthesized from other information. */ 145fddef416Sniklas flagword flags; 146fddef416Sniklas 147fddef416Sniklas#define SEC_NO_FLAGS 0x000 148fddef416Sniklas 149fddef416Sniklas /* Tells the OS to allocate space for this section when loading. 1505f210c2aSfgsch This is clear for a section containing debug information only. */ 151fddef416Sniklas#define SEC_ALLOC 0x001 152fddef416Sniklas 153fddef416Sniklas /* Tells the OS to load the section from the file when loading. 154fddef416Sniklas This is clear for a .bss section. */ 155fddef416Sniklas#define SEC_LOAD 0x002 156fddef416Sniklas 157fddef416Sniklas /* The section contains data still to be relocated, so there is 158fddef416Sniklas some relocation information too. */ 159fddef416Sniklas#define SEC_RELOC 0x004 160fddef416Sniklas 161d2201f2fSdrahn /* ELF reserves 4 processor specific bits and 8 operating system 162d2201f2fSdrahn specific bits in sh_flags; at present we can get away with just 163d2201f2fSdrahn one in communicating between the assembler and BFD, but this 164d2201f2fSdrahn isn't a good long-term solution. */ 165d2201f2fSdrahn#define SEC_ARCH_BIT_0 0x008 166fddef416Sniklas 1675f210c2aSfgsch /* A signal to the OS that the section contains read only data. */ 168fddef416Sniklas#define SEC_READONLY 0x010 169fddef416Sniklas 170fddef416Sniklas /* The section contains code only. */ 171fddef416Sniklas#define SEC_CODE 0x020 172fddef416Sniklas 173fddef416Sniklas /* The section contains data only. */ 174fddef416Sniklas#define SEC_DATA 0x040 175fddef416Sniklas 176fddef416Sniklas /* The section will reside in ROM. */ 177fddef416Sniklas#define SEC_ROM 0x080 178fddef416Sniklas 179fddef416Sniklas /* The section contains constructor information. This section 180fddef416Sniklas type is used by the linker to create lists of constructors and 181fddef416Sniklas destructors used by @code{g++}. When a back end sees a symbol 182fddef416Sniklas which should be used in a constructor list, it creates a new 183fddef416Sniklas section for the type of name (e.g., @code{__CTOR_LIST__}), attaches 184fddef416Sniklas the symbol to it, and builds a relocation. To build the lists 185fddef416Sniklas of constructors, all the linker has to do is catenate all the 186fddef416Sniklas sections called @code{__CTOR_LIST__} and relocate the data 187fddef416Sniklas contained within - exactly the operations it would peform on 188fddef416Sniklas standard data. */ 189fddef416Sniklas#define SEC_CONSTRUCTOR 0x100 190fddef416Sniklas 191fddef416Sniklas /* The section has contents - a data section could be 192fddef416Sniklas @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be 193fddef416Sniklas @code{SEC_HAS_CONTENTS} */ 194fddef416Sniklas#define SEC_HAS_CONTENTS 0x200 195fddef416Sniklas 196fddef416Sniklas /* An instruction to the linker to not output the section 197fddef416Sniklas even if it has information which would normally be written. */ 198fddef416Sniklas#define SEC_NEVER_LOAD 0x400 199fddef416Sniklas 200fddef416Sniklas /* The section is a COFF shared library section. This flag is 201fddef416Sniklas only for the linker. If this type of section appears in 202fddef416Sniklas the input file, the linker must copy it to the output file 203fddef416Sniklas without changing the vma or size. FIXME: Although this 204fddef416Sniklas was originally intended to be general, it really is COFF 205fddef416Sniklas specific (and the flag was renamed to indicate this). It 206fddef416Sniklas might be cleaner to have some more general mechanism to 207fddef416Sniklas allow the back end to control what the linker does with 208fddef416Sniklas sections. */ 209fddef416Sniklas#define SEC_COFF_SHARED_LIBRARY 0x800 210fddef416Sniklas 211d2201f2fSdrahn /* The section contains thread local data. */ 212d2201f2fSdrahn#define SEC_THREAD_LOCAL 0x1000 213d2201f2fSdrahn 2145f210c2aSfgsch /* The section has GOT references. This flag is only for the 2155f210c2aSfgsch linker, and is currently only used by the elf32-hppa back end. 2165f210c2aSfgsch It will be set if global offset table references were detected 2175f210c2aSfgsch in this section, which indicate to the linker that the section 2185f210c2aSfgsch contains PIC code, and must be handled specially when doing a 2195f210c2aSfgsch static link. */ 2205f210c2aSfgsch#define SEC_HAS_GOT_REF 0x4000 2215f210c2aSfgsch 222fddef416Sniklas /* The section contains common symbols (symbols may be defined 223fddef416Sniklas multiple times, the value of a symbol is the amount of 224fddef416Sniklas space it requires, and the largest symbol value is the one 225fddef416Sniklas used). Most targets have exactly one of these (which we 226fddef416Sniklas translate to bfd_com_section_ptr), but ECOFF has two. */ 227fddef416Sniklas#define SEC_IS_COMMON 0x8000 228fddef416Sniklas 229fddef416Sniklas /* The section contains only debugging information. For 230fddef416Sniklas example, this is set for ELF .debug and .stab sections. 231fddef416Sniklas strip tests this flag to see if a section can be 232fddef416Sniklas discarded. */ 233fddef416Sniklas#define SEC_DEBUGGING 0x10000 234fddef416Sniklas 235fddef416Sniklas /* The contents of this section are held in memory pointed to 2365f210c2aSfgsch by the contents field. This is checked by bfd_get_section_contents, 2375f210c2aSfgsch and the data is retrieved from memory if appropriate. */ 238fddef416Sniklas#define SEC_IN_MEMORY 0x20000 239fddef416Sniklas 240fddef416Sniklas /* The contents of this section are to be excluded by the 241fddef416Sniklas linker for executable and shared objects unless those 242fddef416Sniklas objects are to be further relocated. */ 243fddef416Sniklas#define SEC_EXCLUDE 0x40000 244fddef416Sniklas 245d2201f2fSdrahn /* The contents of this section are to be sorted based on the sum of 246d2201f2fSdrahn the symbol and addend values specified by the associated relocation 247d2201f2fSdrahn entries. Entries without associated relocation entries will be 248d2201f2fSdrahn appended to the end of the section in an unspecified order. */ 249fddef416Sniklas#define SEC_SORT_ENTRIES 0x80000 250fddef416Sniklas 251fddef416Sniklas /* When linking, duplicate sections of the same name should be 252fddef416Sniklas discarded, rather than being combined into a single section as 253fddef416Sniklas is usually done. This is similar to how common symbols are 254fddef416Sniklas handled. See SEC_LINK_DUPLICATES below. */ 255fddef416Sniklas#define SEC_LINK_ONCE 0x100000 256fddef416Sniklas 257fddef416Sniklas /* If SEC_LINK_ONCE is set, this bitfield describes how the linker 258fddef416Sniklas should handle duplicate sections. */ 259fddef416Sniklas#define SEC_LINK_DUPLICATES 0x600000 260fddef416Sniklas 261fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that duplicate 262fddef416Sniklas sections with the same name should simply be discarded. */ 263fddef416Sniklas#define SEC_LINK_DUPLICATES_DISCARD 0x0 264fddef416Sniklas 265fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 266fddef416Sniklas should warn if there are any duplicate sections, although 267fddef416Sniklas it should still only link one copy. */ 268fddef416Sniklas#define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000 269fddef416Sniklas 270fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 271fddef416Sniklas should warn if any duplicate sections are a different size. */ 272fddef416Sniklas#define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000 273fddef416Sniklas 274fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 275fddef416Sniklas should warn if any duplicate sections contain different 276fddef416Sniklas contents. */ 277fddef416Sniklas#define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000 278fddef416Sniklas 279fddef416Sniklas /* This section was created by the linker as part of dynamic 280fddef416Sniklas relocation or other arcane processing. It is skipped when 281fddef416Sniklas going through the first-pass output, trusting that someone 282fddef416Sniklas else up the line will take care of it later. */ 283fddef416Sniklas#define SEC_LINKER_CREATED 0x800000 284fddef416Sniklas 285f7cc78ecSespie /* This section should not be subject to garbage collection. */ 286f7cc78ecSespie#define SEC_KEEP 0x1000000 287f7cc78ecSespie 288f7cc78ecSespie /* This section contains "short" data, and should be placed 289f7cc78ecSespie "near" the GP. */ 290f7cc78ecSespie#define SEC_SMALL_DATA 0x2000000 291f7cc78ecSespie 292f7cc78ecSespie /* This section contains data which may be shared with other 293f7cc78ecSespie executables or shared objects. */ 294f7cc78ecSespie#define SEC_SHARED 0x4000000 295f7cc78ecSespie 2965f210c2aSfgsch /* When a section with this flag is being linked, then if the size of 2975f210c2aSfgsch the input section is less than a page, it should not cross a page 2985f210c2aSfgsch boundary. If the size of the input section is one page or more, it 2995f210c2aSfgsch should be aligned on a page boundary. */ 3005f210c2aSfgsch#define SEC_BLOCK 0x8000000 3015f210c2aSfgsch 3025f210c2aSfgsch /* Conditionally link this section; do not link if there are no 3035f210c2aSfgsch references found to any symbol in the section. */ 3045f210c2aSfgsch#define SEC_CLINK 0x10000000 3055f210c2aSfgsch 306d2201f2fSdrahn /* Attempt to merge identical entities in the section. 307d2201f2fSdrahn Entity size is given in the entsize field. */ 308d2201f2fSdrahn#define SEC_MERGE 0x20000000 309d2201f2fSdrahn 310d2201f2fSdrahn /* If given with SEC_MERGE, entities to merge are zero terminated 311d2201f2fSdrahn strings where entsize specifies character size instead of fixed 312d2201f2fSdrahn size entries. */ 313d2201f2fSdrahn#define SEC_STRINGS 0x40000000 314d2201f2fSdrahn 315d2201f2fSdrahn /* This section contains data about section groups. */ 316d2201f2fSdrahn#define SEC_GROUP 0x80000000 317d2201f2fSdrahn 318fddef416Sniklas /* End of section flags. */ 319fddef416Sniklas 320fddef416Sniklas /* Some internal packed boolean fields. */ 321fddef416Sniklas 322fddef416Sniklas /* See the vma field. */ 323fddef416Sniklas unsigned int user_set_vma : 1; 324fddef416Sniklas 325fddef416Sniklas /* Whether relocations have been processed. */ 326fddef416Sniklas unsigned int reloc_done : 1; 327fddef416Sniklas 328fddef416Sniklas /* A mark flag used by some of the linker backends. */ 329fddef416Sniklas unsigned int linker_mark : 1; 330fddef416Sniklas 3315f210c2aSfgsch /* Another mark flag used by some of the linker backends. Set for 332d2201f2fSdrahn output sections that have an input section. */ 3335f210c2aSfgsch unsigned int linker_has_input : 1; 3345f210c2aSfgsch 335f7cc78ecSespie /* A mark flag used by some linker backends for garbage collection. */ 336f7cc78ecSespie unsigned int gc_mark : 1; 337f7cc78ecSespie 338d2201f2fSdrahn /* The following flags are used by the ELF linker. */ 339d2201f2fSdrahn 340d2201f2fSdrahn /* Mark sections which have been allocated to segments. */ 3415f210c2aSfgsch unsigned int segment_mark : 1; 3425f210c2aSfgsch 343d2201f2fSdrahn /* Type of sec_info information. */ 344d2201f2fSdrahn unsigned int sec_info_type:3; 345d2201f2fSdrahn#define ELF_INFO_TYPE_NONE 0 346d2201f2fSdrahn#define ELF_INFO_TYPE_STABS 1 347d2201f2fSdrahn#define ELF_INFO_TYPE_MERGE 2 348d2201f2fSdrahn#define ELF_INFO_TYPE_EH_FRAME 3 349d2201f2fSdrahn#define ELF_INFO_TYPE_JUST_SYMS 4 350d2201f2fSdrahn 351d2201f2fSdrahn /* Nonzero if this section uses RELA relocations, rather than REL. */ 352d2201f2fSdrahn unsigned int use_rela_p:1; 353d2201f2fSdrahn 354d2201f2fSdrahn /* Bits used by various backends. */ 355d2201f2fSdrahn unsigned int has_tls_reloc:1; 356d2201f2fSdrahn 357d2201f2fSdrahn /* Nonzero if this section needs the relax finalize pass. */ 358d2201f2fSdrahn unsigned int need_finalize_relax:1; 359d2201f2fSdrahn 360*cf2f2c56Smiod /* Nonzero if this section has a gp reloc. */ 361*cf2f2c56Smiod unsigned int has_gp_reloc:1; 362*cf2f2c56Smiod 363*cf2f2c56Smiod /* Unused bits. */ 364d2201f2fSdrahn unsigned int flag13:1; 365d2201f2fSdrahn unsigned int flag14:1; 366d2201f2fSdrahn unsigned int flag15:1; 367d2201f2fSdrahn unsigned int flag16:4; 368d2201f2fSdrahn unsigned int flag20:4; 369d2201f2fSdrahn unsigned int flag24:8; 370d2201f2fSdrahn 371fddef416Sniklas /* End of internal packed boolean fields. */ 372fddef416Sniklas 373fddef416Sniklas /* The virtual memory address of the section - where it will be 374fddef416Sniklas at run time. The symbols are relocated against this. The 375fddef416Sniklas user_set_vma flag is maintained by bfd; if it's not set, the 376fddef416Sniklas backend can assign addresses (for example, in @code{a.out}, where 377fddef416Sniklas the default address for @code{.data} is dependent on the specific 378fddef416Sniklas target and various flags). */ 379fddef416Sniklas bfd_vma vma; 380fddef416Sniklas 381fddef416Sniklas /* The load address of the section - where it would be in a 382fddef416Sniklas rom image; really only used for writing section header 383fddef416Sniklas information. */ 384fddef416Sniklas bfd_vma lma; 385fddef416Sniklas 386f7cc78ecSespie /* The size of the section in octets, as it will be output. 387f7cc78ecSespie Contains a value even if the section has no contents (e.g., the 388f7cc78ecSespie size of @code{.bss}). This will be filled in after relocation. */ 389fddef416Sniklas bfd_size_type _cooked_size; 390fddef416Sniklas 391f7cc78ecSespie /* The original size on disk of the section, in octets. Normally this 392fddef416Sniklas value is the same as the size, but if some relaxing has 393fddef416Sniklas been done, then this value will be bigger. */ 394fddef416Sniklas bfd_size_type _raw_size; 395fddef416Sniklas 396fddef416Sniklas /* If this section is going to be output, then this value is the 397f7cc78ecSespie offset in *bytes* into the output section of the first byte in the 398f7cc78ecSespie input section (byte ==> smallest addressable unit on the 399f7cc78ecSespie target). In most cases, if this was going to start at the 400f7cc78ecSespie 100th octet (8-bit quantity) in the output section, this value 401f7cc78ecSespie would be 100. However, if the target byte size is 16 bits 402f7cc78ecSespie (bfd_octets_per_byte is "2"), this value would be 50. */ 403fddef416Sniklas bfd_vma output_offset; 404fddef416Sniklas 405fddef416Sniklas /* The output section through which to map on output. */ 406*cf2f2c56Smiod struct bfd_section *output_section; 407fddef416Sniklas 408fddef416Sniklas /* The alignment requirement of the section, as an exponent of 2 - 409fddef416Sniklas e.g., 3 aligns to 2^3 (or 8). */ 410fddef416Sniklas unsigned int alignment_power; 411fddef416Sniklas 412fddef416Sniklas /* If an input section, a pointer to a vector of relocation 413fddef416Sniklas records for the data in this section. */ 414fddef416Sniklas struct reloc_cache_entry *relocation; 415fddef416Sniklas 416fddef416Sniklas /* If an output section, a pointer to a vector of pointers to 417fddef416Sniklas relocation records for the data in this section. */ 418fddef416Sniklas struct reloc_cache_entry **orelocation; 419fddef416Sniklas 420d2201f2fSdrahn /* The number of relocation records in one of the above. */ 421fddef416Sniklas unsigned reloc_count; 422fddef416Sniklas 423fddef416Sniklas /* Information below is back end specific - and not always used 424fddef416Sniklas or updated. */ 425fddef416Sniklas 4265f210c2aSfgsch /* File position of section data. */ 427fddef416Sniklas file_ptr filepos; 428fddef416Sniklas 4295f210c2aSfgsch /* File position of relocation info. */ 430fddef416Sniklas file_ptr rel_filepos; 431fddef416Sniklas 4325f210c2aSfgsch /* File position of line data. */ 433fddef416Sniklas file_ptr line_filepos; 434fddef416Sniklas 4355f210c2aSfgsch /* Pointer to data for applications. */ 436*cf2f2c56Smiod void *userdata; 437fddef416Sniklas 438fddef416Sniklas /* If the SEC_IN_MEMORY flag is set, this points to the actual 439fddef416Sniklas contents. */ 440fddef416Sniklas unsigned char *contents; 441fddef416Sniklas 4425f210c2aSfgsch /* Attached line number information. */ 443fddef416Sniklas alent *lineno; 444fddef416Sniklas 4455f210c2aSfgsch /* Number of line number records. */ 446fddef416Sniklas unsigned int lineno_count; 447fddef416Sniklas 448d2201f2fSdrahn /* Entity size for merging purposes. */ 449d2201f2fSdrahn unsigned int entsize; 450d2201f2fSdrahn 4515f210c2aSfgsch /* Optional information about a COMDAT entry; NULL if not COMDAT. */ 452f7cc78ecSespie struct bfd_comdat_info *comdat; 453f7cc78ecSespie 454*cf2f2c56Smiod /* Points to the kept section if this section is a link-once section, 455*cf2f2c56Smiod and is discarded. */ 456*cf2f2c56Smiod struct bfd_section *kept_section; 457*cf2f2c56Smiod 458fddef416Sniklas /* When a section is being output, this value changes as more 4595f210c2aSfgsch linenumbers are written out. */ 460fddef416Sniklas file_ptr moving_line_filepos; 461fddef416Sniklas 4625f210c2aSfgsch /* What the section number is in the target world. */ 463fddef416Sniklas int target_index; 464fddef416Sniklas 465*cf2f2c56Smiod void *used_by_bfd; 466fddef416Sniklas 467fddef416Sniklas /* If this is a constructor section then here is a list of the 468fddef416Sniklas relocations created to relocate items within it. */ 469fddef416Sniklas struct relent_chain *constructor_chain; 470fddef416Sniklas 471fddef416Sniklas /* The BFD which owns the section. */ 472fddef416Sniklas bfd *owner; 473fddef416Sniklas 474d2201f2fSdrahn /* A symbol which points at this section only. */ 475*cf2f2c56Smiod struct bfd_symbol *symbol; 476*cf2f2c56Smiod struct bfd_symbol **symbol_ptr_ptr; 477fddef416Sniklas 478fddef416Sniklas struct bfd_link_order *link_order_head; 479fddef416Sniklas struct bfd_link_order *link_order_tail; 480fddef416Sniklas@} asection; 481fddef416Sniklas 482fddef416Sniklas/* These sections are global, and are managed by BFD. The application 483fddef416Sniklas and target back end are not permitted to change the values in 484fddef416Sniklas these sections. New code should use the section_ptr macros rather 485fddef416Sniklas than referring directly to the const sections. The const sections 486fddef416Sniklas may eventually vanish. */ 487fddef416Sniklas#define BFD_ABS_SECTION_NAME "*ABS*" 488fddef416Sniklas#define BFD_UND_SECTION_NAME "*UND*" 489fddef416Sniklas#define BFD_COM_SECTION_NAME "*COM*" 490fddef416Sniklas#define BFD_IND_SECTION_NAME "*IND*" 491fddef416Sniklas 492d2201f2fSdrahn/* The absolute section. */ 493*cf2f2c56Smiodextern asection bfd_abs_section; 494fddef416Sniklas#define bfd_abs_section_ptr ((asection *) &bfd_abs_section) 495fddef416Sniklas#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) 496d2201f2fSdrahn/* Pointer to the undefined section. */ 497*cf2f2c56Smiodextern asection bfd_und_section; 498fddef416Sniklas#define bfd_und_section_ptr ((asection *) &bfd_und_section) 499fddef416Sniklas#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) 500d2201f2fSdrahn/* Pointer to the common section. */ 501*cf2f2c56Smiodextern asection bfd_com_section; 502fddef416Sniklas#define bfd_com_section_ptr ((asection *) &bfd_com_section) 503d2201f2fSdrahn/* Pointer to the indirect section. */ 504*cf2f2c56Smiodextern asection bfd_ind_section; 505fddef416Sniklas#define bfd_ind_section_ptr ((asection *) &bfd_ind_section) 506fddef416Sniklas#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) 507fddef416Sniklas 508d2201f2fSdrahn#define bfd_is_const_section(SEC) \ 509d2201f2fSdrahn ( ((SEC) == bfd_abs_section_ptr) \ 510d2201f2fSdrahn || ((SEC) == bfd_und_section_ptr) \ 511d2201f2fSdrahn || ((SEC) == bfd_com_section_ptr) \ 512d2201f2fSdrahn || ((SEC) == bfd_ind_section_ptr)) 513d2201f2fSdrahn 514*cf2f2c56Smiodextern const struct bfd_symbol * const bfd_abs_symbol; 515*cf2f2c56Smiodextern const struct bfd_symbol * const bfd_com_symbol; 516*cf2f2c56Smiodextern const struct bfd_symbol * const bfd_und_symbol; 517*cf2f2c56Smiodextern const struct bfd_symbol * const bfd_ind_symbol; 518fddef416Sniklas#define bfd_get_section_size_before_reloc(section) \ 519*cf2f2c56Smiod ((section)->_raw_size) 520fddef416Sniklas#define bfd_get_section_size_after_reloc(section) \ 521f7cc78ecSespie ((section)->reloc_done ? (section)->_cooked_size \ 522f7cc78ecSespie : (abort (), (bfd_size_type) 1)) 523d2201f2fSdrahn 524d2201f2fSdrahn/* Macros to handle insertion and deletion of a bfd's sections. These 525d2201f2fSdrahn only handle the list pointers, ie. do not adjust section_count, 526d2201f2fSdrahn target_index etc. */ 527d2201f2fSdrahn#define bfd_section_list_remove(ABFD, PS) \ 528d2201f2fSdrahn do \ 529d2201f2fSdrahn @{ \ 530d2201f2fSdrahn asection **_ps = PS; \ 531d2201f2fSdrahn asection *_s = *_ps; \ 532d2201f2fSdrahn *_ps = _s->next; \ 533d2201f2fSdrahn if (_s->next == NULL) \ 534d2201f2fSdrahn (ABFD)->section_tail = _ps; \ 535d2201f2fSdrahn @} \ 536d2201f2fSdrahn while (0) 537d2201f2fSdrahn#define bfd_section_list_insert(ABFD, PS, S) \ 538d2201f2fSdrahn do \ 539d2201f2fSdrahn @{ \ 540d2201f2fSdrahn asection **_ps = PS; \ 541d2201f2fSdrahn asection *_s = S; \ 542d2201f2fSdrahn _s->next = *_ps; \ 543d2201f2fSdrahn *_ps = _s; \ 544d2201f2fSdrahn if (_s->next == NULL) \ 545d2201f2fSdrahn (ABFD)->section_tail = &_s->next; \ 546d2201f2fSdrahn @} \ 547d2201f2fSdrahn while (0) 548d2201f2fSdrahn 549fddef416Sniklas@end example 550fddef416Sniklas 551fddef416Sniklas@node section prototypes, , typedef asection, Sections 552fddef416Sniklas@subsection Section prototypes 553fddef416SniklasThese are the functions exported by the section handling part of BFD. 554f7cc78ecSespie 555d2201f2fSdrahn@findex bfd_section_list_clear 556d2201f2fSdrahn@subsubsection @code{bfd_section_list_clear} 557d2201f2fSdrahn@strong{Synopsis} 558d2201f2fSdrahn@example 559d2201f2fSdrahnvoid bfd_section_list_clear (bfd *); 560d2201f2fSdrahn@end example 561d2201f2fSdrahn@strong{Description}@* 562d2201f2fSdrahnClears the section list, and also resets the section count and 563d2201f2fSdrahnhash table entries. 564d2201f2fSdrahn 565fddef416Sniklas@findex bfd_get_section_by_name 566fddef416Sniklas@subsubsection @code{bfd_get_section_by_name} 567fddef416Sniklas@strong{Synopsis} 568fddef416Sniklas@example 5695f210c2aSfgschasection *bfd_get_section_by_name (bfd *abfd, const char *name); 570fddef416Sniklas@end example 571fddef416Sniklas@strong{Description}@* 572fddef416SniklasRun through @var{abfd} and return the one of the 573fddef416Sniklas@code{asection}s whose name matches @var{name}, otherwise @code{NULL}. 574fddef416Sniklas@xref{Sections}, for more information. 575fddef416Sniklas 576fddef416SniklasThis should only be used in special cases; the normal way to process 577fddef416Sniklasall sections of a given name is to use @code{bfd_map_over_sections} and 578fddef416Sniklas@code{strcmp} on the name (or better yet, base it on the section flags 579fddef416Sniklasor something else) for each section. 580f7cc78ecSespie 5815f210c2aSfgsch@findex bfd_get_unique_section_name 5825f210c2aSfgsch@subsubsection @code{bfd_get_unique_section_name} 5835f210c2aSfgsch@strong{Synopsis} 5845f210c2aSfgsch@example 585*cf2f2c56Smiodchar *bfd_get_unique_section_name 586*cf2f2c56Smiod (bfd *abfd, const char *templat, int *count); 5875f210c2aSfgsch@end example 5885f210c2aSfgsch@strong{Description}@* 5895f210c2aSfgschInvent a section name that is unique in @var{abfd} by tacking 5905f210c2aSfgscha dot and a digit suffix onto the original @var{templat}. If 5915f210c2aSfgsch@var{count} is non-NULL, then it specifies the first number 5925f210c2aSfgschtried as a suffix to generate a unique name. The value 5935f210c2aSfgschpointed to by @var{count} will be incremented in this case. 5945f210c2aSfgsch 595fddef416Sniklas@findex bfd_make_section_old_way 596fddef416Sniklas@subsubsection @code{bfd_make_section_old_way} 597fddef416Sniklas@strong{Synopsis} 598fddef416Sniklas@example 5995f210c2aSfgschasection *bfd_make_section_old_way (bfd *abfd, const char *name); 600fddef416Sniklas@end example 601fddef416Sniklas@strong{Description}@* 602fddef416SniklasCreate a new empty section called @var{name} 603fddef416Sniklasand attach it to the end of the chain of sections for the 604fddef416SniklasBFD @var{abfd}. An attempt to create a section with a name which 605fddef416Sniklasis already in use returns its pointer without changing the 606fddef416Sniklassection chain. 607fddef416Sniklas 608fddef416SniklasIt has the funny name since this is the way it used to be 609fddef416Sniklasbefore it was rewritten.... 610fddef416Sniklas 611fddef416SniklasPossible errors are: 612fddef416Sniklas@itemize @bullet 613fddef416Sniklas 614fddef416Sniklas@item 615fddef416Sniklas@code{bfd_error_invalid_operation} - 616fddef416SniklasIf output has already started for this BFD. 617fddef416Sniklas@item 618fddef416Sniklas@code{bfd_error_no_memory} - 619fddef416SniklasIf memory allocation fails. 620fddef416Sniklas@end itemize 621f7cc78ecSespie 622fddef416Sniklas@findex bfd_make_section_anyway 623fddef416Sniklas@subsubsection @code{bfd_make_section_anyway} 624fddef416Sniklas@strong{Synopsis} 625fddef416Sniklas@example 6265f210c2aSfgschasection *bfd_make_section_anyway (bfd *abfd, const char *name); 627fddef416Sniklas@end example 628fddef416Sniklas@strong{Description}@* 629fddef416SniklasCreate a new empty section called @var{name} and attach it to the end of 630fddef416Sniklasthe chain of sections for @var{abfd}. Create a new section even if there 631fddef416Sniklasis already a section with that name. 632fddef416Sniklas 633fddef416SniklasReturn @code{NULL} and set @code{bfd_error} on error; possible errors are: 634fddef416Sniklas@itemize @bullet 635fddef416Sniklas 636fddef416Sniklas@item 637fddef416Sniklas@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}. 638fddef416Sniklas@item 639fddef416Sniklas@code{bfd_error_no_memory} - If memory allocation fails. 640fddef416Sniklas@end itemize 641f7cc78ecSespie 642fddef416Sniklas@findex bfd_make_section 643fddef416Sniklas@subsubsection @code{bfd_make_section} 644fddef416Sniklas@strong{Synopsis} 645fddef416Sniklas@example 6465f210c2aSfgschasection *bfd_make_section (bfd *, const char *name); 647fddef416Sniklas@end example 648fddef416Sniklas@strong{Description}@* 649fddef416SniklasLike @code{bfd_make_section_anyway}, but return @code{NULL} (without calling 650fddef416Sniklasbfd_set_error ()) without changing the section chain if there is already a 651fddef416Sniklassection named @var{name}. If there is an error, return @code{NULL} and set 652fddef416Sniklas@code{bfd_error}. 653f7cc78ecSespie 654fddef416Sniklas@findex bfd_set_section_flags 655fddef416Sniklas@subsubsection @code{bfd_set_section_flags} 656fddef416Sniklas@strong{Synopsis} 657fddef416Sniklas@example 658*cf2f2c56Smiodbfd_boolean bfd_set_section_flags 659*cf2f2c56Smiod (bfd *abfd, asection *sec, flagword flags); 660fddef416Sniklas@end example 661fddef416Sniklas@strong{Description}@* 662fddef416SniklasSet the attributes of the section @var{sec} in the BFD 663d2201f2fSdrahn@var{abfd} to the value @var{flags}. Return @code{TRUE} on success, 664d2201f2fSdrahn@code{FALSE} on error. Possible error returns are: 665fddef416Sniklas 666fddef416Sniklas@itemize @bullet 667fddef416Sniklas 668fddef416Sniklas@item 669fddef416Sniklas@code{bfd_error_invalid_operation} - 670fddef416SniklasThe section cannot have one or more of the attributes 671fddef416Sniklasrequested. For example, a .bss section in @code{a.out} may not 672fddef416Sniklashave the @code{SEC_HAS_CONTENTS} field set. 673fddef416Sniklas@end itemize 674f7cc78ecSespie 675fddef416Sniklas@findex bfd_map_over_sections 676fddef416Sniklas@subsubsection @code{bfd_map_over_sections} 677fddef416Sniklas@strong{Synopsis} 678fddef416Sniklas@example 679*cf2f2c56Smiodvoid bfd_map_over_sections 680*cf2f2c56Smiod (bfd *abfd, 681*cf2f2c56Smiod void (*func) (bfd *abfd, asection *sect, void *obj), 682*cf2f2c56Smiod void *obj); 683fddef416Sniklas@end example 684fddef416Sniklas@strong{Description}@* 685fddef416SniklasCall the provided function @var{func} for each section 686fddef416Sniklasattached to the BFD @var{abfd}, passing @var{obj} as an 687fddef416Sniklasargument. The function will be called as if by 688fddef416Sniklas 689fddef416Sniklas@example 690fddef416Sniklas func (abfd, the_section, obj); 691fddef416Sniklas@end example 692fddef416Sniklas 693*cf2f2c56SmiodThis is the preferred method for iterating over sections; an 694fddef416Sniklasalternative would be to use a loop: 695fddef416Sniklas 696fddef416Sniklas@example 697fddef416Sniklas section *p; 698fddef416Sniklas for (p = abfd->sections; p != NULL; p = p->next) 699fddef416Sniklas func (abfd, p, ...) 700fddef416Sniklas@end example 701f7cc78ecSespie 702fddef416Sniklas@findex bfd_set_section_size 703fddef416Sniklas@subsubsection @code{bfd_set_section_size} 704fddef416Sniklas@strong{Synopsis} 705fddef416Sniklas@example 706*cf2f2c56Smiodbfd_boolean bfd_set_section_size 707*cf2f2c56Smiod (bfd *abfd, asection *sec, bfd_size_type val); 708fddef416Sniklas@end example 709fddef416Sniklas@strong{Description}@* 710fddef416SniklasSet @var{sec} to the size @var{val}. If the operation is 711d2201f2fSdrahnok, then @code{TRUE} is returned, else @code{FALSE}. 712fddef416Sniklas 713fddef416SniklasPossible error returns: 714fddef416Sniklas@itemize @bullet 715fddef416Sniklas 716fddef416Sniklas@item 717fddef416Sniklas@code{bfd_error_invalid_operation} - 718fddef416SniklasWriting has started to the BFD, so setting the size is invalid. 719fddef416Sniklas@end itemize 720f7cc78ecSespie 721fddef416Sniklas@findex bfd_set_section_contents 722fddef416Sniklas@subsubsection @code{bfd_set_section_contents} 723fddef416Sniklas@strong{Synopsis} 724fddef416Sniklas@example 725*cf2f2c56Smiodbfd_boolean bfd_set_section_contents 726*cf2f2c56Smiod (bfd *abfd, asection *section, const void *data, 727*cf2f2c56Smiod file_ptr offset, bfd_size_type count); 728fddef416Sniklas@end example 729fddef416Sniklas@strong{Description}@* 730fddef416SniklasSets the contents of the section @var{section} in BFD 731fddef416Sniklas@var{abfd} to the data starting in memory at @var{data}. The 732fddef416Sniklasdata is written to the output section starting at offset 733f7cc78ecSespie@var{offset} for @var{count} octets. 734fddef416Sniklas 735d2201f2fSdrahnNormally @code{TRUE} is returned, else @code{FALSE}. Possible error 736fddef416Sniklasreturns are: 737fddef416Sniklas@itemize @bullet 738fddef416Sniklas 739fddef416Sniklas@item 740fddef416Sniklas@code{bfd_error_no_contents} - 741fddef416SniklasThe output section does not have the @code{SEC_HAS_CONTENTS} 742fddef416Sniklasattribute, so nothing can be written to it. 743fddef416Sniklas@item 744fddef416Sniklasand some more too 745fddef416Sniklas@end itemize 746fddef416SniklasThis routine is front end to the back end function 747fddef416Sniklas@code{_bfd_set_section_contents}. 748f7cc78ecSespie 749fddef416Sniklas@findex bfd_get_section_contents 750fddef416Sniklas@subsubsection @code{bfd_get_section_contents} 751fddef416Sniklas@strong{Synopsis} 752fddef416Sniklas@example 753*cf2f2c56Smiodbfd_boolean bfd_get_section_contents 754*cf2f2c56Smiod (bfd *abfd, asection *section, void *location, file_ptr offset, 755d2201f2fSdrahn bfd_size_type count); 756fddef416Sniklas@end example 757fddef416Sniklas@strong{Description}@* 758fddef416SniklasRead data from @var{section} in BFD @var{abfd} 759fddef416Sniklasinto memory starting at @var{location}. The data is read at an 760fddef416Sniklasoffset of @var{offset} from the start of the input section, 761fddef416Sniklasand is read for @var{count} bytes. 762fddef416Sniklas 763fddef416SniklasIf the contents of a constructor with the @code{SEC_CONSTRUCTOR} 764fddef416Sniklasflag set are requested or if the section does not have the 765fddef416Sniklas@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled 766d2201f2fSdrahnwith zeroes. If no errors occur, @code{TRUE} is returned, else 767d2201f2fSdrahn@code{FALSE}. 768f7cc78ecSespie 769fddef416Sniklas@findex bfd_copy_private_section_data 770fddef416Sniklas@subsubsection @code{bfd_copy_private_section_data} 771fddef416Sniklas@strong{Synopsis} 772fddef416Sniklas@example 773*cf2f2c56Smiodbfd_boolean bfd_copy_private_section_data 774*cf2f2c56Smiod (bfd *ibfd, asection *isec, bfd *obfd, asection *osec); 775fddef416Sniklas@end example 776fddef416Sniklas@strong{Description}@* 777fddef416SniklasCopy private section information from @var{isec} in the BFD 778fddef416Sniklas@var{ibfd} to the section @var{osec} in the BFD @var{obfd}. 779d2201f2fSdrahnReturn @code{TRUE} on success, @code{FALSE} on error. Possible error 780fddef416Sniklasreturns are: 781fddef416Sniklas 782fddef416Sniklas@itemize @bullet 783fddef416Sniklas 784fddef416Sniklas@item 785fddef416Sniklas@code{bfd_error_no_memory} - 786fddef416SniklasNot enough memory exists to create private data for @var{osec}. 787fddef416Sniklas@end itemize 788fddef416Sniklas@example 789fddef416Sniklas#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ 790fddef416Sniklas BFD_SEND (obfd, _bfd_copy_private_section_data, \ 791fddef416Sniklas (ibfd, isection, obfd, osection)) 792fddef416Sniklas@end example 793f7cc78ecSespie 794f7cc78ecSespie@findex _bfd_strip_section_from_output 795f7cc78ecSespie@subsubsection @code{_bfd_strip_section_from_output} 796f7cc78ecSespie@strong{Synopsis} 797f7cc78ecSespie@example 798f7cc78ecSespievoid _bfd_strip_section_from_output 799f7cc78ecSespie (struct bfd_link_info *info, asection *section); 800f7cc78ecSespie@end example 801f7cc78ecSespie@strong{Description}@* 802f7cc78ecSespieRemove @var{section} from the output. If the output section 803d2201f2fSdrahnbecomes empty, remove it from the output bfd. 804d2201f2fSdrahn 805d2201f2fSdrahnThis function won't actually do anything except twiddle flags 806d2201f2fSdrahnif called too late in the linking process, when it's not safe 807d2201f2fSdrahnto remove sections. 808d2201f2fSdrahn 809d2201f2fSdrahn@findex bfd_generic_discard_group 810d2201f2fSdrahn@subsubsection @code{bfd_generic_discard_group} 811d2201f2fSdrahn@strong{Synopsis} 812d2201f2fSdrahn@example 813d2201f2fSdrahnbfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group); 814d2201f2fSdrahn@end example 815d2201f2fSdrahn@strong{Description}@* 816d2201f2fSdrahnRemove all members of @var{group} from the output. 817f7cc78ecSespie 818