bfd/section.c

   1 /* Object file "section" support for the BFD library.
   2    Copyright (C) 1990-1991 Free Software Foundation, Inc.
   3    Written by Cygnus Support.
   4
   5 This file is part of BFD, the Binary File Descriptor library.
   6
   7 This program is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2 of the License, or
  10 (at your option) any later version.
  11
  12 This program is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 GNU General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with this program; if not, write to the Free Software
  19 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20
  21 /*doc*
  22 @section Sections
  23 Sections are supported in BFD in @code{section.c}.
  24
  25 The raw data contained within a BFD is maintained through the section
  26 abstraction.  A single BFD may have any number of sections, and keeps
  27 hold of them by pointing to the first, each one points to the next in
  28 the list.
  29
  30 @menu
  31 * Section Input::
  32 * Section Output::
  33 * typedef asection::
  34 * section prototypes::
  35 @end menu
  36
  37 @node Section Input, Section Output, Sections, Sections
  38 @subsection Section Input
  39 When a BFD is opened for reading, the section structures are created
  40 and attached to the BFD.
  41
  42 Each section has a name which describes the section in the outside
  43 world - for example, @code{a.out} would contain at least three
  44 sections, called @code{.text}, @code{.data} and @code{.bss}.
  45
  46 Sometimes a BFD will contain more than the 'natural' number of
  47 sections. A back end may attach other sections containing constructor
  48 data, or an application may add a section (using bfd_make_section) to
  49 the sections attached to an already open BFD. For example, the linker
  50 creates a supernumary section @code{COMMON} for each input file's BFD
  51 to hold information about common storage.
  52
  53 The raw data is not necessarily read in at the same time as the
  54 section descriptor is created. Some targets may leave the data in
  55 place until a @code{bfd_get_section_contents} call is made. Other back
  56 ends may read in all the data at once - For example; an S-record file
  57 has to be read once to determine the size of the data. An IEEE-695
  58 file doesn't contain raw data in sections, but data and relocation
  59 expressions intermixed, so the data area has to be parsed to get out
  60 the data and relocations.
  61
  62 @node Section Output, typedef asection, Section Input, Sections
  63 @subsection Section Output
  64 To write a new object style BFD, the various sections to be written
  65 have to be created. They are attached to the BFD in the same way as
  66 input sections, data is written to the sections using
  67 @code{bfd_set_section_contents}.
  68
  69 The linker uses the fields @code{output_section} and
  70 @code{output_offset} to create an output file.
  71
  72 The data to be written comes from input sections attached to the
  73 output sections.  The output section structure can be considered a
  74 filter for the input section, the output section determines the vma of
  75 the output data and the name, but the input section determines the
  76 offset into the output section of the data to be written.
  77
  78 Eg to create a section "O", starting at 0x100, 0x123 long, containing two
  79 subsections, "A" at offset 0x0 (ie at vma 0x100) and "B" at offset
  80 0x20 (ie at vma 0x120) the structures would look like:
  81
  82 *+
  83
  84    section name          "A"
  85      output_offset   0x00
  86      size            0x20
  87      output_section ----------->  section name    "O"
  88                              |    vma             0x100
  89    section name          "B" |    size            0x123
  90      output_offset   0x20    |
  91      size            0x103   |
  92      output_section  --------|
  93
  94 *-
  95
  96 */
  97
  98
  99 #include "bfd.h"
 100 #include "sysdep.h"
 101 #include "libbfd.h"
 102
 103
 104 /*doc*
 105 @node typedef asection, section prototypes, Section Output, Sections
 106 @subsection typedef asection
 107 */
 108
 109 /*proto*
 110 The shape of a section struct:
 111
 112 *+++
 113
 114 $typedef struct sec {
 115
 116 The name of the section, the name isn't a copy, the pointer is
 117 the same as that passed to bfd_make_section.
 118
 119 $    CONST char *name;
 120
 121 The next section in the list belonging to the BFD, or NULL.
 122
 123 $    struct sec *next;
 124
 125 The field flags contains attributes of the section. Some of these
 126 flags are read in from the object file, and some are synthesized from
 127 other information.
 128
 129 $flagword flags;
 130
 131
 132 $#define SEC_NO_FLAGS   0x000
 133
 134 Tells the OS to allocate space for this section when loaded.
 135 This would clear for a section containing debug information only.
 136
 137 $#define SEC_ALLOC      0x001
 138
 139 Tells the OS to load the section from the file when loading.
 140 This would be clear for a .bss section
 141
 142 $#define SEC_LOAD       0x002
 143
 144 The section contains data still to be relocated, so there will be some
 145 relocation information too.
 146
 147 $#define SEC_RELOC      0x004
 148
 149 Obsolete ?
 150
 151 $#define SEC_BALIGN     0x008
 152
 153 A signal to the OS that the section contains read only data.
 154
 155 $#define SEC_READONLY   0x010
 156
 157 The section contains code only.
 158
 159 $#define SEC_CODE       0x020
 160
 161 The section contains data only.
 162
 163 $#define SEC_DATA        0x040
 164
 165 The section will reside in ROM.
 166
 167 $#define SEC_ROM        0x080
 168
 169 The section contains constructor information. This section type is
 170 used by the linker to create lists of constructors and destructors
 171 used by @code{g++}. When a back end sees a symbol which should be used
 172 in a constructor list, it creates a new section for the type of name
 173 (eg @code{__CTOR_LIST__}), attaches the symbol to it and builds a
 174 relocation. To build the lists of constructors, all the linker has to
 175 to is catenate all the sections called @code{__CTOR_LIST__} and
 176 relocte the data contained within - exactly the operations it would
 177 peform on standard data.
 178
 179 $#define SEC_CONSTRUCTOR 0x100
 180
 181 The section is a constuctor, and should be placed at the end of the ..
 182
 183 $#define SEC_CONSTRUCTOR_TEXT 0x1100
 184
 185 $#define SEC_CONSTRUCTOR_DATA 0x2100
 186
 187 $#define SEC_CONSTRUCTOR_BSS  0x3100
 188
 189
 190 The section has contents - a bss section could be
 191 @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}, a debug section could be
 192 @code{SEC_HAS_CONTENTS}
 193
 194 $#define SEC_HAS_CONTENTS 0x200
 195
 196 An instruction to the linker not to output sections containing
 197 this flag even if they have information which would normally be written.
 198
 199 $#define SEC_NEVER_LOAD 0x400
 200
 201
 202 The base address of the section in the address space of the target.
 203
 204 $   bfd_vma vma;
 205
 206 The size of the section in bytes of the loaded section. This contains
 207 a value even if the section has no contents (eg, the size of @code{.bss}).
 208
 209 $   bfd_size_type size;
 210
 211 If this section is going to be output, then this value is the
 212 offset into the output section of the first byte in the input
 213 section. Eg, if this was going to start at the 100th byte in the
 214 output section, this value would be 100.
 215
 216 $   bfd_vma output_offset;
 217
 218 The output section through which to map on output.
 219
 220 $   struct sec *output_section;
 221
 222 The alignment requirement of the section, as an exponent - eg 3
 223 aligns to 2^3 (or 8)
 224
 225 $   unsigned int alignment_power;
 226
 227 If an input section, a pointer to a vector of relocation records for
 228 the data in this section.
 229
 230 $   struct reloc_cache_entry *relocation;
 231
 232 If an output section, a pointer to a vector of pointers to
 233 relocation records for the data in this section.
 234
 235 $   struct reloc_cache_entry **orelocation;
 236
 237 The number of relocation records in one of the above
 238
 239 $   unsigned reloc_count;
 240
 241 Which section is it 0..nth
 242
 243 $   int index;
 244
 245 Information below is back end specific - and not always used or
 246 updated
 247
 248 File position of section data
 249
 250 $   file_ptr filepos;
 251 File position of relocation info
 252
 253 $   file_ptr rel_filepos;
 254
 255 File position of line data
 256
 257 $   file_ptr line_filepos;
 258
 259 Pointer to data for applications
 260
 261 $   PTR userdata;
 262
 263 $   struct lang_output_section *otheruserdata;
 264
 265 Attached line number information
 266
 267 $   alent *lineno;
 268 Number of line number records
 269
 270 $   unsigned int lineno_count;
 271
 272 When a section is being output, this value changes as more
 273 linenumbers are written out
 274
 275 $   file_ptr moving_line_filepos;
 276
 277 what the section number is in the target world
 278
 279 $   unsigned int target_index;
 280
 281 $   PTR used_by_bfd;
 282
 283 If this is a constructor section then here is a list of the
 284 relocations created to relocate items within it.
 285
 286 $   struct relent_chain *constructor_chain;
 287
 288 The BFD which owns the section.
 289
 290 $   bfd *owner;
 291
 292 $} asection ;
 293
 294 *---
 295
 296 */
 297
 298 /*doc*
 299 @node section prototypes,  , typedef asection, Sections
 300 @subsection section prototypes
 301
 302 */
 303 /*proto* bfd_get_section_by_name
 304 Runs through the provided @var{abfd} and returns the @code{asection}
 305 who's name matches that provided, otherwise NULL. @xref{Sections}, for more information.
 306
 307 *; PROTO(asection *, bfd_get_section_by_name,
 308     (bfd *abfd, CONST char *name));
 309 */
 310 asection *
 311 DEFUN(bfd_get_section_by_name,(abfd, name),
 312       bfd *abfd AND
 313       CONST char *name)
 314 {
 315   asection *sect;
 316
 317   for (sect = abfd->sections; sect != NULL; sect = sect->next)
 318     if (!strcmp (sect->name, name)) return sect;
 319   return NULL;
 320 }
 321
 322
 323 /*proto* bfd_make_section
 324 This function creates a new empty section called @var{name} and attaches it
 325 to the end of the chain of sections for the BFD supplied. An attempt to
 326 create a section with a name which is already in use, returns NULL without
 327 changing the section chain.
 328
 329 Possible errors are:
 330 @table @code
 331 @item invalid_operation
 332 If output has already started for this BFD.
 333 @item no_memory
 334 If obstack alloc fails.
 335 @end table
 336
 337 *; PROTO(asection *, bfd_make_section, (bfd *, CONST char *name));
 338 */
 339
 340
 341
 342 sec_ptr
 343 DEFUN(bfd_make_section,(abfd, name),
 344       bfd *abfd AND
 345       CONST char * name)
 346 {
 347   asection *newsect;
 348   asection **  prev = &abfd->sections;
 349   asection * sect = abfd->sections;
 350
 351   if (abfd->output_has_begun) {
 352     bfd_error = invalid_operation;
 353     return NULL;
 354   }
 355
 356   while (sect) {
 357     if (!strcmp(sect->name, name)) return NULL;
 358     prev = &sect->next;
 359     sect = sect->next;
 360   }
 361
 362   newsect = (asection *) bfd_zalloc(abfd, sizeof (asection));
 363   if (newsect == NULL) {
 364     bfd_error = no_memory;
 365     return NULL;
 366   }
 367
 368   newsect->name = name;
 369   newsect->index = abfd->section_count++;
 370   newsect->flags = SEC_NO_FLAGS;
 371
 372   newsect->userdata = 0;
 373   newsect->next = (asection *)NULL;
 374   newsect->relocation = (arelent *)NULL;
 375   newsect->reloc_count = 0;
 376   newsect->line_filepos =0;
 377   newsect->owner = abfd;
 378   if (BFD_SEND (abfd, _new_section_hook, (abfd, newsect)) != true) {
 379     free (newsect);
 380     return NULL;
 381   }
 382
 383   *prev = newsect;
 384   return newsect;
 385 }
 386
 387
 388 /*proto* bfd_set_section_flags
 389 Attempts to set the attributes of the section named in the BFD
 390 supplied to the value. Returns true on success, false on error.
 391 Possible error returns are:
 392 @table @code
 393 @item invalid operation
 394 The section cannot have one or more of the attributes requested. For
 395 example, a .bss section in @code{a.out} may not have the
 396 @code{SEC_HAS_CONTENTS} field set.
 397 @end table
 398
 399 *; PROTO(boolean, bfd_set_section_flags,
 400        (bfd *, asection *, flagword));
 401 */
 402
 403 boolean
 404 DEFUN(bfd_set_section_flags,(abfd, section, flags),
 405      bfd *abfd AND
 406      sec_ptr section AND
 407      flagword flags)
 408 {
 409   if ((flags & bfd_applicable_section_flags (abfd)) != flags) {
 410     bfd_error = invalid_operation;
 411     return false;
 412   }
 413
 414   section->flags = flags;
 415   return true;
 416 }
 417
 418
 419 /*proto* bfd_map_over_sections
 420 Calls the provided function @var{func} for each section attached to
 421 the BFD @var{abfd}, passing @var{obj} as an argument. The function
 422 will be called as if by
 423
 424 @example
 425   func(abfd, the_section, obj);
 426 @end example
 427
 428
 429 *; PROTO(void, bfd_map_over_sections,
 430             (bfd *abfd, void (*func)(), PTR obj));
 431
 432 This is the prefered method for iterating over sections, an
 433 alternative would be to use a loop:
 434
 435 @example
 436    section *p;
 437    for (p = abfd->sections; p != NULL; p = p->next)
 438       func(abfd, p, ...)
 439 @end example
 440 */
 441
 442 /*VARARGS2*/
 443 void
 444 DEFUN(bfd_map_over_sections,(abfd, operation, user_storage),
 445       bfd *abfd AND
 446       void (*operation)() AND
 447       PTR user_storage)
 448 {
 449   asection *sect;
 450   int i = 0;
 451
 452   for (sect = abfd->sections; sect != NULL; i++, sect = sect->next)
 453     (*operation) (abfd, sect, user_storage);
 454
 455   if (i != abfd->section_count)         /* Debugging */
 456     abort();
 457 }
 458
 459
 460 /*proto* bfd_set_section_size
 461 Sets @var{section} to the size @var{val}. If the operation is ok, then
 462 @code{true} is returned, else @code{false}.
 463
 464 Possible error returns:
 465 @table @code
 466 @item invalid_operation
 467 Writing has started to the BFD, so setting the size is invalid
 468 @end table
 469
 470 *; PROTO(boolean, bfd_set_section_size,
 471      (bfd *, asection *, bfd_size_type val));
 472 */
 473
 474 boolean
 475 DEFUN(bfd_set_section_size,(abfd, ptr, val),
 476       bfd *abfd AND
 477       sec_ptr ptr AND
 478       bfd_size_type val)
 479 {
 480   /* Once you've started writing to any section you cannot create or change
 481      the size of any others. */
 482
 483   if (abfd->output_has_begun) {
 484     bfd_error = invalid_operation;
 485     return false;
 486   }
 487
 488   ptr->size = val;
 489
 490   return true;
 491 }
 492
 493 /*proto* bfd_set_section_contents
 494 Sets the contents of the section @var{section} in BFD @var{abfd} to
 495 the data starting in memory at @var{data}. The data is written to the
 496 output section starting at offset @var{offset} for @var{count} bytes.
 497
 498 Normally @code{true} is returned, else @code{false}. Possible error
 499 returns are:
 500 @table @code
 501 @item no_contents
 502 The output section does not have the @code{SEC_HAS_CONTENTS}
 503 attribute, so nothing can be written to it.
 504 @item and some more too
 505 @end table
 506 This routine is front end to the back end function @code{_bfd_set_section_contents}.
 507
 508 *; PROTO(boolean, bfd_set_section_contents,
 509          (bfd *abfd,
 510          asection *section,
 511          PTR data,
 512          file_ptr offset,
 513          bfd_size_type count));
 514
 515 */
 516
 517 boolean
 518 DEFUN(bfd_set_section_contents,(abfd, section, location, offset, count),
 519       bfd *abfd AND
 520       sec_ptr section AND
 521       PTR location AND
 522       file_ptr offset AND
 523       bfd_size_type count)
 524 {
 525   if (!(bfd_get_section_flags(abfd, section) & SEC_HAS_CONTENTS))
 526       {
 527         bfd_error = no_contents;
 528         return(false);
 529       }
 530
 531   if (BFD_SEND (abfd, _bfd_set_section_contents,
 532                 (abfd, section, location, offset, count)))
 533       {
 534         abfd->output_has_begun = true;
 535         return true;
 536       }
 537
 538   return false;
 539 }
 540
 541 /*proto* bfd_get_section_contents
 542 This function reads data from @var{section} in BFD @var{abfd} into
 543 memory starting at @var{location}. The data is read at an offset of
 544 @var{offset} from the start of the input section, and is read for
 545 @var{count} bytes.
 546
 547 If the contents of a constuctor with the @code{SEC_CONSTUCTOR} flag
 548 set are requested, then the @var{location} is filled with zeroes.
 549
 550 If no errors occur, @code{true} is returned, else @code{false}.
 551 Possible errors are:
 552
 553 @table @code
 554 @item unknown yet
 555 @end table
 556
 557 *; PROTO(boolean, bfd_get_section_contents,
 558         (bfd *abfd, asection *section, PTR location,
 559          file_ptr offset, bfd_size_type count));
 560
 561
 562 */
 563 boolean
 564 DEFUN(bfd_get_section_contents,(abfd, section, location, offset, count),
 565       bfd *abfd AND
 566       sec_ptr section AND
 567       PTR location AND
 568       file_ptr offset AND
 569       bfd_size_type count)
 570 {
 571   if (section->flags & SEC_CONSTRUCTOR)
 572       {
 573         memset(location, 0, (unsigned)count);
 574         return true;
 575       }
 576   else
 577       {
 578         return  (BFD_SEND (abfd, _bfd_get_section_contents,
 579                            (abfd, section, location, offset, count)));
 580       }
 581 }
 582