Initial revision
[deliverable/binutils-gdb.git] / bfd / section.c
1 /*doc*
2 @section Sections
3 Sections are supported in bfd in @code{section.c}.
4
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
8 the list.
9
10 @menu
11 * Section Input::
12 * Section Output::
13 * typedef asection::
14 * section prototypes::
15 @end menu
16
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.
22
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}.
26
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.
33
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.
42
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}.
49
50 The linker uses the fields @code{output_section} and
51 @code{output_offset} to create an output file.
52
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.
58
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:
62
63 *+
64
65 section name "A"
66 output_offset 0x00
67 size 0x20
68 output_section -----------> section name "O"
69 | vma 0x100
70 section name "B" | size 0x123
71 output_offset 0x20 |
72 size 0x103 |
73 output_section --------|
74
75 *-
76
77 */
78
79
80 #include "sysdep.h"
81 #include "bfd.h"
82 #include "libbfd.h"
83
84
85 /*doc*
86 @node typedef asection,section prototypes,Section Output,Sections
87 @subsection typedef asection
88 */
89
90 /*proto*
91 The shape of a section struct:
92
93 *+++
94
95 $typedef struct sec {
96
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.
99
100 $ CONST char *name;
101
102 The next section in the list belonging to the bfd, or NULL.
103
104 $ struct sec *next;
105
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
108 other information.
109
110 $flagword flags;
111
112
113 $#define SEC_NO_FLAGS 0x000
114
115 Tells the OS to allocate space for this section when loaded.
116 This would clear for a section containing debug information only.
117
118 $#define SEC_ALLOC 0x001
119
120 Tells the OS to load the section from the file when loading.
121 This would be clear for a .bss section
122
123 $#define SEC_LOAD 0x002
124
125 The section contains data still to be relocated, so there will be some
126 relocation information too.
127
128 $#define SEC_RELOC 0x004
129
130 Obsolete ?
131
132 $#define SEC_BALIGN 0x008
133
134 A signal to the OS that the section contains read only data.
135
136 $#define SEC_READONLY 0x010
137
138 The section contains code only.
139
140 $#define SEC_CODE 0x020
141
142 The section contains data only.
143
144 $#define SEC_DATA 0x040
145
146 The section will reside in ROM.
147
148 $#define SEC_ROM 0x080
149
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.
159
160 $#define SEC_CONSTRUCTOR 0x100
161
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}
165
166 $#define SEC_HAS_CONTENTS 0x200
167
168 An instruction to the linker not to output sections containing
169 this flag even if they have information which would normally be written.
170
171 $#define SEC_NEVER_LOAD 0x400
172
173 The base address of the section in the address space of the target.
174
175 $ bfd_vma vma;
176
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}).
179
180 $ bfd_size_type size;
181
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.
186
187 $ bfd_vma output_offset;
188
189 The output section through which to map on output.
190
191 $ struct sec *output_section;
192
193 The alignment requirement of the section, as an exponent - eg 3
194 aligns to 2^3 (or 8)
195
196 $ unsigned int alignment_power;
197
198 If an input section, a pointer to a vector of relocation records for
199 the data in this section.
200
201 $ struct reloc_cache_entry *relocation;
202
203 If an output section, a pointer to a vector of pointers to
204 relocation records for the data in this section.
205
206 $ struct reloc_cache_entry **orelocation;
207
208 The number of relocation records in one of the above
209
210 $ unsigned reloc_count;
211
212 Which section is it 0..nth
213
214 $ int index;
215
216 Information below is back end specific - and not always used or
217 updated
218
219 File position of section data
220
221 $ file_ptr filepos;
222 File position of relocation info
223
224 $ file_ptr rel_filepos;
225
226 File position of line data
227
228 $ file_ptr line_filepos;
229
230 Pointer to data for applications
231
232 $ PTR userdata;
233
234 $ struct lang_output_section *otheruserdata;
235
236 Attached line number information
237
238 $ alent *lineno;
239 Number of line number records
240
241 $ unsigned int lineno_count;
242
243 When a section is being output, this value changes as more
244 linenumbers are written out
245
246 $ file_ptr moving_line_filepos;
247
248 what the section number is in the target world
249
250 $ unsigned int target_index;
251
252 $ PTR used_by_bfd;
253
254 If this is a constructor section then here is a list of the
255 relocations created to relocate items within it.
256
257 $ struct relent_chain *constructor_chain;
258
259 The bfd which owns the section.
260
261 $ bfd *owner;
262
263 $} asection ;
264
265 *---
266
267 */
268
269 /*doc*
270 @node section prototypes,Section,typedef section,Sections
271 @subsection section prototypes
272
273 */
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.
277
278 *; PROTO(asection *, bfd_get_section_by_name,
279 (bfd *abfd, CONST char *name));
280 */
281 asection *
282 DEFUN(bfd_get_section_by_name,(abfd, name),
283 bfd *abfd AND
284 CONST char *name)
285 {
286 asection *sect;
287
288 for (sect = abfd->sections; sect != NULL; sect = sect->next)
289 if (!strcmp (sect->name, name)) return sect;
290 return NULL;
291 }
292
293
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.
299
300 Possible errors are:
301 @table @code
302 @item invalid_operation
303 If output has already started for this bfd.
304 @item no_memory
305 If obstack alloc fails.
306 @end table
307
308 *; PROTO(asection *, bfd_make_section, (bfd *, CONST char *name));
309 */
310
311
312
313 sec_ptr
314 DEFUN(bfd_make_section,(abfd, name),
315 bfd *abfd AND
316 CONST char * name)
317 {
318 asection *newsect;
319 asection ** prev = &abfd->sections;
320 asection * sect = abfd->sections;
321
322 if (abfd->output_has_begun) {
323 bfd_error = invalid_operation;
324 return NULL;
325 }
326
327 while (sect) {
328 if (!strcmp(sect->name, name)) return sect;
329 prev = &sect->next;
330 sect = sect->next;
331 }
332
333 newsect = (asection *) bfd_zalloc(abfd, sizeof (asection));
334 if (newsect == NULL) {
335 bfd_error = no_memory;
336 return NULL;
337 }
338
339 newsect->name = name;
340 newsect->index = abfd->section_count++;
341 newsect->flags = SEC_NO_FLAGS;
342
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) {
350 free (newsect);
351 return NULL;
352 }
353
354 *prev = newsect;
355 return newsect;
356 }
357
358
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:
363 @table @code
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.
368 @end table
369
370 *; PROTO(boolean, bfd_set_section_flags,
371 (bfd *, asection *, flagword));
372 */
373
374 boolean
375 DEFUN(bfd_set_section_flags,(abfd, section, flags),
376 bfd *abfd AND
377 sec_ptr section AND
378 flagword flags)
379 {
380 if ((flags & bfd_applicable_section_flags (abfd)) != flags) {
381 bfd_error = invalid_operation;
382 return false;
383 }
384
385 section->flags = flags;
386 return true;
387 }
388
389
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
394
395 @example
396 func(abfd, the_section, obj);
397 @end example
398
399
400 *; PROTO(void, bfd_map_over_sections,
401 (bfd *abfd, void (*func)(), PTR obj));
402
403 This is the prefered method for iterating over sections, an
404 alternative would be to use a loop:
405
406 @example
407 section *p;
408 for (p = abfd->sections; p != NULL; p = p->next)
409 func(abfd, p, ...)
410 @end example
411 */
412
413 /*VARARGS2*/
414 void
415 DEFUN(bfd_map_over_sections,(abfd, operation, user_storage),
416 bfd *abfd AND
417 void (*operation)() AND
418 PTR user_storage)
419 {
420 asection *sect;
421 int i = 0;
422
423 for (sect = abfd->sections; sect != NULL; i++, sect = sect->next)
424 (*operation) (abfd, sect, user_storage);
425
426 if (i != abfd->section_count) /* Debugging */
427 abort();
428 }
429
430
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}.
434
435 Possible error returns:
436 @table @code
437 @item invalid_operation
438 Writing has started to the bfd, so setting the size is invalid
439 @end table
440
441 *; PROTO(boolean, bfd_set_section_size,
442 (bfd *, asection *, bfd_size_type val));
443 */
444
445 boolean
446 DEFUN(bfd_set_section_size,(abfd, ptr, val),
447 bfd *abfd AND
448 sec_ptr ptr AND
449 unsigned long val)
450 {
451 /* Once you've started writing to any section you cannot create or change
452 the size of any others. */
453
454 if (abfd->output_has_begun) {
455 bfd_error = invalid_operation;
456 return false;
457 }
458
459 ptr->size = val;
460
461 return true;
462 }
463
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.
468
469 Normally @code{true} is returned, else @code{false}. Possible error
470 returns are:
471 @table @code
472 @item no_contents
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
476 @end table
477 This routine is front end to the back end function @code{_bfd_set_section_contents}.
478
479 *; PROTO(boolean, bfd_set_section_contents,
480 (bfd *abfd,
481 asection *section,
482 PTR data,
483 file_ptr offset,
484 bfd_size_type count));
485
486 */
487
488 boolean
489 DEFUN(bfd_set_section_contents,(abfd, section, location, offset, count),
490 bfd *abfd AND
491 sec_ptr section AND
492 PTR location AND
493 file_ptr offset AND
494 bfd_size_type count)
495 {
496 if (!(bfd_get_section_flags(abfd, section) & SEC_HAS_CONTENTS))
497 {
498 bfd_error = no_contents;
499 return(false);
500 }
501
502 if (BFD_SEND (abfd, _bfd_set_section_contents,
503 (abfd, section, location, offset, count)))
504 {
505 abfd->output_has_begun = true;
506 return true;
507 }
508
509 return false;
510 }
511
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
516 @var{count} bytes.
517
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.
520
521 If no errors occur, @code{true} is returned, else @code{false}.
522 Possible errors are:
523
524 @table @code
525 @item unknown yet
526 @end table
527
528 *; PROTO(boolean, bfd_get_section_contents,
529 (bfd *abfd, asection *section, PTR location,
530 file_ptr offset, bfd_size_type count));
531
532
533 */
534 boolean
535 DEFUN(bfd_get_section_contents,(abfd, section, location, offset, count),
536 bfd *abfd AND
537 sec_ptr section AND
538 PTR location AND
539 file_ptr offset AND
540 bfd_size_type count)
541 {
542 if (section->flags & SEC_CONSTRUCTOR)
543 {
544 memset(location, 0, (unsigned)count);
545 return true;
546 }
547 else
548 {
549 return (BFD_SEND (abfd, _bfd_get_section_contents,
550 (abfd, section, location, offset, count)));
551 }
552 }
553
This page took 0.042159 seconds and 5 git commands to generate.