3 Sections are supported in bfd in @code{section.c}.
5 The raw data contained within a bfd is maintained through the section
6 abstraction. A single bfd may have any number of sections, and keeps
7 hold of them by pointing to the first, each one points to the next in
14 * section prototypes::
17 @node Section Input, Section Output,,Sections
18 @comment node-name, next, previous, up
19 @subsection Section Input
20 When a bfd is opened for reading, the section structures are created
21 and attatched to the bfd.
23 Each section has a name which describes the section in the outside
24 world - for example, @code{a.out} would contain at least three
25 sections, called @code{.text}, @code{.data} and @code{.bss}.
27 Sometimes a bfd will contain more than the 'natural' number of
28 sections. A back end may attatch other sections containing constructor
29 data, or an application may add a section (using bfd_make_section) to
30 the sections attatched to an already open bfd. For example, the linker
31 creates a supernumary section @code{COMMON} for each input file's bfd
32 to hold information about common storage.
34 The raw data is not necessarily read in at the same time as the
35 section descriptor is created. Some targets may leave the data in
36 place until a @code{bfd_get_section_contents} call is made. Other back
37 ends may read in all the data at once - For example; an S-record file
38 has to be read once to determine the size of the data. An IEEE-695
39 file doesn't contain raw data in sections, but data and relocation
40 expressions intermixed, so the data area has to be parsed to get out
41 the data and relocations.
43 @node Section Output,typedef asection,Section Input,Sections
44 @subsection Section Output
45 To write a new object style bfd, the various sections to be written
46 have to be created. They are attatched to the bfd in the same way as
47 input sections, data is written to the sections using
48 @code{bfd_set_section_contents}.
50 The linker uses the fields @code{output_section} and
51 @code{output_offset} to create an output file.
53 The data to be written comes from input sections attatched to the
54 output sections. The output section structure can be considered a
55 filter for the input section, the output section determines the vma of
56 the output data and the name, but the input section determines the
57 offset into the output section of the data to be written.
59 Eg to create a section "O", starting at 0x100, 0x123 long, containing two
60 subsections, "A" at offset 0x0 (ie at vma 0x100) and "B" at offset
61 0x20 (ie at vma 0x120) the structures would look like:
68 output_section -----------> section name "O"
70 section name "B" | size 0x123
73 output_section --------|
86 @node typedef asection,section prototypes,Section Output,Sections
87 @subsection typedef asection
91 The shape of a section struct:
97 The name of the section, the name isn't a copy, the pointer is
98 the same as that passed to bfd_make_section.
102 The next section in the list belonging to the bfd, or NULL.
106 The field flags contains attributes of the section. Some of these
107 flags are read in from the object file, and some are synthesized from
113 $#define SEC_NO_FLAGS 0x000
115 Tells the OS to allocate space for this section when loaded.
116 This would clear for a section containing debug information only.
118 $#define SEC_ALLOC 0x001
120 Tells the OS to load the section from the file when loading.
121 This would be clear for a .bss section
123 $#define SEC_LOAD 0x002
125 The section contains data still to be relocated, so there will be some
126 relocation information too.
128 $#define SEC_RELOC 0x004
132 $#define SEC_BALIGN 0x008
134 A signal to the OS that the section contains read only data.
136 $#define SEC_READONLY 0x010
138 The section contains code only.
140 $#define SEC_CODE 0x020
142 The section contains data only.
144 $#define SEC_DATA 0x040
146 The section will reside in ROM.
148 $#define SEC_ROM 0x080
150 The section contains constructor information. This section type is
151 used by the linker to create lists of constructors and destructors
152 used by @code{g++}. When a back end sees a symbol which should be used
153 in a constructor list, it creates a new section for the type of name
154 (eg @code{__CTOR_LIST__}), attatches the symbol to it and builds a
155 relocation. To build the lists of constructors, all the linker has to
156 to is catenate all the sections called @code{__CTOR_LIST__} and
157 relocte the data contained within - exactly the operations it would
158 peform on standard data.
160 $#define SEC_CONSTRUCTOR 0x100
162 The section has contents - a bss section could be
163 @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}, a debug section could be
164 @code{SEC_HAS_CONTENTS}
166 $#define SEC_HAS_CONTENTS 0x200
168 An instruction to the linker not to output sections containing
169 this flag even if they have information which would normally be written.
171 $#define SEC_NEVER_LOAD 0x400
173 The base address of the section in the address space of the target.
177 The size of the section in bytes of the loaded section. This contains
178 a value even if the section has no contents (eg, the size of @code{.bss}).
180 $ bfd_size_type size;
182 If this section is going to be output, then this value is the
183 offset into the output section of the first byte in the input
184 section. Eg, if this was going to start at the 100th byte in the
185 output section, this value would be 100.
187 $ bfd_vma output_offset;
189 The output section through which to map on output.
191 $ struct sec *output_section;
193 The alignment requirement of the section, as an exponent - eg 3
196 $ unsigned int alignment_power;
198 If an input section, a pointer to a vector of relocation records for
199 the data in this section.
201 $ struct reloc_cache_entry *relocation;
203 If an output section, a pointer to a vector of pointers to
204 relocation records for the data in this section.
206 $ struct reloc_cache_entry **orelocation;
208 The number of relocation records in one of the above
210 $ unsigned reloc_count;
212 Which section is it 0..nth
216 Information below is back end specific - and not always used or
219 File position of section data
222 File position of relocation info
224 $ file_ptr rel_filepos;
226 File position of line data
228 $ file_ptr line_filepos;
230 Pointer to data for applications
234 $ struct lang_output_section *otheruserdata;
236 Attached line number information
239 Number of line number records
241 $ unsigned int lineno_count;
243 When a section is being output, this value changes as more
244 linenumbers are written out
246 $ file_ptr moving_line_filepos;
248 what the section number is in the target world
250 $ unsigned int target_index;
254 If this is a constructor section then here is a list of the
255 relocations created to relocate items within it.
257 $ struct relent_chain *constructor_chain;
259 The bfd which owns the section.
270 @node section prototypes,Section,typedef section,Sections
271 @subsection section prototypes
274 /*proto* bfd_get_section_by_name
275 Runs through the provided @var{abfd} and returns the @code{asection}
276 who's name matches that provided, otherwise NULL. @xref{Sections}, for more information.
278 *; PROTO(asection *, bfd_get_section_by_name,
279 (bfd *abfd, CONST char *name));
282 DEFUN(bfd_get_section_by_name
,(abfd
, name
),
288 for (sect
= abfd
->sections
; sect
!= NULL
; sect
= sect
->next
)
289 if (!strcmp (sect
->name
, name
)) return sect
;
294 /*proto* bfd_make_section
295 This function creates a new empty section called @var{name} and attatches it
296 to the end of the chain of sections for @var{bfd}. An attempt to
297 create a section with a name which is already in use, returns the old
298 section by that name instead.
302 @item invalid_operation
303 If output has already started for this bfd.
305 If obstack alloc fails.
308 *; PROTO(asection *, bfd_make_section, (bfd *, CONST char *name));
314 DEFUN(bfd_make_section
,(abfd
, name
),
319 asection
** prev
= &abfd
->sections
;
320 asection
* sect
= abfd
->sections
;
322 if (abfd
->output_has_begun
) {
323 bfd_error
= invalid_operation
;
328 if (!strcmp(sect
->name
, name
)) return sect
;
333 newsect
= (asection
*) bfd_zalloc(abfd
, sizeof (asection
));
334 if (newsect
== NULL
) {
335 bfd_error
= no_memory
;
339 newsect
->name
= name
;
340 newsect
->index
= abfd
->section_count
++;
341 newsect
->flags
= SEC_NO_FLAGS
;
343 newsect
->userdata
= 0;
344 newsect
->next
= (asection
*)NULL
;
345 newsect
->relocation
= (arelent
*)NULL
;
346 newsect
->reloc_count
= 0;
347 newsect
->line_filepos
=0;
348 newsect
->owner
= abfd
;
349 if (BFD_SEND (abfd
, _new_section_hook
, (abfd
, newsect
)) != true) {
359 /*proto* bfd_set_section_flags
360 Attempts to set the attributes of the section named in the bfd
361 supplied to the value. Returns true on success, false on error.
362 Possible error returns are:
364 @item invalid operation
365 The section cannot have one or more of the attributes requested. For
366 example, a .bss section in @code{a.out} may not have the
367 @code{SEC_HAS_CONTENTS} field set.
370 *; PROTO(boolean, bfd_set_section_flags,
371 (bfd *, asection *, flagword));
375 DEFUN(bfd_set_section_flags
,(abfd
, section
, flags
),
380 if ((flags
& bfd_applicable_section_flags (abfd
)) != flags
) {
381 bfd_error
= invalid_operation
;
385 section
->flags
= flags
;
390 /*proto* bfd_map_over_sections
391 Calls the provided function @var{func} for each section attatched to
392 the bfd @var{abfd}, passing @var{obj} as an argument. The function
393 will be called as if by
396 func(abfd, the_section, obj);
400 *; PROTO(void, bfd_map_over_sections,
401 (bfd *abfd, void (*func)(), PTR obj));
403 This is the prefered method for iterating over sections, an
404 alternative would be to use a loop:
408 for (p = abfd->sections; p != NULL; p = p->next)
415 DEFUN(bfd_map_over_sections
,(abfd
, operation
, user_storage
),
417 void (*operation
)() AND
423 for (sect
= abfd
->sections
; sect
!= NULL
; i
++, sect
= sect
->next
)
424 (*operation
) (abfd
, sect
, user_storage
);
426 if (i
!= abfd
->section_count
) /* Debugging */
431 /*proto* bfd_set_section_size
432 Sets @var{section} to the size @var{val}. If the operation is ok, then
433 @code{true} is returned, else @code{false}.
435 Possible error returns:
437 @item invalid_operation
438 Writing has started to the bfd, so setting the size is invalid
441 *; PROTO(boolean, bfd_set_section_size,
442 (bfd *, asection *, bfd_size_type val));
446 DEFUN(bfd_set_section_size
,(abfd
, ptr
, val
),
451 /* Once you've started writing to any section you cannot create or change
452 the size of any others. */
454 if (abfd
->output_has_begun
) {
455 bfd_error
= invalid_operation
;
464 /*proto* bfd_set_section_contents
465 Sets the contents of the section @var{section} in bfd @var{abfd} to
466 the data starting in memory at @var{data}. The data is written to the
467 output section starting at offset @var{offset} for @var{count} bytes.
469 Normally @code{true} is returned, else @code{false}. Possible error
473 The output section does not have the @code{SEC_HAS_CONTENTS}
474 attribute, so nothing can be written to it.
475 @item and some more too
477 This routine is front end to the back end function @code{_bfd_set_section_contents}.
479 *; PROTO(boolean, bfd_set_section_contents,
484 bfd_size_type count));
489 DEFUN(bfd_set_section_contents
,(abfd
, section
, location
, offset
, count
),
496 if (!(bfd_get_section_flags(abfd
, section
) & SEC_HAS_CONTENTS
))
498 bfd_error
= no_contents
;
502 if (BFD_SEND (abfd
, _bfd_set_section_contents
,
503 (abfd
, section
, location
, offset
, count
)))
505 abfd
->output_has_begun
= true;
512 /*proto* bfd_get_section_contents
513 This function reads data from @var{section} in bfd @var{abfd} into
514 memory starting at @var{location}. The data is read at an offset of
515 @var{offset} from the start of the input section, and is read for
518 If the contents of a constuctor with the @code{SEC_CONSTUCTOR} flag
519 set are requested, then the @var{location} is filled with zeroes.
521 If no errors occur, @code{true} is returned, else @code{false}.
528 *; PROTO(boolean, bfd_get_section_contents,
529 (bfd *abfd, asection *section, PTR location,
530 file_ptr offset, bfd_size_type count));
535 DEFUN(bfd_get_section_contents
,(abfd
, section
, location
, offset
, count
),
542 if (section
->flags
& SEC_CONSTRUCTOR
)
544 memset(location
, 0, (unsigned)count
);
549 return (BFD_SEND (abfd
, _bfd_get_section_contents
,
550 (abfd
, section
, location
, offset
, count
)));