1 /* Object file "section" support for the BFD library.
2 Copyright (C) 1990-1991 Free Software Foundation, Inc.
3 Written by Cygnus Support.
5 This file is part of BFD, the Binary File Descriptor library.
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.
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.
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. */
23 Sections are supported in BFD in @code{section.c}.
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
34 * section prototypes::
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.
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}.
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.
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.
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}.
69 The linker uses the fields @code{output_section} and
70 @code{output_offset} to create an output file.
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.
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:
87 output_section -----------> section name "O"
89 section name "B" | size 0x123
92 output_section --------|
105 @node typedef asection, section prototypes, Section Output, Sections
106 @subsection typedef asection
110 The shape of a section struct:
114 $typedef struct sec {
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.
121 The next section in the list belonging to the BFD, or NULL.
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
132 $#define SEC_NO_FLAGS 0x000
134 Tells the OS to allocate space for this section when loaded.
135 This would clear for a section containing debug information only.
137 $#define SEC_ALLOC 0x001
139 Tells the OS to load the section from the file when loading.
140 This would be clear for a .bss section
142 $#define SEC_LOAD 0x002
144 The section contains data still to be relocated, so there will be some
145 relocation information too.
147 $#define SEC_RELOC 0x004
151 $#define SEC_BALIGN 0x008
153 A signal to the OS that the section contains read only data.
155 $#define SEC_READONLY 0x010
157 The section contains code only.
159 $#define SEC_CODE 0x020
161 The section contains data only.
163 $#define SEC_DATA 0x040
165 The section will reside in ROM.
167 $#define SEC_ROM 0x080
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.
179 $#define SEC_CONSTRUCTOR 0x100
181 The section is a constuctor, and should be placed at the end of the ..
183 $#define SEC_CONSTRUCTOR_TEXT 0x1100
185 $#define SEC_CONSTRUCTOR_DATA 0x2100
187 $#define SEC_CONSTRUCTOR_BSS 0x3100
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}
194 $#define SEC_HAS_CONTENTS 0x200
196 An instruction to the linker not to output sections containing
197 this flag even if they have information which would normally be written.
199 $#define SEC_NEVER_LOAD 0x400
202 The base address of the section in the address space of the target.
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}).
209 $ bfd_size_type size;
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.
216 $ bfd_vma output_offset;
218 The output section through which to map on output.
220 $ struct sec *output_section;
222 The alignment requirement of the section, as an exponent - eg 3
225 $ unsigned int alignment_power;
227 If an input section, a pointer to a vector of relocation records for
228 the data in this section.
230 $ struct reloc_cache_entry *relocation;
232 If an output section, a pointer to a vector of pointers to
233 relocation records for the data in this section.
235 $ struct reloc_cache_entry **orelocation;
237 The number of relocation records in one of the above
239 $ unsigned reloc_count;
241 Which section is it 0..nth
245 Information below is back end specific - and not always used or
248 File position of section data
251 File position of relocation info
253 $ file_ptr rel_filepos;
255 File position of line data
257 $ file_ptr line_filepos;
259 Pointer to data for applications
263 $ struct lang_output_section *otheruserdata;
265 Attached line number information
268 Number of line number records
270 $ unsigned int lineno_count;
272 When a section is being output, this value changes as more
273 linenumbers are written out
275 $ file_ptr moving_line_filepos;
277 what the section number is in the target world
279 $ unsigned int target_index;
283 If this is a constructor section then here is a list of the
284 relocations created to relocate items within it.
286 $ struct relent_chain *constructor_chain;
288 The BFD which owns the section.
299 @node section prototypes, , typedef asection, Sections
300 @subsection section prototypes
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.
307 *; PROTO(asection *, bfd_get_section_by_name,
308 (bfd *abfd, CONST char *name));
311 DEFUN(bfd_get_section_by_name
,(abfd
, name
),
317 for (sect
= abfd
->sections
; sect
!= NULL
; sect
= sect
->next
)
318 if (!strcmp (sect
->name
, name
)) return sect
;
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.
331 @item invalid_operation
332 If output has already started for this BFD.
334 If obstack alloc fails.
337 *; PROTO(asection *, bfd_make_section, (bfd *, CONST char *name));
343 DEFUN(bfd_make_section
,(abfd
, name
),
348 asection
** prev
= &abfd
->sections
;
349 asection
* sect
= abfd
->sections
;
351 if (abfd
->output_has_begun
) {
352 bfd_error
= invalid_operation
;
357 if (!strcmp(sect
->name
, name
)) return NULL
;
362 newsect
= (asection
*) bfd_zalloc(abfd
, sizeof (asection
));
363 if (newsect
== NULL
) {
364 bfd_error
= no_memory
;
368 newsect
->name
= name
;
369 newsect
->index
= abfd
->section_count
++;
370 newsect
->flags
= SEC_NO_FLAGS
;
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) {
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:
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.
399 *; PROTO(boolean, bfd_set_section_flags,
400 (bfd *, asection *, flagword));
404 DEFUN(bfd_set_section_flags
,(abfd
, section
, flags
),
409 if ((flags
& bfd_applicable_section_flags (abfd
)) != flags
) {
410 bfd_error
= invalid_operation
;
414 section
->flags
= flags
;
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
425 func(abfd, the_section, obj);
429 *; PROTO(void, bfd_map_over_sections,
430 (bfd *abfd, void (*func)(), PTR obj));
432 This is the prefered method for iterating over sections, an
433 alternative would be to use a loop:
437 for (p = abfd->sections; p != NULL; p = p->next)
444 DEFUN(bfd_map_over_sections
,(abfd
, operation
, user_storage
),
446 void (*operation
)() AND
452 for (sect
= abfd
->sections
; sect
!= NULL
; i
++, sect
= sect
->next
)
453 (*operation
) (abfd
, sect
, user_storage
);
455 if (i
!= abfd
->section_count
) /* Debugging */
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}.
464 Possible error returns:
466 @item invalid_operation
467 Writing has started to the BFD, so setting the size is invalid
470 *; PROTO(boolean, bfd_set_section_size,
471 (bfd *, asection *, bfd_size_type val));
475 DEFUN(bfd_set_section_size
,(abfd
, ptr
, val
),
480 /* Once you've started writing to any section you cannot create or change
481 the size of any others. */
483 if (abfd
->output_has_begun
) {
484 bfd_error
= invalid_operation
;
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.
498 Normally @code{true} is returned, else @code{false}. Possible error
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
506 This routine is front end to the back end function @code{_bfd_set_section_contents}.
508 *; PROTO(boolean, bfd_set_section_contents,
513 bfd_size_type count));
518 DEFUN(bfd_set_section_contents
,(abfd
, section
, location
, offset
, count
),
525 if (!(bfd_get_section_flags(abfd
, section
) & SEC_HAS_CONTENTS
))
527 bfd_error
= no_contents
;
531 if (BFD_SEND (abfd
, _bfd_set_section_contents
,
532 (abfd
, section
, location
, offset
, count
)))
534 abfd
->output_has_begun
= true;
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
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.
550 If no errors occur, @code{true} is returned, else @code{false}.
557 *; PROTO(boolean, bfd_get_section_contents,
558 (bfd *abfd, asection *section, PTR location,
559 file_ptr offset, bfd_size_type count));
564 DEFUN(bfd_get_section_contents
,(abfd
, section
, location
, offset
, count
),
571 if (section
->flags
& SEC_CONSTRUCTOR
)
573 memset(location
, 0, (unsigned)count
);
578 return (BFD_SEND (abfd
, _bfd_get_section_contents
,
579 (abfd
, section
, location
, offset
, count
)));