EditPageHistoryDiffInfoLikePages

Annotated edit history of ld(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	LD
		2	!!!LD
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	OPTIONS
		7	ENVIRONMENT
		8	SEE ALSO
		9	COPYRIGHT
		10	----
		11	!!NAME
		12
		13
		14	ld - Using LD , the GNU linker
		15	!!SYNOPSIS
		16
		17
		18	ld [[__options__] ''objfile'' ...
		19	!!DESCRIPTION
		20
		21
		22	__ld__ combines a number of object and archive files,
		23	relocates their data and ties up symbol references. Usually
		24	the last step in compiling a program is to run
		25	__ld__.
		26
		27
		28	__ld__ accepts Linker Command Language files written in a
		29	superset of AT 's Link Editor Command
		30	Language syntax, to provide explicit and total control over
		31	the linking process.
		32
		33
		34	This man page does not describe the command language; see
		35	the __ld__ entry in info, or the manual ld: the
		36	GNU linker, for full details on the command
		37	language and on other aspects of the GNU
		38	linker.
		39
		40
		41	This version of __ld__ uses the general purpose
		42	BFD libraries to operate on object files.
		43	This allows __ld__ to read, combine, and write object
		44	files in many different formats---for example,
		45	COFF or a.out. Different formats may
		46	be linked together to produce any available kind of object
		47	file.
		48
		49
		50	Aside from its flexibility, the GNU linker is
		51	more helpful than other linkers in providing diagnostic
		52	information. Many linkers abandon execution immediately upon
		53	encountering an error; whenever possible, __ld__
		54	continues executing, allowing you to identify other errors
		55	(or, in some cases, to get an output file in spite of the
		56	error).
		57
		58
		59	The GNU linker __ld__ is meant to cover a
		60	broad range of situations, and to be as compatible as
		61	possible with other linkers. As a result, you have many
		62	choices to control its behavior.
		63	!!OPTIONS
		64
		65
		66	The linker supports a plethora of command-line options, but
		67	in actual practice few of them are used in any particular
		68	context. For instance, a frequent use of __ld__ is to
		69	link standard Unix object files on a standard, supported
		70	Unix system. On such a system, to link a file
		71	hello.o:
		72
		73
		74	ld -o I
		75	This tells __ld__ to produce a file called ''output'' as the result of linking the file /lib/crt0.o with hello.o and the library libc.a, which will come from the standard search directories. (See the discussion of the __-l__ option below.)
		76
		77
		78	Some of the command-line options to __ld__ may be
		79	specified at any point in the command line. However, options
		80	which refer to files, such as __-l__ or __-T__, cause
		81	the file to be read at the point at which the option appears
		82	in the command line, relative to the object files and other
		83	file options. Repeating non-file options with a different
		84	argument will either have no further effect, or override
		85	prior occurrences (those further to the left on the command
		86	line) of that option. Options which may be meaningfully
		87	specified more than once are noted in the descriptions
		88	below.
		89
		90
		91	Non-option arguments are object files or archives which are
		92	to be linked together. They may follow, precede, or be mixed
		93	in with command-line options, except that an object file
		94	argument may not be placed between an option and its
		95	argument.
		96
		97
		98	Usually the linker is invoked with at least one object file,
		99	but you can specify other forms of binary input files using
		100	__-l__, __-R__, and the script command language. If
		101	''no'' binary input files at all are specified, the
		102	linker does not produce any output, and issues the message
		103	__No input files__.
		104
		105
		106	If the linker can not recognize the format of an object
		107	file, it will assume that it is a linker script. A script
		108	specified in this way augments the main linker script used
		109	for the link (either the default linker script or the one
		110	specified by using __-T__). This feature permits the
		111	linker to link against a file which appears to be an object
		112	or an archive, but actually merely defines some symbol
		113	values, or uses INPUT or GROUP to load
		114	other objects. Note that specifying a script in this way
		115	merely augments the main linker script; use the __-T__
		116	option to replace the default linker script
		117	entirely.
		118
		119
		120	For options whose names are a single letter, option
		121	arguments must either follow the option letter without
		122	intervening whitespace, or be given as separate arguments
		123	immediately following the option that requires
		124	them.
		125
		126
		127	For options whose names are multiple letters, either one
		128	dash or two can precede the option name; for example,
		129	__-trace-symbol__ and __--trace-symbol__ are
		130	equivalent. Note - there is one exception to this rule.
		131	Multiple letter options that start with a lower case 'o' can
		132	only be preceeded by two dashes. This is to reduce confusion
		133	with the __-o__ option. So for example __-omagic__
		134	sets the output file name to __magic__ whereas
		135	__--omagic__ sets the NMAGIC flag on the
		136	output.
		137
		138
		139	Arguments to multiple-letter options must either be
		140	separated from the option name by an equals sign, or be
		141	given as separate arguments immediately following the option
		142	that requires them. For example, __--trace-symbol foo__
		143	and __--trace-symbol=foo__ are equivalent. Unique
		144	abbreviations of the names of multiple-letter options are
		145	accepted.
		146
		147
		148	Note - if the linker is being invoked indirectly, via a
		149	compiler driver (eg __gcc__) then all the linker command
		150	line options should be prefixed by __-Wl,__ (or whatever
		151	is appropriate for the particular compiler driver) like
		152	this:
		153
		154
		155	gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
		156	This is important, because otherwise the compiler driver program may silently drop the linker options, resulting in a bad link.
		157
		158
		159	Here is a table of the generic command line switches
		160	accepted by the GNU linker:
		161
		162
		163	__-a__''keyword''
		164
		165
		166	This option is supported for HP/UX
		167	compatibility. The ''keyword'' argument must be one of
		168	the strings __archive__, __shared__, or
		169	__default__. __-aarchive__ is functionally equivalent
		170	to __-Bstatic__, and the other two keywords are
		171	functionally equivalent to __-Bdynamic__. This option may
		172	be used any number of times.
		173
		174
		175	__-A__''architecture''
		176
		177
		178	__--architecture=__''architecture''
		179
		180
		181	In the current release of __ld__, this option is useful
		182	only for the Intel 960 family of architectures. In that
		183	__ld__ configuration, the ''architecture'' argument
		184	identifies the particular architecture in the 960 family,
		185	enabling some safeguards and modifying the archive-library
		186	search path.
		187
		188
		189	Future releases of __ld__ may support similar
		190	functionality for other architecture families.
		191
		192
		193	__-b__ ''input-format''
		194
		195
		196	__--format=__''input-format''
		197
		198
		199	__ld__ may be configured to support more than one kind of
		200	object file. If your __ld__ is configured this way, you
		201	can use the __-b__ option to specify the binary format
		202	for input object files that follow this option on the
		203	command line. Even when __ld__ is configured to support
		204	alternative object formats, you don't usually need to
		205	specify this, as __ld__ should be configured to expect as
		206	a default input format the most usual format on each
		207	machine. ''input-format'' is a text string, the name of a
		208	particular format supported by the BFD
		209	libraries. (You can list the available binary formats with
		210	__objdump -i__.)
		211
		212
		213	You may want to use this option if you are linking files
		214	with an unusual binary format. You can also use __-b__ to
		215	switch formats explicitly (when linking object files of
		216	different formats), by including __-b__
		217	''input-format'' before each group of object files in a
		218	particular format.
		219
		220
		221	The default format is taken from the environment variable
		222	GNUTARGET.
		223
		224
		225	You can also define the input format from a script, using
		226	the command TARGET;
		227
		228
		229	__-c__ ''MRI-commandfile''
		230
		231
		232	__--mri-script=__''MRI-commandfile''
		233
		234
		235	For compatibility with linkers produced by
		236	MRI , __ld__ accepts script files written
		237	in an alternate, restricted command language, described in
		238	the MRI Compatible Script Files section of
		239	GNU ld documentation. Introduce
		240	MRI script files with the option __-c__;
		241	use the __-T__ option to run linker scripts written in
		242	the general-purpose __ld__ scripting language. If
		243	''MRI-cmdfile'' does not exist, __ld__ looks for it in
		244	the directories specified by any __-L__
		245	options.
		246
		247
		248	__-d__
		249
		250
		251	__-dc__
		252
		253
		254	__-dp__
		255
		256
		257	These three options are equivalent; multiple forms are
		258	supported for compatibility with other linkers. They assign
		259	space to common symbols even if a relocatable output file is
		260	specified (with __-r__). The script command
		261	FORCE_COMMON_ALLOCATION has the same
		262	effect.
		263
		264
		265	__-e__ ''entry''
		266
		267
		268	__--entry=__''entry''
		269
		270
		271	Use ''entry'' as the explicit symbol for beginning
		272	execution of your program, rather than the default entry
		273	point. If there is no symbol named ''entry'', the linker
		274	will try to parse ''entry'' as a number, and use that as
		275	the entry address (the number will be interpreted in base
		276	10; you may use a leading __0x__ for base 16, or a
		277	leading __0__ for base 8).
		278
		279
		280	__-E__
		281
		282
		283	__--export-dynamic__
		284
		285
		286	When creating a dynamically linked executable, add all
		287	symbols to the dynamic symbol table. The dynamic symbol
		288	table is the set of symbols which are visible from dynamic
		289	objects at run time.
		290
		291
		292	If you do not use this option, the dynamic symbol table will
		293	normally contain only those symbols which are referenced by
		294	some dynamic object mentioned in the link.
		295
		296
		297	If you use dlopen to load a dynamic object which
		298	needs to refer back to the symbols defined by the program,
		299	rather than some other dynamic object, then you will
		300	probably need to use this option when linking the program
		301	itself.
		302
		303
		304	You can also use the version script to control what symbols
		305	should be added to the dynamic symbol table if the output
		306	format supports it. See the description of
		307	__--version-script__ in @ref{
		308	VERSION }.
		309
		310
		311	__-EB__
		312
		313
		314	Link big-endian objects. This affects the default output
		315	format.
		316
		317
		318	__-EL__
		319
		320
		321	Link little-endian objects. This affects the default output
		322	format.
		323
		324
		325	__-f__
		326
		327
		328	__--auxiliary__ ''name''
		329
		330
		331	When creating an ELF shared object, set the
		332	internal DT_AUXILIARY field to the specified
		333	name. This tells the dynamic linker that the symbol table of
		334	the shared object should be used as an auxiliary filter on
		335	the symbol table of the shared object
		336	''name''.
		337
		338
		339	If you later link a program against this filter object,
		340	then, when you run the program, the dynamic linker will see
		341	the DT_AUXILIARY field. If the dynamic linker
		342	resolves any symbols from the filter object, it will first
		343	check whether there is a definition in the shared object
		344	''name''. If there is one, it will be used instead of the
		345	definition in the filter object. The shared object
		346	''name'' need not exist. Thus the shared object
		347	''name'' may be used to provide an alternative
		348	implementation of certain functions, perhaps for debugging
		349	or for machine specific performance.
		350
		351
		352	This option may be specified more than once. The
		353	DT_AUXILIARY entries will be created in the
		354	order in which they appear on the command line.
		355
		356
		357	__-F__ ''name''
		358
		359
		360	__--filter__ ''name''
		361
		362
		363	When creating an ELF shared object, set the
		364	internal DT_FILTER field to the specified
		365	name. This tells the dynamic linker that the symbol table of
		366	the shared object which is being created should be used as a
		367	filter on the symbol table of the shared object
		368	''name''.
		369
		370
		371	If you later link a program against this filter object,
		372	then, when you run the program, the dynamic linker will see
		373	the DT_FILTER field. The dynamic linker will
		374	resolve symbols according to the symbol table of the filter
		375	object as usual, but it will actually link to the
		376	definitions found in the shared object ''name''. Thus the
		377	filter object can be used to select a subset of the symbols
		378	provided by the object ''name''.
		379
		380
		381	Some older linkers used the __-F__ option throughout a
		382	compilation toolchain for specifying object-file format for
		383	both input and output object files. The GNU
		384	linker uses other mechanisms for this purpose: the
		385	__-b__, __--format__, __--oformat__ options, the
		386	TARGET command in linker scripts, and the
		387	GNUTARGET environment variable. The
		388	GNU linker will ignore the __-F__ option
		389	when not creating an ELF shared
		390	object.
		391
		392
		393	__-fini__ ''name''
		394
		395
		396	When creating an ELF executable or shared
		397	object, call NAME when the executable or
		398	shared object is unloaded, by setting DT_FINI
		399	to the address of the function. By default, the linker uses
		400	_fini as the function to call.
		401
		402
		403	__-g__
		404
		405
		406	Ignored. Provided for compatibility with other
		407	tools.
		408
		409
		410	__-G__''value''
		411
		412
		413	__--gpsize=__''value''
		414
		415
		416	Set the maximum size of objects to be optimized using the
		417	GP register to ''size''. This is only
		418	meaningful for object file formats such as MIPS
		419	ECOFF which supports putting large and small objects
		420	into different sections. This is ignored for other object
		421	file formats.
		422
		423
		424	__-h__''name''
		425
		426
		427	__-soname=__''name''
		428
		429
		430	When creating an ELF shared object, set the
		431	internal DT_SONAME field to the specified
		432	name. When an executable is linked with a shared object
		433	which has a DT_SONAME field, then when the
		434	executable is run the dynamic linker will attempt to load
		435	the shared object specified by the DT_SONAME
		436	field rather than the using the file name given to the
		437	linker.
		438
		439
		440	__-i__
		441
		442
		443	Perform an incremental link (same as option
		444	__-r__).
		445
		446
		447	__-init__ ''name''
		448
		449
		450	When creating an ELF executable or shared
		451	object, call NAME when the executable or
		452	shared object is loaded, by setting DT_INIT
		453	to the address of the function. By default, the linker uses
		454	_init as the function to call.
		455
		456
		457	__-l__''archive''
		458
		459
		460	__--library=__''archive''
		461
		462
		463	Add archive file ''archive'' to the list of files to
		464	link. This option may be used any number of times. __ld__
		465	will search its path-list for occurrences of
		466	libarchive.a for every ''archive''
		467	specified.
		468
		469
		470	On systems which support shared libraries, __ld__ may
		471	also search for libraries with extensions other than
		472	.a. Specifically, on ELF and SunOS
		473	systems, __ld__ will search a directory for a library
		474	with an extension of .so before searching for one
		475	with an extension of .a. By convention, a
		476	.so extension indicates a shared
		477	library.
		478
		479
		480	The linker will search an archive only once, at the location
		481	where it is specified on the command line. If the archive
		482	defines a symbol which was undefined in some object which
		483	appeared before the archive on the command line, the linker
		484	will include the appropriate file(s) from the archive.
		485	However, an undefined symbol in an object appearing later on
		486	the command line will not cause the linker to search the
		487	archive again.
		488
		489
		490	See the __-(__ option for a way to force the linker to
		491	search archives multiple times.
		492
		493
		494	You may list the same archive multiple times on the command
		495	line.
		496
		497
		498	This type of archive searching is standard for Unix linkers.
		499	However, if you are using __ld__ on AIX ,
		500	note that it is different from the behaviour of the
		501	AIX linker.
		502
		503
		504	__-L__''searchdir''
		505
		506
		507	__--library-path=__''searchdir''
		508
		509
		510	Add path ''searchdir'' to the list of paths that
		511	__ld__ will search for archive libraries and __ld__
		512	control scripts. You may use this option any number of
		513	times. The directories are searched in the order in which
		514	they are specified on the command line. Directories
		515	specified on the command line are searched before the
		516	default directories. All __-L__ options apply to all
		517	__-l__ options, regardless of the order in which the
		518	options appear.
		519
		520
		521	The default set of paths searched (without being specified
		522	with __-L__) depends on which emulation mode __ld__ is
		523	using, and in some cases also on how it was
		524	configured.
		525
		526
		527	The paths can also be specified in a link script with the
		528	SEARCH_DIR command. Directories specified this way
		529	are searched at the point in which the linker script appears
		530	in the command line.
		531
		532
		533	__-m__''emulation''
		534
		535
		536	Emulate the ''emulation'' linker. You can list the
		537	available emulations with the __--verbose__ or __-V__
		538	options.
		539
		540
		541	If the __-m__ option is not used, the emulation is taken
		542	from the LDEMULATION environment variable, if that
		543	is defined.
		544
		545
		546	Otherwise, the default emulation depends upon how the linker
		547	was configured.
		548
		549
		550	__-M__
		551
		552
		553	__--print-map__
		554
		555
		556	Print a link map to the standard output. A link map provides
		557	information about the link, including the
		558	following:
		559
		560
		561	Where object files and symbols are mapped into
		562	memory.
		563
		564
		565	How common symbols are allocated.
		566
		567
		568	All archive members included in the link, with a mention of
		569	the symbol which caused the archive member to be brought
		570	in.
		571
		572
		573	__-n__
		574
		575
		576	__--nmagic__
		577
		578
		579	Turn off page alignment of sections, and mark the output as
		580	NMAGIC if possible.
		581
		582
		583	__-N__
		584
		585
		586	__--omagic__
		587
		588
		589	Set the text and data sections to be readable and writable.
		590	Also, do not page-align the data segment. If the output
		591	format supports Unix style magic numbers, mark the output as
		592	OMAGIC.
		593
		594
		595	__-o__ ''output''
		596
		597
		598	__--output=__''output''
		599
		600
		601	Use ''output'' as the name for the program produced by
		602	__ld__; if this option is not specified, the name
		603	''a.out'' is used by default. The script command
		604	OUTPUT can also specify the output file
		605	name.
		606
		607
		608	__-O__ ''level''
		609
		610
		611	If ''level'' is a numeric values greater than zero
		612	__ld__ optimizes the output. This might take
		613	significantly longer and therefore probably should only be
		614	enabled for the final binary.
		615
		616
		617	__-q__
		618
		619
		620	__--emit-relocs__
		621
		622
		623	Leave relocation sections and contents in fully linked
		624	exececutables. Post link analysis and optimization tools may
		625	need this information in order to perform correct
		626	modifications of executables. This results in larger
		627	executables.
		628
		629
		630	This option is currently only supported on
		631	ELF platforms.
		632
		633
		634	__-r__
		635
		636
		637	__--relocateable__
		638
		639
		640	Generate relocatable output---i.e., generate an output file
		641	that can in turn serve as input to __ld__. This is often
		642	called ''partial linking''. As a side effect, in
		643	environments that support standard Unix magic numbers, this
		644	option also sets the output file's magic number to
		645	OMAGIC. If this option is not specified, an
		646	absolute file is produced. When linking C ++
		647	programs, this option ''will not'' resolve references to
		648	constructors; to do that, use __-Ur__.
		649
		650
		651	When an input file does not have the same format as the
		652	output file, partial linking is only supported if that input
		653	file does not contain any relocations. Different output
		654	formats can have further restrictions; for example some
		655	a.out-based formats do not support partial linking
		656	with input files in other formats at all.
		657
		658
		659	This option does the same thing as __-i__.
		660
		661
		662	__-R__ ''filename''
		663
		664
		665	__--just-symbols=__''filename''
		666
		667
		668	Read symbol names and their addresses from ''filename'',
		669	but do not relocate it or include it in the output. This
		670	allows your output file to refer symbolically to absolute
		671	locations of memory defined in other programs. You may use
		672	this option more than once.
		673
		674
		675	For compatibility with other ELF linkers, if
		676	the __-R__ option is followed by a directory name, rather
		677	than a file name, it is treated as the __-rpath__
		678	option.
		679
		680
		681	__-s__
		682
		683
		684	__--strip-all__
		685
		686
		687	Omit all symbol information from the output
		688	file.
		689
		690
		691	__-S__
		692
		693
		694	__--strip-debug__
		695
		696
		697	Omit debugger symbol information (but not all symbols) from
		698	the output file.
		699
		700
		701	__-t__
		702
		703
		704	__--trace__
		705
		706
		707	Print the names of the input files as __ld__ processes
		708	them.
		709
		710
		711	__-T__ ''scriptfile''
		712
		713
		714	__--script=__''scriptfile''
		715
		716
		717	Use ''scriptfile'' as the linker script. This script
		718	replaces __ld__'s default linker script (rather than
		719	adding to it), so ''commandfile'' must specify everything
		720	necessary to describe the output file. If ''scriptfile''
		721	does not exist in the current directory, ld looks
		722	for it in the directories specified by any preceding
		723	__-L__ options. Multiple __-T__ options
		724	accumulate.
		725
		726
		727	__-u__ ''symbol''
		728
		729
		730	__--undefined=__''symbol''
		731
		732
		733	Force ''symbol'' to be entered in the output file as an
		734	undefined symbol. Doing this may, for example, trigger
		735	linking of additional modules from standard libraries.
		736	__-u__ may be repeated with different option arguments to
		737	enter additional undefined symbols. This option is
		738	equivalent to the EXTERN linker script
		739	command.
		740
		741
		742	__-Ur__
		743
		744
		745	For anything other than C ++ programs, this
		746	option is equivalent to __-r__: it generates relocatable
		747	output---i.e., an output file that can in turn serve as
		748	input to __ld__. When linking C ++
		749	programs, __-Ur__ ''does'' resolve references to
		750	constructors, unlike __-r__. It does not work to use
		751	__-Ur__ on files that were themselves linked with
		752	__-Ur__; once the constructor table has been built, it
		753	cannot be added to. Use __-Ur__ only for the last partial
		754	link, and __-r__ for the others.
		755
		756
		757	__--unique[[=__ ''SECTION''
		758	__]__
		759
		760
		761	Creates a separate output section for every input section
		762	matching ''SECTION'' , or if the optional
		763	wildcard ''SECTION'' argument is missing,
		764	for every orphan input section. An orphan section is one not
		765	specifically mentioned in a linker script. You may use this
		766	option multiple times on the command line; It prevents the
		767	normal merging of input sections with the same name,
		768	overriding output section assignments in a linker
		769	script.
		770
		771
		772	__-v__
		773
		774
		775	__--version__
		776
		777
		778	__-V__
		779
		780
		781	Display the version number for __ld__. The __-V__
		782	option also lists the supported emulations.
		783
		784
		785	__-x__
		786
		787
		788	__--discard-all__
		789
		790
		791	Delete all local symbols.
		792
		793
		794	__-X__
		795
		796
		797	__--discard-locals__
		798
		799
		800	Delete all temporary local symbols. For most targets, this
		801	is all local symbols whose names begin with
		802	__L__.
		803
		804
		805	__-y__ ''symbol''
		806
		807
		808	__--trace-symbol=__''symbol''
		809
		810
		811	Print the name of each linked file in which ''symbol''
		812	appears. This option may be given any number of times. On
		813	many systems it is necessary to prepend an
		814	underscore.
		815
		816
		817	This option is useful when you have an undefined symbol in
		818	your link but don't know where the reference is coming
		819	from.
		820
		821
		822	__-Y__ ''path''
		823
		824
		825	Add ''path'' to the default library search path. This
		826	option exists for Solaris compatibility.
		827
		828
		829	__-z__ ''keyword''
		830
		831
		832	The recognized keywords are initfirst,
		833	interpose, loadfltr,
		834	nodefaultlib, nodelete, nodlopen,
		835	nodump, now, origin,
		836	combreloc, nocombreloc and
		837	nocopyreloc. The other keywords are ignored for
		838	Solaris compatibility. initfirst marks the object
		839	to be initialized first at runtime before any other objects.
		840	interpose marks the object that its symbol table
		841	interposes before all symbols but the primary executable.
		842	loadfltr marks the object that its filtees be
		843	processed immediately at runtime. nodefaultlib
		844	marks the object that the search for dependencies of this
		845	object will ignore any default library search paths.
		846	nodelete marks the object shouldn't be unloaded at
		847	runtime. nodlopen marks the object not available to
		848	dlopen. nodump marks the object can not be
		849	dumped by dldump. now marks the object
		850	with the non-lazy runtime binding. origin marks the
		851	object may contain $ORIGIN. defs disallows
		852	undefined symbols. combreloc combines multiple
		853	reloc sections and sorts them to make dynamic symbol lookup
		854	caching possible. nocombreloc disables multiple
		855	reloc sections combining. nocopyreloc disables
		856	production of copy relocs.
		857
		858
		859	__-(__ ''archives'' __-)__
		860
		861
		862	__--start-group__ ''archives''
		863	__--end-group__
		864
		865
		866	The ''archives'' should be a list of archive files. They
		867	may be either explicit file names, or __-l__
		868	options.
		869
		870
		871	The specified archives are searched repeatedly until no new
		872	undefined references are created. Normally, an archive is
		873	searched only once in the order that it is specified on the
		874	command line. If a symbol in that archive is needed to
		875	resolve an undefined symbol referred to by an object in an
		876	archive that appears later on the command line, the linker
		877	would not be able to resolve that reference. By grouping the
		878	archives, they all be searched repeatedly until all possible
		879	references are resolved.
		880
		881
		882	Using this option has a significant performance cost. It is
		883	best to use it only when there are unavoidable circular
		884	references between two or more archives.
		885
		886
		887	__-assert__ ''keyword''
		888
		889
		890	This option is ignored for SunOS compatibility.
		891
		892
		893	__-Bdynamic__
		894
		895
		896	__-dy__
		897
		898
		899	__-call_shared__
		900
		901
		902	Link against dynamic libraries. This is only meaningful on
		903	platforms for which shared libraries are supported. This
		904	option is normally the default on such platforms. The
		905	different variants of this option are for compatibility with
		906	various systems. You may use this option multiple times on
		907	the command line: it affects library searching for __-l__
		908	options which follow it.
		909
		910
		911	__-Bgroup__
		912
		913
		914	Set the DF_1_GROUP flag in the DT_FLAGS_1
		915	entry in the dynamic section. This causes the runtime linker
		916	to handle lookups in this object and its dependencies to be
		917	performed only inside the group. __--no-undefined__ is
		918	implied. This option is only meaningful on
		919	ELF platforms which support shared
		920	libraries.
		921
		922
		923	__-Bstatic__
		924
		925
		926	__-dn__
		927
		928
		929	__-non_shared__
		930
		931
		932	__-static__
		933
		934
		935	Do not link against shared libraries. This is only
		936	meaningful on platforms for which shared libraries are
		937	supported. The different variants of this option are for
		938	compatibility with various systems. You may use this option
		939	multiple times on the command line: it affects library
		940	searching for __-l__ options which follow
		941	it.
		942
		943
		944	__-Bsymbolic__
		945
		946
		947	When creating a shared library, bind references to global
		948	symbols to the definition within the shared library, if any.
		949	Normally, it is possible for a program linked against a
		950	shared library to override the definition within the shared
		951	library. This option is only meaningful on
		952	ELF platforms which support shared
		953	libraries.
		954
		955
		956	__--check-sections__
		957
		958
		959	__--no-check-sections__
		960
		961
		962	Asks the linker ''not'' to check section addresses after
		963	they have been assigned to see if there any overlaps.
		964	Normally the linker will perform this check, and if it finds
		965	any overlaps it will produce suitable error messages. The
		966	linker does know about, and does make allowances for
		967	sections in overlays. The default behaviour can be restored
		968	by using the command line switch
		969	__--check-sections__.
		970
		971
		972	__--cref__
		973
		974
		975	Output a cross reference table. If a linker map file is
		976	being generated, the cross reference table is printed to the
		977	map file. Otherwise, it is printed on the standard
		978	output.
		979
		980
		981	The format of the table is intentionally simple, so that it
		982	may be easily processed by a script if necessary. The
		983	symbols are printed out, sorted by name. For each symbol, a
		984	list of file names is given. If the symbol is defined, the
		985	first file listed is the location of the definition. The
		986	remaining files contain references to the
		987	symbol.
		988
		989
		990	__--no-define-common__
		991
		992
		993	This option inhibits the assignment of addresses to common
		994	symbols. The script command
		995	INHIBIT_COMMON_ALLOCATION has the same
		996	effect.
		997
		998
		999	The __--no-define-common__ option allows decoupling the
		1000	decision to assign addresses to Common symbols from the
		1001	choice of the output file type; otherwise a non-Relocatable
		1002	output type forces assigning addresses to Common symbols.
		1003	Using __--no-define-common__ allows Common symbols that
		1004	are referenced from a shared library to be assigned
		1005	addresses only in the main program. This eliminates the
		1006	unused duplicate space in the shared library, and also
		1007	prevents any possible confusion over resolving to the wrong
		1008	duplicate when there are many dynamic modules with
		1009	specialized search paths for runtime symbol
		1010	resolution.
		1011
		1012
		1013	__--defsym__
		1014	''symbol''__=__''expression''
		1015
		1016
		1017	Create a global symbol in the output file, containing the
		1018	absolute address given by ''expression''. You may use
		1019	this option as many times as necessary to define multiple
		1020	symbols in the command line. A limited form of arithmetic is
		1021	supported for the ''expression'' in this context: you may
		1022	give a hexadecimal constant or the name of an existing
		1023	symbol, or use + and - to add or subtract
		1024	hexadecimal constants or symbols. If you need more elaborate
		1025	expressions, consider using the linker command language from
		1026	a script. ''Note:'' there should be no white space
		1027	between ''symbol'', the equals sign (``__=__''), and
		1028	''expression''.
		1029
		1030
		1031	__--demangle[[=__''style''__]__
		1032
		1033
		1034	__--no-demangle__
		1035
		1036
		1037	These options control whether to demangle symbol names in
		1038	error messages and other output. When the linker is told to
		1039	demangle, it tries to present symbol names in a readable
		1040	fashion: it strips leading underscores if they are used by
		1041	the object file format, and converts C ++
		1042	mangled symbol names into user readable names. Different
		1043	compilers have different mangling styles. The optional
		1044	demangling style argument can be used to choose an
		1045	appropriate demangling style for your compiler. The linker
		1046	will demangle by default unless the environment variable
		1047	__COLLECT_NO_DEMANGLE__ is set. These
		1048	options may be used to override the default.
		1049
		1050
		1051	__--dynamic-linker__ ''file''
		1052
		1053
		1054	Set the name of the dynamic linker. This is only meaningful
		1055	when generating dynamically linked ELF
		1056	executables. The default dynamic linker is normally correct;
		1057	don't use this unless you know what you are
		1058	doing.
		1059
		1060
		1061	__--embedded-relocs__
		1062
		1063
		1064	This option is only meaningful when linking
		1065	MIPS embedded PIC code,
		1066	generated by the -membedded-pic option to the
		1067	GNU compiler and assembler. It causes the
		1068	linker to create a table which may be used at runtime to
		1069	relocate any data which was statically initialized to
		1070	pointer values. See the code in testsuite/ld-empic for
		1071	details.
		1072
		1073
		1074	__--fatal-warnings__
		1075
		1076
		1077	Treat all warnings as errors.
		1078
		1079
		1080	__--force-exe-suffix__
		1081
		1082
		1083	Make sure that an output file has a .exe
		1084	suffix.
		1085
		1086
		1087	If a successfully built fully linked output file does not
		1088	have a .exe or .dll suffix, this option
		1089	forces the linker to copy the output file to one of the same
		1090	name with a .exe suffix. This option is useful when
		1091	using unmodified Unix makefiles on a Microsoft Windows host,
		1092	since some versions of Windows won't run an image unless it
		1093	ends in a .exe suffix.
		1094
		1095
		1096	__--no-gc-sections__
		1097
		1098
		1099	__--gc-sections__
		1100
		1101
		1102	Enable garbage collection of unused input sections. It is
		1103	ignored on targets that do not support this option. This
		1104	option is not compatible with __-r__, nor should it be
		1105	used with dynamic linking. The default behaviour (of not
		1106	performing this garbage collection) can be restored by
		1107	specifying __--no-gc-sections__ on the command
		1108	line.
		1109
		1110
		1111	__--help__
		1112
		1113
		1114	Print a summary of the command-line options on the standard
		1115	output and exit.
		1116
		1117
		1118	__--target-help__
		1119
		1120
		1121	Print a summary of all target specific options on the
		1122	standard output and exit.
		1123
		1124
		1125	__-Map__ ''mapfile''
		1126
		1127
		1128	Print a link map to the file ''mapfile''. See the
		1129	description of the __-M__ option, above.
		1130
		1131
		1132	__--no-keep-memory__
		1133
		1134
		1135	__ld__ normally optimizes for speed over memory usage by
		1136	caching the symbol tables of input files in memory. This
		1137	option tells __ld__ to instead optimize for memory usage,
		1138	by rereading the symbol tables as necessary. This may be
		1139	required if __ld__ runs out of memory space while linking
		1140	a large executable.
		1141
		1142
		1143	__--no-undefined__
		1144
		1145
		1146	__-z defs__
		1147
		1148
		1149	Normally when creating a non-symbolic shared library,
		1150	undefined symbols are allowed and left to be resolved by the
		1151	runtime loader. These options disallows such undefined
		1152	symbols.
		1153
		1154
		1155	__--allow-shlib-undefined__
		1156
		1157
		1158	Allow undefined symbols in shared objects even when
		1159	--no-undefined is set. The net result will be that undefined
		1160	symbols in regular objects will still trigger an error, but
		1161	undefined symbols in shared objects will be ignored. The
		1162	implementation of no_undefined makes the assumption that the
		1163	runtime linker will choke on undefined symbols. However
		1164	there is at least one system (BeOS) where undefined symbols
		1165	in shared libraries is normal since the kernel patches them
		1166	at load time to select which function is most appropriate
		1167	for the current architecture. I.E. dynamically select an
		1168	appropriate memset function. Apparently it is also normal
		1169	for HPPA shared libraries to have undefined
		1170	symbols.
		1171
		1172
		1173	__--no-warn-mismatch__
		1174
		1175
		1176	Normally __ld__ will give an error if you try to link
		1177	together input files that are mismatched for some reason,
		1178	perhaps because they have been compiled for different
		1179	processors or for different endiannesses. This option tells
		1180	__ld__ that it should silently permit such possible
		1181	errors. This option should only be used with care, in cases
		1182	when you have taken some special action that ensures that
		1183	the linker errors are inappropriate.
		1184
		1185
		1186	__--no-whole-archive__
		1187
		1188
		1189	Turn off the effect of the __--whole-archive__ option for
		1190	subsequent archive files.
		1191
		1192
		1193	__--noinhibit-exec__
		1194
		1195
		1196	Retain the executable output file whenever it is still
		1197	usable. Normally, the linker will not produce an output file
		1198	if it encounters errors during the link process; it exits
		1199	without writing an output file when it issues any error
		1200	whatsoever.
		1201
		1202
		1203	__-nostdlib__
		1204
		1205
		1206	Only search library directories explicitly specified on the
		1207	command line. Library directories specified in linker
		1208	scripts (including linker scripts specified on the command
		1209	line) are ignored.
		1210
		1211
		1212	__--oformat__ ''output-format''
		1213
		1214
		1215	__ld__ may be configured to support more than one kind of
		1216	object file. If your __ld__ is configured this way, you
		1217	can use the __--oformat__ option to specify the binary
		1218	format for the output object file. Even when __ld__ is
		1219	configured to support alternative object formats, you don't
		1220	usually need to specify this, as __ld__ should be
		1221	configured to produce as a default output format the most
		1222	usual format on each machine. ''output-format'' is a text
		1223	string, the name of a particular format supported by the
		1224	BFD libraries. (You can list the available
		1225	binary formats with __objdump -i__.) The script command
		1226	OUTPUT_FORMAT can also specify the output format,
		1227	but this option overrides it.
		1228
		1229
		1230	__-qmagic__
		1231
		1232
		1233	This option is ignored for Linux compatibility.
		1234
		1235
		1236	__-Qy__
		1237
		1238
		1239	This option is ignored for SVR4
		1240	compatibility.
		1241
		1242
		1243	__--relax__
		1244
		1245
		1246	An option with machine dependent effects. This option is
		1247	only supported on a few targets.
		1248
		1249
		1250	On some platforms, the __--relax__ option performs global
		1251	optimizations that become possible when the linker resolves
		1252	addressing in the program, such as relaxing address modes
		1253	and synthesizing new instructions in the output object
		1254	file.
		1255
		1256
		1257	On some platforms these link time global optimizations may
		1258	make symbolic debugging of the resulting executable
		1259	impossible. This is known to be the case for the Matsushita
		1260	MN10200 and MN10300 family of
		1261	processors.
		1262
		1263
		1264	On platforms where this is not supported, __--relax__ is
		1265	accepted, but ignored.
		1266
		1267
		1268	__--retain-symbols-file__ ''filename''
		1269
		1270
		1271	Retain ''only'' the symbols listed in the file
		1272	''filename'', discarding all others. ''filename'' is
		1273	simply a flat file, with one symbol name per line. This
		1274	option is especially useful in environments (such as
2	perry	1275	!VxWorks) where a large global symbol table is accumulated
1	perry	1276	gradually, to conserve run-time memory.
		1277
		1278
		1279	__--retain-symbols-file__ does ''not'' discard
		1280	undefined symbols, or symbols needed for
		1281	relocations.
		1282
		1283
		1284	You may only specify __--retain-symbols-file__ once in
		1285	the command line. It overrides __-s__ and
		1286	__-S__.
		1287
		1288
		1289	__-rpath__ ''dir''
		1290
		1291
		1292	Add a directory to the runtime library search path. This is
		1293	used when linking an ELF executable with
		1294	shared objects. All __-rpath__ arguments are concatenated
		1295	and passed to the runtime linker, which uses them to locate
		1296	shared objects at runtime. The __-rpath__ option is also
		1297	used when locating shared objects which are needed by shared
		1298	objects explicitly included in the link; see the description
		1299	of the __-rpath-link__ option. If __-rpath__ is not
		1300	used when linking an ELF executable, the
		1301	contents of the environment variable LD_RUN_PATH
		1302	will be used if it is defined.
		1303
		1304
		1305	The __-rpath__ option may also be used on SunOS. By
		1306	default, on SunOS, the linker will form a runtime search
		1307	patch out of all the __-L__ options it is given. If a
		1308	__-rpath__ option is used, the runtime search path will
		1309	be formed exclusively using the __-rpath__ options,
		1310	ignoring the __-L__ options. This can be useful when
		1311	using gcc, which adds many __-L__ options which may be on
		1312	NFS mounted filesystems.
		1313
		1314
		1315	For compatibility with other ELF linkers, if
		1316	the __-R__ option is followed by a directory name, rather
		1317	than a file name, it is treated as the __-rpath__
		1318	option.
		1319
		1320
		1321	__-rpath-link__ ''DIR''
		1322
		1323
		1324	When using ELF or SunOS, one shared library
		1325	may require another. This happens when an ld
		1326	-shared link includes a shared library as one of the
		1327	input files.
		1328
		1329
		1330	When the linker encounters such a dependency when doing a
		1331	non-shared, non-relocatable link, it will automatically try
		1332	to locate the required shared library and include it in the
		1333	link, if it is not included explicitly. In such a case, the
		1334	__-rpath-link__ option specifies the first set of
		1335	directories to search. The __-rpath-link__ option may
		1336	specify a sequence of directory names either by specifying a
		1337	list of names separated by colons, or by appearing multiple
		1338	times.
		1339
		1340
		1341	This option should be used with caution as it overrides the
		1342	search path that may have been hard compiled into a shared
		1343	library. In such a case it is possible to use
		1344	unintentionally a different search path than the runtime
		1345	linker would do.
		1346
		1347
		1348	The linker uses the following search paths to locate
		1349	required shared libraries.
		1350
		1351
		1352	1.
		1353
		1354
		1355	Any directories specified by __-rpath-link__
		1356	options.
		1357
		1358
		1359	2.
		1360
		1361
		1362	Any directories specified by __-rpath__ options. The
		1363	difference between __-rpath__ and __-rpath-link__ is
		1364	that directories specified by __-rpath__ options are
		1365	included in the executable and used at runtime, whereas the
		1366	__-rpath-link__ option is only effective at link time. It
		1367	is for the native linker only.
		1368
		1369
		1370	3.
		1371
		1372
		1373	On an ELF system, if the __-rpath__ and
		1374	rpath-link options were not used, search the
		1375	contents of the environment variable LD_RUN_PATH.
		1376	It is for the native linker only.
		1377
		1378
		1379	4.
		1380
		1381
		1382	On SunOS, if the __-rpath__ option was not used, search
		1383	any directories specified using __-L__
		1384	options.
		1385
		1386
		1387	5.
		1388
		1389
		1390	For a native linker, the contents of the environment
		1391	variable LD_LIBRARY_PATH.
		1392
		1393
		1394	6.
		1395
		1396
		1397	For a native ELF linker, the directories in
		1398	DT_RUNPATH or DT_RPATH of a shared library
		1399	are searched for shared libraries needed by it. The
		1400	DT_RPATH entries are ignored if DT_RUNPATH
		1401	entries exist.
		1402
		1403
		1404	7.
		1405
		1406
		1407	The default directories, normally ''/lib'' and
		1408	''/usr/lib''.
		1409
		1410
		1411	8.
		1412
		1413
		1414	For a native linker on an ELF system, if the
		1415	file ''/etc/ld.so.conf'' exists, the list of directories
		1416	found in that file.
		1417
		1418
		1419	If the required shared library is not found, the linker will
		1420	issue a warning and continue with the link.
		1421
		1422
		1423	__-shared__
		1424
		1425
		1426	__-Bshareable__
		1427
		1428
		1429	Create a shared library. This is currently only supported on
		1430	ELF , XCOFF and SunOS
		1431	platforms. On SunOS, the linker will automatically create a
		1432	shared library if the __-e__ option is not used and there
		1433	are undefined symbols in the link.
		1434
		1435
		1436	__--sort-common__
		1437
		1438
		1439	This option tells __ld__ to sort the common symbols by
		1440	size when it places them in the appropriate output sections.
		1441	First come all the one byte symbols, then all the two byte,
		1442	then all the four byte, and then everything else. This is to
		1443	prevent gaps between symbols due to alignment
		1444	constraints.
		1445
		1446
		1447	__--split-by-file [[__''size''__]__
		1448
		1449
		1450	Similar to __--split-by-reloc__ but creates a new output
		1451	section for each input file when ''size'' is reached.
		1452	''size'' defaults to a size of 1 if not
		1453	given.
		1454
		1455
		1456	__--split-by-reloc [[__''count''__]__
		1457
		1458
		1459	Tries to creates extra sections in the output file so that
		1460	no single output section in the file contains more than
		1461	''count'' relocations. This is useful when generating
		1462	huge relocatable files for downloading into certain real
		1463	time kernels with the COFF object file
		1464	format; since COFF cannot represent more than
		1465	65535 relocations in a single section. Note that this will
		1466	fail to work with object file formats which do not support
		1467	arbitrary sections. The linker will not split up individual
		1468	input sections for redistribution, so if a single input
		1469	section contains more than ''count'' relocations one
		1470	output section will contain that many relocations.
		1471	''count'' defaults to a value of 32768.
		1472
		1473
		1474	__--stats__
		1475
		1476
		1477	Compute and display statistics about the operation of the
		1478	linker, such as execution time and memory
		1479	usage.
		1480
		1481
		1482	__--traditional-format__
		1483
		1484
		1485	For some targets, the output of __ld__ is different in
		1486	some ways from the output of some existing linker. This
		1487	switch requests __ld__ to use the traditional format
		1488	instead.
		1489
		1490
		1491	For example, on SunOS, __ld__ combines duplicate entries
		1492	in the symbol string table. This can reduce the size of an
		1493	output file with full debugging information by over 30
		1494	percent. Unfortunately, the SunOS dbx program can
		1495	not read the resulting program (gdb has no
		1496	trouble). The __--traditional-format__ switch tells
		1497	__ld__ to not combine duplicate entries.
		1498
		1499
		1500	__--section-start__
		1501	''sectionname''__=__''org''
		1502
		1503
		1504	Locate a section in the output file at the absolute address
		1505	given by ''org''. You may use this option as many times
		1506	as necessary to locate multiple sections in the command
		1507	line. ''org'' must be a single hexadecimal integer; for
		1508	compatibility with other linkers, you may omit the leading
		1509	__0x__ usually associated with hexadecimal values.
		1510	''Note:'' there should be no white space between
		1511	''sectionname'', the equals sign (``__=__''), and
		1512	''org''.
		1513
		1514
		1515	__-Tbss__ ''org''
		1516
		1517
		1518	__-Tdata__ ''org''
		1519
		1520
		1521	__-Ttext__ ''org''
		1522
		1523
		1524	Use ''org'' as the starting address
		1525	for---respectively---the bss, data, or the
		1526	text segment of the output file. ''org'' must be
		1527	a single hexadecimal integer; for compatibility with other
		1528	linkers, you may omit the leading __0x__ usually
		1529	associated with hexadecimal values.
		1530
		1531
		1532	__--dll-verbose__
		1533
		1534
		1535	__--verbose__
		1536
		1537
		1538	Display the version number for __ld__ and list the linker
		1539	emulations supported. Display which input files can and
		1540	cannot be opened. Display the linker script being used by
		1541	the linker.
		1542
		1543
		1544	__--version-script=__''version-scriptfile''
		1545
		1546
		1547	Specify the name of a version script to the linker. This is
		1548	typically used when creating shared libraries to specify
		1549	additional information about the version heirarchy for the
		1550	library being created. This option is only meaningful on
		1551	ELF platforms which support shared
		1552	libraries.
		1553
		1554
		1555	__--warn-common__
		1556
		1557
		1558	Warn when a common symbol is combined with another common
		1559	symbol or with a symbol definition. Unix linkers allow this
		1560	somewhat sloppy practice, but linkers on some other
		1561	operating systems do not. This option allows you to find
		1562	potential problems from combining global symbols.
		1563	Unfortunately, some C libraries use this practice, so you
		1564	may get some warnings about symbols in the libraries as well
		1565	as in your programs.
		1566
		1567
		1568	There are three kinds of global symbols, illustrated here by
		1569	C examples:
		1570
		1571
		1572	__int i = 1;__
		1573
		1574
		1575	A definition, which goes in the initialized data section of
		1576	the output file.
		1577
		1578
		1579	__extern int i;__
		1580
		1581
		1582	An undefined reference, which does not allocate space. There
		1583	must be either a definition or a common symbol for the
		1584	variable somewhere.
		1585
		1586
		1587	__int i;__
		1588
		1589
		1590	A common symbol. If there are only (one or more) common
		1591	symbols for a variable, it goes in the uninitialized data
		1592	area of the output file. The linker merges multiple common
		1593	symbols for the same variable into a single symbol. If they
		1594	are of different sizes, it picks the largest size. The
		1595	linker turns a common symbol into a declaration, if there is
		1596	a definition of the same variable.
		1597
		1598
		1599	The __--warn-common__ option can produce five kinds of
		1600	warnings. Each warning consists of a pair of lines: the
		1601	first describes the symbol just encountered, and the second
		1602	describes the previous symbol encountered with the same
		1603	name. One or both of the two symbols will be a common
		1604	symbol.
		1605
		1606
		1607	1.
		1608
		1609
		1610	Turning a common symbol into a reference, because there is
		1611	already a definition for the symbol.
		1612
		1613
		1614	I
		1615
		1616
		1617	2.
		1618
		1619
		1620	Turning a common symbol into a reference, because a later
		1621	definition for the symbol is encountered. This is the same
		1622	as the previous case, except that the symbols are
		1623	encountered in a different order.
		1624
		1625
		1626	I
		1627
		1628
		1629	3.
		1630
		1631
		1632	Merging a common symbol with a previous same-sized common
		1633	symbol.
		1634
		1635
		1636	I
		1637
		1638
		1639	4.
		1640
		1641
		1642	Merging a common symbol with a previous larger common
		1643	symbol.
		1644
		1645
		1646	I
		1647
		1648
		1649	5.
		1650
		1651
		1652	Merging a common symbol with a previous smaller common
		1653	symbol. This is the same as the previous case, except that
		1654	the symbols are encountered in a different
		1655	order.
		1656
		1657
		1658	I
		1659
		1660
		1661	__--warn-constructors__
		1662
		1663
		1664	Warn if any global constructors are used. This is only
		1665	useful for a few object file formats. For formats like
		1666	COFF or ELF , the linker can
		1667	not detect the use of global constructors.
		1668
		1669
		1670	__--warn-multiple-gp__
		1671
		1672
		1673	Warn if multiple global pointer values are required in the
		1674	output file. This is only meaningful for certain processors,
		1675	such as the Alpha. Specifically, some processors put
		1676	large-valued constants in a special section. A special
		1677	register (the global pointer) points into the middle of this
		1678	section, so that constants can be loaded efficiently via a
		1679	base-register relative addressing mode. Since the offset in
		1680	base-register relative mode is fixed and relatively small
		1681	(e.g., 16 bits), this limits the maximum size of the
		1682	constant pool. Thus, in large programs, it is often
		1683	necessary to use multiple global pointer values in order to
		1684	be able to address all possible constants. This option
		1685	causes a warning to be issued whenever this case
		1686	occurs.
		1687
		1688
		1689	__--warn-once__
		1690
		1691
		1692	Only warn once for each undefined symbol, rather than once
		1693	per module which refers to it.
		1694
		1695
		1696	__--warn-section-align__
		1697
		1698
		1699	Warn if the address of an output section is changed because
		1700	of alignment. Typically, the alignment will be set by an
		1701	input section. The address will only be changed if it not
		1702	explicitly specified; that is, if the SECTIONS
		1703	command does not specify a start address for the
		1704	section.
		1705
		1706
		1707	__--whole-archive__
		1708
		1709
		1710	For each archive mentioned on the command line after the
		1711	__--whole-archive__ option, include every object file in
		1712	the archive in the link, rather than searching the archive
		1713	for the required object files. This is normally used to turn
		1714	an archive file into a shared library, forcing every object
		1715	to be included in the resulting shared library. This option
		1716	may be used more than once.
		1717
		1718
		1719	Two notes when using this option from gcc: First, gcc
		1720	doesn't know about this option, so you have to use
		1721	__-Wl,-whole-archive__. Second, don't forget to use
		1722	__-Wl,-no-whole-archive__ after your list of archives,
		1723	because gcc will add its own list of archives to your link
		1724	and you may not want this flag to affect those as
		1725	well.
		1726
		1727
		1728	__--wrap__ ''symbol''
		1729
		1730
		1731	Use a wrapper function for ''symbol''. Any undefined
		1732	reference to ''symbol'' will be resolved to
		1733	__wrap_symbol. Any undefined reference to
		1734	__real_symbol will be resolved to
		1735	''symbol''.
		1736
		1737
		1738	This can be used to provide a wrapper for a system function.
		1739	The wrapper function should be called
		1740	__wrap_symbol. If it wishes to call the system
		1741	function, it should call
		1742	__real_symbol.
		1743
		1744
		1745	Here is a trivial example:
		1746
		1747
		1748	void *
		1749	__wrap_malloc (int c)
		1750	{
		1751	printf (
		1752	If you link other code with this file using __--wrap malloc__, then all calls to malloc will call the function __wrap_malloc instead. The call to __real_malloc in __wrap_malloc will call the real malloc function.
		1753
		1754
		1755	You may wish to provide a __real_malloc function as
		1756	well, so that links without the __--wrap__ option will
		1757	succeed. If you do this, you should not put the definition
		1758	of __real_malloc in the same file as
		1759	__wrap_malloc; if you do, the assembler may resolve
		1760	the call before the linker has a chance to wrap it to
		1761	malloc.
		1762
		1763
		1764	__--enable-new-dtags__
		1765
		1766
		1767	__--disable-new-dtags__
		1768
		1769
		1770	This linker can create the new dynamic tags in
		1771	ELF . But the older ELF
		1772	systems may not understand them. If you specify
		1773	__--enable-new-dtags__, the dynamic tags will be created
		1774	as needed. If you specify __--disable-new-dtags__, no new
		1775	dynamic tags will be created. By default, the new dynamic
		1776	tags are not created. Note that those options are only
		1777	available for ELF systems.
		1778
		1779
		1780	The i386 PE linker supports the
		1781	__-shared__ option, which causes the output to be a
		1782	dynamically linked library ( DLL ) instead of
		1783	a normal executable. You should name the output
		1784	*.dll when you use this option. In addition, the
		1785	linker fully supports the standard *.def files,
		1786	which may be specified on the linker command line like an
		1787	object file (in fact, it should precede archives it exports
		1788	symbols from, to ensure that they get linked in, just like a
		1789	normal object file).
		1790
		1791
		1792	In addition to the options common to all targets, the i386
		1793	PE linker support additional command line
		1794	options that are specific to the i386 PE
		1795	target. Options that take values may be separated from their
		1796	values by either a space or an equals sign.
		1797
		1798
		1799	__--add-stdcall-alias__
		1800
		1801
		1802	If given, symbols with a stdcall suffix (@''nn'') will be
		1803	exported as-is and also with the suffix
		1804	stripped.
		1805
		1806
		1807	__--base-file__ ''file''
		1808
		1809
		1810	Use ''file'' as the name of a file in which to save the
		1811	base addresses of all the relocations needed for generating
		1812	DLLs with ''dlltool''.
		1813
		1814
		1815	__--dll__
		1816
		1817
		1818	Create a DLL instead of a regular executable.
		1819	You may also use __-shared__ or specify a
		1820	LIBRARY in a given .def file.
		1821
		1822
		1823	__--enable-stdcall-fixup__
		1824
		1825
		1826	__--disable-stdcall-fixup__
		1827
		1828
		1829	If the link finds a symbol that it cannot resolve, it will
		1830	attempt to do ``fuzzy linking'' by looking for another
		1831	defined symbol that differs only in the format of the symbol
		1832	name (cdecl vs stdcall) and will resolve that symbol by
		1833	linking to the match. For example, the undefined symbol
		1834	_foo might be linked to the function
		1835	_foo@12, or the undefined symbol _bar@16
		1836	might be linked to the function _bar. When the
		1837	linker does this, it prints a warning, since it normally
		1838	should have failed to link, but sometimes import libraries
		1839	generated from third-party dlls may need this feature to be
		1840	usable. If you specify __--enable-stdcall-fixup__, this
		1841	feature is fully enabled and warnings are not printed. If
		1842	you specify __--disable-stdcall-fixup__, this feature is
		1843	disabled and such mismatches are considered to be
		1844	errors.
		1845
		1846
		1847	__--export-all-symbols__
		1848
		1849
		1850	If given, all global symbols in the objects used to build a
		1851	DLL will be exported by the
		1852	DLL . Note that this is the default if there
		1853	otherwise wouldn't be any exported symbols. When symbols are
		1854	explicitly exported via DEF files or
		1855	implicitly exported via function attributes, the default is
		1856	to not export anything else unless this option is given.
2	perry	1857	Note that the symbols !DllMain@12,
		1858	!DllEntryPoint@0, DllMainCRTStartup@12, and
1	perry	1859	impure_ptr will not be automatically exported.
		1860	Also, symbols imported from other DLLs will not be
		1861	re-exported, nor will symbols specifying the
		1862	DLL 's internal layout such as those
		1863	beginning with _head_ or ending with
		1864	_iname. In addition, no symbols from
		1865	libgcc, libstd++, libmingw32, or
		1866	crtX.o will be exported. Symbols whose names begin
		1867	with __rtti_ or __builtin_ will not be
		1868	exported, to help with C ++ DLLs. Finally,
		1869	there is an extensive list of cygwin-private symbols that
		1870	are not exported (obviously, this applies on when building
		1871	DLLs for cygwin targets). These cygwin-excludes are:
		1872	_cygwin_dll_entry@12,
		1873	_cygwin_crt0_common@8,
		1874	_cygwin_noncygwin_dll_entry@12, _fmode,
		1875	_impure_ptr, cygwin_attach_dll,
		1876	cygwin_premain0, cygwin_premain1,
		1877	cygwin_premain2, cygwin_premain3, and
		1878	environ.
		1879
		1880
		1881	__--exclude-symbols__
		1882	''symbol''__,__''symbol''__,...__
		1883
		1884
		1885	Specifies a list of symbols which should not be
		1886	automatically exported. The symbol names may be delimited by
		1887	commas or colons.
		1888
		1889
		1890	__--file-alignment__
		1891
		1892
		1893	Specify the file alignment. Sections in the file will always
		1894	begin at file offsets which are multiples of this number.
		1895	This defaults to 512.
		1896
		1897
		1898	__--heap__ ''reserve''
		1899
		1900
		1901	__--heap__
		1902	''reserve''__,__''commit''
		1903
		1904
		1905	Specify the amount of memory to reserve (and optionally
		1906	commit) to be used as heap for this program. The default is
		1907	1Mb reserved, 4K committed.
		1908
		1909
		1910	__--image-base__ ''value''
		1911
		1912
		1913	Use ''value'' as the base address of your program or dll.
		1914	This is the lowest memory location that will be used when
		1915	your program or dll is loaded. To reduce the need to
		1916	relocate and improve performance of your dlls, each should
		1917	have a unique base address and not overlap any other dlls.
		1918	The default is 0x400000 for executables, and 0x10000000 for
		1919	dlls.
		1920
		1921
		1922	__--kill-at__
		1923
		1924
		1925	If given, the stdcall suffixes (@''nn'') will be stripped
		1926	from symbols before they are exported.
		1927
		1928
		1929	__--major-image-version__ ''value''
		1930
		1931
		1932	Sets the major number of the ``image version''. Defaults to
		1933	1.
		1934
		1935
		1936	__--major-os-version__ ''value''
		1937
		1938
		1939	Sets the major number of the ``os version''. Defaults to
		1940	4.
		1941
		1942
		1943	__--major-subsystem-version__ ''value''
		1944
		1945
		1946	Sets the major number of the ``subsystem version''. Defaults
		1947	to 4.
		1948
		1949
		1950	__--minor-image-version__ ''value''
		1951
		1952
		1953	Sets the minor number of the ``image version''. Defaults to
		1954	0.
		1955
		1956
		1957	__--minor-os-version__ ''value''
		1958
		1959
		1960	Sets the minor number of the ``os version''. Defaults to
		1961	0.
		1962
		1963
		1964	__--minor-subsystem-version__ ''value''
		1965
		1966
		1967	Sets the minor number of the ``subsystem version''. Defaults
		1968	to 0.
		1969
		1970
		1971	__--output-def__ ''file''
		1972
		1973
		1974	The linker will create the file ''file'' which will
		1975	contain a DEF file corresponding to the
		1976	DLL the linker is generating. This
		1977	DEF file (which should be called
		1978	*.def) may be used to create an import library with
		1979	dlltool or may be used as a reference to
		1980	automatically or implicitly exported symbols.
		1981
		1982
		1983	__--out-implib__ ''file''
		1984
		1985
		1986	The linker will create the file ''file'' which will
		1987	contain an import lib corresponding to the
		1988	DLL the linker is generating. This import lib
		1989	(which should be called *.dll.a or *.a may
		1990	be used to link clients against the generated
		1991	DLL ; this behavior makes it possible to skip
		1992	a separate dlltool import library creation
		1993	step.
		1994
		1995
		1996	__--enable-auto-image-base__
		1997
		1998
		1999	Automatically choose the image base for DLLs, unless one is
		2000	specified using the --image-base argument. By using
		2001	a hash generated from the dllname to create unique image
		2002	bases for each DLL , in-memory collisions and
		2003	relocations which can delay program execution are
		2004	avoided.
		2005
		2006
		2007	__--disable-auto-image-base__
		2008
		2009
		2010	Do not automatically generate a unique image base. If there
		2011	is no user-specified image base (--image-base) then
		2012	use the platform default.
		2013
		2014
		2015	__--dll-search-prefix__ ''string''
		2016
		2017
		2018	When linking dynamically to a dll without an import library,
		2019	i search for in
		2020	preference to lib. This
		2021	behavior allows easy distinction between DLLs built for the
		2022	various ``subplatforms'': native, cygwin, uwin, pw, etc. For
		2023	instance, cygwin DLLs typically use
		2024	--dll-search-prefix=cyg.
		2025
		2026
		2027	__--enable-auto-import__
		2028
		2029
		2030	Do sophisticated linking of _symbol to
		2031	__imp__symbol for DATA imports from
		2032	DLLs, and create the necessary thunking symbols when
		2033	building the DLLs with those DATA exports.
		2034	This generally will 'just work' -- but sometimes you may see
		2035	this message:
		2036
		2037
		2038	--enable-auto-import for
		2039	details.
		2040
		2041
		2042	This message occurs when some (sub)expression accesses an
		2043	address ultimately given by the sum of two constants (Win32
		2044	import tables only allow one). Instances where this may
		2045	occur include accesses to member fields of struct variables
		2046	imported from a DLL , as well as using a
		2047	constant index into an array variable imported from a
		2048	DLL . Any multiword variable (arrays,
		2049	structs, long long, etc) may trigger this error condition.
		2050	However, regardless of the exact data type of the offending
		2051	exported variable, ld will always detect it, issue the
		2052	warning, and exit.
		2053
		2054
		2055	There are several ways to address this difficulty,
		2056	regardless of the data type of the exported
		2057	variable:
		2058
		2059
		2060	One solution is to force one of the 'constants' to be a
		2061	variable -- that is, unknown and un-optimizable at compile
		2062	time. For arrays, there are two possibilities: a) make the
		2063	indexee (the array's address) a variable, or b) make the
		2064	'constant' index a variable. Thus:
		2065
		2066
		2067	extern type extern_array[[];
		2068	extern_array[[1] --
		2069	or
		2070
		2071
		2072	extern type extern_array[[];
		2073	extern_array[[1] --
		2074	For structs (and most other multiword data types) the only option is to make the struct itself (or the long long, or the ...) variable:
		2075
		2076
		2077	extern struct s extern_struct;
		2078	extern_struct.field --
		2079	or
		2080
		2081
		2082	extern long long extern_ll;
		2083	extern_ll --
		2084	A second method of dealing with this difficulty is to abandon 'auto-import' for the offending symbol and mark it with __declspec(dllimport). However, in practice that requires using compile-time #defines to indicate whether you are building a DLL , building client code that will link to the DLL , or merely building/linking to a static library. In making the choice between the various methods of resolving the 'direct address with constant offset' problem, you should consider typical real-world usage:
		2085
		2086
		2087	Original:
		2088
		2089
		2090	--foo.h
		2091	extern int arr[[];
		2092	--foo.c
		2093	#include
		2094	Solution 1:
		2095
		2096
		2097	--foo.h
		2098	extern int arr[[];
		2099	--foo.c
		2100	#include
		2101	Solution 2:
		2102
		2103
		2104	--foo.h
		2105	/* Note: auto-export is assumed (no __declspec(dllexport)) */
		2106	#if (defined(_WIN32) defined(__CYGWIN__))
		2107	A third way to avoid this problem is to re-code your library to use a functional interface rather than a data interface for the offending variables (e.g. ''set_foo()'' and ''get_foo()'' accessor functions).
		2108
		2109
		2110	__--disable-auto-import__
		2111
		2112
		2113	Do not attempt to do sophisticalted linking of
		2114	_symbol to __imp__symbol for
		2115	DATA imports from DLLs.
		2116
		2117
		2118	__--enable-extra-pe-debug__
		2119
		2120
		2121	Show additional debug info related to auto-import symbol
		2122	thunking.
		2123
		2124
		2125	__--section-alignment__
		2126
		2127
		2128	Sets the section alignment. Sections in memory will always
		2129	begin at addresses which are a multiple of this number.
		2130	Defaults to 0x1000.
		2131
		2132
		2133	__--stack__ ''reserve''
		2134
		2135
		2136	__--stack__
		2137	''reserve''__,__''commit''
		2138
		2139
		2140	Specify the amount of memory to reserve (and optionally
		2141	commit) to be used as stack for this program. The default is
		2142	2Mb reserved, 4K committed.
		2143
		2144
		2145	__--subsystem__ ''which''
		2146
		2147
		2148	__--subsystem__
		2149	''which''__:__''major''
		2150
		2151
		2152	__--subsystem__
		2153	''which''__:__''major''__.__''minor''
		2154
		2155
		2156	Specifies the subsystem under which your program will
		2157	execute. The legal values for ''which'' are
		2158	native, windows, console, and
		2159	posix. You may optionally set the subsystem version
		2160	also.
		2161	!!ENVIRONMENT
		2162
		2163
		2164	You can change the behavior of __ld__ with the
		2165	environment variables GNUTARGET,
		2166	LDEMULATION, and
		2167	COLLECT_NO_DEMANGLE.
		2168
		2169
		2170	GNUTARGET determines the input-file object format
		2171	if you don't use __-b__ (or its synonym __--format__).
		2172	Its value should be one of the BFD names for
		2173	an input format. If there is no GNUTARGET in the
		2174	environment, __ld__ uses the natural format of the
		2175	target. If GNUTARGET is set to default
		2176	then BFD attempts to discover the input
		2177	format by examining binary input files; this method often
		2178	succeeds, but there are potential ambiguities, since there
		2179	is no method of ensuring that the magic number used to
		2180	specify object-file formats is unique. However, the
		2181	configuration procedure for BFD on each
		2182	system places the conventional format for that system first
		2183	in the search-list, so ambiguities are resolved in favor of
		2184	convention.
		2185
		2186
		2187	LDEMULATION determines the default emulation if you
		2188	don't use the __-m__ option. The emulation can affect
		2189	various aspects of linker behaviour, particularly the
		2190	default linker script. You can list the available emulations
		2191	with the __--verbose__ or __-V__ options. If the
		2192	__-m__ option is not used, and the LDEMULATION
		2193	environment variable is not defined, the default emulation
		2194	depends upon how the linker was configured.
		2195
		2196
		2197	Normally, the linker will default to demangling symbols.
		2198	However, if COLLECT_NO_DEMANGLE is set in the
		2199	environment, then it will default to not demangling symbols.
		2200	This environment variable is used in a similar fashion by
		2201	the gcc linker wrapper program. The default may be
		2202	overridden by the __--demangle__ and __--no-demangle__
		2203	options.
		2204	!!SEE ALSO
		2205
		2206
		2207	ar(1), nm(1), objcopy(1),
		2208	objdump(1), readelf(1) and the Info entries
		2209	for ''binutils'' and ''ld''.
		2210	!!COPYRIGHT
		2211
		2212
		2213	Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
		2214	2001 Free Software Foundation, Inc.
		2215
		2216
		2217	Permission is granted to copy, distribute and/or modify this
		2218	document under the terms of the GNU Free
		2219	Documentation License, Version 1.1 or any later version
		2220	published by the Free Software Foundation; with no Invariant
		2221	Sections, with no Front-Cover Texts, and with no Back-Cover
		2222	Texts. A copy of the license is included in the section
		2223	entitled `` GNU Free Documentation
		2224	License''.
		2225	----