Context Navigation

bfd.info-2@ 2963

Visit:

Last change on this file since 2963 was 610, checked in by bird, 22 years ago
This commit was generated by cvs2svn to compensate for changes in r609, which included commits to RCS files with non-trunk default branches.
Property cvs2svn:cvs-rev set to `1.1.1.2` Property svn:eol-style set to `native` Property svn:executable set to ``*
File size: 48.0 KB

Line
1	This is bfd.info, produced by makeinfo version 4.3 from bfd.texinfo.
2
3	START-INFO-DIR-ENTRY
4	* Bfd: (bfd). The Binary File Descriptor library.
5	END-INFO-DIR-ENTRY
6
7	This file documents the BFD library.
8
9	Copyright (C) 1991, 2000, 2001, 2003 Free Software Foundation, Inc.
10
11	Permission is granted to copy, distribute and/or modify this document
12	under the terms of the GNU Free Documentation License, Version 1.1
13	or any later version published by the Free Software Foundation;
14	with no Invariant Sections, with no Front-Cover Texts, and with no
15	Back-Cover Texts. A copy of the license is included in the
16	section entitled "GNU Free Documentation License".
17
18
19	File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
20
21	typedef asection
22	----------------
23
24	Here is the section structure:
25
26
27	/* This structure is used for a comdat section, as in PE. A comdat
28	section is associated with a particular symbol. When the linker
29	sees a comdat section, it keeps only one of the sections with a
30	given name and associated with a given symbol. */
31
32	struct bfd_comdat_info
33	{
34	/* The name of the symbol associated with a comdat section. */
35	const char *name;
36
37	/* The local symbol table index of the symbol associated with a
38	comdat section. This is only meaningful to the object file format
39	specific code; it is not an index into the list returned by
40	bfd_canonicalize_symtab. */
41	long symbol;
42	};
43
44	typedef struct sec
45	{
46	/* The name of the section; the name isn't a copy, the pointer is
47	the same as that passed to bfd_make_section. */
48	const char *name;
49
50	/* A unique sequence number. */
51	int id;
52
53	/* Which section in the bfd; 0..n-1 as sections are created in a bfd. */
54	int index;
55
56	/* The next section in the list belonging to the BFD, or NULL. */
57	struct sec *next;
58
59	/* The field flags contains attributes of the section. Some
60	flags are read in from the object file, and some are
61	synthesized from other information. */
62	flagword flags;
63
64	#define SEC_NO_FLAGS 0x000
65
66	/* Tells the OS to allocate space for this section when loading.
67	This is clear for a section containing debug information only. */
68	#define SEC_ALLOC 0x001
69
70	/* Tells the OS to load the section from the file when loading.
71	This is clear for a .bss section. */
72	#define SEC_LOAD 0x002
73
74	/* The section contains data still to be relocated, so there is
75	some relocation information too. */
76	#define SEC_RELOC 0x004
77
78	/* ELF reserves 4 processor specific bits and 8 operating system
79	specific bits in sh_flags; at present we can get away with just
80	one in communicating between the assembler and BFD, but this
81	isn't a good long-term solution. */
82	#define SEC_ARCH_BIT_0 0x008
83
84	/* A signal to the OS that the section contains read only data. */
85	#define SEC_READONLY 0x010
86
87	/* The section contains code only. */
88	#define SEC_CODE 0x020
89
90	/* The section contains data only. */
91	#define SEC_DATA 0x040
92
93	/* The section will reside in ROM. */
94	#define SEC_ROM 0x080
95
96	/* The section contains constructor information. This section
97	type is used by the linker to create lists of constructors and
98	destructors used by `g++'. When a back end sees a symbol
99	which should be used in a constructor list, it creates a new
100	section for the type of name (e.g., `__CTOR_LIST__'), attaches
101	the symbol to it, and builds a relocation. To build the lists
102	of constructors, all the linker has to do is catenate all the
103	sections called `__CTOR_LIST__' and relocate the data
104	contained within - exactly the operations it would peform on
105	standard data. */
106	#define SEC_CONSTRUCTOR 0x100
107
108	/* The section has contents - a data section could be
109	`SEC_ALLOC' \| `SEC_HAS_CONTENTS'; a debug section could be
110	`SEC_HAS_CONTENTS' */
111	#define SEC_HAS_CONTENTS 0x200
112
113	/* An instruction to the linker to not output the section
114	even if it has information which would normally be written. */
115	#define SEC_NEVER_LOAD 0x400
116
117	/* The section is a COFF shared library section. This flag is
118	only for the linker. If this type of section appears in
119	the input file, the linker must copy it to the output file
120	without changing the vma or size. FIXME: Although this
121	was originally intended to be general, it really is COFF
122	specific (and the flag was renamed to indicate this). It
123	might be cleaner to have some more general mechanism to
124	allow the back end to control what the linker does with
125	sections. */
126	#define SEC_COFF_SHARED_LIBRARY 0x800
127
128	/* The section contains thread local data. */
129	#define SEC_THREAD_LOCAL 0x1000
130
131	/* The section has GOT references. This flag is only for the
132	linker, and is currently only used by the elf32-hppa back end.
133	It will be set if global offset table references were detected
134	in this section, which indicate to the linker that the section
135	contains PIC code, and must be handled specially when doing a
136	static link. */
137	#define SEC_HAS_GOT_REF 0x4000
138
139	/* The section contains common symbols (symbols may be defined
140	multiple times, the value of a symbol is the amount of
141	space it requires, and the largest symbol value is the one
142	used). Most targets have exactly one of these (which we
143	translate to bfd_com_section_ptr), but ECOFF has two. */
144	#define SEC_IS_COMMON 0x8000
145
146	/* The section contains only debugging information. For
147	example, this is set for ELF .debug and .stab sections.
148	strip tests this flag to see if a section can be
149	discarded. */
150	#define SEC_DEBUGGING 0x10000
151
152	/* The contents of this section are held in memory pointed to
153	by the contents field. This is checked by bfd_get_section_contents,
154	and the data is retrieved from memory if appropriate. */
155	#define SEC_IN_MEMORY 0x20000
156
157	/* The contents of this section are to be excluded by the
158	linker for executable and shared objects unless those
159	objects are to be further relocated. */
160	#define SEC_EXCLUDE 0x40000
161
162	/* The contents of this section are to be sorted based on the sum of
163	the symbol and addend values specified by the associated relocation
164	entries. Entries without associated relocation entries will be
165	appended to the end of the section in an unspecified order. */
166	#define SEC_SORT_ENTRIES 0x80000
167
168	/* When linking, duplicate sections of the same name should be
169	discarded, rather than being combined into a single section as
170	is usually done. This is similar to how common symbols are
171	handled. See SEC_LINK_DUPLICATES below. */
172	#define SEC_LINK_ONCE 0x100000
173
174	/* If SEC_LINK_ONCE is set, this bitfield describes how the linker
175	should handle duplicate sections. */
176	#define SEC_LINK_DUPLICATES 0x600000
177
178	/* This value for SEC_LINK_DUPLICATES means that duplicate
179	sections with the same name should simply be discarded. */
180	#define SEC_LINK_DUPLICATES_DISCARD 0x0
181
182	/* This value for SEC_LINK_DUPLICATES means that the linker
183	should warn if there are any duplicate sections, although
184	it should still only link one copy. */
185	#define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000
186
187	/* This value for SEC_LINK_DUPLICATES means that the linker
188	should warn if any duplicate sections are a different size. */
189	#define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000
190
191	/* This value for SEC_LINK_DUPLICATES means that the linker
192	should warn if any duplicate sections contain different
193	contents. */
194	#define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000
195
196	/* This section was created by the linker as part of dynamic
197	relocation or other arcane processing. It is skipped when
198	going through the first-pass output, trusting that someone
199	else up the line will take care of it later. */
200	#define SEC_LINKER_CREATED 0x800000
201
202	/* This section should not be subject to garbage collection. */
203	#define SEC_KEEP 0x1000000
204
205	/* This section contains "short" data, and should be placed
206	"near" the GP. */
207	#define SEC_SMALL_DATA 0x2000000
208
209	/* This section contains data which may be shared with other
210	executables or shared objects. */
211	#define SEC_SHARED 0x4000000
212
213	/* When a section with this flag is being linked, then if the size of
214	the input section is less than a page, it should not cross a page
215	boundary. If the size of the input section is one page or more, it
216	should be aligned on a page boundary. */
217	#define SEC_BLOCK 0x8000000
218
219	/* Conditionally link this section; do not link if there are no
220	references found to any symbol in the section. */
221	#define SEC_CLINK 0x10000000
222
223	/* Attempt to merge identical entities in the section.
224	Entity size is given in the entsize field. */
225	#define SEC_MERGE 0x20000000
226
227	/* If given with SEC_MERGE, entities to merge are zero terminated
228	strings where entsize specifies character size instead of fixed
229	size entries. */
230	#define SEC_STRINGS 0x40000000
231
232	/* This section contains data about section groups. */
233	#define SEC_GROUP 0x80000000
234
235	/* End of section flags. */
236
237	/* Some internal packed boolean fields. */
238
239	/* See the vma field. */
240	unsigned int user_set_vma : 1;
241
242	/* Whether relocations have been processed. */
243	unsigned int reloc_done : 1;
244
245	/* A mark flag used by some of the linker backends. */
246	unsigned int linker_mark : 1;
247
248	/* Another mark flag used by some of the linker backends. Set for
249	output sections that have an input section. */
250	unsigned int linker_has_input : 1;
251
252	/* A mark flag used by some linker backends for garbage collection. */
253	unsigned int gc_mark : 1;
254
255	/* The following flags are used by the ELF linker. */
256
257	/* Mark sections which have been allocated to segments. */
258	unsigned int segment_mark : 1;
259
260	/* Type of sec_info information. */
261	unsigned int sec_info_type:3;
262	#define ELF_INFO_TYPE_NONE 0
263	#define ELF_INFO_TYPE_STABS 1
264	#define ELF_INFO_TYPE_MERGE 2
265	#define ELF_INFO_TYPE_EH_FRAME 3
266	#define ELF_INFO_TYPE_JUST_SYMS 4
267
268	/* Nonzero if this section uses RELA relocations, rather than REL. */
269	unsigned int use_rela_p:1;
270
271	/* Bits used by various backends. */
272	unsigned int has_tls_reloc:1;
273
274	/* Nonzero if this section needs the relax finalize pass. */
275	unsigned int need_finalize_relax:1;
276
277	/* Usused bits. */
278	unsigned int flag12:1;
279	unsigned int flag13:1;
280	unsigned int flag14:1;
281	unsigned int flag15:1;
282	unsigned int flag16:4;
283	unsigned int flag20:4;
284	unsigned int flag24:8;
285
286	/* End of internal packed boolean fields. */
287
288	/* The virtual memory address of the section - where it will be
289	at run time. The symbols are relocated against this. The
290	user_set_vma flag is maintained by bfd; if it's not set, the
291	backend can assign addresses (for example, in `a.out', where
292	the default address for `.data' is dependent on the specific
293	target and various flags). */
294	bfd_vma vma;
295
296	/* The load address of the section - where it would be in a
297	rom image; really only used for writing section header
298	information. */
299	bfd_vma lma;
300
301	/* The size of the section in octets, as it will be output.
302	Contains a value even if the section has no contents (e.g., the
303	size of `.bss'). This will be filled in after relocation. */
304	bfd_size_type _cooked_size;
305
306	/* The original size on disk of the section, in octets. Normally this
307	value is the same as the size, but if some relaxing has
308	been done, then this value will be bigger. */
309	bfd_size_type _raw_size;
310
311	/* If this section is going to be output, then this value is the
312	offset in bytes into the output section of the first byte in the
313	input section (byte ==> smallest addressable unit on the
314	target). In most cases, if this was going to start at the
315	100th octet (8-bit quantity) in the output section, this value
316	would be 100. However, if the target byte size is 16 bits
317	(bfd_octets_per_byte is "2"), this value would be 50. */
318	bfd_vma output_offset;
319
320	/* The output section through which to map on output. */
321	struct sec *output_section;
322
323	/* The alignment requirement of the section, as an exponent of 2 -
324	e.g., 3 aligns to 2^3 (or 8). */
325	unsigned int alignment_power;
326
327	/* If an input section, a pointer to a vector of relocation
328	records for the data in this section. */
329	struct reloc_cache_entry *relocation;
330
331	/* If an output section, a pointer to a vector of pointers to
332	relocation records for the data in this section. */
333	struct reloc_cache_entry **orelocation;
334
335	/* The number of relocation records in one of the above. */
336	unsigned reloc_count;
337
338	/* Information below is back end specific - and not always used
339	or updated. */
340
341	/* File position of section data. */
342	file_ptr filepos;
343
344	/* File position of relocation info. */
345	file_ptr rel_filepos;
346
347	/* File position of line data. */
348	file_ptr line_filepos;
349
350	/* Pointer to data for applications. */
351	PTR userdata;
352
353	/* If the SEC_IN_MEMORY flag is set, this points to the actual
354	contents. */
355	unsigned char *contents;
356
357	/* Attached line number information. */
358	alent *lineno;
359
360	/* Number of line number records. */
361	unsigned int lineno_count;
362
363	/* Entity size for merging purposes. */
364	unsigned int entsize;
365
366	/* Optional information about a COMDAT entry; NULL if not COMDAT. */
367	struct bfd_comdat_info *comdat;
368
369	/* When a section is being output, this value changes as more
370	linenumbers are written out. */
371	file_ptr moving_line_filepos;
372
373	/* What the section number is in the target world. */
374	int target_index;
375
376	PTR used_by_bfd;
377
378	/* If this is a constructor section then here is a list of the
379	relocations created to relocate items within it. */
380	struct relent_chain *constructor_chain;
381
382	/* The BFD which owns the section. */
383	bfd *owner;
384
385	/* A symbol which points at this section only. */
386	struct symbol_cache_entry *symbol;
387	struct symbol_cache_entry **symbol_ptr_ptr;
388
389	struct bfd_link_order *link_order_head;
390	struct bfd_link_order *link_order_tail;
391	} asection;
392
393	/* These sections are global, and are managed by BFD. The application
394	and target back end are not permitted to change the values in
395	these sections. New code should use the section_ptr macros rather
396	than referring directly to the const sections. The const sections
397	may eventually vanish. */
398	#define BFD_ABS_SECTION_NAME "ABS"
399	#define BFD_UND_SECTION_NAME "UND"
400	#define BFD_COM_SECTION_NAME "COM"
401	#define BFD_IND_SECTION_NAME "IND"
402
403	/* The absolute section. */
404	extern const asection bfd_abs_section;
405	#define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
406	#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
407	/* Pointer to the undefined section. */
408	extern const asection bfd_und_section;
409	#define bfd_und_section_ptr ((asection *) &bfd_und_section)
410	#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
411	/* Pointer to the common section. */
412	extern const asection bfd_com_section;
413	#define bfd_com_section_ptr ((asection *) &bfd_com_section)
414	/* Pointer to the indirect section. */
415	extern const asection bfd_ind_section;
416	#define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
417	#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)
418
419	#define bfd_is_const_section(SEC) \
420	( ((SEC) == bfd_abs_section_ptr) \
421	\|\| ((SEC) == bfd_und_section_ptr) \
422	\|\| ((SEC) == bfd_com_section_ptr) \
423	\|\| ((SEC) == bfd_ind_section_ptr))
424
425	extern const struct symbol_cache_entry * const bfd_abs_symbol;
426	extern const struct symbol_cache_entry * const bfd_com_symbol;
427	extern const struct symbol_cache_entry * const bfd_und_symbol;
428	extern const struct symbol_cache_entry * const bfd_ind_symbol;
429	#define bfd_get_section_size_before_reloc(section) \
430	((section)->reloc_done ? (abort (), (bfd_size_type) 1) \
431	: (section)->_raw_size)
432	#define bfd_get_section_size_after_reloc(section) \
433	((section)->reloc_done ? (section)->_cooked_size \
434	: (abort (), (bfd_size_type) 1))
435
436	/* Macros to handle insertion and deletion of a bfd's sections. These
437	only handle the list pointers, ie. do not adjust section_count,
438	target_index etc. */
439	#define bfd_section_list_remove(ABFD, PS) \
440	do \
441	{ \
442	asection **_ps = PS; \
443	asection _s = _ps; \
444	*_ps = _s->next; \
445	if (_s->next == NULL) \
446	(ABFD)->section_tail = _ps; \
447	} \
448	while (0)
449	#define bfd_section_list_insert(ABFD, PS, S) \
450	do \
451	{ \
452	asection **_ps = PS; \
453	asection *_s = S; \
454	_s->next = *_ps; \
455	*_ps = _s; \
456	if (_s->next == NULL) \
457	(ABFD)->section_tail = &_s->next; \
458	} \
459	while (0)
460
461
462	File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections
463
464	Section prototypes
465	------------------
466
467	These are the functions exported by the section handling part of BFD.
468
469	`bfd_section_list_clear'
470	........................
471
472	Synopsis
473	void bfd_section_list_clear (bfd *);
474	Description
475	Clears the section list, and also resets the section count and hash
476	table entries.
477
478	`bfd_get_section_by_name'
479	.........................
480
481	Synopsis
482	asection bfd_get_section_by_name(bfd abfd, const char *name);
483	Description
484	Run through ABFD and return the one of the `asection's whose name
485	matches NAME, otherwise `NULL'. *Note Sections::, for more information.
486
487	This should only be used in special cases; the normal way to process
488	all sections of a given name is to use `bfd_map_over_sections' and
489	`strcmp' on the name (or better yet, base it on the section flags or
490	something else) for each section.
491
492	`bfd_get_unique_section_name'
493	.............................
494
495	Synopsis
496	char bfd_get_unique_section_name(bfd abfd,
497	const char *templat,
498	int *count);
499	Description
500	Invent a section name that is unique in ABFD by tacking a dot and a
501	digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it
502	specifies the first number tried as a suffix to generate a unique name.
503	The value pointed to by COUNT will be incremented in this case.
504
505	`bfd_make_section_old_way'
506	..........................
507
508	Synopsis
509	asection bfd_make_section_old_way(bfd abfd, const char *name);
510	Description
511	Create a new empty section called NAME and attach it to the end of the
512	chain of sections for the BFD ABFD. An attempt to create a section with
513	a name which is already in use returns its pointer without changing the
514	section chain.
515
516	It has the funny name since this is the way it used to be before it
517	was rewritten....
518
519	Possible errors are:
520	* `bfd_error_invalid_operation' - If output has already started for
521	this BFD.
522
523	* `bfd_error_no_memory' - If memory allocation fails.
524
525	`bfd_make_section_anyway'
526	.........................
527
528	Synopsis
529	asection bfd_make_section_anyway(bfd abfd, const char *name);
530	Description
531	Create a new empty section called NAME and attach it to the end of the
532	chain of sections for ABFD. Create a new section even if there is
533	already a section with that name.
534
535	Return `NULL' and set `bfd_error' on error; possible errors are:
536	* `bfd_error_invalid_operation' - If output has already started for
537	ABFD.
538
539	* `bfd_error_no_memory' - If memory allocation fails.
540
541	`bfd_make_section'
542	..................
543
544	Synopsis
545	asection bfd_make_section(bfd , const char *name);
546	Description
547	Like `bfd_make_section_anyway', but return `NULL' (without calling
548	bfd_set_error ()) without changing the section chain if there is
549	already a section named NAME. If there is an error, return `NULL' and
550	set `bfd_error'.
551
552	`bfd_set_section_flags'
553	.......................
554
555	Synopsis
556	bfd_boolean bfd_set_section_flags (bfd abfd, asection sec, flagword flags);
557	Description
558	Set the attributes of the section SEC in the BFD ABFD to the value
559	FLAGS. Return `TRUE' on success, `FALSE' on error. Possible error
560	returns are:
561
562	* `bfd_error_invalid_operation' - The section cannot have one or
563	more of the attributes requested. For example, a .bss section in
564	`a.out' may not have the `SEC_HAS_CONTENTS' field set.
565
566	`bfd_map_over_sections'
567	.......................
568
569	Synopsis
570	void bfd_map_over_sections(bfd *abfd,
571	void (func) (bfd abfd,
572	asection *sect,
573	PTR obj),
574	PTR obj);
575	Description
576	Call the provided function FUNC for each section attached to the BFD
577	ABFD, passing OBJ as an argument. The function will be called as if by
578
579	func(abfd, the_section, obj);
580
581	This is the prefered method for iterating over sections; an
582	alternative would be to use a loop:
583
584	section *p;
585	for (p = abfd->sections; p != NULL; p = p->next)
586	func(abfd, p, ...)
587
588	`bfd_set_section_size'
589	......................
590
591	Synopsis
592	bfd_boolean bfd_set_section_size (bfd abfd, asection sec, bfd_size_type val);
593	Description
594	Set SEC to the size VAL. If the operation is ok, then `TRUE' is
595	returned, else `FALSE'.
596
597	Possible error returns:
598	* `bfd_error_invalid_operation' - Writing has started to the BFD, so
599	setting the size is invalid.
600
601	`bfd_set_section_contents'
602	..........................
603
604	Synopsis
605	bfd_boolean bfd_set_section_contents (bfd abfd, asection section,
606	PTR data, file_ptr offset,
607	bfd_size_type count);
608	Description
609	Sets the contents of the section SECTION in BFD ABFD to the data
610	starting in memory at DATA. The data is written to the output section
611	starting at offset OFFSET for COUNT octets.
612
613	Normally `TRUE' is returned, else `FALSE'. Possible error returns
614	are:
615	* `bfd_error_no_contents' - The output section does not have the
616	`SEC_HAS_CONTENTS' attribute, so nothing can be written to it.
617
618	* and some more too
619	This routine is front end to the back end function
620	`_bfd_set_section_contents'.
621
622	`bfd_get_section_contents'
623	..........................
624
625	Synopsis
626	bfd_boolean bfd_get_section_contents (bfd abfd, asection section,
627	PTR location, file_ptr offset,
628	bfd_size_type count);
629	Description
630	Read data from SECTION in BFD ABFD into memory starting at LOCATION.
631	The data is read at an offset of OFFSET from the start of the input
632	section, and is read for COUNT bytes.
633
634	If the contents of a constructor with the `SEC_CONSTRUCTOR' flag set
635	are requested or if the section does not have the `SEC_HAS_CONTENTS'
636	flag set, then the LOCATION is filled with zeroes. If no errors occur,
637	`TRUE' is returned, else `FALSE'.
638
639	`bfd_copy_private_section_data'
640	...............................
641
642	Synopsis
643	bfd_boolean bfd_copy_private_section_data (bfd ibfd, asection isec,
644	bfd obfd, asection osec);
645	Description
646	Copy private section information from ISEC in the BFD IBFD to the
647	section OSEC in the BFD OBFD. Return `TRUE' on success, `FALSE' on
648	error. Possible error returns are:
649
650	* `bfd_error_no_memory' - Not enough memory exists to create private
651	data for OSEC.
652
653	#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
654	BFD_SEND (obfd, _bfd_copy_private_section_data, \
655	(ibfd, isection, obfd, osection))
656
657	`_bfd_strip_section_from_output'
658	................................
659
660	Synopsis
661	void _bfd_strip_section_from_output
662	(struct bfd_link_info info, asection section);
663	Description
664	Remove SECTION from the output. If the output section becomes empty,
665	remove it from the output bfd.
666
667	This function won't actually do anything except twiddle flags if
668	called too late in the linking process, when it's not safe to remove
669	sections.
670
671	`bfd_generic_discard_group'
672	...........................
673
674	Synopsis
675	bfd_boolean bfd_generic_discard_group (bfd abfd, asection group);
676	Description
677	Remove all members of GROUP from the output.
678
679
680	File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end
681
682	Symbols
683	=======
684
685	BFD tries to maintain as much symbol information as it can when it
686	moves information from file to file. BFD passes information to
687	applications though the `asymbol' structure. When the application
688	requests the symbol table, BFD reads the table in the native form and
689	translates parts of it into the internal format. To maintain more than
690	the information passed to applications, some targets keep some
691	information "behind the scenes" in a structure only the particular back
692	end knows about. For example, the coff back end keeps the original
693	symbol table structure as well as the canonical structure when a BFD is
694	read in. On output, the coff back end can reconstruct the output symbol
695	table so that no information is lost, even information unique to coff
696	which BFD doesn't know or understand. If a coff symbol table were read,
697	but were written through an a.out back end, all the coff specific
698	information would be lost. The symbol table of a BFD is not necessarily
699	read in until a canonicalize request is made. Then the BFD back end
700	fills in a table provided by the application with pointers to the
701	canonical information. To output symbols, the application provides BFD
702	with a table of pointers to pointers to `asymbol's. This allows
703	applications like the linker to output a symbol as it was read, since
704	the "behind the scenes" information will be still available.
705
706	* Menu:
707
708	* Reading Symbols::
709	* Writing Symbols::
710	* Mini Symbols::
711	* typedef asymbol::
712	* symbol handling functions::
713
714
715	File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
716
717	Reading symbols
718	---------------
719
720	There are two stages to reading a symbol table from a BFD:
721	allocating storage, and the actual reading process. This is an excerpt
722	from an application which reads the symbol table:
723
724	long storage_needed;
725	asymbol **symbol_table;
726	long number_of_symbols;
727	long i;
728
729	storage_needed = bfd_get_symtab_upper_bound (abfd);
730
731	if (storage_needed < 0)
732	FAIL
733
734	if (storage_needed == 0)
735	return;
736
737	symbol_table = (asymbol **) xmalloc (storage_needed);
738	...
739	number_of_symbols =
740	bfd_canonicalize_symtab (abfd, symbol_table);
741
742	if (number_of_symbols < 0)
743	FAIL
744
745	for (i = 0; i < number_of_symbols; i++)
746	process_symbol (symbol_table[i]);
747
748	All storage for the symbols themselves is in an objalloc connected
749	to the BFD; it is freed when the BFD is closed.
750
751
752	File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols
753
754	Writing symbols
755	---------------
756
757	Writing of a symbol table is automatic when a BFD open for writing
758	is closed. The application attaches a vector of pointers to pointers to
759	symbols to the BFD being written, and fills in the symbol count. The
760	close and cleanup code reads through the table provided and performs
761	all the necessary operations. The BFD output code must always be
762	provided with an "owned" symbol: one which has come from another BFD,
763	or one which has been created using `bfd_make_empty_symbol'. Here is an
764	example showing the creation of a symbol table with only one element:
765
766	#include "bfd.h"
767	int main (void)
768	{
769	bfd *abfd;
770	asymbol *ptrs[2];
771	asymbol *new;
772
773	abfd = bfd_openw ("foo","a.out-sunos-big");
774	bfd_set_format (abfd, bfd_object);
775	new = bfd_make_empty_symbol (abfd);
776	new->name = "dummy_symbol";
777	new->section = bfd_make_section_old_way (abfd, ".text");
778	new->flags = BSF_GLOBAL;
779	new->value = 0x12345;
780
781	ptrs[0] = new;
782	ptrs[1] = (asymbol *)0;
783
784	bfd_set_symtab (abfd, ptrs, 1);
785	bfd_close (abfd);
786	return 0;
787	}
788
789	./makesym
790	nm foo
791	00012345 A dummy_symbol
792
793	Many formats cannot represent arbitary symbol information; for
794	instance, the `a.out' object format does not allow an arbitary number
795	of sections. A symbol pointing to a section which is not one of
796	`.text', `.data' or `.bss' cannot be described.
797
798
799	File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols
800
801	Mini Symbols
802	------------
803
804	Mini symbols provide read-only access to the symbol table. They use
805	less memory space, but require more time to access. They can be useful
806	for tools like nm or objdump, which may have to handle symbol tables of
807	extremely large executables.
808
809	The `bfd_read_minisymbols' function will read the symbols into
810	memory in an internal form. It will return a `void *' pointer to a
811	block of memory, a symbol count, and the size of each symbol. The
812	pointer is allocated using `malloc', and should be freed by the caller
813	when it is no longer needed.
814
815	The function `bfd_minisymbol_to_symbol' will take a pointer to a
816	minisymbol, and a pointer to a structure returned by
817	`bfd_make_empty_symbol', and return a `asymbol' structure. The return
818	value may or may not be the same as the value from
819	`bfd_make_empty_symbol' which was passed in.
820
821
822	File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols
823
824	typedef asymbol
825	---------------
826
827	An `asymbol' has the form:
828
829
830	typedef struct symbol_cache_entry
831	{
832	/* A pointer to the BFD which owns the symbol. This information
833	is necessary so that a back end can work out what additional
834	information (invisible to the application writer) is carried
835	with the symbol.
836
837	This field is almost redundant, since you can use section->owner
838	instead, except that some symbols point to the global sections
839	bfd_{abs,com,und}_section. This could be fixed by making
840	these globals be per-bfd (or per-target-flavor). FIXME. */
841	struct bfd the_bfd; / Use bfd_asymbol_bfd(sym) to access this field. */
842
843	/* The text of the symbol. The name is left alone, and not copied; the
844	application may not alter it. */
845	const char *name;
846
847	/* The value of the symbol. This really should be a union of a
848	numeric value with a pointer, since some flags indicate that
849	a pointer to another symbol is stored here. */
850	symvalue value;
851
852	/* Attributes of a symbol. */
853	#define BSF_NO_FLAGS 0x00
854
855	/* The symbol has local scope; `static' in `C'. The value
856	is the offset into the section of the data. */
857	#define BSF_LOCAL 0x01
858
859	/* The symbol has global scope; initialized data in `C'. The
860	value is the offset into the section of the data. */
861	#define BSF_GLOBAL 0x02
862
863	/* The symbol has global scope and is exported. The value is
864	the offset into the section of the data. */
865	#define BSF_EXPORT BSF_GLOBAL /* No real difference. */
866
867	/* A normal C symbol would be one of:
868	`BSF_LOCAL', `BSF_FORT_COMM', `BSF_UNDEFINED' or
869	`BSF_GLOBAL'. */
870
871	/* The symbol is a debugging record. The value has an arbitary
872	meaning, unless BSF_DEBUGGING_RELOC is also set. */
873	#define BSF_DEBUGGING 0x08
874
875	/* The symbol denotes a function entry point. Used in ELF,
876	perhaps others someday. */
877	#define BSF_FUNCTION 0x10
878
879	/* Used by the linker. */
880	#define BSF_KEEP 0x20
881	#define BSF_KEEP_G 0x40
882
883	/* A weak global symbol, overridable without warnings by
884	a regular global symbol of the same name. */
885	#define BSF_WEAK 0x80
886
887	/* This symbol was created to point to a section, e.g. ELF's
888	STT_SECTION symbols. */
889	#define BSF_SECTION_SYM 0x100
890
891	/* The symbol used to be a common symbol, but now it is
892	allocated. */
893	#define BSF_OLD_COMMON 0x200
894
895	/* The default value for common data. */
896	#define BFD_FORT_COMM_DEFAULT_VALUE 0
897
898	/* In some files the type of a symbol sometimes alters its
899	location in an output file - ie in coff a `ISFCN' symbol
900	which is also `C_EXT' symbol appears where it was
901	declared and not at the end of a section. This bit is set
902	by the target BFD part to convey this information. */
903	#define BSF_NOT_AT_END 0x400
904
905	/* Signal that the symbol is the label of constructor section. */
906	#define BSF_CONSTRUCTOR 0x800
907
908	/* Signal that the symbol is a warning symbol. The name is a
909	warning. The name of the next symbol is the one to warn about;
910	if a reference is made to a symbol with the same name as the next
911	symbol, a warning is issued by the linker. */
912	#define BSF_WARNING 0x1000
913
914	/* Signal that the symbol is indirect. This symbol is an indirect
915	pointer to the symbol with the same name as the next symbol. */
916	#define BSF_INDIRECT 0x2000
917
918	/* BSF_FILE marks symbols that contain a file name. This is used
919	for ELF STT_FILE symbols. */
920	#define BSF_FILE 0x4000
921
922	/* Symbol is from dynamic linking information. */
923	#define BSF_DYNAMIC 0x8000
924
925	/* The symbol denotes a data object. Used in ELF, and perhaps
926	others someday. */
927	#define BSF_OBJECT 0x10000
928
929	/* This symbol is a debugging symbol. The value is the offset
930	into the section of the data. BSF_DEBUGGING should be set
931	as well. */
932	#define BSF_DEBUGGING_RELOC 0x20000
933
934	/* This symbol is thread local. Used in ELF. */
935	#define BSF_THREAD_LOCAL 0x40000
936
937	flagword flags;
938
939	/* A pointer to the section to which this symbol is
940	relative. This will always be non NULL, there are special
941	sections for undefined and absolute symbols. */
942	struct sec *section;
943
944	/* Back end special data. */
945	union
946	{
947	PTR p;
948	bfd_vma i;
949	}
950	udata;
951	}
952	asymbol;
953
954
955	File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols
956
957	Symbol handling functions
958	-------------------------
959
960	`bfd_get_symtab_upper_bound'
961	............................
962
963	Description
964	Return the number of bytes required to store a vector of pointers to
965	`asymbols' for all the symbols in the BFD ABFD, including a terminal
966	NULL pointer. If there are no symbols in the BFD, then return 0. If an
967	error occurs, return -1.
968	#define bfd_get_symtab_upper_bound(abfd) \
969	BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
970
971	`bfd_is_local_label'
972	....................
973
974	Synopsis
975	bfd_boolean bfd_is_local_label (bfd abfd, asymbol sym);
976	Description
977	Return TRUE if the given symbol SYM in the BFD ABFD is a compiler
978	generated local label, else return FALSE.
979
980	`bfd_is_local_label_name'
981	.........................
982
983	Synopsis
984	bfd_boolean bfd_is_local_label_name (bfd abfd, const char name);
985	Description
986	Return TRUE if a symbol with the name NAME in the BFD ABFD is a
987	compiler generated local label, else return FALSE. This just checks
988	whether the name has the form of a local label.
989	#define bfd_is_local_label_name(abfd, name) \
990	BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
991
992	`bfd_canonicalize_symtab'
993	.........................
994
995	Description
996	Read the symbols from the BFD ABFD, and fills in the vector LOCATION
997	with pointers to the symbols and a trailing NULL. Return the actual
998	number of symbol pointers, not including the NULL.
999	#define bfd_canonicalize_symtab(abfd, location) \
1000	BFD_SEND (abfd, _bfd_canonicalize_symtab,\
1001	(abfd, location))
1002
1003	`bfd_set_symtab'
1004	................
1005
1006	Synopsis
1007	bfd_boolean bfd_set_symtab (bfd abfd, asymbol *location, unsigned int count);
1008	Description
1009	Arrange that when the output BFD ABFD is closed, the table LOCATION of
1010	COUNT pointers to symbols will be written.
1011
1012	`bfd_print_symbol_vandf'
1013	........................
1014
1015	Synopsis
1016	void bfd_print_symbol_vandf (bfd abfd, PTR file, asymbol symbol);
1017	Description
1018	Print the value and flags of the SYMBOL supplied to the stream FILE.
1019
1020	`bfd_make_empty_symbol'
1021	.......................
1022
1023	Description
1024	Create a new `asymbol' structure for the BFD ABFD and return a pointer
1025	to it.
1026
1027	This routine is necessary because each back end has private
1028	information surrounding the `asymbol'. Building your own `asymbol' and
1029	pointing to it will not create the private information, and will cause
1030	problems later on.
1031	#define bfd_make_empty_symbol(abfd) \
1032	BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
1033
1034	`_bfd_generic_make_empty_symbol'
1035	................................
1036
1037	Synopsis
1038	asymbol * _bfd_generic_make_empty_symbol (bfd *);
1039	Description
1040	Create a new `asymbol' structure for the BFD ABFD and return a pointer
1041	to it. Used by core file routines, binary back-end and anywhere else
1042	where no private info is needed.
1043
1044	`bfd_make_debug_symbol'
1045	.......................
1046
1047	Description
1048	Create a new `asymbol' structure for the BFD ABFD, to be used as a
1049	debugging symbol. Further details of its use have yet to be worked out.
1050	#define bfd_make_debug_symbol(abfd,ptr,size) \
1051	BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
1052
1053	`bfd_decode_symclass'
1054	.....................
1055
1056	Description
1057	Return a character corresponding to the symbol class of SYMBOL, or '?'
1058	for an unknown class.
1059
1060	Synopsis
1061	int bfd_decode_symclass (asymbol *symbol);
1062
1063	`bfd_is_undefined_symclass'
1064	...........................
1065
1066	Description
1067	Returns non-zero if the class symbol returned by bfd_decode_symclass
1068	represents an undefined symbol. Returns zero otherwise.
1069
1070	Synopsis
1071	bfd_boolean bfd_is_undefined_symclass (int symclass);
1072
1073	`bfd_symbol_info'
1074	.................
1075
1076	Description
1077	Fill in the basic info about symbol that nm needs. Additional info may
1078	be added by the back-ends after calling this function.
1079
1080	Synopsis
1081	void bfd_symbol_info (asymbol symbol, symbol_info ret);
1082
1083	`bfd_copy_private_symbol_data'
1084	..............................
1085
1086	Synopsis
1087	bfd_boolean bfd_copy_private_symbol_data (bfd ibfd, asymbol isym, bfd obfd, asymbol osym);
1088	Description
1089	Copy private symbol information from ISYM in the BFD IBFD to the symbol
1090	OSYM in the BFD OBFD. Return `TRUE' on success, `FALSE' on error.
1091	Possible error returns are:
1092
1093	* `bfd_error_no_memory' - Not enough memory exists to create private
1094	data for OSEC.
1095
1096	#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
1097	BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
1098	(ibfd, isymbol, obfd, osymbol))
1099
1100
1101	File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end
1102
1103	Archives
1104	========
1105
1106	Description
1107	An archive (or library) is just another BFD. It has a symbol table,
1108	although there's not much a user program will do with it.
1109
1110	The big difference between an archive BFD and an ordinary BFD is
1111	that the archive doesn't have sections. Instead it has a chain of BFDs
1112	that are considered its contents. These BFDs can be manipulated like
1113	any other. The BFDs contained in an archive opened for reading will
1114	all be opened for reading. You may put either input or output BFDs
1115	into an archive opened for output; they will be handled correctly when
1116	the archive is closed.
1117
1118	Use `bfd_openr_next_archived_file' to step through the contents of
1119	an archive opened for input. You don't have to read the entire archive
1120	if you don't want to! Read it until you find what you want.
1121
1122	Archive contents of output BFDs are chained through the `next'
1123	pointer in a BFD. The first one is findable through the `archive_head'
1124	slot of the archive. Set it with `bfd_set_archive_head' (q.v.). A
1125	given BFD may be in only one open output archive at a time.
1126
1127	As expected, the BFD archive code is more general than the archive
1128	code of any given environment. BFD archives may contain files of
1129	different formats (e.g., a.out and coff) and even different
1130	architectures. You may even place archives recursively into archives!
1131
1132	This can cause unexpected confusion, since some archive formats are
1133	more expressive than others. For instance, Intel COFF archives can
1134	preserve long filenames; SunOS a.out archives cannot. If you move a
1135	file from the first to the second format and back again, the filename
1136	may be truncated. Likewise, different a.out environments have different
1137	conventions as to how they truncate filenames, whether they preserve
1138	directory names in filenames, etc. When interoperating with native
1139	tools, be sure your files are homogeneous.
1140
1141	Beware: most of these formats do not react well to the presence of
1142	spaces in filenames. We do the best we can, but can't always handle
1143	this case due to restrictions in the format of archives. Many Unix
1144	utilities are braindead in regards to spaces and such in filenames
1145	anyway, so this shouldn't be much of a restriction.
1146
1147	Archives are supported in BFD in `archive.c'.
1148
1149	`bfd_get_next_mapent'
1150	.....................
1151
1152	Synopsis
1153	symindex bfd_get_next_mapent(bfd abfd, symindex previous, carsym *sym);
1154	Description
1155	Step through archive ABFD's symbol table (if it has one). Successively
1156	update SYM with the next symbol's information, returning that symbol's
1157	(internal) index into the symbol table.
1158
1159	Supply `BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first
1160	one; returns `BFD_NO_MORE_SYMBOLS' when you've already got the last one.
1161
1162	A `carsym' is a canonical archive symbol. The only user-visible
1163	element is its name, a null-terminated string.
1164
1165	`bfd_set_archive_head'
1166	......................
1167
1168	Synopsis
1169	bfd_boolean bfd_set_archive_head(bfd output, bfd new_head);
1170	Description
1171	Set the head of the chain of BFDs contained in the archive OUTPUT to
1172	NEW_HEAD.
1173
1174	`bfd_openr_next_archived_file'
1175	..............................
1176
1177	Synopsis
1178	bfd bfd_openr_next_archived_file(bfd archive, bfd *previous);
1179	Description
1180	Provided a BFD, ARCHIVE, containing an archive and NULL, open an input
1181	BFD on the first contained element and returns that. Subsequent calls
1182	should pass the archive and the previous return value to return a
1183	created BFD to the next contained element. NULL is returned when there
1184	are no more.
1185
1186
1187	File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end
1188
1189	File formats
1190	============
1191
1192	A format is a BFD concept of high level file contents type. The
1193	formats supported by BFD are:
1194
1195	* `bfd_object'
1196	The BFD may contain data, symbols, relocations and debug info.
1197
1198	* `bfd_archive'
1199	The BFD contains other BFDs and an optional index.
1200
1201	* `bfd_core'
1202	The BFD contains the result of an executable core dump.
1203
1204	`bfd_check_format'
1205	..................
1206
1207	Synopsis
1208	bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
1209	Description
1210	Verify if the file attached to the BFD ABFD is compatible with the
1211	format FORMAT (i.e., one of `bfd_object', `bfd_archive' or `bfd_core').
1212
1213	If the BFD has been set to a specific target before the call, only
1214	the named target and format combination is checked. If the target has
1215	not been set, or has been set to `default', then all the known target
1216	backends is interrogated to determine a match. If the default target
1217	matches, it is used. If not, exactly one target must recognize the
1218	file, or an error results.
1219
1220	The function returns `TRUE' on success, otherwise `FALSE' with one
1221	of the following error codes:
1222
1223	* `bfd_error_invalid_operation' - if `format' is not one of
1224	`bfd_object', `bfd_archive' or `bfd_core'.
1225
1226	* `bfd_error_system_call' - if an error occured during a read - even
1227	some file mismatches can cause bfd_error_system_calls.
1228
1229	* `file_not_recognised' - none of the backends recognised the file
1230	format.
1231
1232	* `bfd_error_file_ambiguously_recognized' - more than one backend
1233	recognised the file format.
1234
1235	`bfd_check_format_matches'
1236	..........................
1237
1238	Synopsis
1239	bfd_boolean bfd_check_format_matches (bfd *abfd, bfd_format format,
1240	char ***matching);
1241	Description
1242	Like `bfd_check_format', except when it returns FALSE with `bfd_errno'
1243	set to `bfd_error_file_ambiguously_recognized'. In that case, if
1244	MATCHING is not NULL, it will be filled in with a NULL-terminated list
1245	of the names of the formats that matched, allocated with `malloc'.
1246	Then the user may choose a format and try again.
1247
1248	When done with the list that MATCHING points to, the caller should
1249	free it.
1250
1251	`bfd_set_format'
1252	................
1253
1254	Synopsis
1255	bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
1256	Description
1257	This function sets the file format of the BFD ABFD to the format
1258	FORMAT. If the target set in the BFD does not support the format
1259	requested, the format is invalid, or the BFD is not open for writing,
1260	then an error occurs.
1261
1262	`bfd_format_string'
1263	...................
1264
1265	Synopsis
1266	const char *bfd_format_string (bfd_format format);
1267	Description
1268	Return a pointer to a const string `invalid', `object', `archive',
1269	`core', or `unknown', depending upon the value of FORMAT.
1270
1271
1272	File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end
1273
1274	Relocations
1275	===========
1276
1277	BFD maintains relocations in much the same way it maintains symbols:
1278	they are left alone until required, then read in en-masse and
1279	translated into an internal form. A common routine
1280	`bfd_perform_relocation' acts upon the canonical form to do the fixup.
1281
1282	Relocations are maintained on a per section basis, while symbols are
1283	maintained on a per BFD basis.
1284
1285	All that a back end has to do to fit the BFD interface is to create
1286	a `struct reloc_cache_entry' for each relocation in a particular
1287	section, and fill in the right bits of the structures.
1288
1289	* Menu:
1290
1291	* typedef arelent::
1292	* howto manager::
1293

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format