1*fddef416Sniklas@section Sections 2*fddef416SniklasThe raw data contained within a BFD is maintained through the 3*fddef416Sniklassection abstraction. A single BFD may have any number of 4*fddef416Sniklassections. It keeps hold of them by pointing to the first; 5*fddef416Sniklaseach one points to the next in the list. 6*fddef416Sniklas 7*fddef416SniklasSections are supported in BFD in @code{section.c}. 8*fddef416Sniklas 9*fddef416Sniklas@menu 10*fddef416Sniklas* Section Input:: 11*fddef416Sniklas* Section Output:: 12*fddef416Sniklas* typedef asection:: 13*fddef416Sniklas* section prototypes:: 14*fddef416Sniklas@end menu 15*fddef416Sniklas@* 16*fddef416Sniklas@node Section Input, Section Output, Sections, Sections 17*fddef416Sniklas@subsection Section input 18*fddef416SniklasWhen a BFD is opened for reading, the section structures are 19*fddef416Sniklascreated and attached to the BFD. 20*fddef416Sniklas 21*fddef416SniklasEach section has a name which describes the section in the 22*fddef416Sniklasoutside world---for example, @code{a.out} would contain at least 23*fddef416Sniklasthree sections, called @code{.text}, @code{.data} and @code{.bss}. 24*fddef416Sniklas 25*fddef416SniklasNames need not be unique; for example a COFF file may have several 26*fddef416Sniklassections named @code{.data}. 27*fddef416Sniklas 28*fddef416SniklasSometimes a BFD will contain more than the ``natural'' number of 29*fddef416Sniklassections. A back end may attach other sections containing 30*fddef416Sniklasconstructor data, or an application may add a section (using 31*fddef416Sniklas@code{bfd_make_section}) to the sections attached to an already open 32*fddef416SniklasBFD. For example, the linker creates an extra section 33*fddef416Sniklas@code{COMMON} for each input file's BFD to hold information about 34*fddef416Sniklascommon storage. 35*fddef416Sniklas 36*fddef416SniklasThe raw data is not necessarily read in when 37*fddef416Sniklasthe section descriptor is created. Some targets may leave the 38*fddef416Sniklasdata in place until a @code{bfd_get_section_contents} call is 39*fddef416Sniklasmade. Other back ends may read in all the data at once. For 40*fddef416Sniklasexample, an S-record file has to be read once to determine the 41*fddef416Sniklassize of the data. An IEEE-695 file doesn't contain raw data in 42*fddef416Sniklassections, but data and relocation expressions intermixed, so 43*fddef416Sniklasthe data area has to be parsed to get out the data and 44*fddef416Sniklasrelocations. 45*fddef416Sniklas@* 46*fddef416Sniklas@node Section Output, typedef asection, Section Input, Sections 47*fddef416Sniklas@subsection Section output 48*fddef416SniklasTo write a new object style BFD, the various sections to be 49*fddef416Sniklaswritten have to be created. They are attached to the BFD in 50*fddef416Sniklasthe same way as input sections; data is written to the 51*fddef416Sniklassections using @code{bfd_set_section_contents}. 52*fddef416Sniklas 53*fddef416SniklasAny program that creates or combines sections (e.g., the assembler 54*fddef416Sniklasand linker) must use the @code{asection} fields @code{output_section} and 55*fddef416Sniklas@code{output_offset} to indicate the file sections to which each 56*fddef416Sniklassection must be written. (If the section is being created from 57*fddef416Sniklasscratch, @code{output_section} should probably point to the section 58*fddef416Sniklasitself and @code{output_offset} should probably be zero.) 59*fddef416Sniklas 60*fddef416SniklasThe data to be written comes from input sections attached 61*fddef416Sniklas(via @code{output_section} pointers) to 62*fddef416Sniklasthe output sections. The output section structure can be 63*fddef416Sniklasconsidered a filter for the input section: the output section 64*fddef416Sniklasdetermines the vma of the output data and the name, but the 65*fddef416Sniklasinput section determines the offset into the output section of 66*fddef416Sniklasthe data to be written. 67*fddef416Sniklas 68*fddef416SniklasE.g., to create a section "O", starting at 0x100, 0x123 long, 69*fddef416Sniklascontaining two subsections, "A" at offset 0x0 (i.e., at vma 70*fddef416Sniklas0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection} 71*fddef416Sniklasstructures would look like: 72*fddef416Sniklas 73*fddef416Sniklas@example 74*fddef416Sniklas section name "A" 75*fddef416Sniklas output_offset 0x00 76*fddef416Sniklas size 0x20 77*fddef416Sniklas output_section -----------> section name "O" 78*fddef416Sniklas | vma 0x100 79*fddef416Sniklas section name "B" | size 0x123 80*fddef416Sniklas output_offset 0x20 | 81*fddef416Sniklas size 0x103 | 82*fddef416Sniklas output_section --------| 83*fddef416Sniklas@end example 84*fddef416Sniklas@* 85*fddef416Sniklas@subsection Link orders 86*fddef416SniklasThe data within a section is stored in a @dfn{link_order}. 87*fddef416SniklasThese are much like the fixups in @code{gas}. The link_order 88*fddef416Sniklasabstraction allows a section to grow and shrink within itself. 89*fddef416Sniklas 90*fddef416SniklasA link_order knows how big it is, and which is the next 91*fddef416Sniklaslink_order and where the raw data for it is; it also points to 92*fddef416Sniklasa list of relocations which apply to it. 93*fddef416Sniklas 94*fddef416SniklasThe link_order is used by the linker to perform relaxing on 95*fddef416Sniklasfinal code. The compiler creates code which is as big as 96*fddef416Sniklasnecessary to make it work without relaxing, and the user can 97*fddef416Sniklasselect whether to relax. Sometimes relaxing takes a lot of 98*fddef416Sniklastime. The linker runs around the relocations to see if any 99*fddef416Sniklasare attached to data which can be shrunk, if so it does it on 100*fddef416Sniklasa link_order by link_order basis. 101*fddef416Sniklas@* 102*fddef416Sniklas 103*fddef416Sniklas@node typedef asection, section prototypes, Section Output, Sections 104*fddef416Sniklas@subsection typedef asection 105*fddef416SniklasHere is the section structure: 106*fddef416Sniklas@* 107*fddef416Sniklas. 108*fddef416Sniklas@example 109*fddef416Sniklastypedef struct sec 110*fddef416Sniklas@{ 111*fddef416Sniklas /* The name of the section; the name isn't a copy, the pointer is 112*fddef416Sniklas the same as that passed to bfd_make_section. */ 113*fddef416Sniklas 114*fddef416Sniklas CONST char *name; 115*fddef416Sniklas 116*fddef416Sniklas /* Which section is it; 0..nth. */ 117*fddef416Sniklas 118*fddef416Sniklas int index; 119*fddef416Sniklas 120*fddef416Sniklas /* The next section in the list belonging to the BFD, or NULL. */ 121*fddef416Sniklas 122*fddef416Sniklas struct sec *next; 123*fddef416Sniklas 124*fddef416Sniklas /* The field flags contains attributes of the section. Some 125*fddef416Sniklas flags are read in from the object file, and some are 126*fddef416Sniklas synthesized from other information. */ 127*fddef416Sniklas 128*fddef416Sniklas flagword flags; 129*fddef416Sniklas 130*fddef416Sniklas#define SEC_NO_FLAGS 0x000 131*fddef416Sniklas 132*fddef416Sniklas /* Tells the OS to allocate space for this section when loading. 133*fddef416Sniklas This is clear for a section containing debug information 134*fddef416Sniklas only. */ 135*fddef416Sniklas#define SEC_ALLOC 0x001 136*fddef416Sniklas 137*fddef416Sniklas /* Tells the OS to load the section from the file when loading. 138*fddef416Sniklas This is clear for a .bss section. */ 139*fddef416Sniklas#define SEC_LOAD 0x002 140*fddef416Sniklas 141*fddef416Sniklas /* The section contains data still to be relocated, so there is 142*fddef416Sniklas some relocation information too. */ 143*fddef416Sniklas#define SEC_RELOC 0x004 144*fddef416Sniklas 145*fddef416Sniklas#if 0 /* Obsolete ? */ 146*fddef416Sniklas#define SEC_BALIGN 0x008 147*fddef416Sniklas#endif 148*fddef416Sniklas 149*fddef416Sniklas /* A signal to the OS that the section contains read only 150*fddef416Sniklas data. */ 151*fddef416Sniklas#define SEC_READONLY 0x010 152*fddef416Sniklas 153*fddef416Sniklas /* The section contains code only. */ 154*fddef416Sniklas#define SEC_CODE 0x020 155*fddef416Sniklas 156*fddef416Sniklas /* The section contains data only. */ 157*fddef416Sniklas#define SEC_DATA 0x040 158*fddef416Sniklas 159*fddef416Sniklas /* The section will reside in ROM. */ 160*fddef416Sniklas#define SEC_ROM 0x080 161*fddef416Sniklas 162*fddef416Sniklas /* The section contains constructor information. This section 163*fddef416Sniklas type is used by the linker to create lists of constructors and 164*fddef416Sniklas destructors used by @code{g++}. When a back end sees a symbol 165*fddef416Sniklas which should be used in a constructor list, it creates a new 166*fddef416Sniklas section for the type of name (e.g., @code{__CTOR_LIST__}), attaches 167*fddef416Sniklas the symbol to it, and builds a relocation. To build the lists 168*fddef416Sniklas of constructors, all the linker has to do is catenate all the 169*fddef416Sniklas sections called @code{__CTOR_LIST__} and relocate the data 170*fddef416Sniklas contained within - exactly the operations it would peform on 171*fddef416Sniklas standard data. */ 172*fddef416Sniklas#define SEC_CONSTRUCTOR 0x100 173*fddef416Sniklas 174*fddef416Sniklas /* The section is a constuctor, and should be placed at the 175*fddef416Sniklas end of the text, data, or bss section(?). */ 176*fddef416Sniklas#define SEC_CONSTRUCTOR_TEXT 0x1100 177*fddef416Sniklas#define SEC_CONSTRUCTOR_DATA 0x2100 178*fddef416Sniklas#define SEC_CONSTRUCTOR_BSS 0x3100 179*fddef416Sniklas 180*fddef416Sniklas /* The section has contents - a data section could be 181*fddef416Sniklas @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be 182*fddef416Sniklas @code{SEC_HAS_CONTENTS} */ 183*fddef416Sniklas#define SEC_HAS_CONTENTS 0x200 184*fddef416Sniklas 185*fddef416Sniklas /* An instruction to the linker to not output the section 186*fddef416Sniklas even if it has information which would normally be written. */ 187*fddef416Sniklas#define SEC_NEVER_LOAD 0x400 188*fddef416Sniklas 189*fddef416Sniklas /* The section is a COFF shared library section. This flag is 190*fddef416Sniklas only for the linker. If this type of section appears in 191*fddef416Sniklas the input file, the linker must copy it to the output file 192*fddef416Sniklas without changing the vma or size. FIXME: Although this 193*fddef416Sniklas was originally intended to be general, it really is COFF 194*fddef416Sniklas specific (and the flag was renamed to indicate this). It 195*fddef416Sniklas might be cleaner to have some more general mechanism to 196*fddef416Sniklas allow the back end to control what the linker does with 197*fddef416Sniklas sections. */ 198*fddef416Sniklas#define SEC_COFF_SHARED_LIBRARY 0x800 199*fddef416Sniklas 200*fddef416Sniklas /* The section contains common symbols (symbols may be defined 201*fddef416Sniklas multiple times, the value of a symbol is the amount of 202*fddef416Sniklas space it requires, and the largest symbol value is the one 203*fddef416Sniklas used). Most targets have exactly one of these (which we 204*fddef416Sniklas translate to bfd_com_section_ptr), but ECOFF has two. */ 205*fddef416Sniklas#define SEC_IS_COMMON 0x8000 206*fddef416Sniklas 207*fddef416Sniklas /* The section contains only debugging information. For 208*fddef416Sniklas example, this is set for ELF .debug and .stab sections. 209*fddef416Sniklas strip tests this flag to see if a section can be 210*fddef416Sniklas discarded. */ 211*fddef416Sniklas#define SEC_DEBUGGING 0x10000 212*fddef416Sniklas 213*fddef416Sniklas /* The contents of this section are held in memory pointed to 214*fddef416Sniklas by the contents field. This is checked by 215*fddef416Sniklas bfd_get_section_contents, and the data is retrieved from 216*fddef416Sniklas memory if appropriate. */ 217*fddef416Sniklas#define SEC_IN_MEMORY 0x20000 218*fddef416Sniklas 219*fddef416Sniklas /* The contents of this section are to be excluded by the 220*fddef416Sniklas linker for executable and shared objects unless those 221*fddef416Sniklas objects are to be further relocated. */ 222*fddef416Sniklas#define SEC_EXCLUDE 0x40000 223*fddef416Sniklas 224*fddef416Sniklas /* The contents of this section are to be sorted by the 225*fddef416Sniklas based on the address specified in the associated symbol 226*fddef416Sniklas table. */ 227*fddef416Sniklas#define SEC_SORT_ENTRIES 0x80000 228*fddef416Sniklas 229*fddef416Sniklas /* When linking, duplicate sections of the same name should be 230*fddef416Sniklas discarded, rather than being combined into a single section as 231*fddef416Sniklas is usually done. This is similar to how common symbols are 232*fddef416Sniklas handled. See SEC_LINK_DUPLICATES below. */ 233*fddef416Sniklas#define SEC_LINK_ONCE 0x100000 234*fddef416Sniklas 235*fddef416Sniklas /* If SEC_LINK_ONCE is set, this bitfield describes how the linker 236*fddef416Sniklas should handle duplicate sections. */ 237*fddef416Sniklas#define SEC_LINK_DUPLICATES 0x600000 238*fddef416Sniklas 239*fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that duplicate 240*fddef416Sniklas sections with the same name should simply be discarded. */ 241*fddef416Sniklas#define SEC_LINK_DUPLICATES_DISCARD 0x0 242*fddef416Sniklas 243*fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 244*fddef416Sniklas should warn if there are any duplicate sections, although 245*fddef416Sniklas it should still only link one copy. */ 246*fddef416Sniklas#define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000 247*fddef416Sniklas 248*fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 249*fddef416Sniklas should warn if any duplicate sections are a different size. */ 250*fddef416Sniklas#define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000 251*fddef416Sniklas 252*fddef416Sniklas /* This value for SEC_LINK_DUPLICATES means that the linker 253*fddef416Sniklas should warn if any duplicate sections contain different 254*fddef416Sniklas contents. */ 255*fddef416Sniklas#define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000 256*fddef416Sniklas 257*fddef416Sniklas /* This section was created by the linker as part of dynamic 258*fddef416Sniklas relocation or other arcane processing. It is skipped when 259*fddef416Sniklas going through the first-pass output, trusting that someone 260*fddef416Sniklas else up the line will take care of it later. */ 261*fddef416Sniklas#define SEC_LINKER_CREATED 0x800000 262*fddef416Sniklas 263*fddef416Sniklas /* End of section flags. */ 264*fddef416Sniklas 265*fddef416Sniklas /* Some internal packed boolean fields. */ 266*fddef416Sniklas 267*fddef416Sniklas /* See the vma field. */ 268*fddef416Sniklas unsigned int user_set_vma : 1; 269*fddef416Sniklas 270*fddef416Sniklas /* Whether relocations have been processed. */ 271*fddef416Sniklas unsigned int reloc_done : 1; 272*fddef416Sniklas 273*fddef416Sniklas /* A mark flag used by some of the linker backends. */ 274*fddef416Sniklas unsigned int linker_mark : 1; 275*fddef416Sniklas 276*fddef416Sniklas /* End of internal packed boolean fields. */ 277*fddef416Sniklas 278*fddef416Sniklas /* The virtual memory address of the section - where it will be 279*fddef416Sniklas at run time. The symbols are relocated against this. The 280*fddef416Sniklas user_set_vma flag is maintained by bfd; if it's not set, the 281*fddef416Sniklas backend can assign addresses (for example, in @code{a.out}, where 282*fddef416Sniklas the default address for @code{.data} is dependent on the specific 283*fddef416Sniklas target and various flags). */ 284*fddef416Sniklas 285*fddef416Sniklas bfd_vma vma; 286*fddef416Sniklas 287*fddef416Sniklas /* The load address of the section - where it would be in a 288*fddef416Sniklas rom image; really only used for writing section header 289*fddef416Sniklas information. */ 290*fddef416Sniklas 291*fddef416Sniklas bfd_vma lma; 292*fddef416Sniklas 293*fddef416Sniklas /* The size of the section in bytes, as it will be output. 294*fddef416Sniklas contains a value even if the section has no contents (e.g., the 295*fddef416Sniklas size of @code{.bss}). This will be filled in after relocation */ 296*fddef416Sniklas 297*fddef416Sniklas bfd_size_type _cooked_size; 298*fddef416Sniklas 299*fddef416Sniklas /* The original size on disk of the section, in bytes. Normally this 300*fddef416Sniklas value is the same as the size, but if some relaxing has 301*fddef416Sniklas been done, then this value will be bigger. */ 302*fddef416Sniklas 303*fddef416Sniklas bfd_size_type _raw_size; 304*fddef416Sniklas 305*fddef416Sniklas /* If this section is going to be output, then this value is the 306*fddef416Sniklas offset into the output section of the first byte in the input 307*fddef416Sniklas section. E.g., if this was going to start at the 100th byte in 308*fddef416Sniklas the output section, this value would be 100. */ 309*fddef416Sniklas 310*fddef416Sniklas bfd_vma output_offset; 311*fddef416Sniklas 312*fddef416Sniklas /* The output section through which to map on output. */ 313*fddef416Sniklas 314*fddef416Sniklas struct sec *output_section; 315*fddef416Sniklas 316*fddef416Sniklas /* The alignment requirement of the section, as an exponent of 2 - 317*fddef416Sniklas e.g., 3 aligns to 2^3 (or 8). */ 318*fddef416Sniklas 319*fddef416Sniklas unsigned int alignment_power; 320*fddef416Sniklas 321*fddef416Sniklas /* If an input section, a pointer to a vector of relocation 322*fddef416Sniklas records for the data in this section. */ 323*fddef416Sniklas 324*fddef416Sniklas struct reloc_cache_entry *relocation; 325*fddef416Sniklas 326*fddef416Sniklas /* If an output section, a pointer to a vector of pointers to 327*fddef416Sniklas relocation records for the data in this section. */ 328*fddef416Sniklas 329*fddef416Sniklas struct reloc_cache_entry **orelocation; 330*fddef416Sniklas 331*fddef416Sniklas /* The number of relocation records in one of the above */ 332*fddef416Sniklas 333*fddef416Sniklas unsigned reloc_count; 334*fddef416Sniklas 335*fddef416Sniklas /* Information below is back end specific - and not always used 336*fddef416Sniklas or updated. */ 337*fddef416Sniklas 338*fddef416Sniklas /* File position of section data */ 339*fddef416Sniklas 340*fddef416Sniklas file_ptr filepos; 341*fddef416Sniklas 342*fddef416Sniklas /* File position of relocation info */ 343*fddef416Sniklas 344*fddef416Sniklas file_ptr rel_filepos; 345*fddef416Sniklas 346*fddef416Sniklas /* File position of line data */ 347*fddef416Sniklas 348*fddef416Sniklas file_ptr line_filepos; 349*fddef416Sniklas 350*fddef416Sniklas /* Pointer to data for applications */ 351*fddef416Sniklas 352*fddef416Sniklas PTR userdata; 353*fddef416Sniklas 354*fddef416Sniklas /* If the SEC_IN_MEMORY flag is set, this points to the actual 355*fddef416Sniklas contents. */ 356*fddef416Sniklas unsigned char *contents; 357*fddef416Sniklas 358*fddef416Sniklas /* Attached line number information */ 359*fddef416Sniklas 360*fddef416Sniklas alent *lineno; 361*fddef416Sniklas 362*fddef416Sniklas /* Number of line number records */ 363*fddef416Sniklas 364*fddef416Sniklas unsigned int lineno_count; 365*fddef416Sniklas 366*fddef416Sniklas /* When a section is being output, this value changes as more 367*fddef416Sniklas linenumbers are written out */ 368*fddef416Sniklas 369*fddef416Sniklas file_ptr moving_line_filepos; 370*fddef416Sniklas 371*fddef416Sniklas /* What the section number is in the target world */ 372*fddef416Sniklas 373*fddef416Sniklas int target_index; 374*fddef416Sniklas 375*fddef416Sniklas PTR used_by_bfd; 376*fddef416Sniklas 377*fddef416Sniklas /* If this is a constructor section then here is a list of the 378*fddef416Sniklas relocations created to relocate items within it. */ 379*fddef416Sniklas 380*fddef416Sniklas struct relent_chain *constructor_chain; 381*fddef416Sniklas 382*fddef416Sniklas /* The BFD which owns the section. */ 383*fddef416Sniklas 384*fddef416Sniklas bfd *owner; 385*fddef416Sniklas 386*fddef416Sniklas /* A symbol which points at this section only */ 387*fddef416Sniklas struct symbol_cache_entry *symbol; 388*fddef416Sniklas struct symbol_cache_entry **symbol_ptr_ptr; 389*fddef416Sniklas 390*fddef416Sniklas struct bfd_link_order *link_order_head; 391*fddef416Sniklas struct bfd_link_order *link_order_tail; 392*fddef416Sniklas@} asection ; 393*fddef416Sniklas 394*fddef416Sniklas /* These sections are global, and are managed by BFD. The application 395*fddef416Sniklas and target back end are not permitted to change the values in 396*fddef416Sniklas these sections. New code should use the section_ptr macros rather 397*fddef416Sniklas than referring directly to the const sections. The const sections 398*fddef416Sniklas may eventually vanish. */ 399*fddef416Sniklas#define BFD_ABS_SECTION_NAME "*ABS*" 400*fddef416Sniklas#define BFD_UND_SECTION_NAME "*UND*" 401*fddef416Sniklas#define BFD_COM_SECTION_NAME "*COM*" 402*fddef416Sniklas#define BFD_IND_SECTION_NAME "*IND*" 403*fddef416Sniklas 404*fddef416Sniklas /* the absolute section */ 405*fddef416Sniklasextern const asection bfd_abs_section; 406*fddef416Sniklas#define bfd_abs_section_ptr ((asection *) &bfd_abs_section) 407*fddef416Sniklas#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) 408*fddef416Sniklas /* Pointer to the undefined section */ 409*fddef416Sniklasextern const asection bfd_und_section; 410*fddef416Sniklas#define bfd_und_section_ptr ((asection *) &bfd_und_section) 411*fddef416Sniklas#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) 412*fddef416Sniklas /* Pointer to the common section */ 413*fddef416Sniklasextern const asection bfd_com_section; 414*fddef416Sniklas#define bfd_com_section_ptr ((asection *) &bfd_com_section) 415*fddef416Sniklas /* Pointer to the indirect section */ 416*fddef416Sniklasextern const asection bfd_ind_section; 417*fddef416Sniklas#define bfd_ind_section_ptr ((asection *) &bfd_ind_section) 418*fddef416Sniklas#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) 419*fddef416Sniklas 420*fddef416Sniklasextern const struct symbol_cache_entry * const bfd_abs_symbol; 421*fddef416Sniklasextern const struct symbol_cache_entry * const bfd_com_symbol; 422*fddef416Sniklasextern const struct symbol_cache_entry * const bfd_und_symbol; 423*fddef416Sniklasextern const struct symbol_cache_entry * const bfd_ind_symbol; 424*fddef416Sniklas#define bfd_get_section_size_before_reloc(section) \ 425*fddef416Sniklas (section->reloc_done ? (abort(),1): (section)->_raw_size) 426*fddef416Sniklas#define bfd_get_section_size_after_reloc(section) \ 427*fddef416Sniklas ((section->reloc_done) ? (section)->_cooked_size: (abort(),1)) 428*fddef416Sniklas@end example 429*fddef416Sniklas 430*fddef416Sniklas@node section prototypes, , typedef asection, Sections 431*fddef416Sniklas@subsection Section prototypes 432*fddef416SniklasThese are the functions exported by the section handling part of BFD. 433*fddef416Sniklas@* 434*fddef416Sniklas@findex bfd_get_section_by_name 435*fddef416Sniklas@subsubsection @code{bfd_get_section_by_name} 436*fddef416Sniklas@strong{Synopsis} 437*fddef416Sniklas@example 438*fddef416Sniklasasection *bfd_get_section_by_name(bfd *abfd, CONST char *name); 439*fddef416Sniklas@end example 440*fddef416Sniklas@strong{Description}@* 441*fddef416SniklasRun through @var{abfd} and return the one of the 442*fddef416Sniklas@code{asection}s whose name matches @var{name}, otherwise @code{NULL}. 443*fddef416Sniklas@xref{Sections}, for more information. 444*fddef416Sniklas 445*fddef416SniklasThis should only be used in special cases; the normal way to process 446*fddef416Sniklasall sections of a given name is to use @code{bfd_map_over_sections} and 447*fddef416Sniklas@code{strcmp} on the name (or better yet, base it on the section flags 448*fddef416Sniklasor something else) for each section. 449*fddef416Sniklas@* 450*fddef416Sniklas@findex bfd_make_section_old_way 451*fddef416Sniklas@subsubsection @code{bfd_make_section_old_way} 452*fddef416Sniklas@strong{Synopsis} 453*fddef416Sniklas@example 454*fddef416Sniklasasection *bfd_make_section_old_way(bfd *abfd, CONST char *name); 455*fddef416Sniklas@end example 456*fddef416Sniklas@strong{Description}@* 457*fddef416SniklasCreate a new empty section called @var{name} 458*fddef416Sniklasand attach it to the end of the chain of sections for the 459*fddef416SniklasBFD @var{abfd}. An attempt to create a section with a name which 460*fddef416Sniklasis already in use returns its pointer without changing the 461*fddef416Sniklassection chain. 462*fddef416Sniklas 463*fddef416SniklasIt has the funny name since this is the way it used to be 464*fddef416Sniklasbefore it was rewritten.... 465*fddef416Sniklas 466*fddef416SniklasPossible errors are: 467*fddef416Sniklas@itemize @bullet 468*fddef416Sniklas 469*fddef416Sniklas@item 470*fddef416Sniklas@code{bfd_error_invalid_operation} - 471*fddef416SniklasIf output has already started for this BFD. 472*fddef416Sniklas@item 473*fddef416Sniklas@code{bfd_error_no_memory} - 474*fddef416SniklasIf memory allocation fails. 475*fddef416Sniklas@end itemize 476*fddef416Sniklas@* 477*fddef416Sniklas@findex bfd_make_section_anyway 478*fddef416Sniklas@subsubsection @code{bfd_make_section_anyway} 479*fddef416Sniklas@strong{Synopsis} 480*fddef416Sniklas@example 481*fddef416Sniklasasection *bfd_make_section_anyway(bfd *abfd, CONST char *name); 482*fddef416Sniklas@end example 483*fddef416Sniklas@strong{Description}@* 484*fddef416SniklasCreate a new empty section called @var{name} and attach it to the end of 485*fddef416Sniklasthe chain of sections for @var{abfd}. Create a new section even if there 486*fddef416Sniklasis already a section with that name. 487*fddef416Sniklas 488*fddef416SniklasReturn @code{NULL} and set @code{bfd_error} on error; possible errors are: 489*fddef416Sniklas@itemize @bullet 490*fddef416Sniklas 491*fddef416Sniklas@item 492*fddef416Sniklas@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}. 493*fddef416Sniklas@item 494*fddef416Sniklas@code{bfd_error_no_memory} - If memory allocation fails. 495*fddef416Sniklas@end itemize 496*fddef416Sniklas@* 497*fddef416Sniklas@findex bfd_make_section 498*fddef416Sniklas@subsubsection @code{bfd_make_section} 499*fddef416Sniklas@strong{Synopsis} 500*fddef416Sniklas@example 501*fddef416Sniklasasection *bfd_make_section(bfd *, CONST char *name); 502*fddef416Sniklas@end example 503*fddef416Sniklas@strong{Description}@* 504*fddef416SniklasLike @code{bfd_make_section_anyway}, but return @code{NULL} (without calling 505*fddef416Sniklasbfd_set_error ()) without changing the section chain if there is already a 506*fddef416Sniklassection named @var{name}. If there is an error, return @code{NULL} and set 507*fddef416Sniklas@code{bfd_error}. 508*fddef416Sniklas@* 509*fddef416Sniklas@findex bfd_set_section_flags 510*fddef416Sniklas@subsubsection @code{bfd_set_section_flags} 511*fddef416Sniklas@strong{Synopsis} 512*fddef416Sniklas@example 513*fddef416Sniklasboolean bfd_set_section_flags(bfd *abfd, asection *sec, flagword flags); 514*fddef416Sniklas@end example 515*fddef416Sniklas@strong{Description}@* 516*fddef416SniklasSet the attributes of the section @var{sec} in the BFD 517*fddef416Sniklas@var{abfd} to the value @var{flags}. Return @code{true} on success, 518*fddef416Sniklas@code{false} on error. Possible error returns are: 519*fddef416Sniklas 520*fddef416Sniklas@itemize @bullet 521*fddef416Sniklas 522*fddef416Sniklas@item 523*fddef416Sniklas@code{bfd_error_invalid_operation} - 524*fddef416SniklasThe section cannot have one or more of the attributes 525*fddef416Sniklasrequested. For example, a .bss section in @code{a.out} may not 526*fddef416Sniklashave the @code{SEC_HAS_CONTENTS} field set. 527*fddef416Sniklas@end itemize 528*fddef416Sniklas@* 529*fddef416Sniklas@findex bfd_map_over_sections 530*fddef416Sniklas@subsubsection @code{bfd_map_over_sections} 531*fddef416Sniklas@strong{Synopsis} 532*fddef416Sniklas@example 533*fddef416Sniklasvoid bfd_map_over_sections(bfd *abfd, 534*fddef416Sniklas void (*func)(bfd *abfd, 535*fddef416Sniklas asection *sect, 536*fddef416Sniklas PTR obj), 537*fddef416Sniklas PTR obj); 538*fddef416Sniklas@end example 539*fddef416Sniklas@strong{Description}@* 540*fddef416SniklasCall the provided function @var{func} for each section 541*fddef416Sniklasattached to the BFD @var{abfd}, passing @var{obj} as an 542*fddef416Sniklasargument. The function will be called as if by 543*fddef416Sniklas 544*fddef416Sniklas@example 545*fddef416Sniklas func(abfd, the_section, obj); 546*fddef416Sniklas@end example 547*fddef416Sniklas 548*fddef416SniklasThis is the prefered method for iterating over sections; an 549*fddef416Sniklasalternative would be to use a loop: 550*fddef416Sniklas 551*fddef416Sniklas@example 552*fddef416Sniklas section *p; 553*fddef416Sniklas for (p = abfd->sections; p != NULL; p = p->next) 554*fddef416Sniklas func(abfd, p, ...) 555*fddef416Sniklas@end example 556*fddef416Sniklas@* 557*fddef416Sniklas@findex bfd_set_section_size 558*fddef416Sniklas@subsubsection @code{bfd_set_section_size} 559*fddef416Sniklas@strong{Synopsis} 560*fddef416Sniklas@example 561*fddef416Sniklasboolean bfd_set_section_size(bfd *abfd, asection *sec, bfd_size_type val); 562*fddef416Sniklas@end example 563*fddef416Sniklas@strong{Description}@* 564*fddef416SniklasSet @var{sec} to the size @var{val}. If the operation is 565*fddef416Sniklasok, then @code{true} is returned, else @code{false}. 566*fddef416Sniklas 567*fddef416SniklasPossible error returns: 568*fddef416Sniklas@itemize @bullet 569*fddef416Sniklas 570*fddef416Sniklas@item 571*fddef416Sniklas@code{bfd_error_invalid_operation} - 572*fddef416SniklasWriting has started to the BFD, so setting the size is invalid. 573*fddef416Sniklas@end itemize 574*fddef416Sniklas@* 575*fddef416Sniklas@findex bfd_set_section_contents 576*fddef416Sniklas@subsubsection @code{bfd_set_section_contents} 577*fddef416Sniklas@strong{Synopsis} 578*fddef416Sniklas@example 579*fddef416Sniklasboolean bfd_set_section_contents 580*fddef416Sniklas (bfd *abfd, 581*fddef416Sniklas asection *section, 582*fddef416Sniklas PTR data, 583*fddef416Sniklas file_ptr offset, 584*fddef416Sniklas bfd_size_type count); 585*fddef416Sniklas@end example 586*fddef416Sniklas@strong{Description}@* 587*fddef416SniklasSets the contents of the section @var{section} in BFD 588*fddef416Sniklas@var{abfd} to the data starting in memory at @var{data}. The 589*fddef416Sniklasdata is written to the output section starting at offset 590*fddef416Sniklas@var{offset} for @var{count} bytes. 591*fddef416Sniklas 592*fddef416SniklasNormally @code{true} is returned, else @code{false}. Possible error 593*fddef416Sniklasreturns are: 594*fddef416Sniklas@itemize @bullet 595*fddef416Sniklas 596*fddef416Sniklas@item 597*fddef416Sniklas@code{bfd_error_no_contents} - 598*fddef416SniklasThe output section does not have the @code{SEC_HAS_CONTENTS} 599*fddef416Sniklasattribute, so nothing can be written to it. 600*fddef416Sniklas@item 601*fddef416Sniklasand some more too 602*fddef416Sniklas@end itemize 603*fddef416SniklasThis routine is front end to the back end function 604*fddef416Sniklas@code{_bfd_set_section_contents}. 605*fddef416Sniklas@* 606*fddef416Sniklas@findex bfd_get_section_contents 607*fddef416Sniklas@subsubsection @code{bfd_get_section_contents} 608*fddef416Sniklas@strong{Synopsis} 609*fddef416Sniklas@example 610*fddef416Sniklasboolean bfd_get_section_contents 611*fddef416Sniklas (bfd *abfd, asection *section, PTR location, 612*fddef416Sniklas file_ptr offset, bfd_size_type count); 613*fddef416Sniklas@end example 614*fddef416Sniklas@strong{Description}@* 615*fddef416SniklasRead data from @var{section} in BFD @var{abfd} 616*fddef416Sniklasinto memory starting at @var{location}. The data is read at an 617*fddef416Sniklasoffset of @var{offset} from the start of the input section, 618*fddef416Sniklasand is read for @var{count} bytes. 619*fddef416Sniklas 620*fddef416SniklasIf the contents of a constructor with the @code{SEC_CONSTRUCTOR} 621*fddef416Sniklasflag set are requested or if the section does not have the 622*fddef416Sniklas@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled 623*fddef416Sniklaswith zeroes. If no errors occur, @code{true} is returned, else 624*fddef416Sniklas@code{false}. 625*fddef416Sniklas@* 626*fddef416Sniklas@findex bfd_copy_private_section_data 627*fddef416Sniklas@subsubsection @code{bfd_copy_private_section_data} 628*fddef416Sniklas@strong{Synopsis} 629*fddef416Sniklas@example 630*fddef416Sniklasboolean bfd_copy_private_section_data(bfd *ibfd, asection *isec, bfd *obfd, asection *osec); 631*fddef416Sniklas@end example 632*fddef416Sniklas@strong{Description}@* 633*fddef416SniklasCopy private section information from @var{isec} in the BFD 634*fddef416Sniklas@var{ibfd} to the section @var{osec} in the BFD @var{obfd}. 635*fddef416SniklasReturn @code{true} on success, @code{false} on error. Possible error 636*fddef416Sniklasreturns are: 637*fddef416Sniklas 638*fddef416Sniklas@itemize @bullet 639*fddef416Sniklas 640*fddef416Sniklas@item 641*fddef416Sniklas@code{bfd_error_no_memory} - 642*fddef416SniklasNot enough memory exists to create private data for @var{osec}. 643*fddef416Sniklas@end itemize 644*fddef416Sniklas@example 645*fddef416Sniklas#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ 646*fddef416Sniklas BFD_SEND (obfd, _bfd_copy_private_section_data, \ 647*fddef416Sniklas (ibfd, isection, obfd, osection)) 648*fddef416Sniklas@end example 649*fddef416Sniklas@* 650