1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
7675
7676
7677
7678
7679
7680
7681
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730
7731
7732
7733
7734
7735
7736
7737
7738
7739
7740
7741
7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
7752
7753
7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
7844
7845
7846
7847
7848
7849
7850
7851
7852
7853
7854
7855
7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895
7896
7897
7898
7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
7920
7921
7922
7923
7924
7925
7926
7927
7928
7929
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
7944
7945
7946
7947
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
8014
8015
8016
8017
8018
8019
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
8038
8039
8040
8041
8042
8043
8044
8045
8046
8047
8048
8049
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
8066
8067
8068
8069
8070
8071
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
8127
8128
8129
8130
8131
8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
8213
8214
8215
8216
8217
8218
8219
8220
8221
8222
8223
8224
8225
8226
8227
8228
8229
8230
8231
8232
8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
8249
8250
8251
8252
8253
8254
8255
8256
8257
8258
8259
8260
8261
8262
8263
8264
8265
8266
8267
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
8278
8279
8280
8281
8282
8283
8284
8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
8308
8309
8310
8311
8312
8313
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
8328
8329
8330
8331
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
8358
8359
8360
8361
8362
8363
8364
8365
8366
8367
8368
8369
8370
8371
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
8397
8398
8399
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
8561
8562
8563
8564
8565
8566
8567
8568
8569
8570
8571
8572
8573
8574
8575
8576
8577
8578
8579
8580
8581
8582
8583
8584
8585
8586
8587
8588
8589
8590
8591
8592
8593
8594
8595
8596
8597
8598
8599
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
8612
8613
8614
8615
8616
8617
8618
8619
8620
8621
8622
8623
8624
8625
8626
8627
8628
8629
8630
8631
8632
8633
8634
8635
8636
8637
8638
8639
8640
8641
8642
8643
8644
8645
8646
8647
8648
8649
8650
8651
8652
8653
8654
8655
8656
8657
8658
8659
8660
8661
8662
8663
8664
8665
8666
8667
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
8679
8680
8681
8682
8683
8684
8685
8686
8687
8688
8689
8690
8691
8692
8693
8694
8695
8696
8697
8698
8699
8700
8701
8702
8703
8704
8705
8706
8707
8708
8709
8710
8711
8712
8713
8714
8715
8716
8717
8718
8719
8720
8721
8722
8723
8724
8725
8726
8727
8728
8729
8730
8731
8732
8733
8734
8735
8736
8737
8738
8739
8740
8741
8742
8743
8744
8745
8746
8747
8748
8749
8750
8751
8752
8753
8754
8755
8756
8757
8758
8759
8760
8761
8762
8763
8764
8765
8766
8767
8768
8769
8770
8771
8772
8773
8774
8775
8776
8777
8778
8779
8780
8781
8782
8783
8784
8785
8786
8787
8788
8789
8790
8791
8792
8793
8794
8795
8796
8797
8798
8799
8800
8801
8802
8803
8804
8805
8806
8807
8808
8809
8810
8811
8812
8813
8814
8815
8816
8817
8818
8819
8820
8821
8822
8823
8824
8825
8826
8827
8828
8829
8830
8831
8832
8833
8834
8835
8836
8837
8838
8839
8840
8841
8842
8843
8844
8845
8846
8847
8848
8849
8850
8851
8852
8853
8854
8855
8856
8857
8858
8859
8860
8861
8862
8863
8864
8865
8866
8867
8868
8869
8870
8871
8872
8873
8874
8875
8876
8877
8878
8879
8880
8881
8882
8883
8884
8885
8886
8887
8888
8889
8890
8891
8892
8893
8894
8895
8896
8897
8898
8899
8900
8901
8902
8903
8904
8905
8906
8907
8908
8909
8910
8911
8912
8913
8914
8915
8916
8917
8918
8919
8920
8921
8922
8923
8924
8925
8926
8927
8928
8929
8930
8931
8932
8933
8934
8935
8936
8937
8938
8939
8940
8941
8942
8943
8944
8945
8946
8947
8948
8949
8950
8951
8952
8953
8954
8955
8956
8957
8958
8959
8960
8961
8962
8963
8964
8965
8966
8967
8968
8969
8970
8971
8972
8973
8974
8975
8976
8977
8978
8979
8980
8981
8982
8983
8984
8985
8986
8987
8988
8989
8990
8991
8992
8993
8994
8995
8996
8997
8998
8999
9000
9001
9002
9003
9004
9005
9006
9007
9008
9009
9010
9011
9012
9013
9014
9015
9016
9017
9018
9019
9020
9021
9022
9023
9024
9025
9026
9027
9028
9029
9030
9031
9032
9033
9034
9035
9036
9037
9038
9039
9040
9041
9042
9043
9044
9045
9046
9047
9048
9049
9050
9051
9052
9053
9054
9055
9056
9057
9058
9059
9060
9061
9062
9063
9064
9065
9066
9067
9068
9069
9070
9071
9072
9073
9074
9075
9076
9077
9078
9079
9080
9081
9082
9083
9084
9085
9086
9087
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
9102
9103
9104
9105
9106
9107
9108
9109
9110
9111
9112
9113
9114
9115
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
9126
9127
9128
9129
9130
9131
9132
9133
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
9148
9149
9150
9151
9152
9153
9154
9155
9156
9157
9158
9159
9160
9161
9162
9163
9164
9165
9166
9167
9168
9169
9170
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
9182
9183
9184
9185
9186
9187
9188
9189
9190
9191
9192
9193
9194
9195
9196
9197
9198
9199
9200
9201
9202
9203
9204
9205
9206
9207
9208
9209
9210
9211
9212
9213
9214
9215
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
9226
9227
9228
9229
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
9241
9242
9243
9244
9245
9246
9247
9248
9249
9250
9251
9252
9253
9254
9255
9256
9257
9258
9259
9260
9261
9262
9263
9264
9265
9266
9267
9268
9269
9270
9271
9272
9273
9274
9275
9276
9277
9278
9279
9280
9281
9282
9283
9284
9285
9286
9287
9288
9289
9290
9291
9292
9293
9294
9295
9296
9297
9298
9299
9300
9301
9302
9303
9304
9305
9306
9307
9308
9309
9310
9311
9312
9313
9314
9315
9316
9317
9318
9319
9320
9321
9322
9323
9324
9325
9326
9327
9328
9329
9330
9331
9332
9333
9334
9335
9336
9337
9338
9339
9340
9341
9342
9343
9344
9345
9346
9347
9348
9349
9350
9351
9352
9353
9354
9355
9356
9357
9358
9359
9360
9361
9362
9363
9364
9365
9366
9367
9368
9369
9370
9371
9372
9373
9374
9375
9376
9377
9378
9379
9380
9381
9382
9383
9384
9385
9386
9387
9388
9389
9390
9391
9392
9393
9394
9395
9396
9397
9398
9399
9400
9401
9402
9403
9404
9405
9406
9407
9408
9409
9410
9411
9412
9413
9414
9415
9416
9417
9418
9419
9420
9421
9422
9423
9424
9425
9426
9427
9428
9429
9430
9431
9432
9433
9434
9435
9436
9437
9438
9439
9440
9441
9442
9443
9444
9445
9446
9447
9448
9449
9450
9451
9452
9453
9454
|
\input texinfo
@setfilename ld.info
@c Copyright (C) 1991-2023 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
@include bfdver.texi
@c man end
@c @smallbook
@macro gcctabopt{body}
@code{\body\}
@end macro
@c man begin NAME
@ifset man
@c Configure for the generation of man pages
@set UsesEnvVars
@set GENERIC
@set ARM
@set C6X
@set CSKY
@set H8300
@set HPPA
@set M68HC11
@set M68K
@set MIPS
@set MMIX
@set MSP430
@set NDS32
@set NIOSII
@set PDP11
@set POWERPC
@set POWERPC64
@set Renesas
@set S/390
@set SPU
@set TICOFF
@set WIN32
@set XTENSA
@end ifset
@c man end
@ifnottex
@dircategory Software development
@direntry
* Ld: (ld). The GNU linker.
@end direntry
@end ifnottex
@copying
This file documents the @sc{gnu} linker LD
@ifset VERSION_PACKAGE
@value{VERSION_PACKAGE}
@end ifset
version @value{VERSION}.
Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@end copying
@iftex
@finalout
@setchapternewpage odd
@settitle The GNU linker
@titlepage
@title The GNU linker
@sp 1
@subtitle @code{ld}
@ifset VERSION_PACKAGE
@subtitle @value{VERSION_PACKAGE}
@end ifset
@subtitle Version @value{VERSION}
@author Steve Chamberlain
@author Ian Lance Taylor
@page
@tex
{\parskip=0pt
\hfill Red Hat Inc\par
\hfill nickc\@credhat.com, doc\@redhat.com\par
\hfill {\it The GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
\global\parindent=0pt % Steve likes it this way.
@end tex
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
@c man end
@end titlepage
@end iftex
@contents
@c FIXME: Talk about importance of *order* of args, cmds to linker!
@ifnottex
@node Top
@top LD
This file documents the @sc{gnu} linker ld
@ifset VERSION_PACKAGE
@value{VERSION_PACKAGE}
@end ifset
version @value{VERSION}.
This document is distributed under the terms of the GNU Free
Documentation License version 1.3. A copy of the license is included
in the section entitled ``GNU Free Documentation License''.
@menu
* Overview:: Overview
* Invocation:: Invocation
* Scripts:: Linker Scripts
* Plugins:: Linker Plugins
@ifset GENERIC
* Machine Dependent:: Machine Dependent Features
@end ifset
@ifclear GENERIC
@ifset H8300
* H8/300:: ld and the H8/300
@end ifset
@ifset Renesas
* Renesas:: ld and other Renesas micros
@end ifset
@ifset ARM
* ARM:: ld and the ARM family
@end ifset
@ifset M68HC11
* M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
@end ifset
@ifset HPPA
* HPPA ELF32:: ld and HPPA 32-bit ELF
@end ifset
@ifset M68K
* M68K:: ld and Motorola 68K family
@end ifset
@ifset MIPS
* MIPS:: ld and MIPS family
@end ifset
@ifset POWERPC
* PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
@end ifset
@ifset POWERPC64
* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
@end ifset
@ifset S/390
* S/390 ELF:: ld and S/390 ELF Support
@end ifset
@ifset SPU
* SPU ELF:: ld and SPU ELF Support
@end ifset
@ifset TICOFF
* TI COFF:: ld and the TI COFF
@end ifset
@ifset WIN32
* Win32:: ld and WIN32 (cygwin/mingw)
@end ifset
@ifset XTENSA
* Xtensa:: ld and Xtensa Processors
@end ifset
@end ifclear
@ifclear SingleFormat
* BFD:: BFD
@end ifclear
@c Following blank line required for remaining bug in makeinfo conds/menus
* Reporting Bugs:: Reporting Bugs
* MRI:: MRI Compatible Script Files
* GNU Free Documentation License:: GNU Free Documentation License
* LD Index:: LD Index
@end menu
@end ifnottex
@node Overview
@chapter Overview
@cindex @sc{gnu} linker
@cindex what is this?
@ifset man
@c man begin SYNOPSIS
ld [@b{options}] @var{objfile} @dots{}
@c man end
@c man begin SEEALSO
ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
the Info entries for @file{binutils} and
@file{ld}.
@c man end
@end ifset
@c man begin DESCRIPTION
@command{ld} combines a number of object and archive files, relocates
their data and ties up symbol references. Usually the last step in
compiling a program is to run @command{ld}.
@command{ld} accepts Linker Command Language files written in
a superset of AT&T's Link Editor Command Language syntax,
to provide explicit and total control over the linking process.
@ifset man
@c For the man only
This man page does not describe the command language; see the
@command{ld} entry in @code{info} for full details on the command
language and on other aspects of the GNU linker.
@end ifset
@ifclear SingleFormat
This version of @command{ld} uses the general purpose BFD libraries
to operate on object files. This allows @command{ld} to read, combine, and
write object files in many different formats---for example, COFF or
@code{a.out}. Different formats may be linked together to produce any
available kind of object file. @xref{BFD}, for more information.
@end ifclear
Aside from its flexibility, the @sc{gnu} linker is more helpful than other
linkers in providing diagnostic information. Many linkers abandon
execution immediately upon encountering an error; whenever possible,
@command{ld} continues executing, allowing you to identify other errors
(or, in some cases, to get an output file in spite of the error).
@c man end
@node Invocation
@chapter Invocation
@c man begin DESCRIPTION
The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
and to be as compatible as possible with other linkers. As a result,
you have many choices to control its behavior.
@c man end
@ifset UsesEnvVars
@menu
* Options:: Command-line Options
* Environment:: Environment Variables
@end menu
@node Options
@section Command-line Options
@end ifset
@cindex command line
@cindex options
@c man begin OPTIONS
The linker supports a plethora of command-line options, but in actual
practice few of them are used in any particular context.
@cindex standard Unix system
For instance, a frequent use of @command{ld} is to link standard Unix
object files on a standard, supported Unix system. On such a system, to
link a file @code{hello.o}:
@smallexample
ld -o @var{output} /lib/crt0.o hello.o -lc
@end smallexample
This tells @command{ld} to produce a file called @var{output} as the
result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
the library @code{libc.a}, which will come from the standard search
directories. (See the discussion of the @samp{-l} option below.)
Some of the command-line options to @command{ld} may be specified at any
point in the command line. However, options which refer to files, such
as @samp{-l} or @samp{-T}, cause the file to be read at the point at
which the option appears in the command line, relative to the object
files and other file options. Repeating non-file options with a
different argument will either have no further effect, or override prior
occurrences (those further to the left on the command line) of that
option. Options which may be meaningfully specified more than once are
noted in the descriptions below.
@cindex object files
Non-option arguments are object files or archives which are to be linked
together. They may follow, precede, or be mixed in with command-line
options, except that an object file argument may not be placed between
an option and its argument.
Usually the linker is invoked with at least one object file, but you can
specify other forms of binary input files using @samp{-l}, @samp{-R},
and the script command language. If @emph{no} binary input files at all
are specified, the linker does not produce any output, and issues the
message @samp{No input files}.
If the linker cannot recognize the format of an object file, it will
assume that it is a linker script. A script specified in this way
augments the main linker script used for the link (either the default
linker script or the one specified by using @samp{-T}). This feature
permits the linker to link against a file which appears to be an object
or an archive, but actually merely defines some symbol values, or uses
@code{INPUT} or @code{GROUP} to load other objects. Specifying a
script in this way merely augments the main linker script, with the
extra commands placed after the main script; use the @samp{-T} option
to replace the default linker script entirely, but note the effect of
the @code{INSERT} command. @xref{Scripts}.
For options whose names are a single letter,
option arguments must either follow the option letter without intervening
whitespace, or be given as separate arguments immediately following the
option that requires them.
For options whose names are multiple letters, either one dash or two can
precede the option name; for example, @samp{-trace-symbol} and
@samp{--trace-symbol} are equivalent. Note---there is one exception to
this rule. Multiple letter options that start with a lower case 'o' can
only be preceded by two dashes. This is to reduce confusion with the
@samp{-o} option. So for example @samp{-omagic} sets the output file
name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
output.
Arguments to multiple-letter options must either be separated from the
option name by an equals sign, or be given as separate arguments
immediately following the option that requires them. For example,
@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
Unique abbreviations of the names of multiple-letter options are
accepted.
Note---if the linker is being invoked indirectly, via a compiler driver
(e.g. @samp{gcc}) then all the linker command-line options should be
prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
compiler driver) like this:
@smallexample
gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
@end smallexample
This is important, because otherwise the compiler driver program may
silently drop the linker options, resulting in a bad link. Confusion
may also arise when passing options that require values through a
driver, as the use of a space between option and argument acts as
a separator, and causes the driver to pass only the option to the linker
and the argument to the compiler. In this case, it is simplest to use
the joined forms of both single- and multiple-letter options, such as:
@smallexample
gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
@end smallexample
Here is a table of the generic command-line switches accepted by the GNU
linker:
@table @gcctabopt
@include at-file.texi
@kindex -a @var{keyword}
@item -a @var{keyword}
This option is supported for HP/UX compatibility. The @var{keyword}
argument must be one of the strings @samp{archive}, @samp{shared}, or
@samp{default}. @samp{-aarchive} is functionally equivalent to
@samp{-Bstatic}, and the other two keywords are functionally equivalent
to @samp{-Bdynamic}. This option may be used any number of times.
@kindex --audit @var{AUDITLIB}
@item --audit @var{AUDITLIB}
Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
specified in the library. If specified multiple times @code{DT_AUDIT}
will contain a colon separated list of audit interfaces to use. If the linker
finds an object with an audit entry while searching for shared libraries,
it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
This option is only meaningful on ELF platforms supporting the rtld-audit
interface.
@ifclear SingleFormat
@cindex binary input format
@kindex -b @var{format}
@kindex --format=@var{format}
@cindex input format
@cindex input format
@item -b @var{input-format}
@itemx --format=@var{input-format}
@command{ld} may be configured to support more than one kind of object
file. If your @command{ld} is configured this way, you can use the
@samp{-b} option to specify the binary format for input object files
that follow this option on the command line. Even when @command{ld} is
configured to support alternative object formats, you don't usually need
to specify this, as @command{ld} should be configured to expect as a
default input format the most usual format on each machine.
@var{input-format} is a text string, the name of a particular format
supported by the BFD libraries. (You can list the available binary
formats with @samp{objdump -i}.)
@xref{BFD}.
You may want to use this option if you are linking files with an unusual
binary format. You can also use @samp{-b} to switch formats explicitly (when
linking object files of different formats), by including
@samp{-b @var{input-format}} before each group of object files in a
particular format.
The default format is taken from the environment variable
@code{GNUTARGET}.
@ifset UsesEnvVars
@xref{Environment}.
@end ifset
You can also define the input format from a script, using the command
@code{TARGET};
@ifclear man
see @ref{Format Commands}.
@end ifclear
@end ifclear
@kindex -c @var{MRI-cmdfile}
@kindex --mri-script=@var{MRI-cmdfile}
@cindex compatibility, MRI
@item -c @var{MRI-commandfile}
@itemx --mri-script=@var{MRI-commandfile}
For compatibility with linkers produced by MRI, @command{ld} accepts script
files written in an alternate, restricted command language, described in
@ifclear man
@ref{MRI,,MRI Compatible Script Files}.
@end ifclear
@ifset man
the MRI Compatible Script Files section of GNU ld documentation.
@end ifset
Introduce MRI script files with
the option @samp{-c}; use the @samp{-T} option to run linker
scripts written in the general-purpose @command{ld} scripting language.
If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
specified by any @samp{-L} options.
@cindex common allocation
@kindex -d
@kindex -dc
@kindex -dp
@item -d
@itemx -dc
@itemx -dp
These three options are equivalent; multiple forms are supported for
compatibility with other linkers. They assign space to common symbols
even if a relocatable output file is specified (with @samp{-r}). The
script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
@xref{Miscellaneous Commands}.
@kindex --depaudit @var{AUDITLIB}
@kindex -P @var{AUDITLIB}
@item --depaudit @var{AUDITLIB}
@itemx -P @var{AUDITLIB}
Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
specified in the library. If specified multiple times @code{DT_DEPAUDIT}
will contain a colon separated list of audit interfaces to use. This
option is only meaningful on ELF platforms supporting the rtld-audit interface.
The -P option is provided for Solaris compatibility.
@kindex --enable-non-contiguous-regions
@item --enable-non-contiguous-regions
This option avoids generating an error if an input section does not
fit a matching output section. The linker tries to allocate the input
section to subseque nt matching output sections, and generates an
error only if no output section is large enough. This is useful when
several non-contiguous memory regions are available and the input
section does not require a particular one. The order in which input
sections are evaluated does not change, for instance:
@smallexample
MEMORY @{
MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14
MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40
MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40
@}
SECTIONS @{
mem1 : @{ *(.data.*); @} > MEM1
mem2 : @{ *(.data.*); @} > MEM2
mem3 : @{ *(.data.*); @} > MEM2
@}
with input sections:
.data.1: size 8
.data.2: size 0x10
.data.3: size 4
results in .data.1 affected to mem1, and .data.2 and .data.3
affected to mem2, even though .data.3 would fit in mem3.
@end smallexample
This option is incompatible with INSERT statements because it changes
the way input sections are mapped to output sections.
@kindex --enable-non-contiguous-regions-warnings
@item --enable-non-contiguous-regions-warnings
This option enables warnings when
@code{--enable-non-contiguous-regions} allows possibly unexpected
matches in sections mapping, potentially leading to silently
discarding a section instead of failing because it does not fit any
output region.
@cindex entry point, from command line
@kindex -e @var{entry}
@kindex --entry=@var{entry}
@item -e @var{entry}
@itemx --entry=@var{entry}
Use @var{entry} as the explicit symbol for beginning execution of your
program, rather than the default entry point. If there is no symbol
named @var{entry}, the linker will try to parse @var{entry} as a number,
and use that as the entry address (the number will be interpreted in
base 10; you may use a leading @samp{0x} for base 16, or a leading
@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
and other ways of specifying the entry point.
@kindex --exclude-libs
@item --exclude-libs @var{lib},@var{lib},...
Specifies a list of archive libraries from which symbols should not be automatically
exported. The library names may be delimited by commas or colons. Specifying
@code{--exclude-libs ALL} excludes symbols in all archive libraries from
automatic export. This option is available only for the i386 PE targeted
port of the linker and for ELF targeted ports. For i386 PE, symbols
explicitly listed in a .def file are still exported, regardless of this
option. For ELF targeted ports, symbols affected by this option will
be treated as hidden.
@kindex --exclude-modules-for-implib
@item --exclude-modules-for-implib @var{module},@var{module},...
Specifies a list of object files or archive members, from which symbols
should not be automatically exported, but which should be copied wholesale
into the import library being generated during the link. The module names
may be delimited by commas or colons, and must match exactly the filenames
used by @command{ld} to open the files; for archive members, this is simply
the member name, but for object files the name listed must include and
match precisely any path used to specify the input file on the linker's
command-line. This option is available only for the i386 PE targeted port
of the linker. Symbols explicitly listed in a .def file are still exported,
regardless of this option.
@cindex dynamic symbol table
@kindex -E
@kindex --export-dynamic
@kindex --no-export-dynamic
@item -E
@itemx --export-dynamic
@itemx --no-export-dynamic
When creating a dynamically linked executable, using the @option{-E}
option or the @option{--export-dynamic} option causes the linker to add
all symbols to the dynamic symbol table. The dynamic symbol table is the
set of symbols which are visible from dynamic objects at run time.
If you do not use either of these options (or use the
@option{--no-export-dynamic} option to restore the default behavior), the
dynamic symbol table will normally contain only those symbols which are
referenced by some dynamic object mentioned in the link.
If you use @code{dlopen} to load a dynamic object which needs to refer
back to the symbols defined by the program, rather than some other
dynamic object, then you will probably need to use this option when
linking the program itself.
You can also use the dynamic list to control what symbols should
be added to the dynamic symbol table if the output format supports it.
See the description of @samp{--dynamic-list}.
Note that this option is specific to ELF targeted ports. PE targets
support a similar function to export all symbols from a DLL or EXE; see
the description of @samp{--export-all-symbols} below.
@kindex --export-dynamic-symbol=@var{glob}
@cindex export dynamic symbol
@item --export-dynamic-symbol=@var{glob}
When creating a dynamically linked executable, symbols matching
@var{glob} will be added to the dynamic symbol table. When creating a
shared library, references to symbols matching @var{glob} will not be
bound to the definitions within the shared library. This option is a
no-op when creating a shared library and @samp{-Bsymbolic} or
@samp{--dynamic-list} are not specified. This option is only meaningful
on ELF platforms which support shared libraries.
@kindex --export-dynamic-symbol-list=@var{file}
@cindex export dynamic symbol list
@item --export-dynamic-symbol-list=@var{file}
Specify a @samp{--export-dynamic-symbol} for each pattern in the file.
The format of the file is the same as the version node without
scope and node name. See @ref{VERSION} for more information.
@ifclear SingleFormat
@cindex big-endian objects
@cindex endianness
@kindex -EB
@item -EB
Link big-endian objects. This affects the default output format.
@cindex little-endian objects
@kindex -EL
@item -EL
Link little-endian objects. This affects the default output format.
@end ifclear
@kindex -f @var{name}
@kindex --auxiliary=@var{name}
@item -f @var{name}
@itemx --auxiliary=@var{name}
When creating an ELF shared object, set the internal DT_AUXILIARY field
to the specified name. This tells the dynamic linker that the symbol
table of the shared object should be used as an auxiliary filter on the
symbol table of the shared object @var{name}.
If you later link a program against this filter object, then, when you
run the program, the dynamic linker will see the DT_AUXILIARY field. If
the dynamic linker resolves any symbols from the filter object, it will
first check whether there is a definition in the shared object
@var{name}. If there is one, it will be used instead of the definition
in the filter object. The shared object @var{name} need not exist.
Thus the shared object @var{name} may be used to provide an alternative
implementation of certain functions, perhaps for debugging or for
machine-specific performance.
This option may be specified more than once. The DT_AUXILIARY entries
will be created in the order in which they appear on the command line.
@kindex -F @var{name}
@kindex --filter=@var{name}
@item -F @var{name}
@itemx --filter=@var{name}
When creating an ELF shared object, set the internal DT_FILTER field to
the specified name. This tells the dynamic linker that the symbol table
of the shared object which is being created should be used as a filter
on the symbol table of the shared object @var{name}.
If you later link a program against this filter object, then, when you
run the program, the dynamic linker will see the DT_FILTER field. The
dynamic linker will resolve symbols according to the symbol table of the
filter object as usual, but it will actually link to the definitions
found in the shared object @var{name}. Thus the filter object can be
used to select a subset of the symbols provided by the object
@var{name}.
Some older linkers used the @option{-F} option throughout a compilation
toolchain for specifying object-file format for both input and output
object files.
@ifclear SingleFormat
The @sc{gnu} linker uses other mechanisms for this purpose: the
@option{-b}, @option{--format}, @option{--oformat} options, the
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
environment variable.
@end ifclear
The @sc{gnu} linker will ignore the @option{-F} option when not
creating an ELF shared object.
@cindex finalization function
@kindex -fini=@var{name}
@item -fini=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is unloaded, by setting DT_FINI to the
address of the function. By default, the linker uses @code{_fini} as
the function to call.
@kindex -g
@item -g
Ignored. Provided for compatibility with other tools.
@kindex -G @var{value}
@kindex --gpsize=@var{value}
@cindex object size
@item -G @var{value}
@itemx --gpsize=@var{value}
Set the maximum size of objects to be optimized using the GP register to
@var{size}. This is only meaningful for object file formats such as
MIPS ELF that support putting large and small objects into different
sections. This is ignored for other object file formats.
@cindex runtime library name
@kindex -h @var{name}
@kindex -soname=@var{name}
@item -h @var{name}
@itemx -soname=@var{name}
When creating an ELF shared object, set the internal DT_SONAME field to
the specified name. When an executable is linked with a shared object
which has a DT_SONAME field, then when the executable is run the dynamic
linker will attempt to load the shared object specified by the DT_SONAME
field rather than using the file name given to the linker.
@kindex -i
@cindex incremental link
@item -i
Perform an incremental link (same as option @samp{-r}).
@cindex initialization function
@kindex -init=@var{name}
@item -init=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is loaded, by setting DT_INIT to the address
of the function. By default, the linker uses @code{_init} as the
function to call.
@cindex archive files, from cmd line
@kindex -l @var{namespec}
@kindex --library=@var{namespec}
@item -l @var{namespec}
@itemx --library=@var{namespec}
Add the archive or object file specified by @var{namespec} to the
list of files to link. This option may be used any number of times.
If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
will search the library path for a file called @var{filename}, otherwise it
will search the library path for a file called @file{lib@var{namespec}.a}.
On systems which support shared libraries, @command{ld} may also search for
files other than @file{lib@var{namespec}.a}. Specifically, on ELF
and SunOS systems, @command{ld} will search a directory for a library
called @file{lib@var{namespec}.so} before searching for one called
@file{lib@var{namespec}.a}. (By convention, a @code{.so} extension
indicates a shared library.) Note that this behavior does not apply
to @file{:@var{filename}}, which always specifies a file called
@var{filename}.
The linker will search an archive only once, at the location where it is
specified on the command line. If the archive defines a symbol which
was undefined in some object which appeared before the archive on the
command line, the linker will include the appropriate file(s) from the
archive. However, an undefined symbol in an object appearing later on
the command line will not cause the linker to search the archive again.
See the @option{-(} option for a way to force the linker to search
archives multiple times.
You may list the same archive multiple times on the command line.
@ifset GENERIC
This type of archive searching is standard for Unix linkers. However,
if you are using @command{ld} on AIX, note that it is different from the
behaviour of the AIX linker.
@end ifset
@cindex search directory, from cmd line
@kindex -L @var{dir}
@kindex --library-path=@var{dir}
@item -L @var{searchdir}
@itemx --library-path=@var{searchdir}
Add path @var{searchdir} to the list of paths that @command{ld} will search
for archive libraries and @command{ld} control scripts. You may use this
option any number of times. The directories are searched in the order
in which they are specified on the command line. Directories specified
on the command line are searched before the default directories. All
@option{-L} options apply to all @option{-l} options, regardless of the
order in which the options appear. @option{-L} options do not affect
how @command{ld} searches for a linker script unless @option{-T}
option is specified.
If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
@samp{--sysroot} option, or specified when the linker is configured.
@ifset UsesEnvVars
The default set of paths searched (without being specified with
@samp{-L}) depends on which emulation mode @command{ld} is using, and in
some cases also on how it was configured. @xref{Environment}.
@end ifset
The paths can also be specified in a link script with the
@code{SEARCH_DIR} command. Directories specified this way are searched
at the point in which the linker script appears in the command line.
@cindex emulation
@kindex -m @var{emulation}
@item -m @var{emulation}
Emulate the @var{emulation} linker. You can list the available
emulations with the @samp{--verbose} or @samp{-V} options.
If the @samp{-m} option is not used, the emulation is taken from the
@code{LDEMULATION} environment variable, if that is defined.
Otherwise, the default emulation depends upon how the linker was
configured.
@cindex link map
@kindex -M
@kindex --print-map
@item -M
@itemx --print-map
Print a link map to the standard output. A link map provides
information about the link, including the following:
@itemize @bullet
@item
Where object files are mapped into memory.
@item
How common symbols are allocated.
@item
All archive members included in the link, with a mention of the symbol
which caused the archive member to be brought in.
@item
The values assigned to symbols.
Note - symbols whose values are computed by an expression which
involves a reference to a previous value of the same symbol may not
have correct result displayed in the link map. This is because the
linker discards intermediate results and only retains the final value
of an expression. Under such circumstances the linker will display
the final value enclosed by square brackets. Thus for example a
linker script containing:
@smallexample
foo = 1
foo = foo * 4
foo = foo + 8
@end smallexample
will produce the following output in the link map if the @option{-M}
option is used:
@smallexample
0x00000001 foo = 0x1
[0x0000000c] foo = (foo * 0x4)
[0x0000000c] foo = (foo + 0x8)
@end smallexample
See @ref{Expressions} for more information about expressions in linker
scripts.
@item
How GNU properties are merged.
When the linker merges input .note.gnu.property sections into one output
.note.gnu.property section, some properties are removed or updated.
These actions are reported in the link map. For example:
@smallexample
Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
@end smallexample
This indicates that property 0xc0000002 is removed from output when
merging properties in @file{foo.o}, whose property 0xc0000002 value
is 0x1, and @file{bar.o}, which doesn't have property 0xc0000002.
@smallexample
Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
@end smallexample
This indicates that property 0xc0010001 value is updated to 0x1 in output
when merging properties in @file{foo.o}, whose 0xc0010001 property value
is 0x1, and @file{bar.o}, whose 0xc0010001 property value is 0x1.
@end itemize
@cindex link map discarded
@kindex --print-map-discarded
@kindex --no-print-map-discarded
@item --print-map-discarded
@itemx --no-print-map-discarded
Print (or do not print) the list of discarded and garbage collected sections
in the link map. Enabled by default.
@kindex -n
@cindex read-only text
@cindex NMAGIC
@kindex --nmagic
@item -n
@itemx --nmagic
Turn off page alignment of sections, and disable linking against shared
libraries. If the output format supports Unix style magic numbers,
mark the output as @code{NMAGIC}.
@kindex -N
@kindex --omagic
@cindex read/write from cmd line
@cindex OMAGIC
@item -N
@itemx --omagic
Set the text and data sections to be readable and writable. Also, do
not page-align the data segment, and disable linking against shared
libraries. If the output format supports Unix style magic numbers,
mark the output as @code{OMAGIC}. Note: Although a writable text section
is allowed for PE-COFF targets, it does not conform to the format
specification published by Microsoft.
@kindex --no-omagic
@cindex OMAGIC
@item --no-omagic
This option negates most of the effects of the @option{-N} option. It
sets the text section to be read-only, and forces the data segment to
be page-aligned. Note - this option does not enable linking against
shared libraries. Use @option{-Bdynamic} for this.
@kindex -o @var{output}
@kindex --output=@var{output}
@cindex naming the output file
@item -o @var{output}
@itemx --output=@var{output}
Use @var{output} as the name for the program produced by @command{ld}; if this
option is not specified, the name @file{a.out} is used by default. The
script command @code{OUTPUT} can also specify the output file name.
@kindex --dependency-file=@var{depfile}
@cindex dependency file
@item --dependency-file=@var{depfile}
Write a @dfn{dependency file} to @var{depfile}. This file contains a rule
suitable for @code{make} describing the output file and all the input files
that were read to produce it. The output is similar to the compiler's
output with @samp{-M -MP} (@pxref{Preprocessor Options,, Options
Controlling the Preprocessor, gcc.info, Using the GNU Compiler
Collection}). Note that there is no option like the compiler's @samp{-MM},
to exclude ``system files'' (which is not a well-specified concept in the
linker, unlike ``system headers'' in the compiler). So the output from
@samp{--dependency-file} is always specific to the exact state of the
installation where it was produced, and should not be copied into
distributed makefiles without careful editing.
@kindex -O @var{level}
@cindex generating optimized output
@item -O @var{level}
If @var{level} is a numeric values greater than zero @command{ld} optimizes
the output. This might take significantly longer and therefore probably
should only be enabled for the final binary. At the moment this
option only affects ELF shared library generation. Future releases of
the linker may make more use of this option. Also currently there is
no difference in the linker's behaviour for different non-zero values
of this option. Again this may change with future releases.
@kindex -plugin @var{name}
@item -plugin @var{name}
Involve a plugin in the linking process. The @var{name} parameter is
the absolute filename of the plugin. Usually this parameter is
automatically added by the complier, when using link time
optimization, but users can also add their own plugins if they so
wish.
Note that the location of the compiler originated plugins is different
from the place where the @command{ar}, @command{nm} and
@command{ranlib} programs search for their plugins. In order for
those commands to make use of a compiler based plugin it must first be
copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc
based linker plugins are backward compatible, so it is sufficient to
just copy in the newest one.
@kindex --push-state
@cindex push state governing input file handling
@item --push-state
The @option{--push-state} allows one to preserve the current state of the
flags which govern the input file handling so that they can all be
restored with one corresponding @option{--pop-state} option.
The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
@option{--no-whole-archive}, @option{-r}, @option{-Ur},
@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
@option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
One target for this option are specifications for @file{pkg-config}. When
used with the @option{--libs} option all possibly needed libraries are
listed and then possibly linked with all the time. It is better to return
something as follows:
@smallexample
-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
@end smallexample
@kindex --pop-state
@cindex pop state governing input file handling
@item --pop-state
Undoes the effect of --push-state, restores the previous values of the
flags governing input file handling.
@kindex -q
@kindex --emit-relocs
@cindex retain relocations in final executable
@item -q
@itemx --emit-relocs
Leave relocation sections and contents in fully linked executables.
Post link analysis and optimization tools may need this information in
order to perform correct modifications of executables. This results
in larger executables.
This option is currently only supported on ELF platforms.
@kindex --force-dynamic
@cindex forcing the creation of dynamic sections
@item --force-dynamic
Force the output file to have dynamic sections. This option is specific
to VxWorks targets.
@cindex partial link
@cindex relocatable output
@kindex -r
@kindex --relocatable
@item -r
@itemx --relocatable
Generate relocatable output---i.e., generate an output file that can in
turn serve as input to @command{ld}. This is often called @dfn{partial
linking}. As a side effect, in environments that support standard Unix
magic numbers, this option also sets the output file's magic number to
@code{OMAGIC}.
@c ; see @option{-N}.
If this option is not specified, an absolute file is produced. When
linking C++ programs, this option @emph{will not} resolve references to
constructors; to do that, use @samp{-Ur}.
When an input file does not have the same format as the output file,
partial linking is only supported if that input file does not contain any
relocations. Different output formats can have further restrictions; for
example some @code{a.out}-based formats do not support partial linking
with input files in other formats at all.
This option does the same thing as @samp{-i}.
@kindex -R @var{file}
@kindex --just-symbols=@var{file}
@cindex symbol-only input
@item -R @var{filename}
@itemx --just-symbols=@var{filename}
Read symbol names and their addresses from @var{filename}, but do not
relocate it or include it in the output. This allows your output file
to refer symbolically to absolute locations of memory defined in other
programs. You may use this option more than once.
For compatibility with other ELF linkers, if the @option{-R} option is
followed by a directory name, rather than a file name, it is treated as
the @option{-rpath} option.
@kindex -s
@kindex --strip-all
@cindex strip all symbols
@item -s
@itemx --strip-all
Omit all symbol information from the output file.
@kindex -S
@kindex --strip-debug
@cindex strip debugger symbols
@item -S
@itemx --strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
@kindex --strip-discarded
@kindex --no-strip-discarded
@item --strip-discarded
@itemx --no-strip-discarded
Omit (or do not omit) global symbols defined in discarded sections.
Enabled by default.
@kindex -t
@kindex --trace
@cindex input files, displaying
@item -t
@itemx --trace
Print the names of the input files as @command{ld} processes them. If
@samp{-t} is given twice then members within archives are also printed.
@samp{-t} output is useful to generate a list of all the object files
and scripts involved in linking, for example, when packaging files for
a linker bug report.
@kindex -T @var{script}
@kindex --script=@var{script}
@cindex script files
@item -T @var{scriptfile}
@itemx --script=@var{scriptfile}
Use @var{scriptfile} as the linker script. This script replaces
@command{ld}'s default linker script (rather than adding to it), so
@var{commandfile} must specify everything necessary to describe the
output file. @xref{Scripts}. If @var{scriptfile} does not exist in
the current directory, @code{ld} looks for it in the directories
specified by any preceding @samp{-L} options. Multiple @samp{-T}
options accumulate.
@kindex -dT @var{script}
@kindex --default-script=@var{script}
@cindex script files
@item -dT @var{scriptfile}
@itemx --default-script=@var{scriptfile}
Use @var{scriptfile} as the default linker script. @xref{Scripts}.
This option is similar to the @option{--script} option except that
processing of the script is delayed until after the rest of the
command line has been processed. This allows options placed after the
@option{--default-script} option on the command line to affect the
behaviour of the linker script, which can be important when the linker
command line cannot be directly controlled by the user. (eg because
the command line is being constructed by another tool, such as
@samp{gcc}).
@kindex -u @var{symbol}
@kindex --undefined=@var{symbol}
@cindex undefined symbol
@item -u @var{symbol}
@itemx --undefined=@var{symbol}
Force @var{symbol} to be entered in the output file as an undefined
symbol. Doing this may, for example, trigger linking of additional
modules from standard libraries. @samp{-u} may be repeated with
different option arguments to enter additional undefined symbols. This
option is equivalent to the @code{EXTERN} linker script command.
If this option is being used to force additional modules to be pulled
into the link, and if it is an error for the symbol to remain
undefined, then the option @option{--require-defined} should be used
instead.
@kindex --require-defined=@var{symbol}
@cindex symbols, require defined
@cindex defined symbol
@item --require-defined=@var{symbol}
Require that @var{symbol} is defined in the output file. This option
is the same as option @option{--undefined} except that if @var{symbol}
is not defined in the output file then the linker will issue an error
and exit. The same effect can be achieved in a linker script by using
@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option
can be used multiple times to require additional symbols.
@kindex -Ur
@cindex constructors
@item -Ur
For anything other than C++ programs, this option is equivalent to
@samp{-r}: it generates relocatable output---i.e., an output file that can in
turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
@emph{does} resolve references to constructors, unlike @samp{-r}.
It does not work to use @samp{-Ur} on files that were themselves linked
with @samp{-Ur}; once the constructor table has been built, it cannot
be added to. Use @samp{-Ur} only for the last partial link, and
@samp{-r} for the others.
@kindex --orphan-handling=@var{MODE}
@cindex orphan sections
@cindex sections, orphan
@item --orphan-handling=@var{MODE}
Control how orphan sections are handled. An orphan section is one not
specifically mentioned in a linker script. @xref{Orphan Sections}.
@var{MODE} can have any of the following values:
@table @code
@item place
Orphan sections are placed into a suitable output section following
the strategy described in @ref{Orphan Sections}. The option
@samp{--unique} also affects how sections are placed.
@item discard
All orphan sections are discarded, by placing them in the
@samp{/DISCARD/} section (@pxref{Output Section Discarding}).
@item warn
The linker will place the orphan section as for @code{place} and also
issue a warning.
@item error
The linker will exit with an error if any orphan section is found.
@end table
The default if @samp{--orphan-handling} is not given is @code{place}.
@kindex --unique[=@var{SECTION}]
@item --unique[=@var{SECTION}]
Creates a separate output section for every input section matching
@var{SECTION}, or if the optional wildcard @var{SECTION} argument is
missing, for every orphan input section. An orphan section is one not
specifically mentioned in a linker script. You may use this option
multiple times on the command line; It prevents the normal merging of
input sections with the same name, overriding output section assignments
in a linker script.
@kindex -v
@kindex -V
@kindex --version
@cindex version
@item -v
@itemx --version
@itemx -V
Display the version number for @command{ld}. The @option{-V} option also
lists the supported emulations.
@kindex -x
@kindex --discard-all
@cindex deleting local symbols
@item -x
@itemx --discard-all
Delete all local symbols.
@kindex -X
@kindex --discard-locals
@cindex local symbols, deleting
@item -X
@itemx --discard-locals
Delete all temporary local symbols. (These symbols start with
system-specific local label prefixes, typically @samp{.L} for ELF systems
or @samp{L} for traditional a.out systems.)
@kindex -y @var{symbol}
@kindex --trace-symbol=@var{symbol}
@cindex symbol tracing
@item -y @var{symbol}
@itemx --trace-symbol=@var{symbol}
Print the name of each linked file in which @var{symbol} appears. This
option may be given any number of times. On many systems it is necessary
to prepend an underscore.
This option is useful when you have an undefined symbol in your link but
don't know where the reference is coming from.
@kindex -Y @var{path}
@item -Y @var{path}
Add @var{path} to the default library search path. This option exists
for Solaris compatibility.
@kindex -z @var{keyword}
@item -z @var{keyword}
The recognized keywords are:
@table @samp
@item call-nop=prefix-addr
@itemx call-nop=suffix-nop
@itemx call-nop=prefix-@var{byte}
@itemx call-nop=suffix-@var{byte}
Specify the 1-byte @code{NOP} padding when transforming indirect call
to a locally defined function, foo, via its GOT slot.
@option{call-nop=prefix-addr} generates @code{0x67 call foo}.
@option{call-nop=suffix-nop} generates @code{call foo 0x90}.
@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
Supported for i386 and x86_64.
@item cet-report=none
@itemx cet-report=warning
@itemx cet-report=error
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and
GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property
section. @option{cet-report=none}, which is the default, will make the
linker not report missing properties in input files.
@option{cet-report=warning} will make the linker issue a warning for
missing properties in input files. @option{cet-report=error} will make
the linker issue an error for missing properties in input files.
Note that @option{ibt} will turn off the missing
GNU_PROPERTY_X86_FEATURE_1_IBT property report and @option{shstk} will
turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
Supported for Linux/i386 and Linux/x86_64.
@item combreloc
@itemx nocombreloc
Combine multiple dynamic relocation sections and sort to improve
dynamic symbol lookup caching. Do not do this if @samp{nocombreloc}.
@item common
@itemx nocommon
Generate common symbols with STT_COMMON type during a relocatable
link. Use STT_OBJECT type if @samp{nocommon}.
@item common-page-size=@var{value}
Set the page size most commonly used to @var{value}. Memory image
layout will be optimized to minimize memory pages if the system is
using pages of this size.
@item defs
Report unresolved symbol references from regular object files. This
is done even if the linker is creating a non-symbolic shared library.
This option is the inverse of @samp{-z undefs}.
@item dynamic-undefined-weak
@itemx nodynamic-undefined-weak
Make undefined weak symbols dynamic when building a dynamic object,
if they are referenced from a regular object file and not forced local
by symbol visibility or versioning. Do not make them dynamic if
@samp{nodynamic-undefined-weak}. If neither option is given, a target
may default to either option being in force, or make some other
selection of undefined weak symbols dynamic. Not all targets support
these options.
@item execstack
Marks the object as requiring executable stack.
@item global
This option is only meaningful when building a shared object. It makes
the symbols defined by this shared object available for symbol resolution
of subsequently loaded libraries.
@item globalaudit
This option is only meaningful when building a dynamic executable.
This option marks the executable as requiring global auditing by
setting the @code{DF_1_GLOBAUDIT} bit in the @code{DT_FLAGS_1} dynamic
tag. Global auditing requires that any auditing library defined via
the @option{--depaudit} or @option{-P} command-line options be run for
all dynamic objects loaded by the application.
@item ibtplt
Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
Supported for Linux/i386 and Linux/x86_64.
@item ibt
Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
to indicate compatibility with IBT. This also implies @option{ibtplt}.
Supported for Linux/i386 and Linux/x86_64.
@item indirect-extern-access
@itemx noindirect-extern-access
Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in
.note.gnu.property section to indicate that object file requires
canonical function pointers and cannot be used with copy relocation.
This option also implies @option{noextern-protected-data} and
@option{nocopyreloc}. Supported for i386 and x86-64.
@option{noindirect-extern-access} removes
GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property
section.
@item initfirst
This option is only meaningful when building a shared object.
It marks the object so that its runtime initialization will occur
before the runtime initialization of any other objects brought into
the process at the same time. Similarly the runtime finalization of
the object will occur after the runtime finalization of any other
objects.
@item interpose
Specify that the dynamic loader should modify its symbol search order
so that symbols in this shared library interpose all other shared
libraries not so marked.
@item unique
@itemx nounique
When generating a shared library or other dynamically loadable ELF
object mark it as one that should (by default) only ever be loaded once,
and only in the main namespace (when using @code{dlmopen}). This is
primarily used to mark fundamental libraries such as libc, libpthread et
al which do not usually function correctly unless they are the sole instances
of themselves. This behaviour can be overridden by the @code{dlmopen} caller
and does not apply to certain loading mechanisms (such as audit libraries).
@item lam-u48
Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section
to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64.
@item lam-u57
Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section
to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64.
@item lam-u48-report=none
@itemx lam-u48-report=warning
@itemx lam-u48-report=error
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48
property in input .note.gnu.property section.
@option{lam-u48-report=none}, which is the default, will make the
linker not report missing properties in input files.
@option{lam-u48-report=warning} will make the linker issue a warning for
missing properties in input files. @option{lam-u48-report=error} will
make the linker issue an error for missing properties in input files.
Supported for Linux/x86_64.
@item lam-u57-report=none
@itemx lam-u57-report=warning
@itemx lam-u57-report=error
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57
property in input .note.gnu.property section.
@option{lam-u57-report=none}, which is the default, will make the
linker not report missing properties in input files.
@option{lam-u57-report=warning} will make the linker issue a warning for
missing properties in input files. @option{lam-u57-report=error} will
make the linker issue an error for missing properties in input files.
Supported for Linux/x86_64.
@item lam-report=none
@itemx lam-report=warning
@itemx lam-report=error
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and
GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property
section. @option{lam-report=none}, which is the default, will make the
linker not report missing properties in input files.
@option{lam-report=warning} will make the linker issue a warning for
missing properties in input files. @option{lam-report=error} will make
the linker issue an error for missing properties in input files.
Supported for Linux/x86_64.
@item lazy
When generating an executable or shared library, mark it to tell the
dynamic linker to defer function call resolution to the point when
the function is called (lazy binding), rather than at load time.
Lazy binding is the default.
@item loadfltr
Specify that the object's filters be processed immediately at runtime.
@item max-page-size=@var{value}
Set the maximum memory page size supported to @var{value}.
@item muldefs
Allow multiple definitions.
@item nocopyreloc
Disable linker generated .dynbss variables used in place of variables
defined in shared libraries. May result in dynamic text relocations.
@item nodefaultlib
Specify that the dynamic loader search for dependencies of this object
should ignore any default library search paths.
@item nodelete
Specify that the object shouldn't be unloaded at runtime.
@item nodlopen
Specify that the object is not available to @code{dlopen}.
@item nodump
Specify that the object can not be dumped by @code{dldump}.
@item noexecstack
Marks the object as not requiring executable stack.
@item noextern-protected-data
Don't treat protected data symbols as external when building a shared
library. This option overrides the linker backend default. It can be
used to work around incorrect relocations against protected data symbols
generated by compiler. Updates on protected data symbols by another
module aren't visible to the resulting shared library. Supported for
i386 and x86-64.
@item noreloc-overflow
Disable relocation overflow check. This can be used to disable
relocation overflow check if there will be no dynamic relocation
overflow at run-time. Supported for x86_64.
@item now
When generating an executable or shared library, mark it to tell the
dynamic linker to resolve all symbols when the program is started, or
when the shared library is loaded by dlopen, instead of deferring
function call resolution to the point when the function is first
called.
@item origin
Specify that the object requires @samp{$ORIGIN} handling in paths.
@item pack-relative-relocs
@itemx nopack-relative-relocs
Generate compact relative relocation in position-independent executable
and shared library. It adds @code{DT_RELR}, @code{DT_RELRSZ} and
@code{DT_RELRENT} entries to the dynamic section. It is ignored when
building position-dependent executable and relocatable output.
@option{nopack-relative-relocs} is the default, which disables compact
relative relocation. When linked against the GNU C Library, a
GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is
added to the output. Supported for i386 and x86-64.
@item relro
@itemx norelro
Create an ELF @code{PT_GNU_RELRO} segment header in the object. This
specifies a memory segment that should be made read-only after
relocation, if supported. Specifying @samp{common-page-size} smaller
than the system page size will render this protection ineffective.
Don't create an ELF @code{PT_GNU_RELRO} segment if @samp{norelro}.
@item report-relative-reloc
Report dynamic relative relocations generated by linker. Supported for
Linux/i386 and Linux/x86_64.
@item separate-code
@itemx noseparate-code
Create separate code @code{PT_LOAD} segment header in the object. This
specifies a memory segment that should contain only instructions and must
be in wholly disjoint pages from any other data. Don't create separate
code @code{PT_LOAD} segment if @samp{noseparate-code} is used.
@item shstk
Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
to indicate compatibility with Intel Shadow Stack. Supported for
Linux/i386 and Linux/x86_64.
@item stack-size=@var{value}
Specify a stack size for an ELF @code{PT_GNU_STACK} segment.
Specifying zero will override any default non-zero sized
@code{PT_GNU_STACK} segment creation.
@item start-stop-gc
@itemx nostart-stop-gc
@cindex start-stop-gc
When @samp{--gc-sections} is in effect, a reference from a retained
section to @code{__start_SECNAME} or @code{__stop_SECNAME} causes all
input sections named @code{SECNAME} to also be retained, if
@code{SECNAME} is representable as a C identifier and either
@code{__start_SECNAME} or @code{__stop_SECNAME} is synthesized by the
linker. @samp{-z start-stop-gc} disables this effect, allowing
sections to be garbage collected as if the special synthesized symbols
were not defined. @samp{-z start-stop-gc} has no effect on a
definition of @code{__start_SECNAME} or @code{__stop_SECNAME} in an
object file or linker script. Such a definition will prevent the
linker providing a synthesized @code{__start_SECNAME} or
@code{__stop_SECNAME} respectively, and therefore the special
treatment by garbage collection for those references.
@item start-stop-visibility=@var{value}
@cindex visibility
@cindex ELF symbol visibility
Specify the ELF symbol visibility for synthesized
@code{__start_SECNAME} and @code{__stop_SECNAME} symbols (@pxref{Input
Section Example}). @var{value} must be exactly @samp{default},
@samp{internal}, @samp{hidden}, or @samp{protected}. If no @samp{-z
start-stop-visibility} option is given, @samp{protected} is used for
compatibility with historical practice. However, it's highly
recommended to use @samp{-z start-stop-visibility=hidden} in new
programs and shared libraries so that these symbols are not exported
between shared objects, which is not usually what's intended.
@item text
@itemx notext
@itemx textoff
Report an error if DT_TEXTREL is set, i.e., if the position-independent
or shared object has dynamic relocations in read-only sections. Don't
report an error if @samp{notext} or @samp{textoff}.
@item undefs
Do not report unresolved symbol references from regular object files,
either when creating an executable, or when creating a shared library.
This option is the inverse of @samp{-z defs}.
@item unique-symbol
@itemx nounique-symbol
Avoid duplicated local symbol names in the symbol string table. Append
".@code{number}" to duplicated local symbol names if @samp{unique-symbol}
is used. @option{nounique-symbol} is the default.
@item x86-64-baseline
@item x86-64-v2
@item x86-64-v3
@itemx x86-64-v4
Specify the x86-64 ISA level needed in .note.gnu.property section.
@option{x86-64-baseline} generates @code{GNU_PROPERTY_X86_ISA_1_BASELINE}.
@option{x86-64-v2} generates @code{GNU_PROPERTY_X86_ISA_1_V2}.
@option{x86-64-v3} generates @code{GNU_PROPERTY_X86_ISA_1_V3}.
@option{x86-64-v4} generates @code{GNU_PROPERTY_X86_ISA_1_V4}.
Supported for Linux/i386 and Linux/x86_64.
@end table
Other keywords are ignored for Solaris compatibility.
@kindex -(
@cindex groups of archives
@item -( @var{archives} -)
@itemx --start-group @var{archives} --end-group
The @var{archives} should be a list of archive files. They may be
either explicit file names, or @samp{-l} options.
The specified archives are searched repeatedly until no new undefined
references are created. Normally, an archive is searched only once in
the order that it is specified on the command line. If a symbol in that
archive is needed to resolve an undefined symbol referred to by an
object in an archive that appears later on the command line, the linker
would not be able to resolve that reference. By grouping the archives,
they will all be searched repeatedly until all possible references are
resolved.
Using this option has a significant performance cost. It is best to use
it only when there are unavoidable circular references between two or
more archives.
@kindex --accept-unknown-input-arch
@kindex --no-accept-unknown-input-arch
@item --accept-unknown-input-arch
@itemx --no-accept-unknown-input-arch
Tells the linker to accept input files whose architecture cannot be
recognised. The assumption is that the user knows what they are doing
and deliberately wants to link in these unknown input files. This was
the default behaviour of the linker, before release 2.14. The default
behaviour from release 2.14 onwards is to reject such input files, and
so the @samp{--accept-unknown-input-arch} option has been added to
restore the old behaviour.
@kindex --as-needed
@kindex --no-as-needed
@item --as-needed
@itemx --no-as-needed
This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
on the command line after the @option{--as-needed} option. Normally
the linker will add a DT_NEEDED tag for each dynamic library mentioned
on the command line, regardless of whether the library is actually
needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
emitted for a library that @emph{at that point in the link} satisfies a
non-weak undefined symbol reference from a regular object file or, if
the library is not found in the DT_NEEDED lists of other needed libraries, a
non-weak undefined symbol reference from another needed dynamic library.
Object files or libraries appearing on the command line @emph{after}
the library in question do not affect whether the library is seen as
needed. This is similar to the rules for extraction of object files
from archives. @option{--no-as-needed} restores the default behaviour.
Note: On Linux based systems the @option{--as-needed} option also has
an affect on the behaviour of the @option{--rpath} and
@option{--rpath-link} options. See the description of
@option{--rpath-link} for more details.
@kindex --add-needed
@kindex --no-add-needed
@item --add-needed
@itemx --no-add-needed
These two options have been deprecated because of the similarity of
their names to the @option{--as-needed} and @option{--no-as-needed}
options. They have been replaced by @option{--copy-dt-needed-entries}
and @option{--no-copy-dt-needed-entries}.
@kindex -assert @var{keyword}
@item -assert @var{keyword}
This option is ignored for SunOS compatibility.
@kindex -Bdynamic
@kindex -dy
@kindex -call_shared
@item -Bdynamic
@itemx -dy
@itemx -call_shared
Link against dynamic libraries. This is only meaningful on platforms
for which shared libraries are supported. This option is normally the
default on such platforms. The different variants of this option are
for compatibility with various systems. You may use this option
multiple times on the command line: it affects library searching for
@option{-l} options which follow it.
@kindex -Bgroup
@item -Bgroup
Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
section. This causes the runtime linker to handle lookups in this
object and its dependencies to be performed only inside the group.
@option{--unresolved-symbols=report-all} is implied. This option is
only meaningful on ELF platforms which support shared libraries.
@kindex -Bstatic
@kindex -dn
@kindex -non_shared
@kindex -static
@item -Bstatic
@itemx -dn
@itemx -non_shared
@itemx -static
Do not link against shared libraries. This is only meaningful on
platforms for which shared libraries are supported. The different
variants of this option are for compatibility with various systems. You
may use this option multiple times on the command line: it affects
library searching for @option{-l} options which follow it. This
option also implies @option{--unresolved-symbols=report-all}. This
option can be used with @option{-shared}. Doing so means that a
shared library is being created but that all of the library's external
references must be resolved by pulling in entries from static
libraries.
@kindex -Bsymbolic
@item -Bsymbolic
When creating a shared library, bind references to global symbols to the
definition within the shared library, if any. Normally, it is possible
for a program linked against a shared library to override the definition
within the shared library. This option is only meaningful on ELF
platforms which support shared libraries.
@kindex -Bsymbolic-functions
@item -Bsymbolic-functions
When creating a shared library, bind references to global function
symbols to the definition within the shared library, if any.
This option is only meaningful on ELF platforms which support shared
libraries.
@kindex -Bno-symbolic
@item -Bno-symbolic
This option can cancel previously specified @samp{-Bsymbolic} and
@samp{-Bsymbolic-functions}.
@kindex --dynamic-list=@var{dynamic-list-file}
@item --dynamic-list=@var{dynamic-list-file}
Specify the name of a dynamic list file to the linker. This is
typically used when creating shared libraries to specify a list of
global symbols whose references shouldn't be bound to the definition
within the shared library, or creating dynamically linked executables
to specify a list of symbols which should be added to the symbol table
in the executable. This option is only meaningful on ELF platforms
which support shared libraries.
The format of the dynamic list is the same as the version node without
scope and node name. See @ref{VERSION} for more information.
@kindex --dynamic-list-data
@item --dynamic-list-data
Include all global data symbols to the dynamic list.
@kindex --dynamic-list-cpp-new
@item --dynamic-list-cpp-new
Provide the builtin dynamic list for C++ operator new and delete. It
is mainly useful for building shared libstdc++.
@kindex --dynamic-list-cpp-typeinfo
@item --dynamic-list-cpp-typeinfo
Provide the builtin dynamic list for C++ runtime type identification.
@kindex --check-sections
@kindex --no-check-sections
@item --check-sections
@itemx --no-check-sections
Asks the linker @emph{not} to check section addresses after they have
been assigned to see if there are any overlaps. Normally the linker will
perform this check, and if it finds any overlaps it will produce
suitable error messages. The linker does know about, and does make
allowances for sections in overlays. The default behaviour can be
restored by using the command-line switch @option{--check-sections}.
Section overlap is not usually checked for relocatable links. You can
force checking in that case by using the @option{--check-sections}
option.
@kindex --copy-dt-needed-entries
@kindex --no-copy-dt-needed-entries
@item --copy-dt-needed-entries
@itemx --no-copy-dt-needed-entries
This option affects the treatment of dynamic libraries referred to
by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
command line. Normally the linker won't add a DT_NEEDED tag to the
output binary for each library mentioned in a DT_NEEDED tag in an
input dynamic library. With @option{--copy-dt-needed-entries}
specified on the command line however any dynamic libraries that
follow it will have their DT_NEEDED entries added. The default
behaviour can be restored with @option{--no-copy-dt-needed-entries}.
This option also has an effect on the resolution of symbols in dynamic
libraries. With @option{--copy-dt-needed-entries} dynamic libraries
mentioned on the command line will be recursively searched, following
their DT_NEEDED tags to other libraries, in order to resolve symbols
required by the output binary. With the default setting however
the searching of dynamic libraries that follow it will stop with the
dynamic library itself. No DT_NEEDED links will be traversed to resolve
symbols.
@cindex cross reference table
@kindex --cref
@item --cref
Output a cross reference table. If a linker map file is being
generated, the cross reference table is printed to the map file.
Otherwise, it is printed on the standard output.
The format of the table is intentionally simple, so that it may be
easily processed by a script if necessary. The symbols are printed out,
sorted by name. For each symbol, a list of file names is given. If the
symbol is defined, the first file listed is the location of the
definition. If the symbol is defined as a common value then any files
where this happens appear next. Finally any files that reference the
symbol are listed.
@cindex ctf variables
@kindex --ctf-variables
@kindex --no-ctf-variables
@item --ctf-variables
@item --no-ctf-variables
The CTF debuginfo format supports a section which encodes the names and
types of variables found in the program which do not appear in any symbol
table. These variables clearly cannot be looked up by address by
conventional debuggers, so the space used for their types and names is
usually wasted: the types are usually small but the names are often not.
@option{--ctf-variables} causes the generation of such a section.
The default behaviour can be restored with @option{--no-ctf-variables}.
@cindex ctf type sharing
@kindex --ctf-share-types
@item --ctf-share-types=@var{method}
Adjust the method used to share types between translation units in CTF.
@table @samp
@item share-unconflicted
Put all types that do not have ambiguous definitions into the shared dictionary,
where debuggers can easily access them, even if they only occur in one
translation unit. This is the default.
@item share-duplicated
Put only types that occur in multiple translation units into the shared
dictionary: types with only one definition go into per-translation-unit
dictionaries. Types with ambiguous definitions in multiple translation units
always go into per-translation-unit dictionaries. This tends to make the CTF
larger, but may reduce the amount of CTF in the shared dictionary. For very
large projects this may speed up opening the CTF and save memory in the CTF
consumer at runtime.
@end table
@cindex common allocation
@kindex --no-define-common
@item --no-define-common
This option inhibits the assignment of addresses to common symbols.
The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
@xref{Miscellaneous Commands}.
The @samp{--no-define-common} option allows decoupling
the decision to assign addresses to Common symbols from the choice
of the output file type; otherwise a non-Relocatable output type
forces assigning addresses to Common symbols.
Using @samp{--no-define-common} allows Common symbols that are referenced
from a shared library to be assigned addresses only in the main program.
This eliminates the unused duplicate space in the shared library,
and also prevents any possible confusion over resolving to the wrong
duplicate when there are many dynamic modules with specialized search
paths for runtime symbol resolution.
@cindex group allocation in linker script
@cindex section groups
@cindex COMDAT
@kindex --force-group-allocation
@item --force-group-allocation
This option causes the linker to place section group members like
normal input sections, and to delete the section groups. This is the
default behaviour for a final link but this option can be used to
change the behaviour of a relocatable link (@samp{-r}). The script
command @code{FORCE_GROUP_ALLOCATION} has the same
effect. @xref{Miscellaneous Commands}.
@cindex symbols, from command line
@kindex --defsym=@var{symbol}=@var{exp}
@item --defsym=@var{symbol}=@var{expression}
Create a global symbol in the output file, containing the absolute
address given by @var{expression}. You may use this option as many
times as necessary to define multiple symbols in the command line. A
limited form of arithmetic is supported for the @var{expression} in this
context: you may give a hexadecimal constant or the name of an existing
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
constants or symbols. If you need more elaborate expressions, consider
using the linker command language from a script (@pxref{Assignments}).
@emph{Note:} there should be no white space between @var{symbol}, the
equals sign (``@key{=}''), and @var{expression}.
The linker processes @samp{--defsym} arguments and @samp{-T} arguments
in order, placing @samp{--defsym} before @samp{-T} will define the
symbol before the linker script from @samp{-T} is processed, while
placing @samp{--defsym} after @samp{-T} will define the symbol after
the linker script has been processed. This difference has
consequences for expressions within the linker script that use the
@samp{--defsym} symbols, which order is correct will depend on what
you are trying to achieve.
@cindex demangling, from command line
@kindex --demangle[=@var{style}]
@kindex --no-demangle
@item --demangle[=@var{style}]
@itemx --no-demangle
These options control whether to demangle symbol names in error messages
and other output. When the linker is told to demangle, it tries to
present symbol names in a readable fashion: it strips leading
underscores if they are used by the object file format, and converts C++
mangled symbol names into user readable names. Different compilers have
different mangling styles. The optional demangling style argument can be used
to choose an appropriate demangling style for your compiler. The linker will
demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
is set. These options may be used to override the default.
@cindex dynamic linker, from command line
@kindex -I@var{file}
@kindex --dynamic-linker=@var{file}
@item -I@var{file}
@itemx --dynamic-linker=@var{file}
Set the name of the dynamic linker. This is only meaningful when
generating dynamically linked ELF executables. The default dynamic
linker is normally correct; don't use this unless you know what you are
doing.
@kindex --no-dynamic-linker
@item --no-dynamic-linker
When producing an executable file, omit the request for a dynamic
linker to be used at load-time. This is only meaningful for ELF
executables that contain dynamic relocations, and usually requires
entry point code that is capable of processing these relocations.
@kindex --embedded-relocs
@item --embedded-relocs
This option is similar to the @option{--emit-relocs} option except
that the relocs are stored in a target-specific section. This option
is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
targets.
@kindex --disable-multiple-abs-defs
@item --disable-multiple-abs-defs
Do not allow multiple definitions with symbols included
in filename invoked by -R or --just-symbols
@kindex --fatal-warnings
@kindex --no-fatal-warnings
@item --fatal-warnings
@itemx --no-fatal-warnings
Treat all warnings as errors. The default behaviour can be restored
with the option @option{--no-fatal-warnings}.
@kindex -w
@kindex --no-warnings
@item -w
@itemx --no-warnings
Do not display any warning or error messages. This overrides
@option{--fatal-warnings} if it has been enabled. This option can be
used when it is known that the output binary will not work, but there
is still a need to create it.
@kindex --force-exe-suffix
@item --force-exe-suffix
Make sure that an output file has a .exe suffix.
If a successfully built fully linked output file does not have a
@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
the output file to one of the same name with a @code{.exe} suffix. This
option is useful when using unmodified Unix makefiles on a Microsoft
Windows host, since some versions of Windows won't run an image unless
it ends in a @code{.exe} suffix.
@kindex --gc-sections
@kindex --no-gc-sections
@cindex garbage collection
@item --gc-sections
@itemx --no-gc-sections
Enable garbage collection of unused input sections. It is ignored on
targets that do not support this option. The default behaviour (of not
performing this garbage collection) can be restored by specifying
@samp{--no-gc-sections} on the command line. Note that garbage
collection for COFF and PE format targets is supported, but the
implementation is currently considered to be experimental.
@samp{--gc-sections} decides which input sections are used by
examining symbols and relocations. The section containing the entry
symbol and all sections containing symbols undefined on the
command-line will be kept, as will sections containing symbols
referenced by dynamic objects. Note that when building shared
libraries, the linker must assume that any visible symbol is
referenced. Once this initial set of sections has been determined,
the linker recursively marks as used any section referenced by their
relocations. See @samp{--entry}, @samp{--undefined}, and
@samp{--gc-keep-exported}.
This option can be set when doing a partial link (enabled with option
@samp{-r}). In this case the root of symbols kept must be explicitly
specified either by one of the options @samp{--entry},
@samp{--undefined}, or @samp{--gc-keep-exported} or by a @code{ENTRY}
command in the linker script.
As a GNU extension, ELF input sections marked with the
@code{SHF_GNU_RETAIN} flag will not be garbage collected.
@kindex --print-gc-sections
@kindex --no-print-gc-sections
@cindex garbage collection
@item --print-gc-sections
@itemx --no-print-gc-sections
List all sections removed by garbage collection. The listing is
printed on stderr. This option is only effective if garbage
collection has been enabled via the @samp{--gc-sections}) option. The
default behaviour (of not listing the sections that are removed) can
be restored by specifying @samp{--no-print-gc-sections} on the command
line.
@kindex --gc-keep-exported
@cindex garbage collection
@item --gc-keep-exported
When @samp{--gc-sections} is enabled, this option prevents garbage
collection of unused input sections that contain global symbols having
default or protected visibility. This option is intended to be used for
executables where unreferenced sections would otherwise be garbage
collected regardless of the external visibility of contained symbols.
Note that this option has no effect when linking shared objects since
it is already the default behaviour. This option is only supported for
ELF format targets.
@kindex --print-output-format
@cindex output format
@item --print-output-format
Print the name of the default output format (perhaps influenced by
other command-line options). This is the string that would appear
in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
@kindex --print-memory-usage
@cindex memory usage
@item --print-memory-usage
Print used size, total size and used size of memory regions created with
the @ref{MEMORY} command. This is useful on embedded targets to have a
quick view of amount of free memory. The format of the output has one
headline and one line per region. It is both human readable and easily
parsable by tools. Here is an example of an output:
@smallexample
Memory region Used Size Region Size %age Used
ROM: 256 KB 1 MB 25.00%
RAM: 32 B 2 GB 0.00%
@end smallexample
@cindex help
@cindex usage
@kindex --help
@item --help
Print a summary of the command-line options on the standard output and exit.
@kindex --target-help
@item --target-help
Print a summary of all target-specific options on the standard output and exit.
@kindex -Map=@var{mapfile}
@item -Map=@var{mapfile}
Print a link map to the file @var{mapfile}. See the description of the
@option{-M} option, above. If @var{mapfile} is just the character
@code{-} then the map will be written to stdout.
Specifying a directory as @var{mapfile} causes the linker map to be
written as a file inside the directory. Normally name of the file
inside the directory is computed as the basename of the @var{output}
file with @code{.map} appended. If however the special character
@code{%} is used then this will be replaced by the full path of the
output file. Additionally if there are any characters after the
@var{%} symbol then @code{.map} will no longer be appended.
@smallexample
-o foo.exe -Map=bar [Creates ./bar]
-o ../dir/foo.exe -Map=bar [Creates ./bar]
-o foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
-o ../dir2/foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
-o foo.exe -Map=% [Creates ./foo.exe.map]
-o ../dir/foo.exe -Map=% [Creates ../dir/foo.exe.map]
-o foo.exe -Map=%.bar [Creates ./foo.exe.bar]
-o ../dir/foo.exe -Map=%.bar [Creates ../dir/foo.exe.bar]
-o ../dir2/foo.exe -Map=../dir/% [Creates ../dir/../dir2/foo.exe.map]
-o ../dir2/foo.exe -Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar]
@end smallexample
It is an error to specify more than one @code{%} character.
If the map file already exists then it will be overwritten by this
operation.
@cindex memory usage
@kindex --no-keep-memory
@item --no-keep-memory
@command{ld} normally optimizes for speed over memory usage by caching the
symbol tables of input files in memory. This option tells @command{ld} to
instead optimize for memory usage, by rereading the symbol tables as
necessary. This may be required if @command{ld} runs out of memory space
while linking a large executable.
@kindex --no-undefined
@kindex -z defs
@kindex -z undefs
@item --no-undefined
@itemx -z defs
Report unresolved symbol references from regular object files. This
is done even if the linker is creating a non-symbolic shared library.
The switch @option{--[no-]allow-shlib-undefined} controls the
behaviour for reporting unresolved references found in shared
libraries being linked in.
The effects of this option can be reverted by using @code{-z undefs}.
@kindex --allow-multiple-definition
@kindex -z muldefs
@item --allow-multiple-definition
@itemx -z muldefs
Normally when a symbol is defined multiple times, the linker will
report a fatal error. These options allow multiple definitions and the
first definition will be used.
@kindex --allow-shlib-undefined
@kindex --no-allow-shlib-undefined
@item --allow-shlib-undefined
@itemx --no-allow-shlib-undefined
Allows or disallows undefined symbols in shared libraries.
This switch is similar to @option{--no-undefined} except that it
determines the behaviour when the undefined symbols are in a
shared library rather than a regular object file. It does not affect
how undefined symbols in regular object files are handled.
The default behaviour is to report errors for any undefined symbols
referenced in shared libraries if the linker is being used to create
an executable, but to allow them if the linker is being used to create
a shared library.
The reasons for allowing undefined symbol references in shared
libraries specified at link time are that:
@itemize @bullet
@item
A shared library specified at link time may not be the same as the one
that is available at load time, so the symbol might actually be
resolvable at load time.
@item
There are some operating systems, eg BeOS and HPPA, where undefined
symbols in shared libraries are normal.
The BeOS kernel for example patches shared libraries at load time to
select whichever function is most appropriate for the current
architecture. This is used, for example, to dynamically select an
appropriate memset function.
@end itemize
@kindex --error-handling-script=@var{scriptname}
@item --error-handling-script=@var{scriptname}
If this option is provided then the linker will invoke
@var{scriptname} whenever an error is encountered. Currently however
only two kinds of error are supported: missing symbols and missing
libraries. Two arguments will be passed to script: the keyword
``undefined-symbol'' or `missing-lib'' and the @var{name} of the
undefined symbol or missing library. The intention is that the script
will provide suggestions to the user as to where the symbol or library
might be found. After the script has finished then the normal linker
error message will be displayed.
The availability of this option is controlled by a configure time
switch, so it may not be present in specific implementations.
@kindex --no-undefined-version
@item --no-undefined-version
Normally when a symbol has an undefined version, the linker will ignore
it. This option disallows symbols with undefined version and a fatal error
will be issued instead.
@kindex --default-symver
@item --default-symver
Create and use a default symbol version (the soname) for unversioned
exported symbols.
@kindex --default-imported-symver
@item --default-imported-symver
Create and use a default symbol version (the soname) for unversioned
imported symbols.
@kindex --no-warn-mismatch
@item --no-warn-mismatch
Normally @command{ld} will give an error if you try to link together input
files that are mismatched for some reason, perhaps because they have
been compiled for different processors or for different endiannesses.
This option tells @command{ld} that it should silently permit such possible
errors. This option should only be used with care, in cases when you
have taken some special action that ensures that the linker errors are
inappropriate.
@kindex --no-warn-search-mismatch
@item --no-warn-search-mismatch
Normally @command{ld} will give a warning if it finds an incompatible
library during a library search. This option silences the warning.
@kindex --no-whole-archive
@item --no-whole-archive
Turn off the effect of the @option{--whole-archive} option for subsequent
archive files.
@cindex output file after errors
@kindex --noinhibit-exec
@item --noinhibit-exec
Retain the executable output file whenever it is still usable.
Normally, the linker will not produce an output file if it encounters
errors during the link process; it exits without writing an output file
when it issues any error whatsoever.
@kindex -nostdlib
@item -nostdlib
Only search library directories explicitly specified on the
command line. Library directories specified in linker scripts
(including linker scripts specified on the command line) are ignored.
@ifclear SingleFormat
@kindex --oformat=@var{output-format}
@item --oformat=@var{output-format}
@command{ld} may be configured to support more than one kind of object
file. If your @command{ld} is configured this way, you can use the
@samp{--oformat} option to specify the binary format for the output
object file. Even when @command{ld} is configured to support alternative
object formats, you don't usually need to specify this, as @command{ld}
should be configured to produce as a default output format the most
usual format on each machine. @var{output-format} is a text string, the
name of a particular format supported by the BFD libraries. (You can
list the available binary formats with @samp{objdump -i}.) The script
command @code{OUTPUT_FORMAT} can also specify the output format, but
this option overrides it. @xref{BFD}.
@end ifclear
@kindex --out-implib
@item --out-implib @var{file}
Create an import library in @var{file} corresponding to the executable
the linker is generating (eg. a DLL or ELF program). This import
library (which should be called @code{*.dll.a} or @code{*.a} for DLLs)
may be used to link clients against the generated executable; this
behaviour makes it possible to skip a separate import library creation
step (eg. @code{dlltool} for DLLs). This option is only available for
the i386 PE and ELF targetted ports of the linker.
@kindex -pie
@kindex --pic-executable
@item -pie
@itemx --pic-executable
@cindex position independent executables
Create a position independent executable. This is currently only supported on
ELF platforms. Position independent executables are similar to shared
libraries in that they are relocated by the dynamic linker to the virtual
address the OS chooses for them (which can vary between invocations). Like
normal dynamically linked executables they can be executed and symbols
defined in the executable cannot be overridden by shared libraries.
@kindex -no-pie
@item -no-pie
@cindex position dependent executables
Create a position dependent executable. This is the default.
@kindex -qmagic
@item -qmagic
This option is ignored for Linux compatibility.
@kindex -Qy
@item -Qy
This option is ignored for SVR4 compatibility.
@kindex --relax
@cindex synthesizing linker
@cindex relaxing addressing modes
@cindex --no-relax
@item --relax
@itemx --no-relax
An option with machine dependent effects.
@ifset GENERIC
This option is only supported on a few targets.
@end ifset
@ifset H8300
@xref{H8/300,,@command{ld} and the H8/300}.
@end ifset
@ifset XTENSA
@xref{Xtensa,, @command{ld} and Xtensa Processors}.
@end ifset
@ifset M68HC11
@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
@end ifset
@ifset NIOSII
@xref{Nios II,,@command{ld} and the Altera Nios II}.
@end ifset
@ifset POWERPC
@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
@end ifset
On some platforms the @option{--relax} option performs target specific,
global optimizations that become possible when the linker resolves
addressing in the program, such as relaxing address modes,
synthesizing new instructions, selecting shorter version of current
instructions, and combining constant values.
On some platforms these link time global optimizations may make symbolic
debugging of the resulting executable impossible.
@ifset GENERIC
This is known to be the case for the Matsushita MN10200 and MN10300
family of processors.
@end ifset
On platforms where the feature is supported, the option
@option{--no-relax} will disable it.
On platforms where the feature is not supported, both @option{--relax}
and @option{--no-relax} are accepted, but ignored.
@cindex retaining specified symbols
@cindex stripping all but some symbols
@cindex symbols, retaining selectively
@kindex --retain-symbols-file=@var{filename}
@item --retain-symbols-file=@var{filename}
Retain @emph{only} the symbols listed in the file @var{filename},
discarding all others. @var{filename} is simply a flat file, with one
symbol name per line. This option is especially useful in environments
@ifset GENERIC
(such as VxWorks)
@end ifset
where a large global symbol table is accumulated gradually, to conserve
run-time memory.
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
or symbols needed for relocations.
You may only specify @samp{--retain-symbols-file} once in the command
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
@item -rpath=@var{dir}
@cindex runtime library search path
@kindex -rpath=@var{dir}
Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All @option{-rpath}
arguments are concatenated and passed to the runtime linker, which uses
them to locate shared objects at runtime.
The @option{-rpath} option is also used when locating shared objects which
are needed by shared objects explicitly included in the link; see the
description of the @option{-rpath-link} option. Searching @option{-rpath}
in this way is only supported by native linkers and cross linkers which
have been configured with the @option{--with-sysroot} option.
If @option{-rpath} is not used when linking an ELF executable, the
contents of the environment variable @code{LD_RUN_PATH} will be used if it
is defined.
The @option{-rpath} option may also be used on SunOS. By default, on
SunOS, the linker will form a runtime search path out of all the
@option{-L} options it is given. If a @option{-rpath} option is used, the
runtime search path will be formed exclusively using the @option{-rpath}
options, ignoring the @option{-L} options. This can be useful when using
gcc, which adds many @option{-L} options which may be on NFS mounted
file systems.
For compatibility with other ELF linkers, if the @option{-R} option is
followed by a directory name, rather than a file name, it is treated as
the @option{-rpath} option.
@end ifset
@ifset GENERIC
@cindex link-time runtime library search path
@kindex -rpath-link=@var{dir}
@item -rpath-link=@var{dir}
When using ELF or SunOS, one shared library may require another. This
happens when an @code{ld -shared} link includes a shared library as one
of the input files.
When the linker encounters such a dependency when doing a non-shared,
non-relocatable link, it will automatically try to locate the required
shared library and include it in the link, if it is not included
explicitly. In such a case, the @option{-rpath-link} option
specifies the first set of directories to search. The
@option{-rpath-link} option may specify a sequence of directory names
either by specifying a list of names separated by colons, or by
appearing multiple times.
The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search
directories. They will be replaced by the full path to the directory
containing the program or shared object in the case of @var{$ORIGIN}
and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
64-bit binaries - in the case of @var{$LIB}.
The alternative form of these tokens - @var{$@{ORIGIN@}} and
@var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
supported.
This option should be used with caution as it overrides the search path
that may have been hard compiled into a shared library. In such a case it
is possible to use unintentionally a different search path than the
runtime linker would do.
The linker uses the following search paths to locate required shared
libraries:
@enumerate
@item
Any directories specified by @option{-rpath-link} options.
@item
Any directories specified by @option{-rpath} options. The difference
between @option{-rpath} and @option{-rpath-link} is that directories
specified by @option{-rpath} options are included in the executable and
used at runtime, whereas the @option{-rpath-link} option is only effective
at link time. Searching @option{-rpath} in this way is only supported
by native linkers and cross linkers which have been configured with
the @option{--with-sysroot} option.
@item
On an ELF system, for native linkers, if the @option{-rpath} and
@option{-rpath-link} options were not used, search the contents of the
environment variable @code{LD_RUN_PATH}.
@item
On SunOS, if the @option{-rpath} option was not used, search any
directories specified using @option{-L} options.
@item
For a native linker, search the contents of the environment
variable @code{LD_LIBRARY_PATH}.
@item
For a native ELF linker, the directories in @code{DT_RUNPATH} or
@code{DT_RPATH} of a shared library are searched for shared
libraries needed by it. The @code{DT_RPATH} entries are ignored if
@code{DT_RUNPATH} entries exist.
@item
For a linker for a Linux system, if the file @file{/etc/ld.so.conf}
exists, the list of directories found in that file. Note: the path
to this file is prefixed with the @code{sysroot} value, if that is
defined, and then any @code{prefix} string if the linker was
configured with the @command{--prefix=<path>} option.
@item
For a native linker on a FreeBSD system, any directories specified by
the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h}
header file.
@item
Any directories specified by a @code{SEARCH_DIR} command in a
linker script given on the command line, including scripts specified
by @option{-T} (but not @option{-dT}).
@item
The default directories, normally @file{/lib} and @file{/usr/lib}.
@item
Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH.
@item
Any directories specified by a @code{SEARCH_DIR} command in a default
linker script.
@end enumerate
Note however on Linux based systems there is an additional caveat: If
the @option{--as-needed} option is active @emph{and} a shared library
is located which would normally satisfy the search @emph{and} this
library does not have DT_NEEDED tag for @file{libc.so}
@emph{and} there is a shared library later on in the set of search
directories which also satisfies the search @emph{and}
this second shared library does have a DT_NEEDED tag for
@file{libc.so} @emph{then} the second library will be selected instead
of the first.
If the required shared library is not found, the linker will issue a
warning and continue with the link.
@end ifset
@kindex -shared
@kindex -Bshareable
@item -shared
@itemx -Bshareable
@cindex shared libraries
Create a shared library. This is currently only supported on ELF, XCOFF
and SunOS platforms. On SunOS, the linker will automatically create a
shared library if the @option{-e} option is not used and there are
undefined symbols in the link.
@kindex --sort-common
@item --sort-common
@itemx --sort-common=ascending
@itemx --sort-common=descending
This option tells @command{ld} to sort the common symbols by alignment in
ascending or descending order when it places them in the appropriate output
sections. The symbol alignments considered are sixteen-byte or larger,
eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
between symbols due to alignment constraints. If no sorting order is
specified, then descending order is assumed.
@kindex --sort-section=name
@item --sort-section=name
This option will apply @code{SORT_BY_NAME} to all wildcard section
patterns in the linker script.
@kindex --sort-section=alignment
@item --sort-section=alignment
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
@kindex --spare-dynamic-tags
@item --spare-dynamic-tags=@var{count}
This option specifies the number of empty slots to leave in the
.dynamic section of ELF shared objects. Empty slots may be needed by
post processing tools, such as the prelinker. The default is 5.
@kindex --split-by-file
@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
each input file when @var{size} is reached. @var{size} defaults to a
size of 1 if not given.
@kindex --split-by-reloc
@item --split-by-reloc[=@var{count}]
Tries to creates extra sections in the output file so that no single
output section in the file contains more than @var{count} relocations.
This is useful when generating huge relocatable files for downloading into
certain real time kernels with the COFF object file format; since COFF
cannot represent more than 65535 relocations in a single section. Note
that this will fail to work with object file formats which do not
support arbitrary sections. The linker will not split up individual
input sections for redistribution, so if a single input section contains
more than @var{count} relocations one output section will contain that
many relocations. @var{count} defaults to a value of 32768.
@kindex --stats
@item --stats
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
@kindex --sysroot=@var{directory}
@item --sysroot=@var{directory}
Use @var{directory} as the location of the sysroot, overriding the
configure-time default. This option is only supported by linkers
that were configured using @option{--with-sysroot}.
@kindex --task-link
@item --task-link
This is used by COFF/PE based targets to create a task-linked object
file where all of the global symbols have been converted to statics.
@kindex --traditional-format
@cindex traditional format
@item --traditional-format
For some targets, the output of @command{ld} is different in some ways from
the output of some existing linker. This switch requests @command{ld} to
use the traditional format instead.
@cindex dbx
For example, on SunOS, @command{ld} combines duplicate entries in the
symbol string table. This can reduce the size of an output file with
full debugging information by over 30 percent. Unfortunately, the SunOS
@code{dbx} program can not read the resulting program (@code{gdb} has no
trouble). The @samp{--traditional-format} switch tells @command{ld} to not
combine duplicate entries.
@kindex --section-start=@var{sectionname}=@var{org}
@item --section-start=@var{sectionname}=@var{org}
Locate a section in the output file at the absolute
address given by @var{org}. You may use this option as many
times as necessary to locate multiple sections in the command
line.
@var{org} must be a single hexadecimal integer;
for compatibility with other linkers, you may omit the leading
@samp{0x} usually associated with hexadecimal values. @emph{Note:} there
should be no white space between @var{sectionname}, the equals
sign (``@key{=}''), and @var{org}.
@kindex -Tbss=@var{org}
@kindex -Tdata=@var{org}
@kindex -Ttext=@var{org}
@cindex segment origins, cmd line
@item -Tbss=@var{org}
@itemx -Tdata=@var{org}
@itemx -Ttext=@var{org}
Same as @option{--section-start}, with @code{.bss}, @code{.data} or
@code{.text} as the @var{sectionname}.
@kindex -Ttext-segment=@var{org}
@item -Ttext-segment=@var{org}
@cindex text segment origin, cmd line
When creating an ELF executable, it will set the address of the first
byte of the text segment.
@kindex -Trodata-segment=@var{org}
@item -Trodata-segment=@var{org}
@cindex rodata segment origin, cmd line
When creating an ELF executable or shared object for a target where
the read-only data is in its own segment separate from the executable
text, it will set the address of the first byte of the read-only data segment.
@kindex -Tldata-segment=@var{org}
@item -Tldata-segment=@var{org}
@cindex ldata segment origin, cmd line
When creating an ELF executable or shared object for x86-64 medium memory
model, it will set the address of the first byte of the ldata segment.
@kindex --unresolved-symbols
@item --unresolved-symbols=@var{method}
Determine how to handle unresolved symbols. There are four possible
values for @samp{method}:
@table @samp
@item ignore-all
Do not report any unresolved symbols.
@item report-all
Report all unresolved symbols. This is the default.
@item ignore-in-object-files
Report unresolved symbols that are contained in shared libraries, but
ignore them if they come from regular object files.
@item ignore-in-shared-libs
Report unresolved symbols that come from regular object files, but
ignore them if they come from shared libraries. This can be useful
when creating a dynamic binary and it is known that all the shared
libraries that it should be referencing are included on the linker's
command line.
@end table
The behaviour for shared libraries on their own can also be controlled
by the @option{--[no-]allow-shlib-undefined} option.
Normally the linker will generate an error message for each reported
unresolved symbol but the option @option{--warn-unresolved-symbols}
can change this to a warning.
@kindex --verbose[=@var{NUMBER}]
@cindex verbose[=@var{NUMBER}]
@item --dll-verbose
@itemx --verbose[=@var{NUMBER}]
Display the version number for @command{ld} and list the linker emulations
supported. Display which input files can and cannot be opened. Display
the linker script being used by the linker. If the optional @var{NUMBER}
argument > 1, plugin symbol status will also be displayed.
@kindex --version-script=@var{version-scriptfile}
@cindex version script, symbol versions
@item --version-script=@var{version-scriptfile}
Specify the name of a version script to the linker. This is typically
used when creating shared libraries to specify additional information
about the version hierarchy for the library being created. This option
is only fully supported on ELF platforms which support shared libraries;
see @ref{VERSION}. It is partially supported on PE platforms, which can
use version scripts to filter symbol visibility in auto-export mode: any
symbols marked @samp{local} in the version script will not be exported.
@xref{WIN32}.
@kindex --warn-common
@cindex warnings, on combining symbols
@cindex combining symbols, warnings on
@item --warn-common
Warn when a common symbol is combined with another common symbol or with
a symbol definition. Unix linkers allow this somewhat sloppy practice,
but linkers on some other operating systems do not. This option allows
you to find potential problems from combining global symbols.
Unfortunately, some C libraries use this practice, so you may get some
warnings about symbols in the libraries as well as in your programs.
There are three kinds of global symbols, illustrated here by C examples:
@table @samp
@item int i = 1;
A definition, which goes in the initialized data section of the output
file.
@item extern int i;
An undefined reference, which does not allocate space.
There must be either a definition or a common symbol for the
variable somewhere.
@item int i;
A common symbol. If there are only (one or more) common symbols for a
variable, it goes in the uninitialized data area of the output file.
The linker merges multiple common symbols for the same variable into a
single symbol. If they are of different sizes, it picks the largest
size. The linker turns a common symbol into a declaration, if there is
a definition of the same variable.
@end table
The @samp{--warn-common} option can produce five kinds of warnings.
Each warning consists of a pair of lines: the first describes the symbol
just encountered, and the second describes the previous symbol
encountered with the same name. One or both of the two symbols will be
a common symbol.
@enumerate
@item
Turning a common symbol into a reference, because there is already a
definition for the symbol.
@smallexample
@var{file}(@var{section}): warning: common of `@var{symbol}'
overridden by definition
@var{file}(@var{section}): warning: defined here
@end smallexample
@item
Turning a common symbol into a reference, because a later definition for
the symbol is encountered. This is the same as the previous case,
except that the symbols are encountered in a different order.
@smallexample
@var{file}(@var{section}): warning: definition of `@var{symbol}'
overriding common
@var{file}(@var{section}): warning: common is here
@end smallexample
@item
Merging a common symbol with a previous same-sized common symbol.
@smallexample
@var{file}(@var{section}): warning: multiple common
of `@var{symbol}'
@var{file}(@var{section}): warning: previous common is here
@end smallexample
@item
Merging a common symbol with a previous larger common symbol.
@smallexample
@var{file}(@var{section}): warning: common of `@var{symbol}'
overridden by larger common
@var{file}(@var{section}): warning: larger common is here
@end smallexample
@item
Merging a common symbol with a previous smaller common symbol. This is
the same as the previous case, except that the symbols are
encountered in a different order.
@smallexample
@var{file}(@var{section}): warning: common of `@var{symbol}'
overriding smaller common
@var{file}(@var{section}): warning: smaller common is here
@end smallexample
@end enumerate
@kindex --warn-constructors
@item --warn-constructors
Warn if any global constructors are used. This is only useful for a few
object file formats. For formats like COFF or ELF, the linker can not
detect the use of global constructors.
@kindex --warn-execstack
@cindex warnings, on executable stack
@cindex executable stack, warnings on
@item --warn-execstack
@itemx --no-warn-execstack
On ELF platforms this option controls how the linker generates warning
messages when it creates an output file with an executable stack. By
default the linker will not warn if the @command{-z execstack} command
line option has been used, but this behaviour can be overridden by the
@option{--warn-execstack} option.
On the other hand the linker will normally warn if the stack is made
executable because one or more of the input files need an execuable
stack and neither of the @command{-z execstack} or @command{-z
noexecstack} command line options have been specified. This warning
can be disabled via the @command{--no-warn-execstack} option.
Note: ELF format input files specify that they need an executable
stack by having a @var{.note.GNU-stack} section with the executable
bit set in its section flags. They can specify that they do not need
an executable stack by having that section, but without the executable
flag bit set. If an input file does not have a @var{.note.GNU-stack}
section present then the default behaviour is target specific. For
some targets, then absence of such a section implies that an
executable stack @emph{is} required. This is often a problem for hand
crafted assembler files.
@kindex --warn-multiple-gp
@item --warn-multiple-gp
Warn if multiple global pointer values are required in the output file.
This is only meaningful for certain processors, such as the Alpha.
Specifically, some processors put large-valued constants in a special
section. A special register (the global pointer) points into the middle
of this section, so that constants can be loaded efficiently via a
base-register relative addressing mode. Since the offset in
base-register relative mode is fixed and relatively small (e.g., 16
bits), this limits the maximum size of the constant pool. Thus, in
large programs, it is often necessary to use multiple global pointer
values in order to be able to address all possible constants. This
option causes a warning to be issued whenever this case occurs.
@kindex --warn-once
@cindex warnings, on undefined symbols
@cindex undefined symbols, warnings on
@item --warn-once
Only warn once for each undefined symbol, rather than once per module
which refers to it.
@kindex --warn-rwx-segments
@cindex warnings, on writeable and exectuable segments
@cindex executable segments, warnings on
@item --warn-rwx-segments
@itemx --no-warn-rwx-segments
Warn if the linker creates a loadable, non-zero sized segment that has
all three of the read, write and execute permission flags set. Such a
segment represents a potential security vulnerability. In addition
warnings will be generated if a thread local storage segment is
created with the execute permission flag set, regardless of whether or
not it has the read and/or write flags set.
These warnings are enabled by default. They can be disabled via the
@option{--no-warn-rwx-segments} option and re-enabled via the
@option{--warn-rwx-segments} option.
@kindex --warn-section-align
@cindex warnings, on section alignment
@cindex section alignment, warnings on
@item --warn-section-align
Warn if the address of an output section is changed because of
alignment. Typically, the alignment will be set by an input section.
The address will only be changed if it not explicitly specified; that
is, if the @code{SECTIONS} command does not specify a start address for
the section (@pxref{SECTIONS}).
@kindex --warn-textrel
@item --warn-textrel
Warn if the linker adds DT_TEXTREL to a position-independent executable
or shared object.
@kindex --warn-alternate-em
@item --warn-alternate-em
Warn if an object has alternate ELF machine code.
@kindex --warn-unresolved-symbols
@item --warn-unresolved-symbols
If the linker is going to report an unresolved symbol (see the option
@option{--unresolved-symbols}) it will normally generate an error.
This option makes it generate a warning instead.
@kindex --error-unresolved-symbols
@item --error-unresolved-symbols
This restores the linker's default behaviour of generating errors when
it is reporting unresolved symbols.
@kindex --whole-archive
@cindex including an entire archive
@item --whole-archive
For each archive mentioned on the command line after the
@option{--whole-archive} option, include every object file in the archive
in the link, rather than searching the archive for the required object
files. This is normally used to turn an archive file into a shared
library, forcing every object to be included in the resulting shared
library. This option may be used more than once.
Two notes when using this option from gcc: First, gcc doesn't know
about this option, so you have to use @option{-Wl,-whole-archive}.
Second, don't forget to use @option{-Wl,-no-whole-archive} after your
list of archives, because gcc will add its own list of archives to
your link and you may not want this flag to affect those as well.
@kindex --wrap=@var{symbol}
@item --wrap=@var{symbol}
Use a wrapper function for @var{symbol}. Any undefined reference to
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
undefined reference to @code{__real_@var{symbol}} will be resolved to
@var{symbol}.
This can be used to provide a wrapper for a system function. The
wrapper function should be called @code{__wrap_@var{symbol}}. If it
wishes to call the system function, it should call
@code{__real_@var{symbol}}.
Here is a trivial example:
@smallexample
void *
__wrap_malloc (size_t c)
@{
printf ("malloc called with %zu\n", c);
return __real_malloc (c);
@}
@end smallexample
If you link other code with this file using @option{--wrap malloc}, then
all calls to @code{malloc} will call the function @code{__wrap_malloc}
instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
call the real @code{malloc} function.
You may wish to provide a @code{__real_malloc} function as well, so that
links without the @option{--wrap} option will succeed. If you do this,
you should not put the definition of @code{__real_malloc} in the same
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to @code{malloc}.
Only undefined references are replaced by the linker. So, translation unit
internal references to @var{symbol} are not resolved to
@code{__wrap_@var{symbol}}. In the next example, the call to @code{f} in
@code{g} is not resolved to @code{__wrap_f}.
@smallexample
int
f (void)
@{
return 123;
@}
int
g (void)
@{
return f();
@}
@end smallexample
@kindex --eh-frame-hdr
@kindex --no-eh-frame-hdr
@item --eh-frame-hdr
@itemx --no-eh-frame-hdr
Request (@option{--eh-frame-hdr}) or suppress
(@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
section and ELF @code{PT_GNU_EH_FRAME} segment header.
@kindex --ld-generated-unwind-info
@item --no-ld-generated-unwind-info
Request creation of @code{.eh_frame} unwind info for linker
generated code sections like PLT. This option is on by default
if linker generated unwind info is supported. This option also
controls the generation of @code{.sframe} stack trace info for linker
generated code sections like PLT.
@kindex --enable-new-dtags
@kindex --disable-new-dtags
@item --enable-new-dtags
@itemx --disable-new-dtags
This linker can create the new dynamic tags in ELF. But the older ELF
systems may not understand them. If you specify
@option{--enable-new-dtags}, the new dynamic tags will be created as needed
and older dynamic tags will be omitted.
If you specify @option{--disable-new-dtags}, no new dynamic tags will be
created. By default, the new dynamic tags are not created. Note that
those options are only available for ELF systems.
@kindex --hash-size=@var{number}
@item --hash-size=@var{number}
Set the default size of the linker's hash tables to a prime number
close to @var{number}. Increasing this value can reduce the length of
time it takes the linker to perform its tasks, at the expense of
increasing the linker's memory requirements. Similarly reducing this
value can reduce the memory requirements at the expense of speed.
@kindex --hash-style=@var{style}
@item --hash-style=@var{style}
Set the type of linker's hash table(s). @var{style} can be either
@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
new style GNU @code{.gnu.hash} section or @code{both} for both
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
hash tables. The default depends upon how the linker was configured,
but for most Linux based systems it will be @code{both}.
@kindex --compress-debug-sections=none
@kindex --compress-debug-sections=zlib
@kindex --compress-debug-sections=zlib-gnu
@kindex --compress-debug-sections=zlib-gabi
@kindex --compress-debug-sections=zstd
@item --compress-debug-sections=none
@itemx --compress-debug-sections=zlib
@itemx --compress-debug-sections=zlib-gnu
@itemx --compress-debug-sections=zlib-gabi
@itemx --compress-debug-sections=zstd
On ELF platforms, these options control how DWARF debug sections are
compressed using zlib.
@option{--compress-debug-sections=none} doesn't compress DWARF debug
sections. @option{--compress-debug-sections=zlib-gnu} compresses
DWARF debug sections and renames them to begin with @samp{.zdebug}
instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
also compresses DWARF debug sections, but rather than renaming them it
sets the SHF_COMPRESSED flag in the sections' headers.
The @option{--compress-debug-sections=zlib} option is an alias for
@option{--compress-debug-sections=zlib-gabi}.
@option{--compress-debug-sections=zstd} compresses DWARF debug sections using
zstd.
Note that this option overrides any compression in input debug
sections, so if a binary is linked with @option{--compress-debug-sections=none}
for example, then any compressed debug sections in input files will be
uncompressed before they are copied into the output binary.
The default compression behaviour varies depending upon the target
involved and the configure options used to build the toolchain. The
default can be determined by examining the output from the linker's
@option{--help} option.
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
This option reduces memory requirements at ld runtime, at the expense of
linking speed. This was introduced to select the old O(n^2) algorithm
for link map file generation, rather than the new O(n) algorithm which uses
about 40% more memory for symbol storage.
Another effect of the switch is to set the default hash table size to
1021, which again saves memory at the cost of lengthening the linker's
run time. This is not done however if the @option{--hash-size} switch
has been used.
The @option{--reduce-memory-overheads} switch may be also be used to
enable other tradeoffs in future versions of the linker.
@kindex --max-cache-size=@var{size}
@item --max-cache-size=@var{size}
@command{ld} normally caches the relocation information and symbol tables
of input files in memory with the unlimited size. This option sets the
maximum cache size to @var{size}.
@kindex --build-id
@kindex --build-id=@var{style}
@item --build-id
@itemx --build-id=@var{style}
Request the creation of a @code{.note.gnu.build-id} ELF note section
or a @code{.buildid} COFF section. The contents of the note are
unique bits identifying this linked file. @var{style} can be
@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
@sc{SHA1} hash on the normative parts of the output contents,
@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
the output contents, or @code{0x@var{hexstring}} to use a chosen bit
string specified as an even number of hexadecimal digits (@code{-} and
@code{:} characters between digit pairs are ignored). If @var{style}
is omitted, @code{sha1} is used.
The @code{md5} and @code{sha1} styles produces an identifier
that is always the same in an identical output file, but will be
unique among all nonidentical output files. It is not intended
to be compared as a checksum for the file's contents. A linked
file may be changed later by other tools, but the build ID bit
string identifying the original linked file does not change.
Passing @code{none} for @var{style} disables the setting from any
@code{--build-id} options earlier on the command line.
@kindex --package-metadata=@var{JSON}
@item --package-metadata=@var{JSON}
Request the creation of a @code{.note.package} ELF note section. The
contents of the note are in JSON format, as per the package metadata
specification. For more information see:
https://systemd.io/ELF_PACKAGE_METADATA/
If the JSON argument is missing/empty then this will disable the
creation of the metadata note, if one had been enabled by an earlier
occurrence of the --package-metdata option.
If the linker has been built with libjansson, then the JSON string
will be validated.
@end table
@c man end
@subsection Options Specific to i386 PE Targets
@c man begin OPTIONS
The i386 PE linker supports the @option{-shared} option, which causes
the output to be a dynamically linked library (DLL) instead of a
normal executable. You should name the output @code{*.dll} when you
use this option. In addition, the linker fully supports the standard
@code{*.def} files, which may be specified on the linker command line
like an object file (in fact, it should precede archives it exports
symbols from, to ensure that they get linked in, just like a normal
object file).
In addition to the options common to all targets, the i386 PE linker
support additional command-line options that are specific to the i386
PE target. Options that take values may be separated from their
values by either a space or an equals sign.
@table @gcctabopt
@kindex --add-stdcall-alias
@item --add-stdcall-alias
If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
as-is and also with the suffix stripped.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --base-file
@item --base-file @var{file}
Use @var{file} as the name of a file in which to save the base
addresses of all the relocations needed for generating DLLs with
@file{dlltool}.
[This is an i386 PE specific option]
@kindex --dll
@item --dll
Create a DLL instead of a regular executable. You may also use
@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
file.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-long-section-names
@kindex --disable-long-section-names
@item --enable-long-section-names
@itemx --disable-long-section-names
The PE variants of the COFF object format add an extension that permits
the use of section names longer than eight characters, the normal limit
for COFF. By default, these names are only allowed in object files, as
fully-linked executable images do not carry the COFF string table required
to support the longer names. As a GNU extension, it is possible to
allow their use in executable images as well, or to (probably pointlessly!)
disallow it in object files, by using these two options. Executable images
generated with these long section names are slightly non-standard, carrying
as they do a string table, and may generate confusing output when examined
with non-GNU PE-aware tools, such as file viewers and dumpers. However,
GDB relies on the use of PE long section names to find Dwarf-2 debug
information sections in an executable image at runtime, and so if neither
option is specified on the command-line, @command{ld} will enable long
section names, overriding the default and technically correct behaviour,
when it finds the presence of debug information while linking an executable
image and not stripping symbols.
[This option is valid for all PE targeted ports of the linker]
@kindex --enable-stdcall-fixup
@kindex --disable-stdcall-fixup
@item --enable-stdcall-fixup
@itemx --disable-stdcall-fixup
If the link finds a symbol that it cannot resolve, it will attempt to
do ``fuzzy linking'' by looking for another defined symbol that differs
only in the format of the symbol name (cdecl vs stdcall) and will
resolve that symbol by linking to the match. For example, the
undefined symbol @code{_foo} might be linked to the function
@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
to the function @code{_bar}. When the linker does this, it prints a
warning, since it normally should have failed to link, but sometimes
import libraries generated from third-party dlls may need this feature
to be usable. If you specify @option{--enable-stdcall-fixup}, this
feature is fully enabled and warnings are not printed. If you specify
@option{--disable-stdcall-fixup}, this feature is disabled and such
mismatches are considered to be errors.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --leading-underscore
@kindex --no-leading-underscore
@item --leading-underscore
@itemx --no-leading-underscore
For most targets default symbol-prefix is an underscore and is defined
in target's description. By this option it is possible to
disable/enable the default underscore symbol-prefix.
@cindex DLLs, creating
@kindex --export-all-symbols
@item --export-all-symbols
If given, all global symbols in the objects used to build a DLL will
be exported by the DLL. Note that this is the default if there
otherwise wouldn't be any exported symbols. When symbols are
explicitly exported via DEF files or implicitly exported via function
attributes, the default is to not export anything else unless this
option is given. Note that the symbols @code{DllMain@@12},
@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
@code{impure_ptr} will not be automatically
exported. Also, symbols imported from other DLLs will not be
re-exported, nor will symbols specifying the DLL's internal layout
such as those beginning with @code{_head_} or ending with
@code{_iname}. In addition, no symbols from @code{libgcc},
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
not be exported, to help with C++ DLLs. Finally, there is an
extensive list of cygwin-private symbols that are not exported
(obviously, this applies on when building DLLs for cygwin targets).
These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
@code{cygwin_premain3}, and @code{environ}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-symbols
@item --exclude-symbols @var{symbol},@var{symbol},...
Specifies a list of symbols which should not be automatically
exported. The symbol names may be delimited by commas or colons.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-all-symbols
@item --exclude-all-symbols
Specifies no symbols should be automatically exported.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --file-alignment
@item --file-alignment
Specify the file alignment. Sections in the file will always begin at
file offsets which are multiples of this number. This defaults to
512.
[This option is specific to the i386 PE targeted port of the linker]
@cindex heap size
@kindex --heap
@item --heap @var{reserve}
@itemx --heap @var{reserve},@var{commit}
Specify the number of bytes of memory to reserve (and optionally commit)
to be used as heap for this program. The default is 1MB reserved, 4K
committed.
[This option is specific to the i386 PE targeted port of the linker]
@cindex image base
@kindex --image-base
@item --image-base @var{value}
Use @var{value} as the base address of your program or dll. This is
the lowest memory location that will be used when your program or dll
is loaded. To reduce the need to relocate and improve performance of
your dlls, each should have a unique base address and not overlap any
other dlls. The default is 0x400000 for executables, and 0x10000000
for dlls.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --kill-at
@item --kill-at
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
symbols before they are exported.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --large-address-aware
@item --large-address-aware
If given, the appropriate bit in the ``Characteristics'' field of the COFF
header is set to indicate that this executable supports virtual addresses
greater than 2 gigabytes. This should be used in conjunction with the /3GB
or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
section of the BOOT.INI. Otherwise, this bit has no effect.
[This option is specific to PE targeted ports of the linker]
@kindex --disable-large-address-aware
@item --disable-large-address-aware
Reverts the effect of a previous @samp{--large-address-aware} option.
This is useful if @samp{--large-address-aware} is always set by the compiler
driver (e.g. Cygwin gcc) and the executable does not support virtual
addresses greater than 2 gigabytes.
[This option is specific to PE targeted ports of the linker]
@kindex --major-image-version
@item --major-image-version @var{value}
Sets the major number of the ``image version''. Defaults to 1.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --major-os-version
@item --major-os-version @var{value}
Sets the major number of the ``os version''. Defaults to 4.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --major-subsystem-version
@item --major-subsystem-version @var{value}
Sets the major number of the ``subsystem version''. Defaults to 4.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-image-version
@item --minor-image-version @var{value}
Sets the minor number of the ``image version''. Defaults to 0.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-os-version
@item --minor-os-version @var{value}
Sets the minor number of the ``os version''. Defaults to 0.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --minor-subsystem-version
@item --minor-subsystem-version @var{value}
Sets the minor number of the ``subsystem version''. Defaults to 0.
[This option is specific to the i386 PE targeted port of the linker]
@cindex DEF files, creating
@cindex DLLs, creating
@kindex --output-def
@item --output-def @var{file}
The linker will create the file @var{file} which will contain a DEF
file corresponding to the DLL the linker is generating. This DEF file
(which should be called @code{*.def}) may be used to create an import
library with @code{dlltool} or may be used as a reference to
automatically or implicitly exported symbols.
[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, creating
@kindex --enable-auto-image-base
@item --enable-auto-image-base
@itemx --enable-auto-image-base=@var{value}
Automatically choose the image base for DLLs, optionally starting with base
@var{value}, unless one is specified using the @code{--image-base} argument.
By using a hash generated from the dllname to create unique image bases
for each DLL, in-memory collisions and relocations which can delay program
execution are avoided.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-auto-image-base
@item --disable-auto-image-base
Do not automatically generate a unique image base. If there is no
user-specified image base (@code{--image-base}) then use the platform
default.
[This option is specific to the i386 PE targeted port of the linker]
@cindex DLLs, linking to
@kindex --dll-search-prefix
@item --dll-search-prefix @var{string}
When linking dynamically to a dll without an import library,
search for @code{<string><basename>.dll} in preference to
@code{lib<basename>.dll}. This behaviour allows easy distinction
between DLLs built for the various "subplatforms": native, cygwin,
uwin, pw, etc. For instance, cygwin DLLs typically use
@code{--dll-search-prefix=cyg}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-auto-import
@item --enable-auto-import
Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
DATA imports from DLLs, thus making it possible to bypass the dllimport
mechanism on the user side and to reference unmangled symbol names.
[This option is specific to the i386 PE targeted port of the linker]
The following remarks pertain to the original implementation of the
feature and are obsolete nowadays for Cygwin and MinGW targets.
Note: Use of the 'auto-import' extension will cause the text section
of the image file to be made writable. This does not conform to the
PE-COFF format specification published by Microsoft.
Note - use of the 'auto-import' extension will also cause read only
data which would normally be placed into the .rdata section to be
placed into the .data section instead. This is in order to work
around a problem with consts that is described here:
http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
Using 'auto-import' generally will 'just work' -- but sometimes you may
see this message:
"variable '<var>' can't be auto-imported. Please read the
documentation for ld's @code{--enable-auto-import} for details."
This message occurs when some (sub)expression accesses an address
ultimately given by the sum of two constants (Win32 import tables only
allow one). Instances where this may occur include accesses to member
fields of struct variables imported from a DLL, as well as using a
constant index into an array variable imported from a DLL. Any
multiword variable (arrays, structs, long long, etc) may trigger
this error condition. However, regardless of the exact data type
of the offending exported variable, ld will always detect it, issue
the warning, and exit.
There are several ways to address this difficulty, regardless of the
data type of the exported variable:
One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
of adjusting references in your client code for runtime environment, so
this method works only when runtime environment supports this feature.
A second solution is to force one of the 'constants' to be a variable --
that is, unknown and un-optimizable at compile time. For arrays,
there are two possibilities: a) make the indexee (the array's address)
a variable, or b) make the 'constant' index a variable. Thus:
@example
extern type extern_array[];
extern_array[1] -->
@{ volatile type *t=extern_array; t[1] @}
@end example
or
@example
extern type extern_array[];
extern_array[1] -->
@{ volatile int t=1; extern_array[t] @}
@end example
For structs (and most other multiword data types) the only option
is to make the struct itself (or the long long, or the ...) variable:
@example
extern struct s extern_struct;
extern_struct.field -->
@{ volatile struct s *t=&extern_struct; t->field @}
@end example
or
@example
extern long long extern_ll;
extern_ll -->
@{ volatile long long * local_ll=&extern_ll; *local_ll @}
@end example
A third method of dealing with this difficulty is to abandon
'auto-import' for the offending symbol and mark it with
@code{__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:
Original:
@example
--foo.h
extern int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv)@{
printf("%d\n",arr[1]);
@}
@end example
Solution 1:
@example
--foo.h
extern int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv)@{
/* This workaround is for win32 and cygwin; do not "optimize" */
volatile int *parr = arr;
printf("%d\n",parr[1]);
@}
@end example
Solution 2:
@example
--foo.h
/* Note: auto-export is assumed (no __declspec(dllexport)) */
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
!(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
#define FOO_IMPORT __declspec(dllimport)
#else
#define FOO_IMPORT
#endif
extern FOO_IMPORT int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv)@{
printf("%d\n",arr[1]);
@}
@end example
A fourth 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).
@kindex --disable-auto-import
@item --disable-auto-import
Do not attempt to do sophisticated linking of @code{_symbol} to
@code{__imp__symbol} for DATA imports from DLLs.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-runtime-pseudo-reloc
@item --enable-runtime-pseudo-reloc
If your code contains expressions described in --enable-auto-import section,
that is, DATA imports from DLL with non-zero offset, this switch will create
a vector of 'runtime pseudo relocations' which can be used by runtime
environment to adjust references to such data in your client code.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --disable-runtime-pseudo-reloc
@item --disable-runtime-pseudo-reloc
Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-extra-pe-debug
@item --enable-extra-pe-debug
Show additional debug info related to auto-import symbol thunking.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --section-alignment
@item --section-alignment
Sets the section alignment. Sections in memory will always begin at
addresses which are a multiple of this number. Defaults to 0x1000.
[This option is specific to the i386 PE targeted port of the linker]
@cindex stack size
@kindex --stack
@item --stack @var{reserve}
@itemx --stack @var{reserve},@var{commit}
Specify the number of bytes of memory to reserve (and optionally commit)
to be used as stack for this program. The default is 2MB reserved, 4K
committed.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --subsystem
@item --subsystem @var{which}
@itemx --subsystem @var{which}:@var{major}
@itemx --subsystem @var{which}:@var{major}.@var{minor}
Specifies the subsystem under which your program will execute. The
legal values for @var{which} are @code{native}, @code{windows},
@code{console}, @code{posix}, and @code{xbox}. You may optionally set
the subsystem version also. Numeric values are also accepted for
@var{which}.
[This option is specific to the i386 PE targeted port of the linker]
The following options set flags in the @code{DllCharacteristics} field
of the PE file header:
[These options are specific to PE targeted ports of the linker]
@kindex --high-entropy-va
@item --high-entropy-va
@itemx --disable-high-entropy-va
Image is compatible with 64-bit address space layout randomization
(ASLR). This option is enabled by default for 64-bit PE images.
This option also implies @option{--dynamicbase} and
@option{--enable-reloc-section}.
@kindex --dynamicbase
@item --dynamicbase
@itemx --disable-dynamicbase
The image base address may be relocated using address space layout
randomization (ASLR). This feature was introduced with MS Windows
Vista for i386 PE targets. This option is enabled by default but
can be disabled via the @option{--disable-dynamicbase} option.
This option also implies @option{--enable-reloc-section}.
@kindex --forceinteg
@item --forceinteg
@itemx --disable-forceinteg
Code integrity checks are enforced. This option is disabled by
default.
@kindex --nxcompat
@item --nxcompat
@item --disable-nxcompat
The image is compatible with the Data Execution Prevention.
This feature was introduced with MS Windows XP SP2 for i386 PE
targets. The option is enabled by default.
@kindex --no-isolation
@item --no-isolation
@itemx --disable-no-isolation
Although the image understands isolation, do not isolate the image.
This option is disabled by default.
@kindex --no-seh
@item --no-seh
@itemx --disable-no-seh
The image does not use SEH. No SE handler may be called from
this image. This option is disabled by default.
@kindex --no-bind
@item --no-bind
@itemx --disable-no-bind
Do not bind this image. This option is disabled by default.
@kindex --wdmdriver
@item --wdmdriver
@itemx --disable-wdmdriver
The driver uses the MS Windows Driver Model. This option is disabled
by default.
@kindex --tsaware
@item --tsaware
@itemx --disable-tsaware
The image is Terminal Server aware. This option is disabled by
default.
@kindex --insert-timestamp
@item --insert-timestamp
@itemx --no-insert-timestamp
Insert a real timestamp into the image. This is the default behaviour
as it matches legacy code and it means that the image will work with
other, proprietary tools. The problem with this default is that it
will result in slightly different images being produced each time the
same sources are linked. The option @option{--no-insert-timestamp}
can be used to insert a zero value for the timestamp, this ensuring
that binaries produced from identical sources will compare
identically.
@kindex --enable-reloc-section
@item --enable-reloc-section
@itemx --disable-reloc-section
Create the base relocation table, which is necessary if the image
is loaded at a different image base than specified in the PE header.
This option is enabled by default.
@end table
@c man end
@ifset C6X
@subsection Options specific to C6X uClinux targets
@c man begin OPTIONS
The C6X uClinux target uses a binary format called DSBT to support shared
libraries. Each shared library in the system needs to have a unique index;
all executables use an index of 0.
@table @gcctabopt
@kindex --dsbt-size
@item --dsbt-size @var{size}
This option sets the number of entries in the DSBT of the current executable
or shared library to @var{size}. The default is to create a table with 64
entries.
@kindex --dsbt-index
@item --dsbt-index @var{index}
This option sets the DSBT index of the current executable or shared library
to @var{index}. The default is 0, which is appropriate for generating
executables. If a shared library is generated with a DSBT index of 0, the
@code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
@kindex --no-merge-exidx-entries
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
exidx entries in frame unwind info.
@end table
@c man end
@end ifset
@ifset CSKY
@subsection Options specific to C-SKY targets
@c man begin OPTIONS
@table @gcctabopt
@kindex --branch-stub on C-SKY
@item --branch-stub
This option enables linker branch relaxation by inserting branch stub
sections when needed to extend the range of branches. This option is
usually not required since C-SKY supports branch and call instructions that
can access the full memory range and branch relaxation is normally handled by
the compiler or assembler.
@kindex --stub-group-size on C-SKY
@item --stub-group-size=@var{N}
This option allows finer control of linker branch stub creation.
It sets the maximum size of a group of input sections that can
be handled by one stub section. A negative value of @var{N} locates
stub sections after their branches, while a positive value allows stub
sections to appear either before or after the branches. Values of
@samp{1} or @samp{-1} indicate that the
linker should choose suitable defaults.
@end table
@c man end
@end ifset
@ifset M68HC11
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
@c man begin OPTIONS
The 68HC11 and 68HC12 linkers support specific options to control the
memory bank switching mapping and trampoline code generation.
@table @gcctabopt
@kindex --no-trampoline
@item --no-trampoline
This option disables the generation of trampoline. By default a trampoline
is generated for each far function which is called using a @code{jsr}
instruction (this happens when a pointer to a far function is taken).
@kindex --bank-window
@item --bank-window @var{name}
This option indicates to the linker the name of the memory region in
the @samp{MEMORY} specification that describes the memory bank window.
The definition of such region is then used by the linker to compute
paging and addresses within the memory window.
@end table
@c man end
@end ifset
@ifset M68K
@subsection Options specific to Motorola 68K target
@c man begin OPTIONS
The following options are supported to control handling of GOT generation
when linking for 68K targets.
@table @gcctabopt
@kindex --got
@item --got=@var{type}
This option tells the linker which GOT generation scheme to use.
@var{type} should be one of @samp{single}, @samp{negative},
@samp{multigot} or @samp{target}. For more information refer to the
Info entry for @file{ld}.
@end table
@c man end
@end ifset
@ifset MIPS
@subsection Options specific to MIPS targets
@c man begin OPTIONS
The following options are supported to control microMIPS instruction
generation and branch relocation checks for ISA mode transitions when
linking for MIPS targets.
@table @gcctabopt
@kindex --insn32
@item --insn32
@kindex --no-insn32
@itemx --no-insn32
These options control the choice of microMIPS instructions used in code
generated by the linker, such as that in the PLT or lazy binding stubs,
or in relaxation. If @samp{--insn32} is used, then the linker only uses
32-bit instruction encodings. By default or if @samp{--no-insn32} is
used, all instruction encodings are used, including 16-bit ones where
possible.
@kindex --ignore-branch-isa
@item --ignore-branch-isa
@kindex --no-ignore-branch-isa
@itemx --no-ignore-branch-isa
These options control branch relocation checks for invalid ISA mode
transitions. If @samp{--ignore-branch-isa} is used, then the linker
accepts any branch relocations and any ISA mode transition required
is lost in relocation calculation, except for some cases of @code{BAL}
instructions which meet relaxation conditions and are converted to
equivalent @code{JALX} instructions as the associated relocation is
calculated. By default or if @samp{--no-ignore-branch-isa} is used
a check is made causing the loss of an ISA mode transition to produce
an error.
@kindex --compact-branches
@item --compact-branches
@kindex --no-compact-branches
@itemx --no-compact-branches
These options control the generation of compact instructions by the linker
in the PLT entries for MIPS R6.
@end table
@c man end
@end ifset
@ifset PDP11
@subsection Options specific to PDP11 targets
@c man begin OPTIONS
For the pdp11-aout target, three variants of the output format can be
produced as selected by the following options. The default variant
for pdp11-aout is the @samp{--omagic} option, whereas for other
targets @samp{--nmagic} is the default. The @samp{--imagic} option is
defined only for the pdp11-aout target, while the others are described
here as they apply to the pdp11-aout target.
@table @gcctabopt
@kindex -N
@item -N
@kindex --omagic
@itemx --omagic
Mark the output as @code{OMAGIC} (0407) in the @file{a.out} header to
indicate that the text segment is not to be write-protected and
shared. Since the text and data sections are both readable and
writable, the data section is allocated immediately contiguous after
the text segment. This is the oldest format for PDP11 executable
programs and is the default for @command{ld} on PDP11 Unix systems
from the beginning through 2.11BSD.
@kindex -n
@item -n
@kindex --nmagic
@itemx --nmagic
Mark the output as @code{NMAGIC} (0410) in the @file{a.out} header to
indicate that when the output file is executed, the text portion will
be read-only and shareable among all processes executing the same
file. This involves moving the data areas up to the first possible 8K
byte page boundary following the end of the text. This option creates
a @emph{pure executable} format.
@kindex -z
@item -z
@kindex --imagic
@itemx --imagic
Mark the output as @code{IMAGIC} (0411) in the @file{a.out} header to
indicate that when the output file is executed, the program text and
data areas will be loaded into separate address spaces using the split
instruction and data space feature of the memory management unit in
larger models of the PDP11. This doubles the address space available
to the program. The text segment is again pure, write-protected, and
shareable. The only difference in the output format between this
option and the others, besides the magic number, is that both the text
and data sections start at location 0. The @samp{-z} option selected
this format in 2.11BSD. This option creates a @emph{separate
executable} format.
@kindex --no-omagic
@item --no-omagic
Equivalent to @samp{--nmagic} for pdp11-aout.
@end table
@c man end
@end ifset
@ifset UsesEnvVars
@node Environment
@section Environment Variables
@c man begin ENVIRONMENT
You can change the behaviour of @command{ld} with the environment variables
@ifclear SingleFormat
@code{GNUTARGET},
@end ifclear
@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
@ifclear SingleFormat
@kindex GNUTARGET
@cindex default input format
@code{GNUTARGET} determines the input-file object format if you don't
use @samp{-b} (or its synonym @samp{--format}). Its value should be one
of the BFD names for an input format (@pxref{BFD}). If there is no
@code{GNUTARGET} in the environment, @command{ld} uses the natural format
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
attempts to discover the input format by examining binary input files;
this method often succeeds, but there are potential ambiguities, since
there is no method of ensuring that the magic number used to specify
object-file formats is unique. However, the configuration procedure for
BFD on each system places the conventional format for that system first
in the search-list, so ambiguities are resolved in favor of convention.
@end ifclear
@kindex LDEMULATION
@cindex default emulation
@cindex emulation, default
@code{LDEMULATION} determines the default emulation if you don't use the
@samp{-m} option. The emulation can affect various aspects of linker
behaviour, particularly the default linker script. You can list the
available emulations with the @samp{--verbose} or @samp{-V} options. If
the @samp{-m} option is not used, and the @code{LDEMULATION} environment
variable is not defined, the default emulation depends upon how the
linker was configured.
@kindex COLLECT_NO_DEMANGLE
@cindex demangling, default
Normally, the linker will default to demangling symbols. However, if
@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
default to not demangling symbols. This environment variable is used in
a similar fashion by the @code{gcc} linker wrapper program. The default
may be overridden by the @samp{--demangle} and @samp{--no-demangle}
options.
@c man end
@end ifset
@node Scripts
@chapter Linker Scripts
@cindex scripts
@cindex linker scripts
@cindex command files
Every link is controlled by a @dfn{linker script}. This script is
written in the linker command language.
The main purpose of the linker script is to describe how the sections in
the input files should be mapped into the output file, and to control
the memory layout of the output file. Most linker scripts do nothing
more than this. However, when necessary, the linker script can also
direct the linker to perform many other operations, using the commands
described below.
The linker always uses a linker script. If you do not supply one
yourself, the linker will use a default script that is compiled into the
linker executable. You can use the @samp{--verbose} command-line option
to display the default linker script. Certain command-line options,
such as @samp{-r} or @samp{-N}, will affect the default linker script.
You may supply your own linker script by using the @samp{-T} command
line option. When you do this, your linker script will replace the
default linker script.
You may also use linker scripts implicitly by naming them as input files
to the linker, as though they were files to be linked. @xref{Implicit
Linker Scripts}.
@menu
* Basic Script Concepts:: Basic Linker Script Concepts
* Script Format:: Linker Script Format
* Simple Example:: Simple Linker Script Example
* Simple Commands:: Simple Linker Script Commands
* Assignments:: Assigning Values to Symbols
* SECTIONS:: SECTIONS Command
* MEMORY:: MEMORY Command
* PHDRS:: PHDRS Command
* VERSION:: VERSION Command
* Expressions:: Expressions in Linker Scripts
* Implicit Linker Scripts:: Implicit Linker Scripts
@end menu
@node Basic Script Concepts
@section Basic Linker Script Concepts
@cindex linker script concepts
We need to define some basic concepts and vocabulary in order to
describe the linker script language.
The linker combines input files into a single output file. The output
file and each input file are in a special data format known as an
@dfn{object file format}. Each file is called an @dfn{object file}.
The output file is often called an @dfn{executable}, but for our
purposes we will also call it an object file. Each object file has,
among other things, a list of @dfn{sections}. We sometimes refer to a
section in an input file as an @dfn{input section}; similarly, a section
in the output file is an @dfn{output section}.
Each section in an object file has a name and a size. Most sections
also have an associated block of data, known as the @dfn{section
contents}. A section may be marked as @dfn{loadable}, which means that
the contents should be loaded into memory when the output file is run.
A section with no contents may be @dfn{allocatable}, which means that an
area in memory should be set aside, but nothing in particular should be
loaded there (in some cases this memory must be zeroed out). A section
which is neither loadable nor allocatable typically contains some sort
of debugging information.
Every loadable or allocatable output section has two addresses. The
first is the @dfn{VMA}, or virtual memory address. This is the address
the section will have when the output file is run. The second is the
@dfn{LMA}, or load memory address. This is the address at which the
section will be loaded. In most cases the two addresses will be the
same. An example of when they might be different is when a data section
is loaded into ROM, and then copied into RAM when the program starts up
(this technique is often used to initialize global variables in a ROM
based system). In this case the ROM address would be the LMA, and the
RAM address would be the VMA.
You can see the sections in an object file by using the @code{objdump}
program with the @samp{-h} option.
Every object file also has a list of @dfn{symbols}, known as the
@dfn{symbol table}. A symbol may be defined or undefined. Each symbol
has a name, and each defined symbol has an address, among other
information. If you compile a C or C++ program into an object file, you
will get a defined symbol for every defined function and global or
static variable. Every undefined function or global variable which is
referenced in the input file will become an undefined symbol.
You can see the symbols in an object file by using the @code{nm}
program, or by using the @code{objdump} program with the @samp{-t}
option.
@node Script Format
@section Linker Script Format
@cindex linker script format
Linker scripts are text files.
You write a linker script as a series of commands. Each command is
either a keyword, possibly followed by arguments, or an assignment to a
symbol. You may separate commands using semicolons. Whitespace is
generally ignored.
Strings such as file or format names can normally be entered directly.
If the file name contains a character such as a comma which would
otherwise serve to separate file names, you may put the file name in
double quotes. There is no way to use a double quote character in a
file name.
You may include comments in linker scripts just as in C, delimited by
@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
to whitespace.
@node Simple Example
@section Simple Linker Script Example
@cindex linker script example
@cindex example of linker script
Many linker scripts are fairly simple.
The simplest possible linker script has just one command:
@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
memory layout of the output file.
The @samp{SECTIONS} command is a powerful command. Here we will
describe a simple use of it. Let's assume your program consists only of
code, initialized data, and uninitialized data. These will be in the
@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
Let's assume further that these are the only sections which appear in
your input files.
For this example, let's say that the code should be loaded at address
0x10000, and that the data should start at address 0x8000000. Here is a
linker script which will do that:
@smallexample
SECTIONS
@{
. = 0x10000;
.text : @{ *(.text) @}
. = 0x8000000;
.data : @{ *(.data) @}
.bss : @{ *(.bss) @}
@}
@end smallexample
You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
followed by a series of symbol assignments and output section
descriptions enclosed in curly braces.
The first line inside the @samp{SECTIONS} command of the above example
sets the value of the special symbol @samp{.}, which is the location
counter. If you do not specify the address of an output section in some
other way (other ways are described later), the address is set from the
current value of the location counter. The location counter is then
incremented by the size of the output section. At the start of the
@samp{SECTIONS} command, the location counter has the value @samp{0}.
The second line defines an output section, @samp{.text}. The colon is
required syntax which may be ignored for now. Within the curly braces
after the output section name, you list the names of the input sections
which should be placed into this output section. The @samp{*} is a
wildcard which matches any file name. The expression @samp{*(.text)}
means all @samp{.text} input sections in all input files.
Since the location counter is @samp{0x10000} when the output section
@samp{.text} is defined, the linker will set the address of the
@samp{.text} section in the output file to be @samp{0x10000}.
The remaining lines define the @samp{.data} and @samp{.bss} sections in
the output file. The linker will place the @samp{.data} output section
at address @samp{0x8000000}. After the linker places the @samp{.data}
output section, the value of the location counter will be
@samp{0x8000000} plus the size of the @samp{.data} output section. The
effect is that the linker will place the @samp{.bss} output section
immediately after the @samp{.data} output section in memory.
The linker will ensure that each output section has the required
alignment, by increasing the location counter if necessary. In this
example, the specified addresses for the @samp{.text} and @samp{.data}
sections will probably satisfy any alignment constraints, but the linker
may have to create a small gap between the @samp{.data} and @samp{.bss}
sections.
That's it! That's a simple and complete linker script.
@node Simple Commands
@section Simple Linker Script Commands
@cindex linker script simple commands
In this section we describe the simple linker script commands.
@menu
* Entry Point:: Setting the entry point
* File Commands:: Commands dealing with files
@ifclear SingleFormat
* Format Commands:: Commands dealing with object file formats
@end ifclear
* REGION_ALIAS:: Assign alias names to memory regions
* Miscellaneous Commands:: Other linker script commands
@end menu
@node Entry Point
@subsection Setting the Entry Point
@kindex ENTRY(@var{symbol})
@cindex start of execution
@cindex first instruction
@cindex entry point
The first instruction to execute in a program is called the @dfn{entry
point}. You can use the @code{ENTRY} linker script command to set the
entry point. The argument is a symbol name:
@smallexample
ENTRY(@var{symbol})
@end smallexample
There are several ways to set the entry point. The linker will set the
entry point by trying each of the following methods in order, and
stopping when one of them succeeds:
@itemize @bullet
@item
the @samp{-e} @var{entry} command-line option;
@item
the @code{ENTRY(@var{symbol})} command in a linker script;
@item
the value of a target-specific symbol, if it is defined; For many
targets this is @code{start}, but PE- and BeOS-based systems for example
check a list of possible entry symbols, matching the first one found.
@item
the address of the first byte of the code section, if present and an
executable is being created - the code section is usually
@samp{.text}, but can be something else;
@item
The address @code{0}.
@end itemize
@node File Commands
@subsection Commands Dealing with Files
@cindex linker script file commands
Several linker script commands deal with files.
@table @code
@item INCLUDE @var{filename}
@kindex INCLUDE @var{filename}
@cindex including a linker script
Include the linker script @var{filename} at this point. The file will
be searched for in the current directory, and in any directory specified
with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
10 levels deep.
You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
@code{SECTIONS} commands, or in output section descriptions.
@item INPUT(@var{file}, @var{file}, @dots{})
@itemx INPUT(@var{file} @var{file} @dots{})
@kindex INPUT(@var{files})
@cindex input files in linker scripts
@cindex input object files in linker scripts
@cindex linker script input object files
The @code{INPUT} command directs the linker to include the named files
in the link, as though they were named on the command line.
For example, if you always want to include @file{subr.o} any time you do
a link, but you can't be bothered to put it on every link command line,
then you can put @samp{INPUT (subr.o)} in your linker script.
In fact, if you like, you can list all of your input files in the linker
script, and then invoke the linker with nothing but a @samp{-T} option.
In case a @dfn{sysroot prefix} is configured, and the filename starts
with the @samp{/} character, and the script being processed was
located inside the @dfn{sysroot prefix}, the filename will be looked
for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying
@code{=} as the first character in the filename path, or prefixing the
filename path with @code{$SYSROOT}. See also the description of
@samp{-L} in @ref{Options,,Command-line Options}.
If a @dfn{sysroot prefix} is not used then the linker will try to open
the file in the directory containing the linker script. If it is not
found the linker will then search the current directory. If it is still
not found the linker will search through the archive library search
path.
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
name to @code{lib@var{file}.a}, as with the command-line argument
@samp{-l}.
When you use the @code{INPUT} command in an implicit linker script, the
files will be included in the link at the point at which the linker
script file is included. This can affect archive searching.
@item GROUP(@var{file}, @var{file}, @dots{})
@itemx GROUP(@var{file} @var{file} @dots{})
@kindex GROUP(@var{files})
@cindex grouping input files
The @code{GROUP} command is like @code{INPUT}, except that the named
files should all be archives, and they are searched repeatedly until no
new undefined references are created. See the description of @samp{-(}
in @ref{Options,,Command-line Options}.
@item AS_NEEDED(@var{file}, @var{file}, @dots{})
@itemx AS_NEEDED(@var{file} @var{file} @dots{})
@kindex AS_NEEDED(@var{files})
This construct can appear only inside of the @code{INPUT} or @code{GROUP}
commands, among other filenames. The files listed will be handled
as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
with the exception of ELF shared libraries, that will be added only
when they are actually needed. This construct essentially enables
@option{--as-needed} option for all the files listed inside of it
and restores previous @option{--as-needed} resp. @option{--no-as-needed}
setting afterwards.
@item OUTPUT(@var{filename})
@kindex OUTPUT(@var{filename})
@cindex output file name in linker script
The @code{OUTPUT} command names the output file. Using
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
Line Options}). If both are used, the command-line option takes
precedence.
You can use the @code{OUTPUT} command to define a default name for the
output file other than the usual default of @file{a.out}.
@item SEARCH_DIR(@var{path})
@kindex SEARCH_DIR(@var{path})
@cindex library search path in linker script
@cindex archive search path in linker script
@cindex search path in linker script
The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
@command{ld} looks for archive libraries. Using
@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
on the command line (@pxref{Options,,Command-line Options}). If both
are used, then the linker will search both paths. Paths specified using
the command-line option are searched first.
@item STARTUP(@var{filename})
@kindex STARTUP(@var{filename})
@cindex first input file
The @code{STARTUP} command is just like the @code{INPUT} command, except
that @var{filename} will become the first input file to be linked, as
though it were specified first on the command line. This may be useful
when using a system in which the entry point is always the start of the
first file.
@end table
@ifclear SingleFormat
@node Format Commands
@subsection Commands Dealing with Object File Formats
A couple of linker script commands deal with object file formats.
@table @code
@item OUTPUT_FORMAT(@var{bfdname})
@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
@kindex OUTPUT_FORMAT(@var{bfdname})
@cindex output file format in linker script
The @code{OUTPUT_FORMAT} command names the BFD format to use for the
output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
exactly like using @samp{--oformat @var{bfdname}} on the command line
(@pxref{Options,,Command-line Options}). If both are used, the command
line option takes precedence.
You can use @code{OUTPUT_FORMAT} with three arguments to use different
formats based on the @samp{-EB} and @samp{-EL} command-line options.
This permits the linker script to set the output format based on the
desired endianness.
If neither @samp{-EB} nor @samp{-EL} are used, then the output format
will be the first argument, @var{default}. If @samp{-EB} is used, the
output format will be the second argument, @var{big}. If @samp{-EL} is
used, the output format will be the third argument, @var{little}.
For example, the default linker script for the MIPS ELF target uses this
command:
@smallexample
OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
@end smallexample
This says that the default format for the output file is
@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command-line
option, the output file will be created in the @samp{elf32-littlemips}
format.
@item TARGET(@var{bfdname})
@kindex TARGET(@var{bfdname})
@cindex input file format in linker script
The @code{TARGET} command names the BFD format to use when reading input
files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
This command is like using @samp{-b @var{bfdname}} on the command line
(@pxref{Options,,Command-line Options}). If the @code{TARGET} command
is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
command is also used to set the format for the output file. @xref{BFD}.
@end table
@end ifclear
@node REGION_ALIAS
@subsection Assign alias names to memory regions
@kindex REGION_ALIAS(@var{alias}, @var{region})
@cindex region alias
@cindex region names
Alias names can be added to existing memory regions created with the
@ref{MEMORY} command. Each name corresponds to at most one memory region.
@smallexample
REGION_ALIAS(@var{alias}, @var{region})
@end smallexample
The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
memory region @var{region}. This allows a flexible mapping of output sections
to memory regions. An example follows.
Suppose we have an application for embedded systems which come with various
memory storage devices. All have a general purpose, volatile memory @code{RAM}
that allows code execution or data storage. Some may have a read-only,
non-volatile memory @code{ROM} that allows code execution and read-only data
access. The last variant is a read-only, non-volatile memory @code{ROM2} with
read-only data access and no code execution capability. We have four output
sections:
@itemize @bullet
@item
@code{.text} program code;
@item
@code{.rodata} read-only data;
@item
@code{.data} read-write initialized data;
@item
@code{.bss} read-write zero initialized data.
@end itemize
The goal is to provide a linker command file that contains a system independent
part defining the output sections and a system dependent part mapping the
output sections to the memory regions available on the system. Our embedded
systems come with three different memory setups @code{A}, @code{B} and
@code{C}:
@multitable @columnfractions .25 .25 .25 .25
@item Section @tab Variant A @tab Variant B @tab Variant C
@item .text @tab RAM @tab ROM @tab ROM
@item .rodata @tab RAM @tab ROM @tab ROM2
@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
@item .bss @tab RAM @tab RAM @tab RAM
@end multitable
The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
the load address of the @code{.data} section starts in all three variants at
the end of the @code{.rodata} section.
The base linker script that deals with the output sections follows. It
includes the system dependent @code{linkcmds.memory} file that describes the
memory layout:
@smallexample
INCLUDE linkcmds.memory
SECTIONS
@{
.text :
@{
*(.text)
@} > REGION_TEXT
.rodata :
@{
*(.rodata)
rodata_end = .;
@} > REGION_RODATA
.data : AT (rodata_end)
@{
data_start = .;
*(.data)
@} > REGION_DATA
data_size = SIZEOF(.data);
data_load_start = LOADADDR(.data);
.bss :
@{
*(.bss)
@} > REGION_BSS
@}
@end smallexample
Now we need three different @code{linkcmds.memory} files to define memory
regions and alias names. The content of @code{linkcmds.memory} for the three
variants @code{A}, @code{B} and @code{C}:
@table @code
@item A
Here everything goes into the @code{RAM}.
@smallexample
MEMORY
@{
RAM : ORIGIN = 0, LENGTH = 4M
@}
REGION_ALIAS("REGION_TEXT", RAM);
REGION_ALIAS("REGION_RODATA", RAM);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
@end smallexample
@item B
Program code and read-only data go into the @code{ROM}. Read-write data goes
into the @code{RAM}. An image of the initialized data is loaded into the
@code{ROM} and will be copied during system start into the @code{RAM}.
@smallexample
MEMORY
@{
ROM : ORIGIN = 0, LENGTH = 3M
RAM : ORIGIN = 0x10000000, LENGTH = 1M
@}
REGION_ALIAS("REGION_TEXT", ROM);
REGION_ALIAS("REGION_RODATA", ROM);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
@end smallexample
@item C
Program code goes into the @code{ROM}. Read-only data goes into the
@code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
initialized data is loaded into the @code{ROM2} and will be copied during
system start into the @code{RAM}.
@smallexample
MEMORY
@{
ROM : ORIGIN = 0, LENGTH = 2M
ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
RAM : ORIGIN = 0x20000000, LENGTH = 1M
@}
REGION_ALIAS("REGION_TEXT", ROM);
REGION_ALIAS("REGION_RODATA", ROM2);
REGION_ALIAS("REGION_DATA", RAM);
REGION_ALIAS("REGION_BSS", RAM);
@end smallexample
@end table
It is possible to write a common system initialization routine to copy the
@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
necessary:
@smallexample
#include <string.h>
extern char data_start [];
extern char data_size [];
extern char data_load_start [];
void copy_data(void)
@{
if (data_start != data_load_start)
@{
memcpy(data_start, data_load_start, (size_t) data_size);
@}
@}
@end smallexample
@node Miscellaneous Commands
@subsection Other Linker Script Commands
There are a few other linker scripts commands.
@table @code
@item ASSERT(@var{exp}, @var{message})
@kindex ASSERT
@cindex assertion in linker script
Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
with an error code, and print @var{message}.
Note that assertions are checked before the final stages of linking
take place. This means that expressions involving symbols PROVIDEd
inside section definitions will fail if the user has not set values
for those symbols. The only exception to this rule is PROVIDEd
symbols that just reference dot. Thus an assertion like this:
@smallexample
.stack :
@{
PROVIDE (__stack = .);
PROVIDE (__stack_size = 0x100);
ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
@}
@end smallexample
will fail if @code{__stack_size} is not defined elsewhere. Symbols
PROVIDEd outside of section definitions are evaluated earlier, so they
can be used inside ASSERTions. Thus:
@smallexample
PROVIDE (__stack_size = 0x100);
.stack :
@{
PROVIDE (__stack = .);
ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
@}
@end smallexample
will work.
@item EXTERN(@var{symbol} @var{symbol} @dots{})
@kindex EXTERN
@cindex undefined symbol in linker script
Force @var{symbol} to be entered in the output file as an undefined
symbol. Doing this may, for example, trigger linking of additional
modules from standard libraries. You may list several @var{symbol}s for
each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
command has the same effect as the @samp{-u} command-line option.
@item FORCE_COMMON_ALLOCATION
@kindex FORCE_COMMON_ALLOCATION
@cindex common allocation in linker script
This command has the same effect as the @samp{-d} command-line option:
to make @command{ld} assign space to common symbols even if a relocatable
output file is specified (@samp{-r}).
@item INHIBIT_COMMON_ALLOCATION
@kindex INHIBIT_COMMON_ALLOCATION
@cindex common allocation in linker script
This command has the same effect as the @samp{--no-define-common}
command-line option: to make @code{ld} omit the assignment of addresses
to common symbols even for a non-relocatable output file.
@item FORCE_GROUP_ALLOCATION
@kindex FORCE_GROUP_ALLOCATION
@cindex group allocation in linker script
@cindex section groups
@cindex COMDAT
This command has the same effect as the
@samp{--force-group-allocation} command-line option: to make
@command{ld} place section group members like normal input sections,
and to delete the section groups even if a relocatable output file is
specified (@samp{-r}).
@item INSERT [ AFTER | BEFORE ] @var{output_section}
@kindex INSERT
@cindex insert user script into default script
This command is typically used in a script specified by @samp{-T} to
augment the default @code{SECTIONS} with, for example, overlays. It
inserts all prior linker script statements after (or before)
@var{output_section}, and also causes @samp{-T} to not override the
default linker script. The exact insertion point is as for orphan
sections. @xref{Location Counter}. The insertion happens after the
linker has mapped input sections to output sections. Prior to the
insertion, since @samp{-T} scripts are parsed before the default
linker script, statements in the @samp{-T} script occur before the
default linker script statements in the internal linker representation
of the script. In particular, input section assignments will be made
to @samp{-T} output sections before those in the default script. Here
is an example of how a @samp{-T} script using @code{INSERT} might look:
@smallexample
SECTIONS
@{
OVERLAY :
@{
.ov1 @{ ov1*(.text) @}
.ov2 @{ ov2*(.text) @}
@}
@}
INSERT AFTER .text;
@end smallexample
@item NOCROSSREFS(@var{section} @var{section} @dots{})
@kindex NOCROSSREFS(@var{sections})
@cindex cross references
This command may be used to tell @command{ld} to issue an error about any
references among certain output sections.
In certain types of programs, particularly on embedded systems when
using overlays, when one section is loaded into memory, another section
will not be. Any direct references between the two sections would be
errors. For example, it would be an error if code in one section called
a function defined in the other section.
The @code{NOCROSSREFS} command takes a list of output section names. If
@command{ld} detects any cross references between the sections, it reports
an error and returns a non-zero exit status. Note that the
@code{NOCROSSREFS} command uses output section names, not input section
names.
@item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
@kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
@cindex cross references
This command may be used to tell @command{ld} to issue an error about any
references to one section from a list of other sections.
The @code{NOCROSSREFS} command is useful when ensuring that two or more
output sections are entirely independent but there are situations where
a one-way dependency is needed. For example, in a multi-core application
there may be shared code that can be called from each core but for safety
must never call back.
The @code{NOCROSSREFS_TO} command takes a list of output section names.
The first section can not be referenced from any of the other sections.
If @command{ld} detects any references to the first section from any of
the other sections, it reports an error and returns a non-zero exit
status. Note that the @code{NOCROSSREFS_TO} command uses output section
names, not input section names.
@ifclear SingleFormat
@item OUTPUT_ARCH(@var{bfdarch})
@kindex OUTPUT_ARCH(@var{bfdarch})
@cindex machine architecture
@cindex architecture
Specify a particular output machine architecture. The argument is one
of the names used by the BFD library (@pxref{BFD}). You can see the
architecture of an object file by using the @code{objdump} program with
the @samp{-f} option.
@end ifclear
@item LD_FEATURE(@var{string})
@kindex LD_FEATURE(@var{string})
This command may be used to modify @command{ld} behavior. If
@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
in a script are simply treated as numbers everywhere.
@xref{Expression Section}.
@end table
@node Assignments
@section Assigning Values to Symbols
@cindex assignment in scripts
@cindex symbol definition, scripts
@cindex variables, defining
You may assign a value to a symbol in a linker script. This will define
the symbol and place it into the symbol table with a global scope.
@menu
* Simple Assignments:: Simple Assignments
* HIDDEN:: HIDDEN
* PROVIDE:: PROVIDE
* PROVIDE_HIDDEN:: PROVIDE_HIDDEN
* Source Code Reference:: How to use a linker script defined symbol in source code
@end menu
@node Simple Assignments
@subsection Simple Assignments
You may assign to a symbol using any of the C assignment operators:
@table @code
@item @var{symbol} = @var{expression} ;
@itemx @var{symbol} += @var{expression} ;
@itemx @var{symbol} -= @var{expression} ;
@itemx @var{symbol} *= @var{expression} ;
@itemx @var{symbol} /= @var{expression} ;
@itemx @var{symbol} <<= @var{expression} ;
@itemx @var{symbol} >>= @var{expression} ;
@itemx @var{symbol} &= @var{expression} ;
@itemx @var{symbol} |= @var{expression} ;
@end table
The first case will define @var{symbol} to the value of
@var{expression}. In the other cases, @var{symbol} must already be
defined, and the value will be adjusted accordingly.
The special symbol name @samp{.} indicates the location counter. You
may only use this within a @code{SECTIONS} command. @xref{Location Counter}.
The semicolon after @var{expression} is required.
Expressions are defined below; see @ref{Expressions}.
You may write symbol assignments as commands in their own right, or as
statements within a @code{SECTIONS} command, or as part of an output
section description in a @code{SECTIONS} command.
The section of the symbol will be set from the section of the
expression; for more information, see @ref{Expression Section}.
Here is an example showing the three different places that symbol
assignments may be used:
@smallexample
floating_point = 0;
SECTIONS
@{
.text :
@{
*(.text)
_etext = .;
@}
_bdata = (. + 3) & ~ 3;
.data : @{ *(.data) @}
@}
@end smallexample
@noindent
In this example, the symbol @samp{floating_point} will be defined as
zero. The symbol @samp{_etext} will be defined as the address following
the last @samp{.text} input section. The symbol @samp{_bdata} will be
defined as the address following the @samp{.text} output section aligned
upward to a 4 byte boundary.
@node HIDDEN
@subsection HIDDEN
@cindex HIDDEN
For ELF targeted ports, define a symbol that will be hidden and won't be
exported. The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}.
Here is the example from @ref{Simple Assignments}, rewritten to use
@code{HIDDEN}:
@smallexample
HIDDEN(floating_point = 0);
SECTIONS
@{
.text :
@{
*(.text)
HIDDEN(_etext = .);
@}
HIDDEN(_bdata = (. + 3) & ~ 3);
.data : @{ *(.data) @}
@}
@end smallexample
@noindent
In this case none of the three symbols will be visible outside this module.
@node PROVIDE
@subsection PROVIDE
@cindex PROVIDE
In some cases, it is desirable for a linker script to define a symbol
only if it is referenced and is not defined by any object included in
the link. For example, traditional linkers defined the symbol
@samp{etext}. However, ANSI C requires that the user be able to use
@samp{etext} as a function name without encountering an error. The
@code{PROVIDE} keyword may be used to define a symbol, such as
@samp{etext}, only if it is referenced but not defined. The syntax is
@code{PROVIDE(@var{symbol} = @var{expression})}.
Here is an example of using @code{PROVIDE} to define @samp{etext}:
@smallexample
SECTIONS
@{
.text :
@{
*(.text)
_etext = .;
PROVIDE(etext = .);
@}
@}
@end smallexample
In this example, if the program defines @samp{_etext} (with a leading
underscore), the linker will give a multiple definition diagnostic. If,
on the other hand, the program defines @samp{etext} (with no leading
underscore), the linker will silently use the definition in the program.
If the program references @samp{etext} but does not define it, the
linker will use the definition in the linker script.
Note - the @code{PROVIDE} directive considers a common symbol to be
defined, even though such a symbol could be combined with the symbol
that the @code{PROVIDE} would create. This is particularly important
when considering constructor and destructor list symbols such as
@samp{__CTOR_LIST__} as these are often defined as common symbols.
@node PROVIDE_HIDDEN
@subsection PROVIDE_HIDDEN
@cindex PROVIDE_HIDDEN
Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be
hidden and won't be exported.
@node Source Code Reference
@subsection Source Code Reference
Accessing a linker script defined variable from source code is not
intuitive. In particular a linker script symbol is not equivalent to
a variable declaration in a high level language, it is instead a
symbol that does not have a value.
Before going further, it is important to note that compilers often
transform names in the source code into different names when they are
stored in the symbol table. For example, Fortran compilers commonly
prepend or append an underscore, and C++ performs extensive @samp{name
mangling}. Therefore there might be a discrepancy between the name
of a variable as it is used in source code and the name of the same
variable as it is defined in a linker script. For example in C a
linker script variable might be referred to as:
@smallexample
extern int foo;
@end smallexample
But in the linker script it might be defined as:
@smallexample
_foo = 1000;
@end smallexample
In the remaining examples however it is assumed that no name
transformation has taken place.
When a symbol is declared in a high level language such as C, two
things happen. The first is that the compiler reserves enough space
in the program's memory to hold the @emph{value} of the symbol. The
second is that the compiler creates an entry in the program's symbol
table which holds the symbol's @emph{address}. ie the symbol table
contains the address of the block of memory holding the symbol's
value. So for example the following C declaration, at file scope:
@smallexample
int foo = 1000;
@end smallexample
creates an entry called @samp{foo} in the symbol table. This entry
holds the address of an @samp{int} sized block of memory where the
number 1000 is initially stored.
When a program references a symbol the compiler generates code that
first accesses the symbol table to find the address of the symbol's
memory block and then code to read the value from that memory block.
So:
@smallexample
foo = 1;
@end smallexample
looks up the symbol @samp{foo} in the symbol table, gets the address
associated with this symbol and then writes the value 1 into that
address. Whereas:
@smallexample
int * a = & foo;
@end smallexample
looks up the symbol @samp{foo} in the symbol table, gets its address
and then copies this address into the block of memory associated with
the variable @samp{a}.
Linker scripts symbol declarations, by contrast, create an entry in
the symbol table but do not assign any memory to them. Thus they are
an address without a value. So for example the linker script definition:
@smallexample
foo = 1000;
@end smallexample
creates an entry in the symbol table called @samp{foo} which holds
the address of memory location 1000, but nothing special is stored at
address 1000. This means that you cannot access the @emph{value} of a
linker script defined symbol - it has no value - all you can do is
access the @emph{address} of a linker script defined symbol.
Hence when you are using a linker script defined symbol in source code
you should always take the address of the symbol, and never attempt to
use its value. For example suppose you want to copy the contents of a
section of memory called .ROM into a section called .FLASH and the
linker script contains these declarations:
@smallexample
@group
start_of_ROM = .ROM;
end_of_ROM = .ROM + sizeof (.ROM);
start_of_FLASH = .FLASH;
@end group
@end smallexample
Then the C source code to perform the copy would be:
@smallexample
@group
extern char start_of_ROM, end_of_ROM, start_of_FLASH;
memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
@end group
@end smallexample
Note the use of the @samp{&} operators. These are correct.
Alternatively the symbols can be treated as the names of vectors or
arrays and then the code will again work as expected:
@smallexample
@group
extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
@end group
@end smallexample
Note how using this method does not require the use of @samp{&}
operators.
@node SECTIONS
@section SECTIONS Command
@kindex SECTIONS
The @code{SECTIONS} command tells the linker how to map input sections
into output sections, and how to place the output sections in memory.
The format of the @code{SECTIONS} command is:
@smallexample
SECTIONS
@{
@var{sections-command}
@var{sections-command}
@dots{}
@}
@end smallexample
Each @var{sections-command} may of be one of the following:
@itemize @bullet
@item
an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
@item
a symbol assignment (@pxref{Assignments})
@item
an output section description
@item
an overlay description
@end itemize
The @code{ENTRY} command and symbol assignments are permitted inside the
@code{SECTIONS} command for convenience in using the location counter in
those commands. This can also make the linker script easier to
understand because you can use those commands at meaningful points in
the layout of the output file.
Output section descriptions and overlay descriptions are described
below.
If you do not use a @code{SECTIONS} command in your linker script, the
linker will place each input section into an identically named output
section in the order that the sections are first encountered in the
input files. If all input sections are present in the first file, for
example, the order of sections in the output file will match the order
in the first input file. The first section will be at address zero.
@menu
* Output Section Description:: Output section description
* Output Section Name:: Output section name
* Output Section Address:: Output section address
* Input Section:: Input section description
* Output Section Data:: Output section data
* Output Section Keywords:: Output section keywords
* Output Section Discarding:: Output section discarding
* Output Section Attributes:: Output section attributes
* Overlay Description:: Overlay description
@end menu
@node Output Section Description
@subsection Output Section Description
The full description of an output section looks like this:
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
[AT(@var{lma})]
[ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
[SUBALIGN(@var{subsection_align})]
[@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
@dots{}
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
@end group
@end smallexample
Most output sections do not use most of the optional section attributes.
The whitespace around @var{section} is required, so that the section
name is unambiguous. The colon and the curly braces are also required.
The comma at the end may be required if a @var{fillexp} is used and
the next @var{sections-command} looks like a continuation of the expression.
The line breaks and other white space are optional.
Each @var{output-section-command} may be one of the following:
@itemize @bullet
@item
a symbol assignment (@pxref{Assignments})
@item
an input section description (@pxref{Input Section})
@item
data values to include directly (@pxref{Output Section Data})
@item
a special output section keyword (@pxref{Output Section Keywords})
@end itemize
@node Output Section Name
@subsection Output Section Name
@cindex name, section
@cindex section name
The name of the output section is @var{section}. @var{section} must
meet the constraints of your output format. In formats which only
support a limited number of sections, such as @code{a.out}, the name
must be one of the names supported by the format (@code{a.out}, for
example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
output format supports any number of sections, but with numbers and not
names (as is the case for Oasys), the name should be supplied as a
quoted numeric string. A section name may consist of any sequence of
characters, but a name which contains any unusual characters such as
commas must be quoted.
The output section name @samp{/DISCARD/} is special; @ref{Output Section
Discarding}.
@node Output Section Address
@subsection Output Section Address
@cindex address, section
@cindex section address
The @var{address} is an expression for the VMA (the virtual memory
address) of the output section. This address is optional, but if it
is provided then the output address will be set exactly as specified.
If the output address is not specified then one will be chosen for the
section, based on the heuristic below. This address will be adjusted
to fit the alignment requirement of the output section. The
alignment requirement is the strictest alignment of any input section
contained within the output section.
The output section address heuristic is as follows:
@itemize @bullet
@item
If an output memory @var{region} is set for the section then it
is added to this region and its address will be the next free address
in that region.
@item
If the MEMORY command has been used to create a list of memory
regions then the first region which has attributes compatible with the
section is selected to contain it. The section's output address will
be the next free address in that region; @ref{MEMORY}.
@item
If no memory regions were specified, or none match the section then
the output address will be based on the current value of the location
counter.
@end itemize
@noindent
For example:
@smallexample
.text . : @{ *(.text) @}
@end smallexample
@noindent
and
@smallexample
.text : @{ *(.text) @}
@end smallexample
@noindent
are subtly different. The first will set the address of the
@samp{.text} output section to the current value of the location
counter. The second will set it to the current value of the location
counter aligned to the strictest alignment of any of the @samp{.text}
input sections.
The @var{address} may be an arbitrary expression; @ref{Expressions}.
For example, if you want to align the section on a 0x10 byte boundary,
so that the lowest four bits of the section address are zero, you could
do something like this:
@smallexample
.text ALIGN(0x10) : @{ *(.text) @}
@end smallexample
@noindent
This works because @code{ALIGN} returns the current location counter
aligned upward to the specified value.
Specifying @var{address} for a section will change the value of the
location counter, provided that the section is non-empty. (Empty
sections are ignored).
@node Input Section
@subsection Input Section Description
@cindex input sections
@cindex mapping input sections to output sections
The most common output section command is an input section description.
The input section description is the most basic linker script operation.
You use output sections to tell the linker how to lay out your program
in memory. You use input section descriptions to tell the linker how to
map the input files into your memory layout.
@menu
* Input Section Basics:: Input section basics
* Input Section Wildcards:: Input section wildcard patterns
* Input Section Common:: Input section for common symbols
* Input Section Keep:: Input section and garbage collection
* Input Section Example:: Input section example
@end menu
@node Input Section Basics
@subsubsection Input Section Basics
@cindex input section basics
An input section description consists of a file name optionally followed
by a list of section names in parentheses.
The file name and the section name may be wildcard patterns, which we
describe further below (@pxref{Input Section Wildcards}).
The most common input section description is to include all input
sections with a particular name in the output section. For example, to
include all input @samp{.text} sections, you would write:
@smallexample
*(.text)
@end smallexample
@noindent
Here the @samp{*} is a wildcard which matches any file name. To exclude a list
@cindex EXCLUDE_FILE
of files from matching the file name wildcard, EXCLUDE_FILE may be used to
match all files except the ones specified in the EXCLUDE_FILE list. For
example:
@smallexample
EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
@end smallexample
@noindent
will cause all .ctors sections from all files except @file{crtend.o}
and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
placed inside the section list, for example:
@smallexample
*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
@end smallexample
@noindent
The result of this is identically to the previous example. Supporting
two syntaxes for EXCLUDE_FILE is useful if the section list contains
more than one section, as described below.
There are two ways to include more than one section:
@smallexample
*(.text .rdata)
*(.text) *(.rdata)
@end smallexample
@noindent
The difference between these is the order in which the @samp{.text} and
@samp{.rdata} input sections will appear in the output section. In the
first example, they will be intermingled, appearing in the same order as
they are found in the linker input. In the second example, all
@samp{.text} input sections will appear first, followed by all
@samp{.rdata} input sections.
When using EXCLUDE_FILE with more than one section, if the exclusion
is within the section list then the exclusion only applies to the
immediately following section, for example:
@smallexample
*(EXCLUDE_FILE (*somefile.o) .text .rdata)
@end smallexample
@noindent
will cause all @samp{.text} sections from all files except
@file{somefile.o} to be included, while all @samp{.rdata} sections
from all files, including @file{somefile.o}, will be included. To
exclude the @samp{.rdata} sections from @file{somefile.o} the example
could be modified to:
@smallexample
*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
@end smallexample
@noindent
Alternatively, placing the EXCLUDE_FILE outside of the section list,
before the input file selection, will cause the exclusion to apply for
all sections. Thus the previous example can be rewritten as:
@smallexample
EXCLUDE_FILE (*somefile.o) *(.text .rdata)
@end smallexample
You can specify a file name to include sections from a particular file.
You would do this if one or more of your files contain special data that
needs to be at a particular location in memory. For example:
@smallexample
data.o(.data)
@end smallexample
To refine the sections that are included based on the section flags
of an input section, INPUT_SECTION_FLAGS may be used.
Here is a simple example for using Section header flags for ELF sections:
@smallexample
@group
SECTIONS @{
.text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
.text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
@}
@end group
@end smallexample
In this example, the output section @samp{.text} will be comprised of any
input section matching the name *(.text) whose section header flags
@code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section
@samp{.text2} will be comprised of any input section matching the name *(.text)
whose section header flag @code{SHF_WRITE} is clear.
You can also specify files within archives by writing a pattern
matching the archive, a colon, then the pattern matching the file,
with no whitespace around the colon.
@table @samp
@item archive:file
matches file within archive
@item archive:
matches the whole archive
@item :file
matches file but not one in an archive
@end table
Either one or both of @samp{archive} and @samp{file} can contain shell
wildcards. On DOS based file systems, the linker will assume that a
single letter followed by a colon is a drive specifier, so
@samp{c:myfile.o} is a simple file specification, not @samp{myfile.o}
within an archive called @samp{c}. @samp{archive:file} filespecs may
also be used within an @code{EXCLUDE_FILE} list, but may not appear in
other linker script contexts. For instance, you cannot extract a file
from an archive by using @samp{archive:file} in an @code{INPUT}
command.
If you use a file name without a list of sections, then all sections in
the input file will be included in the output section. This is not
commonly done, but it may by useful on occasion. For example:
@smallexample
data.o
@end smallexample
When you use a file name which is not an @samp{archive:file} specifier
and does not contain any wild card
characters, the linker will first see if you also specified the file
name on the linker command line or in an @code{INPUT} command. If you
did not, the linker will attempt to open the file as an input file, as
though it appeared on the command line. Note that this differs from an
@code{INPUT} command, because the linker will not search for the file in
the archive search path.
@node Input Section Wildcards
@subsubsection Input Section Wildcard Patterns
@cindex input section wildcards
@cindex wildcard file name patterns
@cindex file name wildcard patterns
@cindex section name wildcard patterns
In an input section description, either the file name or the section
name or both may be wildcard patterns.
The file name of @samp{*} seen in many examples is a simple wildcard
pattern for the file name.
The wildcard patterns are like those used by the Unix shell.
@table @samp
@item *
matches any number of characters
@item ?
matches any single character
@item [@var{chars}]
matches a single instance of any of the @var{chars}; the @samp{-}
character may be used to specify a range of characters, as in
@samp{[a-z]} to match any lower case letter
@item \
quotes the following character
@end table
File name wildcard patterns only match files which are explicitly
specified on the command line or in an @code{INPUT} command. The linker
does not search directories to expand wildcards.
If a file name matches more than one wildcard pattern, or if a file name
appears explicitly and is also matched by a wildcard pattern, the linker
will use the first match in the linker script. For example, this
sequence of input section descriptions is probably in error, because the
@file{data.o} rule will not be used:
@smallexample
.data : @{ *(.data) @}
.data1 : @{ data.o(.data) @}
@end smallexample
@cindex SORT_BY_NAME
Normally, the linker will place files and sections matched by wildcards
in the order in which they are seen during the link. You can change
this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard
pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
into ascending order by name before placing them in the output file.
@cindex SORT_BY_ALIGNMENT
@code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
@code{SORT_BY_ALIGNMENT} will sort sections into descending order of
alignment before placing them in the output file. Placing larger
alignments before smaller alignments can reduce the amount of padding
needed.
@cindex SORT_BY_INIT_PRIORITY
@code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
@code{SORT_BY_INIT_PRIORITY} will sort sections into ascending
numerical order of the GCC init_priority attribute encoded in the
section name before placing them in the output file. In
@code{.init_array.NNNNN} and @code{.fini_array.NNNNN}, @code{NNNNN} is
the init_priority. In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
@code{NNNNN} is 65535 minus the init_priority.
@cindex SORT
@code{SORT} is an alias for @code{SORT_BY_NAME}.
When there are nested section sorting commands in linker script, there
can be at most 1 level of nesting for section sorting commands.
@enumerate
@item
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
It will sort the input sections by name first, then by alignment if two
sections have the same name.
@item
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
It will sort the input sections by alignment first, then by name if two
sections have the same alignment.
@item
@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
@item
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
@item
All other nested section sorting commands are invalid.
@end enumerate
When both command-line section sorting option and linker script
section sorting command are used, section sorting command always
takes precedence over the command-line option.
If the section sorting command in linker script isn't nested, the
command-line option will make the section sorting command to be
treated as nested sorting command.
@enumerate
@item
@code{SORT_BY_NAME} (wildcard section pattern ) with
@option{--sort-sections alignment} is equivalent to
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
@item
@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
@option{--sort-section name} is equivalent to
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
@end enumerate
If the section sorting command in linker script is nested, the
command-line option will be ignored.
@cindex SORT_NONE
@code{SORT_NONE} disables section sorting by ignoring the command-line
section sorting option.
If you ever get confused about where input sections are going, use the
@samp{-M} linker option to generate a map file. The map file shows
precisely how input sections are mapped to output sections.
This example shows how wildcard patterns might be used to partition
files. This linker script directs the linker to place all @samp{.text}
sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
The linker will place the @samp{.data} section from all files beginning
with an upper case character in @samp{.DATA}; for all other files, the
linker will place the @samp{.data} section in @samp{.data}.
@smallexample
@group
SECTIONS @{
.text : @{ *(.text) @}
.DATA : @{ [A-Z]*(.data) @}
.data : @{ *(.data) @}
.bss : @{ *(.bss) @}
@}
@end group
@end smallexample
@node Input Section Common
@subsubsection Input Section for Common Symbols
@cindex common symbol placement
@cindex uninitialized data placement
A special notation is needed for common symbols, because in many object
file formats common symbols do not have a particular input section. The
linker treats common symbols as though they are in an input section
named @samp{COMMON}.
You may use file names with the @samp{COMMON} section just as with any
other input sections. You can use this to place common symbols from a
particular input file in one section while common symbols from other
input files are placed in another section.
In most cases, common symbols in input files will be placed in the
@samp{.bss} section in the output file. For example:
@smallexample
.bss @{ *(.bss) *(COMMON) @}
@end smallexample
@cindex scommon section
@cindex small common symbols
Some object file formats have more than one type of common symbol. For
example, the MIPS ELF object file format distinguishes standard common
symbols and small common symbols. In this case, the linker will use a
different special section name for other types of common symbols. In
the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
symbols and @samp{.scommon} for small common symbols. This permits you
to map the different types of common symbols into memory at different
locations.
@cindex [COMMON]
You will sometimes see @samp{[COMMON]} in old linker scripts. This
notation is now considered obsolete. It is equivalent to
@samp{*(COMMON)}.
@node Input Section Keep
@subsubsection Input Section and Garbage Collection
@cindex KEEP
@cindex garbage collection
When link-time garbage collection is in use (@samp{--gc-sections}),
it is often useful to mark sections that should not be eliminated.
This is accomplished by surrounding an input section's wildcard entry
with @code{KEEP()}, as in @code{KEEP(*(.init))} or
@code{KEEP(SORT_BY_NAME(*)(.ctors))}.
@node Input Section Example
@subsubsection Input Section Example
The following example is a complete linker script. It tells the linker
to read all of the sections from file @file{all.o} and place them at the
start of output section @samp{outputa} which starts at location
@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
follows immediately, in the same output section. All of section
@samp{.input2} from @file{foo.o} goes into output section
@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
All of the remaining @samp{.input1} and @samp{.input2} sections from any
files are written to output section @samp{outputc}.
@smallexample
@group
SECTIONS @{
outputa 0x10000 :
@{
all.o
foo.o (.input1)
@}
@end group
@group
outputb :
@{
foo.o (.input2)
foo1.o (.input1)
@}
@end group
@group
outputc :
@{
*(.input1)
*(.input2)
@}
@}
@end group
@end smallexample
If an output section's name is the same as the input section's name
and is representable as a C identifier, then the linker will
automatically @pxref{PROVIDE} two symbols: __start_SECNAME and
__stop_SECNAME, where SECNAME is the name of the section. These
indicate the start address and end address of the output section
respectively. Note: most section names are not representable as
C identifiers because they contain a @samp{.} character.
@node Output Section Data
@subsection Output Section Data
@cindex data
@cindex section data
@cindex output section data
@kindex ASCIZ ``@var{string}''
@kindex BYTE(@var{expression})
@kindex SHORT(@var{expression})
@kindex LONG(@var{expression})
@kindex QUAD(@var{expression})
@kindex SQUAD(@var{expression})
You can include explicit bytes of data in an output section by using
@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
an output section command. Each keyword is followed by an expression in
parentheses providing the value to store (@pxref{Expressions}). The
value of the expression is stored at the current value of the location
counter.
The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
store one, two, four, and eight bytes (respectively). After storing the
bytes, the location counter is incremented by the number of bytes
stored.
For example, this will store the byte 1 followed by the four byte value
of the symbol @samp{addr}:
@smallexample
BYTE(1)
LONG(addr)
@end smallexample
When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
same; they both store an 8 byte, or 64 bit, value. When both host and
target are 32 bits, an expression is computed as 32 bits. In this case
@code{QUAD} stores a 32 bit value zero extended to 64 bits, and
@code{SQUAD} stores a 32 bit value sign extended to 64 bits.
If the object file format of the output file has an explicit endianness,
which is the normal case, the value will be stored in that endianness.
When the object file format does not have an explicit endianness, as is
true of, for example, S-records, the value will be stored in the
endianness of the first input object file.
You can include a zero-terminated string in an output section by using
@code{ASCIZ}. The keyword is followed by a string which is stored at
the current value of the location counter adding a zero byte at the
end. If the string includes spaces it must be enclosed in double
quotes. The string may contain '\n', '\r', '\t' and octal numbers.
Hex numbers are not supported.
For example, this string of 16 characters will create a 17 byte area
@smallexample
ASCIZ "This is 16 bytes"
@end smallexample
Note---these commands only work inside a section description and not
between them, so the following will produce an error from the linker:
@smallexample
SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
@end smallexample
whereas this will work:
@smallexample
SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
@end smallexample
@kindex FILL(@var{expression})
@cindex holes, filling
@cindex unspecified memory
You may use the @code{FILL} command to set the fill pattern for the
current section. It is followed by an expression in parentheses. Any
otherwise unspecified regions of memory within the section (for example,
gaps left due to the required alignment of input sections) are filled
with the value of the expression, repeated as
necessary. A @code{FILL} statement covers memory locations after the
point at which it occurs in the section definition; by including more
than one @code{FILL} statement, you can have different fill patterns in
different parts of an output section.
This example shows how to fill unspecified regions of memory with the
value @samp{0x90}:
@smallexample
FILL(0x90909090)
@end smallexample
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
section attribute, but it only affects the
part of the section following the @code{FILL} command, rather than the
entire section. If both are used, the @code{FILL} command takes
precedence. @xref{Output Section Fill}, for details on the fill
expression.
@node Output Section Keywords
@subsection Output Section Keywords
There are a couple of keywords which can appear as output section
commands.
@table @code
@kindex CREATE_OBJECT_SYMBOLS
@cindex input filename symbols
@cindex filename symbols
@item CREATE_OBJECT_SYMBOLS
The command tells the linker to create a symbol for each input file.
The name of each symbol will be the name of the corresponding input
file. The section of each symbol will be the output section in which
the @code{CREATE_OBJECT_SYMBOLS} command appears.
This is conventional for the a.out object file format. It is not
normally used for any other object file format.
@kindex CONSTRUCTORS
@cindex C++ constructors, arranging in link
@cindex constructors, arranging in link
@item CONSTRUCTORS
When linking using the a.out object file format, the linker uses an
unusual set construct to support C++ global constructors and
destructors. When linking object file formats which do not support
arbitrary sections, such as ECOFF and XCOFF, the linker will
automatically recognize C++ global constructors and destructors by name.
For these object file formats, the @code{CONSTRUCTORS} command tells the
linker to place constructor information in the output section where the
@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
ignored for other object file formats.
The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
the start and end of the global destructors. The
first word in the list is the number of entries, followed by the address
of each constructor or destructor, followed by a zero word. The
compiler must arrange to actually run the code. For these object file
formats @sc{gnu} C++ normally calls constructors from a subroutine
@code{__main}; a call to @code{__main} is automatically inserted into
the startup code for @code{main}. @sc{gnu} C++ normally runs
destructors either by using @code{atexit}, or directly from the function
@code{exit}.
For object file formats such as @code{COFF} or @code{ELF} which support
arbitrary section names, @sc{gnu} C++ will normally arrange to put the
addresses of global constructors and destructors into the @code{.ctors}
and @code{.dtors} sections. Placing the following sequence into your
linker script will build the sort of table which the @sc{gnu} C++
runtime code expects to see.
@smallexample
__CTOR_LIST__ = .;
LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
*(.ctors)
LONG(0)
__CTOR_END__ = .;
__DTOR_LIST__ = .;
LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
*(.dtors)
LONG(0)
__DTOR_END__ = .;
@end smallexample
If you are using the @sc{gnu} C++ support for initialization priority,
which provides some control over the order in which global constructors
are run, you must sort the constructors at link time to ensure that they
are executed in the correct order. When using the @code{CONSTRUCTORS}
command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the
@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
@samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
@samp{*(.dtors)}.
Normally the compiler and linker will handle these issues automatically,
and you will not need to concern yourself with them. However, you may
need to consider this if you are using C++ and writing your own linker
scripts.
@end table
@node Output Section Discarding
@subsection Output Section Discarding
@cindex discarding sections
@cindex sections, discarding
@cindex removing sections
The linker will not normally create output sections with no contents.
This is for convenience when referring to input sections that may or
may not be present in any of the input files. For example:
@smallexample
.foo : @{ *(.foo) @}
@end smallexample
@noindent
will only create a @samp{.foo} section in the output file if there is a
@samp{.foo} section in at least one input file, and if the input
sections are not all empty. Other link script directives that allocate
space in an output section will also create the output section. So
too will assignments to dot even if the assignment does not create
space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym},
@samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
@samp{sym} is an absolute symbol of value 0 defined in the script.
This allows you to force output of an empty section with @samp{. = .}.
The linker will ignore address assignments (@pxref{Output Section Address})
on discarded output sections, except when the linker script defines
symbols in the output section. In that case the linker will obey
the address assignments, possibly advancing dot even though the
section is discarded.
@cindex /DISCARD/
The special output section name @samp{/DISCARD/} may be used to discard
input sections. Any input sections which are assigned to an output
section named @samp{/DISCARD/} are not included in the output file.
This can be used to discard input sections marked with the ELF flag
@code{SHF_GNU_RETAIN}, which would otherwise have been saved from linker
garbage collection.
Note, sections that match the @samp{/DISCARD/} output section will be
discarded even if they are in an ELF section group which has other
members which are not being discarded. This is deliberate.
Discarding takes precedence over grouping.
@node Output Section Attributes
@subsection Output Section Attributes
@cindex output section attributes
We showed above that the full description of an output section looked
like this:
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
[AT(@var{lma})]
[ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
[SUBALIGN(@var{subsection_align})]
[@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
@dots{}
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
@end group
@end smallexample
We've already described @var{section}, @var{address}, and
@var{output-section-command}. In this section we will describe the
remaining section attributes.
@menu
* Output Section Type:: Output section type
* Output Section LMA:: Output section LMA
* Forced Output Alignment:: Forced Output Alignment
* Forced Input Alignment:: Forced Input Alignment
* Output Section Constraint:: Output section constraint
* Output Section Region:: Output section region
* Output Section Phdr:: Output section phdr
* Output Section Fill:: Output section fill
@end menu
@node Output Section Type
@subsubsection Output Section Type
Each output section may have a type. The type is a keyword in
parentheses. The following types are defined:
@table @code
@item NOLOAD
The section should be marked as not loadable, so that it will not be
loaded into memory when the program is run.
@item READONLY
The section should be marked as read-only.
@item DSECT
@item COPY
@item INFO
@item OVERLAY
These type names are supported for backward compatibility, and are
rarely used. They all have the same effect: the section should be
marked as not allocatable, so that no memory is allocated for the
section when the program is run.
@item TYPE = @var{type}
Set the section type to the integer @var{type}. When generating an ELF
output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
@code{SHT_NOTE}, @code{SHT_NOBITS}, @code{SHT_INIT_ARRAY},
@code{SHT_FINI_ARRAY}, and @code{SHT_PREINIT_ARRAY} are also allowed
for @var{type}. It is the user's responsibility to ensure that any
special requirements of the section type are met.
Note - the TYPE only is used if some or all of the contents of the
section do not have an implicit type of their own. So for example:
@smallexample
.foo . TYPE = SHT_PROGBITS @{ *(.bar) @}
@end smallexample
will set the type of section @samp{.foo} to the type of the section
@samp{.bar} in the input files, which may not be the SHT_PROGBITS
type. Whereas:
@smallexample
.foo . TYPE = SHT_PROGBITS @{ BYTE(1) @}
@end smallexample
will set the type of @samp{.foo} to SHT_PROGBBITS. If it is necessary
to override the type of incoming sections and force the output section
type then an extra piece of untyped data will be needed:
@smallexample
.foo . TYPE = SHT_PROGBITS @{ BYTE(1); *(.bar) @}
@end smallexample
@item READONLY ( TYPE = @var{type} )
This form of the syntax combines the @var{READONLY} type with the
type specified by @var{type}.
@end table
@kindex NOLOAD
@cindex prevent unnecessary loading
@cindex loading, preventing
The linker normally sets the attributes of an output section based on
the input sections which map into it. You can override this by using
the section type. For example, in the script sample below, the
@samp{ROM} section is addressed at memory location @samp{0} and does not
need to be loaded when the program is run.
@smallexample
@group
SECTIONS @{
ROM 0 (NOLOAD) : @{ @dots{} @}
@dots{}
@}
@end group
@end smallexample
@node Output Section LMA
@subsubsection Output Section LMA
@kindex AT>@var{lma_region}
@kindex AT(@var{lma})
@cindex load address
@cindex section load address
Every section has a virtual address (VMA) and a load address (LMA); see
@ref{Basic Script Concepts}. The virtual address is specified by the
@pxref{Output Section Address} described earlier. The load address is
specified by the @code{AT} or @code{AT>} keywords. Specifying a load
address is optional.
The @code{AT} keyword takes an expression as an argument. This
specifies the exact load address of the section. The @code{AT>} keyword
takes the name of a memory region as an argument. @xref{MEMORY}. The
load address of the section is set to the next free address in the
region, aligned to the section's alignment requirements.
If neither @code{AT} nor @code{AT>} is specified for an allocatable
section, the linker will use the following heuristic to determine the
load address:
@itemize @bullet
@item
If the section has a specific VMA address, then this is used as
the LMA address as well.
@item
If the section is not allocatable then its LMA is set to its VMA.
@item
Otherwise if a memory region can be found that is compatible
with the current section, and this region contains at least one
section, then the LMA is set so the difference between the
VMA and LMA is the same as the difference between the VMA and LMA of
the last section in the located region.
@item
If no memory regions have been declared then a default region
that covers the entire address space is used in the previous step.
@item
If no suitable region could be found, or there was no previous
section then the LMA is set equal to the VMA.
@end itemize
@cindex ROM initialized data
@cindex initialized data in ROM
This feature is designed to make it easy to build a ROM image. For
example, the following linker script creates three output sections: one
called @samp{.text}, which starts at @code{0x1000}, one called
@samp{.mdata}, which is loaded at the end of the @samp{.text} section
even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
uninitialized data at address @code{0x3000}. The symbol @code{_data} is
defined with the value @code{0x2000}, which shows that the location
counter holds the VMA value, not the LMA value.
@smallexample
@group
SECTIONS
@{
.text 0x1000 : @{ *(.text) _etext = . ; @}
.mdata 0x2000 :
AT ( ADDR (.text) + SIZEOF (.text) )
@{ _data = . ; *(.data); _edata = . ; @}
.bss 0x3000 :
@{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
@}
@end group
@end smallexample
The run-time initialization code for use with a program generated with
this linker script would include something like the following, to copy
the initialized data from the ROM image to its runtime address. Notice
how this code takes advantage of the symbols defined by the linker
script.
@smallexample
@group
extern char _etext, _data, _edata, _bstart, _bend;
char *src = &_etext;
char *dst = &_data;
/* ROM has data at end of text; copy it. */
while (dst < &_edata)
*dst++ = *src++;
/* Zero bss. */
for (dst = &_bstart; dst< &_bend; dst++)
*dst = 0;
@end group
@end smallexample
@node Forced Output Alignment
@subsubsection Forced Output Alignment
@kindex ALIGN(@var{section_align})
@cindex forcing output section alignment
@cindex output section alignment
You can increase an output section's alignment by using ALIGN. As an
alternative you can enforce that the difference between the VMA and LMA remains
intact throughout this output section with the ALIGN_WITH_INPUT attribute.
@node Forced Input Alignment
@subsubsection Forced Input Alignment
@kindex SUBALIGN(@var{subsection_align})
@cindex forcing input section alignment
@cindex input section alignment
You can force input section alignment within an output section by using
SUBALIGN. The value specified overrides any alignment given by input
sections, whether larger or smaller.
@node Output Section Constraint
@subsubsection Output Section Constraint
@kindex ONLY_IF_RO
@kindex ONLY_IF_RW
@cindex constraints on output sections
You can specify that an output section should only be created if all
of its input sections are read-only or all of its input sections are
read-write by using the keyword @code{ONLY_IF_RO} and
@code{ONLY_IF_RW} respectively.
@node Output Section Region
@subsubsection Output Section Region
@kindex >@var{region}
@cindex section, assigning to memory region
@cindex memory regions and sections
You can assign a section to a previously defined region of memory by
using @samp{>@var{region}}. @xref{MEMORY}.
Here is a simple example:
@smallexample
@group
MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
SECTIONS @{ ROM : @{ *(.text) @} >rom @}
@end group
@end smallexample
@node Output Section Phdr
@subsubsection Output Section Phdr
@kindex :@var{phdr}
@cindex section, assigning to program header
@cindex program headers and sections
You can assign a section to a previously defined program segment by
using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
one or more segments, then all subsequent allocated sections will be
assigned to those segments as well, unless they use an explicitly
@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
linker to not put the section in any segment at all.
Here is a simple example:
@smallexample
@group
PHDRS @{ text PT_LOAD ; @}
SECTIONS @{ .text : @{ *(.text) @} :text @}
@end group
@end smallexample
@node Output Section Fill
@subsubsection Output Section Fill
@kindex =@var{fillexp}
@cindex section fill pattern
@cindex fill pattern, entire section
You can set the fill pattern for an entire section by using
@samp{=@var{fillexp}}. @var{fillexp} is an expression
(@pxref{Expressions}). Any otherwise unspecified regions of memory
within the output section (for example, gaps left due to the required
alignment of input sections) will be filled with the value, repeated as
necessary. If the fill expression is a simple hex number, ie. a string
of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
an arbitrarily long sequence of hex digits can be used to specify the
fill pattern; Leading zeros become part of the pattern too. For all
other cases, including extra parentheses or a unary @code{+}, the fill
pattern is the four least significant bytes of the value of the
expression. In all cases, the number is big-endian.
You can also change the fill value with a @code{FILL} command in the
output section commands; (@pxref{Output Section Data}).
Here is a simple example:
@smallexample
@group
SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
@end group
@end smallexample
@node Overlay Description
@subsection Overlay Description
@kindex OVERLAY
@cindex overlays
An overlay description provides an easy way to describe sections which
are to be loaded as part of a single memory image but are to be run at
the same memory address. At run time, some sort of overlay manager will
copy the overlaid sections in and out of the runtime memory address as
required, perhaps by simply manipulating addressing bits. This approach
can be useful, for example, when a certain region of memory is faster
than another.
Overlays are described using the @code{OVERLAY} command. The
@code{OVERLAY} command is used within a @code{SECTIONS} command, like an
output section description. The full syntax of the @code{OVERLAY}
command is as follows:
@smallexample
@group
OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
@{
@var{secname1}
@{
@var{output-section-command}
@var{output-section-command}
@dots{}
@} [:@var{phdr}@dots{}] [=@var{fill}]
@var{secname2}
@{
@var{output-section-command}
@var{output-section-command}
@dots{}
@} [:@var{phdr}@dots{}] [=@var{fill}]
@dots{}
@} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
@end group
@end smallexample
Everything is optional except @code{OVERLAY} (a keyword), and each
section must have a name (@var{secname1} and @var{secname2} above). The
section definitions within the @code{OVERLAY} construct are identical to
those within the general @code{SECTIONS} construct (@pxref{SECTIONS}),
except that no addresses and no memory regions may be defined for
sections within an @code{OVERLAY}.
The comma at the end may be required if a @var{fill} is used and
the next @var{sections-command} looks like a continuation of the expression.
The sections are all defined with the same starting address. The load
addresses of the sections are arranged such that they are consecutive in
memory starting at the load address used for the @code{OVERLAY} as a
whole (as with normal section definitions, the load address is optional,
and defaults to the start address; the start address is also optional,
and defaults to the current value of the location counter).
If the @code{NOCROSSREFS} keyword is used, and there are any
references among the sections, the linker will report an error. Since
the sections all run at the same address, it normally does not make
sense for one section to refer directly to another.
@xref{Miscellaneous Commands, NOCROSSREFS}.
For each section within the @code{OVERLAY}, the linker automatically
provides two symbols. The symbol @code{__load_start_@var{secname}} is
defined as the starting load address of the section. The symbol
@code{__load_stop_@var{secname}} is defined as the final load address of
the section. Any characters within @var{secname} which are not legal
within C identifiers are removed. C (or assembler) code may use these
symbols to move the overlaid sections around as necessary.
At the end of the overlay, the value of the location counter is set to
the start address of the overlay plus the size of the largest section.
Here is an example. Remember that this would appear inside a
@code{SECTIONS} construct.
@smallexample
@group
OVERLAY 0x1000 : AT (0x4000)
@{
.text0 @{ o1/*.o(.text) @}
.text1 @{ o2/*.o(.text) @}
@}
@end group
@end smallexample
@noindent
This will define both @samp{.text0} and @samp{.text1} to start at
address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
@samp{.text1} will be loaded immediately after @samp{.text0}. The
following symbols will be defined if referenced: @code{__load_start_text0},
@code{__load_stop_text0}, @code{__load_start_text1},
@code{__load_stop_text1}.
C code to copy overlay @code{.text1} into the overlay area might look
like the following.
@smallexample
@group
extern char __load_start_text1, __load_stop_text1;
memcpy ((char *) 0x1000, &__load_start_text1,
&__load_stop_text1 - &__load_start_text1);
@end group
@end smallexample
Note that the @code{OVERLAY} command is just syntactic sugar, since
everything it does can be done using the more basic commands. The above
example could have been written identically as follows.
@smallexample
@group
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
PROVIDE (__load_start_text0 = LOADADDR (.text0));
PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
PROVIDE (__load_start_text1 = LOADADDR (.text1));
PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
@end group
@end smallexample
@node MEMORY
@section MEMORY Command
@kindex MEMORY
@cindex memory regions
@cindex regions of memory
@cindex allocating memory
@cindex discontinuous memory
The linker's default configuration permits allocation of all available
memory. You can override this by using the @code{MEMORY} command.
The @code{MEMORY} command describes the location and size of blocks of
memory in the target. You can use it to describe which memory regions
may be used by the linker, and which memory regions it must avoid. You
can then assign sections to particular memory regions. The linker will
set section addresses based on the memory regions, and will warn about
regions that become too full. The linker will not shuffle sections
around to fit into the available regions.
A linker script may contain many uses of the @code{MEMORY} command,
however, all memory blocks defined are treated as if they were
specified inside a single @code{MEMORY} command. The syntax for
@code{MEMORY} is:
@smallexample
@group
MEMORY
@{
@var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
@dots{}
@}
@end group
@end smallexample
The @var{name} is a name used in the linker script to refer to the
region. The region name has no meaning outside of the linker script.
Region names are stored in a separate name space, and will not conflict
with symbol names, file names, or section names. Each memory region
must have a distinct name within the @code{MEMORY} command. However you can
add later alias names to existing memory regions with the @ref{REGION_ALIAS}
command.
@cindex memory region attributes
The @var{attr} string is an optional list of attributes that specify
whether to use a particular memory region for an input section which is
not explicitly mapped in the linker script. As described in
@ref{SECTIONS}, if you do not specify an output section for some input
section, the linker will create an output section with the same name as
the input section. If you define region attributes, the linker will use
them to select the memory region for the output section that it creates.
The @var{attr} string must consist only of the following characters:
@table @samp
@item R
Read-only section
@item W
Read/write section
@item X
Executable section
@item A
Allocatable section
@item I
Initialized section
@item L
Same as @samp{I}
@item !
Invert the sense of any of the attributes that follow
@end table
If an unmapped section matches any of the listed attributes other than
@samp{!}, it will be placed in the memory region. The @samp{!}
attribute reverses the test for the characters that follow, so that an
unmapped section will be placed in the memory region only if it does
not match any of the attributes listed afterwards. Thus an attribute
string of @samp{RW!X} will match any unmapped section that has either
or both of the @samp{R} and @samp{W} attributes, but only as long as
the section does not also have the @samp{X} attribute.
@kindex ORIGIN =
@kindex o =
@kindex org =
The @var{origin} is an numerical expression for the start address of
the memory region. The expression must evaluate to a constant and it
cannot involve any symbols. The keyword @code{ORIGIN} may be
abbreviated to @code{org} or @code{o} (but not, for example,
@code{ORG}).
@kindex LENGTH =
@kindex len =
@kindex l =
The @var{len} is an expression for the size in bytes of the memory
region. As with the @var{origin} expression, the expression must
be numerical only and must evaluate to a constant. The keyword
@code{LENGTH} may be abbreviated to @code{len} or @code{l}.
In the following example, we specify that there are two memory regions
available for allocation: one starting at @samp{0} for 256 kilobytes,
and the other starting at @samp{0x40000000} for four megabytes. The
linker will place into the @samp{rom} memory region every section which
is not explicitly mapped into a memory region, and is either read-only
or executable. The linker will place other sections which are not
explicitly mapped into a memory region into the @samp{ram} memory
region.
@smallexample
@group
MEMORY
@{
rom (rx) : ORIGIN = 0, LENGTH = 256K
ram (!rx) : org = 0x40000000, l = 4M
@}
@end group
@end smallexample
Once you define a memory region, you can direct the linker to place
specific output sections into that memory region by using the
@samp{>@var{region}} output section attribute. For example, if you have
a memory region named @samp{mem}, you would use @samp{>mem} in the
output section definition. @xref{Output Section Region}. If no address
was specified for the output section, the linker will set the address to
the next available address within the memory region. If the combined
output sections directed to a memory region are too large for the
region, the linker will issue an error message.
It is possible to access the origin and length of a memory in an
expression via the @code{ORIGIN(@var{memory})} and
@code{LENGTH(@var{memory})} functions:
@smallexample
@group
_fstack = ORIGIN(ram) + LENGTH(ram) - 4;
@end group
@end smallexample
@node PHDRS
@section PHDRS Command
@kindex PHDRS
@cindex program headers
@cindex ELF program headers
@cindex program segments
@cindex segments, ELF
The ELF object file format uses @dfn{program headers}, also knows as
@dfn{segments}. The program headers describe how the program should be
loaded into memory. You can print them out by using the @code{objdump}
program with the @samp{-p} option.
When you run an ELF program on a native ELF system, the system loader
reads the program headers in order to figure out how to load the
program. This will only work if the program headers are set correctly.
This manual does not describe the details of how the system loader
interprets program headers; for more information, see the ELF ABI.
The linker will create reasonable program headers by default. However,
in some cases, you may need to specify the program headers more
precisely. You may use the @code{PHDRS} command for this purpose. When
the linker sees the @code{PHDRS} command in the linker script, it will
not create any program headers other than the ones specified.
The linker only pays attention to the @code{PHDRS} command when
generating an ELF output file. In other cases, the linker will simply
ignore @code{PHDRS}.
This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
@smallexample
@group
PHDRS
@{
@var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
[ FLAGS ( @var{flags} ) ] ;
@}
@end group
@end smallexample
The @var{name} is used only for reference in the @code{SECTIONS} command
of the linker script. It is not put into the output file. Program
header names are stored in a separate name space, and will not conflict
with symbol names, file names, or section names. Each program header
must have a distinct name. The headers are processed in order and it
is usual for them to map to sections in ascending load address order.
Certain program header types describe segments of memory which the
system loader will load from the file. In the linker script, you
specify the contents of these segments by placing allocatable output
sections in the segments. You use the @samp{:@var{phdr}} output section
attribute to place a section in a particular segment. @xref{Output
Section Phdr}.
It is normal to put certain sections in more than one segment. This
merely implies that one segment of memory contains another. You may
repeat @samp{:@var{phdr}}, using it once for each segment which should
contain the section.
If you place a section in one or more segments using @samp{:@var{phdr}},
then the linker will place all subsequent allocatable sections which do
not specify @samp{:@var{phdr}} in the same segments. This is for
convenience, since generally a whole set of contiguous sections will be
placed in a single segment. You can use @code{:NONE} to override the
default segment and tell the linker to not put the section in any
segment at all.
@kindex FILEHDR
@kindex PHDRS
You may use the @code{FILEHDR} and @code{PHDRS} keywords after
the program header type to further describe the contents of the segment.
The @code{FILEHDR} keyword means that the segment should include the ELF
file header. The @code{PHDRS} keyword means that the segment should
include the ELF program headers themselves. If applied to a loadable
segment (@code{PT_LOAD}), all prior loadable segments must have one of
these keywords.
The @var{type} may be one of the following. The numbers indicate the
value of the keyword.
@table @asis
@item @code{PT_NULL} (0)
Indicates an unused program header.
@item @code{PT_LOAD} (1)
Indicates that this program header describes a segment to be loaded from
the file.
@item @code{PT_DYNAMIC} (2)
Indicates a segment where dynamic linking information can be found.
@item @code{PT_INTERP} (3)
Indicates a segment where the name of the program interpreter may be
found.
@item @code{PT_NOTE} (4)
Indicates a segment holding note information.
@item @code{PT_SHLIB} (5)
A reserved program header type, defined but not specified by the ELF
ABI.
@item @code{PT_PHDR} (6)
Indicates a segment where the program headers may be found.
@item @code{PT_TLS} (7)
Indicates a segment containing thread local storage.
@item @var{expression}
An expression giving the numeric type of the program header. This may
be used for types not defined above.
@end table
You can specify that a segment should be loaded at a particular address
in memory by using an @code{AT} expression. This is identical to the
@code{AT} command used as an output section attribute (@pxref{Output
Section LMA}). The @code{AT} command for a program header overrides the
output section attribute.
The linker will normally set the segment flags based on the sections
which comprise the segment. You may use the @code{FLAGS} keyword to
explicitly specify the segment flags. The value of @var{flags} must be
an integer. It is used to set the @code{p_flags} field of the program
header.
Here is an example of @code{PHDRS}. This shows a typical set of program
headers used on a native ELF system.
@example
@group
PHDRS
@{
headers PT_PHDR PHDRS ;
interp PT_INTERP ;
text PT_LOAD FILEHDR PHDRS ;
data PT_LOAD ;
dynamic PT_DYNAMIC ;
@}
SECTIONS
@{
. = SIZEOF_HEADERS;
.interp : @{ *(.interp) @} :text :interp
.text : @{ *(.text) @} :text
.rodata : @{ *(.rodata) @} /* defaults to :text */
@dots{}
. = . + 0x1000; /* move to a new page in memory */
.data : @{ *(.data) @} :data
.dynamic : @{ *(.dynamic) @} :data :dynamic
@dots{}
@}
@end group
@end example
@node VERSION
@section VERSION Command
@kindex VERSION @{script text@}
@cindex symbol versions
@cindex version script
@cindex versions of symbols
The linker supports symbol versions when using ELF. Symbol versions are
only useful when using shared libraries. The dynamic linker can use
symbol versions to select a specific version of a function when it runs
a program that may have been linked against an earlier version of the
shared library.
You can include a version script directly in the main linker script, or
you can supply the version script as an implicit linker script. You can
also use the @samp{--version-script} linker option.
The syntax of the @code{VERSION} command is simply
@smallexample
VERSION @{ version-script-commands @}
@end smallexample
The format of the version script commands is identical to that used by
Sun's linker in Solaris 2.5. The version script defines a tree of
version nodes. You specify the node names and interdependencies in the
version script. You can specify which symbols are bound to which
version nodes, and you can reduce a specified set of symbols to local
scope so that they are not globally visible outside of the shared
library.
The easiest way to demonstrate the version script language is with a few
examples.
@smallexample
VERS_1.1 @{
global:
foo1;
local:
old*;
original*;
new*;
@};
VERS_1.2 @{
foo2;
@} VERS_1.1;
VERS_2.0 @{
bar1; bar2;
extern "C++" @{
ns::*;
"f(int, double)";
@};
@} VERS_1.2;
@end smallexample
This example version script defines three version nodes. The first
version node defined is @samp{VERS_1.1}; it has no other dependencies.
The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
a number of symbols to local scope so that they are not visible outside
of the shared library; this is done using wildcard patterns, so that any
symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
is matched. The wildcard patterns available are the same as those used
in the shell when matching filenames (also known as ``globbing'').
However, if you specify the symbol name inside double quotes, then the
name is treated as literal, rather than as a glob pattern.
Next, the version script defines node @samp{VERS_1.2}. This node
depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
to the version node @samp{VERS_1.2}.
Finally, the version script defines node @samp{VERS_2.0}. This node
depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
When the linker finds a symbol defined in a library which is not
specifically bound to a version node, it will effectively bind it to an
unspecified base version of the library. You can bind all otherwise
unspecified symbols to a given version node by using @samp{global: *;}
somewhere in the version script. Note that it's slightly crazy to use
wildcards in a global spec except on the last version node. Global
wildcards elsewhere run the risk of accidentally adding symbols to the
set exported for an old version. That's wrong since older versions
ought to have a fixed set of symbols.
The names of the version nodes have no specific meaning other than what
they might suggest to the person reading them. The @samp{2.0} version
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
However, this would be a confusing way to write a version script.
Node name can be omitted, provided it is the only version node
in the version script. Such version script doesn't assign any versions to
symbols, only selects which symbols will be globally visible out and which
won't.
@smallexample
@{ global: foo; bar; local: *; @};
@end smallexample
When you link an application against a shared library that has versioned
symbols, the application itself knows which version of each symbol it
requires, and it also knows which version nodes it needs from each
shared library it is linked against. Thus at runtime, the dynamic
loader can make a quick check to make sure that the libraries you have
linked against do in fact supply all of the version nodes that the
application will need to resolve all of the dynamic symbols. In this
way it is possible for the dynamic linker to know with certainty that
all external symbols that it needs will be resolvable without having to
search for each symbol reference.
The symbol versioning is in effect a much more sophisticated way of
doing minor version checking that SunOS does. The fundamental problem
that is being addressed here is that typically references to external
functions are bound on an as-needed basis, and are not all bound when
the application starts up. If a shared library is out of date, a
required interface may be missing; when the application tries to use
that interface, it may suddenly and unexpectedly fail. With symbol
versioning, the user will get a warning when they start their program if
the libraries being used with the application are too old.
There are several GNU extensions to Sun's versioning approach. The
first of these is the ability to bind a symbol to a version node in the
source file where the symbol is defined instead of in the versioning
script. This was done mainly to reduce the burden on the library
maintainer. You can do this by putting something like:
@smallexample
__asm__(".symver original_foo,foo@@VERS_1.1");
@end smallexample
@noindent
in the C source file. This renames the function @samp{original_foo} to
be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
The @samp{local:} directive can be used to prevent the symbol
@samp{original_foo} from being exported. A @samp{.symver} directive
takes precedence over a version script.
The second GNU extension is to allow multiple versions of the same
function to appear in a given shared library. In this way you can make
an incompatible change to an interface without increasing the major
version number of the shared library, while still allowing applications
linked against the old interface to continue to function.
To do this, you must use multiple @samp{.symver} directives in the
source file. Here is an example:
@smallexample
__asm__(".symver original_foo,foo@@");
__asm__(".symver old_foo,foo@@VERS_1.1");
__asm__(".symver old_foo1,foo@@VERS_1.2");
__asm__(".symver new_foo,foo@@@@VERS_2.0");
@end smallexample
In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
unspecified base version of the symbol. The source file that contains this
example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
@samp{old_foo1}, and @samp{new_foo}.
When you have multiple definitions of a given symbol, there needs to be
some way to specify a default version to which external references to
this symbol will be bound. You can do this with the
@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
declare one version of a symbol as the default in this manner; otherwise
you would effectively have multiple definitions of the same symbol.
If you wish to bind a reference to a specific version of the symbol
within the shared library, you can use the aliases of convenience
(i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
specifically bind to an external version of the function in question.
You can also specify the language in the version script:
@smallexample
VERSION extern "lang" @{ version-script-commands @}
@end smallexample
The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
The linker will iterate over the list of symbols at the link time and
demangle them according to @samp{lang} before matching them to the
patterns specified in @samp{version-script-commands}. The default
@samp{lang} is @samp{C}.
Demangled names may contains spaces and other special characters. As
described above, you can use a glob pattern to match demangled names,
or you can use a double-quoted string to match the string exactly. In
the latter case, be aware that minor differences (such as differing
whitespace) between the version script and the demangler output will
cause a mismatch. As the exact string generated by the demangler
might change in the future, even if the mangled name does not, you
should check that all of your version directives are behaving as you
expect when you upgrade.
@node Expressions
@section Expressions in Linker Scripts
@cindex expressions
@cindex arithmetic
The syntax for expressions in the linker script language is identical to
that of C expressions, except that whitespace is required in some
places to resolve syntactic ambiguities. All expressions are
evaluated as integers. All expressions are evaluated in the same
size, which is 32 bits if both the host and target are 32 bits, and is
otherwise 64 bits.
You can use and set symbol values in expressions.
The linker defines several special purpose builtin functions for use in
expressions.
@menu
* Constants:: Constants
* Symbolic Constants:: Symbolic constants
* Symbols:: Symbol Names
* Orphan Sections:: Orphan Sections
* Location Counter:: The Location Counter
* Operators:: Operators
* Evaluation:: Evaluation
* Expression Section:: The Section of an Expression
* Builtin Functions:: Builtin Functions
@end menu
@node Constants
@subsection Constants
@cindex integer notation
@cindex constants in linker scripts
All constants are integers.
As in C, the linker considers an integer beginning with @samp{0} to be
octal, and an integer beginning with @samp{0x} or @samp{0X} to be
hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or
@samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or
@samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer
value without a prefix or a suffix is considered to be decimal.
@cindex scaled integers
@cindex K and M integer suffixes
@cindex M and K integer suffixes
@cindex suffixes for integers
@cindex integer suffixes
In addition, you can use the suffixes @code{K} and @code{M} to scale a
constant by
@c TEXI2ROFF-KILL
@ifnottex
@c END TEXI2ROFF-KILL
@code{1024} or @code{1024*1024}
@c TEXI2ROFF-KILL
@end ifnottex
@tex
${\rm 1024}$ or ${\rm 1024}^2$
@end tex
@c END TEXI2ROFF-KILL
respectively. For example, the following
all refer to the same quantity:
@smallexample
_fourk_1 = 4K;
_fourk_2 = 4096;
_fourk_3 = 0x1000;
_fourk_4 = 10000o;
@end smallexample
Note - the @code{K} and @code{M} suffixes cannot be used in
conjunction with the base suffixes mentioned above.
@node Symbolic Constants
@subsection Symbolic Constants
@cindex symbolic constants
@kindex CONSTANT
It is possible to refer to target-specific constants via the use of
the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
@table @code
@item MAXPAGESIZE
@kindex MAXPAGESIZE
The target's maximum page size.
@item COMMONPAGESIZE
@kindex COMMONPAGESIZE
The target's default page size.
@end table
So for example:
@smallexample
.text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
@end smallexample
will create a text section aligned to the largest page boundary
supported by the target.
@node Symbols
@subsection Symbol Names
@cindex symbol names
@cindex names
@cindex quoted symbol names
@kindex "
Unless quoted, symbol names start with a letter, underscore, or period
and may include letters, digits, underscores, periods, and hyphens.
Unquoted symbol names must not conflict with any keywords. You can
specify a symbol which contains odd characters or has the same name as a
keyword by surrounding the symbol name in double quotes:
@smallexample
"SECTION" = 9;
"with a space" = "also with a space" + 10;
@end smallexample
Since symbols can contain many non-alphabetic characters, it is safest
to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
whereas @samp{A - B} is an expression involving subtraction.
@node Orphan Sections
@subsection Orphan Sections
@cindex orphan
Orphan sections are sections present in the input files which
are not explicitly placed into the output file by the linker
script. The linker will still copy these sections into the
output file by either finding, or creating a suitable output section
in which to place the orphaned input section.
If the name of an orphaned input section exactly matches the name of
an existing output section, then the orphaned input section will be
placed at the end of that output section.
If there is no output section with a matching name then new output
sections will be created. Each new output section will have the same
name as the orphan section placed within it. If there are multiple
orphan sections with the same name, these will all be combined into
one new output section.
If new output sections are created to hold orphaned input sections,
then the linker must decide where to place these new output sections
in relation to existing output sections. On most modern targets, the
linker attempts to place orphan sections after sections of the same
attribute, such as code vs data, loadable vs non-loadable, etc. If no
sections with matching attributes are found, or your target lacks this
support, the orphan section is placed at the end of the file.
The command-line options @samp{--orphan-handling} and @samp{--unique}
(@pxref{Options,,Command-line Options}) can be used to control which
output sections an orphan is placed in.
@node Location Counter
@subsection The Location Counter
@kindex .
@cindex dot
@cindex location counter
@cindex current output location
The special linker variable @dfn{dot} @samp{.} always contains the
current output location counter. Since the @code{.} always refers to a
location in an output section, it may only appear in an expression
within a @code{SECTIONS} command. The @code{.} symbol may appear
anywhere that an ordinary symbol is allowed in an expression.
@cindex holes
Assigning a value to @code{.} will cause the location counter to be
moved. This may be used to create holes in the output section. The
location counter may not be moved backwards inside an output section,
and may not be moved backwards outside of an output section if so
doing creates areas with overlapping LMAs.
@smallexample
SECTIONS
@{
output :
@{
file1(.text)
. = . + 1000;
file2(.text)
. += 1000;
file3(.text)
@} = 0x12345678;
@}
@end smallexample
@noindent
In the previous example, the @samp{.text} section from @file{file1} is
located at the beginning of the output section @samp{output}. It is
followed by a 1000 byte gap. Then the @samp{.text} section from
@file{file2} appears, also with a 1000 byte gap following before the
@samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
specifies what data to write in the gaps (@pxref{Output Section Fill}).
@cindex dot inside sections
Note: @code{.} actually refers to the byte offset from the start of the
current containing object. Normally this is the @code{SECTIONS}
statement, whose start address is 0, hence @code{.} can be used as an
absolute address. If @code{.} is used inside a section description
however, it refers to the byte offset from the start of that section,
not an absolute address. Thus in a script like this:
@smallexample
SECTIONS
@{
. = 0x100
.text: @{
*(.text)
. = 0x200
@}
. = 0x500
.data: @{
*(.data)
. += 0x600
@}
@}
@end smallexample
The @samp{.text} section will be assigned a starting address of 0x100
and a size of exactly 0x200 bytes, even if there is not enough data in
the @samp{.text} input sections to fill this area. (If there is too
much data, an error will be produced because this would be an attempt to
move @code{.} backwards). The @samp{.data} section will start at 0x500
and it will have an extra 0x600 bytes worth of space after the end of
the values from the @samp{.data} input sections and before the end of
the @samp{.data} output section itself.
@cindex dot outside sections
Setting symbols to the value of the location counter outside of an
output section statement can result in unexpected values if the linker
needs to place orphan sections. For example, given the following:
@smallexample
SECTIONS
@{
start_of_text = . ;
.text: @{ *(.text) @}
end_of_text = . ;
start_of_data = . ;
.data: @{ *(.data) @}
end_of_data = . ;
@}
@end smallexample
If the linker needs to place some input section, e.g. @code{.rodata},
not mentioned in the script, it might choose to place that section
between @code{.text} and @code{.data}. You might think the linker
should place @code{.rodata} on the blank line in the above script, but
blank lines are of no particular significance to the linker. As well,
the linker doesn't associate the above symbol names with their
sections. Instead, it assumes that all assignments or other
statements belong to the previous output section, except for the
special case of an assignment to @code{.}. I.e., the linker will
place the orphan @code{.rodata} section as if the script was written
as follows:
@smallexample
SECTIONS
@{
start_of_text = . ;
.text: @{ *(.text) @}
end_of_text = . ;
start_of_data = . ;
.rodata: @{ *(.rodata) @}
.data: @{ *(.data) @}
end_of_data = . ;
@}
@end smallexample
This may or may not be the script author's intention for the value of
@code{start_of_data}. One way to influence the orphan section
placement is to assign the location counter to itself, as the linker
assumes that an assignment to @code{.} is setting the start address of
a following output section and thus should be grouped with that
section. So you could write:
@smallexample
SECTIONS
@{
start_of_text = . ;
.text: @{ *(.text) @}
end_of_text = . ;
. = . ;
start_of_data = . ;
.data: @{ *(.data) @}
end_of_data = . ;
@}
@end smallexample
Now, the orphan @code{.rodata} section will be placed between
@code{end_of_text} and @code{start_of_data}.
@need 2000
@node Operators
@subsection Operators
@cindex operators for arithmetic
@cindex arithmetic operators
@cindex precedence in expressions
The linker recognizes the standard C set of arithmetic operators, with
the standard bindings and precedence levels:
@c TEXI2ROFF-KILL
@ifnottex
@c END TEXI2ROFF-KILL
@smallexample
precedence associativity Operators Notes
(highest)
1 left ! - ~ (1)
2 left * / %
3 left + -
4 left >> <<
5 left == != > < <= >=
6 left &
7 left |
8 left &&
9 left ||
10 right ? :
11 right &= += -= *= /= (2)
(lowest)
@end smallexample
Notes:
(1) Prefix operators
(2) @xref{Assignments}.
@c TEXI2ROFF-KILL
@end ifnottex
@tex
\vskip \baselineskip
%"lispnarrowing" is the extra indent used generally for smallexample
\hskip\lispnarrowing\vbox{\offinterlineskip
\hrule
\halign
{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
height2pt&\omit&&\omit&&\omit&\cr
&Precedence&& Associativity &&{\rm Operators}&\cr
height2pt&\omit&&\omit&&\omit&\cr
\noalign{\hrule}
height2pt&\omit&&\omit&&\omit&\cr
&highest&&&&&\cr
% '176 is tilde, '~' in tt font
&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
&2&&left&&* / \%&\cr
&3&&left&&+ -&\cr
&4&&left&&>> <<&\cr
&5&&left&&== != > < <= >=&\cr
&6&&left&&\&&\cr
&7&&left&&|&\cr
&8&&left&&{\&\&}&\cr
&9&&left&&||&\cr
&10&&right&&? :&\cr
&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
&lowest&&&&&\cr
height2pt&\omit&&\omit&&\omit&\cr}
\hrule}
@end tex
@iftex
{
@obeylines@parskip=0pt@parindent=0pt
@dag@quad Prefix operators.
@ddag@quad @xref{Assignments}.
}
@end iftex
@c END TEXI2ROFF-KILL
@node Evaluation
@subsection Evaluation
@cindex lazy evaluation
@cindex expression evaluation order
The linker evaluates expressions lazily. It only computes the value of
an expression when absolutely necessary.
The linker needs some information, such as the value of the start
address of the first section, and the origins and lengths of memory
regions, in order to do any linking at all. These values are computed
as soon as possible when the linker reads in the linker script.
However, other values (such as symbol values) are not known or needed
until after storage allocation. Such values are evaluated later, when
other information (such as the sizes of output sections) is available
for use in the symbol assignment expression.
The sizes of sections cannot be known until after allocation, so
assignments dependent upon these are not performed until after
allocation.
Some expressions, such as those depending upon the location counter
@samp{.}, must be evaluated during section allocation.
If the result of an expression is required, but the value is not
available, then an error results. For example, a script like the
following
@smallexample
@group
SECTIONS
@{
.text 9+this_isnt_constant :
@{ *(.text) @}
@}
@end group
@end smallexample
@noindent
will cause the error message @samp{non constant expression for initial
address}.
@node Expression Section
@subsection The Section of an Expression
@cindex expression sections
@cindex absolute expressions
@cindex relative expressions
@cindex absolute and relocatable symbols
@cindex relocatable and absolute symbols
@cindex symbols, relocatable and absolute
Addresses and symbols may be section relative, or absolute. A section
relative symbol is relocatable. If you request relocatable output
using the @samp{-r} option, a further link operation may change the
value of a section relative symbol. On the other hand, an absolute
symbol will retain the same value throughout any further link
operations.
Some terms in linker expressions are addresses. This is true of
section relative symbols and for builtin functions that return an
address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
@code{SEGMENT_START}. Other terms are simply numbers, or are builtin
functions that return a non-address value, such as @code{LENGTH}.
One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
differently depending on their location, for compatibility with older
versions of @code{ld}. Expressions appearing outside an output
section definition treat all numbers as absolute addresses.
Expressions appearing inside an output section definition treat
absolute symbols as numbers. If @code{LD_FEATURE ("SANE_EXPR")} is
given, then absolute symbols and numbers are simply treated as numbers
everywhere.
In the following simple example,
@smallexample
@group
SECTIONS
@{
. = 0x100;
__executable_start = 0x100;
.data :
@{
. = 0x10;
__data_start = 0x10;
*(.data)
@}
@dots{}
@}
@end group
@end smallexample
both @code{.} and @code{__executable_start} are set to the absolute
address 0x100 in the first two assignments, then both @code{.} and
@code{__data_start} are set to 0x10 relative to the @code{.data}
section in the second two assignments.
For expressions involving numbers, relative addresses and absolute
addresses, ld follows these rules to evaluate terms:
@itemize @bullet
@item
Unary operations on an absolute address or number, and binary
operations on two absolute addresses or two numbers, or between one
absolute address and a number, apply the operator to the value(s).
@item
Unary operations on a relative address, and binary operations on two
relative addresses in the same section or between one relative address
and a number, apply the operator to the offset part of the address(es).
@item
Other binary operations, that is, between two relative addresses not
in the same section, or between a relative address and an absolute
address, first convert any non-absolute term to an absolute address
before applying the operator.
@end itemize
The result section of each sub-expression is as follows:
@itemize @bullet
@item
An operation involving only numbers results in a number.
@item
The result of comparisons, @samp{&&} and @samp{||} is also a number.
@item
The result of other binary arithmetic and logical operations on two
relative addresses in the same section or two absolute addresses
(after above conversions) is also a number when
@code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition
but an absolute address otherwise.
@item
The result of other operations on relative addresses or one
relative address and a number, is a relative address in the same
section as the relative operand(s).
@item
The result of other operations on absolute addresses (after above
conversions) is an absolute address.
@end itemize
You can use the builtin function @code{ABSOLUTE} to force an expression
to be absolute when it would otherwise be relative. For example, to
create an absolute symbol set to the address of the end of the output
section @samp{.data}:
@smallexample
SECTIONS
@{
.data : @{ *(.data) _edata = ABSOLUTE(.); @}
@}
@end smallexample
@noindent
If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
@samp{.data} section.
Using @code{LOADADDR} also forces an expression absolute, since this
particular builtin function returns an absolute address.
@node Builtin Functions
@subsection Builtin Functions
@cindex functions in expressions
The linker script language includes a number of builtin functions for
use in linker script expressions.
@table @code
@item ABSOLUTE(@var{exp})
@kindex ABSOLUTE(@var{exp})
@cindex expression, absolute
Return the absolute (non-relocatable, as opposed to non-negative) value
of the expression @var{exp}. Primarily useful to assign an absolute
value to a symbol within a section definition, where symbol values are
normally section relative. @xref{Expression Section}.
@item ADDR(@var{section})
@kindex ADDR(@var{section})
@cindex section address in expression
Return the address (VMA) of the named @var{section}. Your
script must previously have defined the location of that section. In
the following example, @code{start_of_output_1}, @code{symbol_1} and
@code{symbol_2} are assigned equivalent values, except that
@code{symbol_1} will be relative to the @code{.output1} section while
the other two will be absolute:
@smallexample
@group
SECTIONS @{ @dots{}
.output1 :
@{
start_of_output_1 = ABSOLUTE(.);
@dots{}
@}
.output :
@{
symbol_1 = ADDR(.output1);
symbol_2 = start_of_output_1;
@}
@dots{} @}
@end group
@end smallexample
@item ALIGN(@var{align})
@itemx ALIGN(@var{exp},@var{align})
@kindex ALIGN(@var{align})
@kindex ALIGN(@var{exp},@var{align})
@cindex round up location counter
@cindex align location counter
@cindex round up expression
@cindex align expression
Return the location counter (@code{.}) or arbitrary expression aligned
to the next @var{align} boundary. The single operand @code{ALIGN}
doesn't change the value of the location counter---it just does
arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
expression to be aligned upwards (@code{ALIGN(@var{align})} is
equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
Here is an example which aligns the output @code{.data} section to the
next @code{0x2000} byte boundary after the preceding section and sets a
variable within the section to the next @code{0x8000} boundary after the
input sections:
@smallexample
@group
SECTIONS @{ @dots{}
.data ALIGN(0x2000): @{
*(.data)
variable = ALIGN(0x8000);
@}
@dots{} @}
@end group
@end smallexample
@noindent
The first use of @code{ALIGN} in this example specifies the location of
a section because it is used as the optional @var{address} attribute of
a section definition (@pxref{Output Section Address}). The second use
of @code{ALIGN} is used to defines the value of a symbol.
The builtin function @code{NEXT} is closely related to @code{ALIGN}.
@item ALIGNOF(@var{section})
@kindex ALIGNOF(@var{section})
@cindex section alignment
Return the alignment in bytes of the named @var{section}, if that section has
been allocated. If the section has not been allocated when this is
evaluated, the linker will report an error. In the following example,
the alignment of the @code{.output} section is stored as the first
value in that section.
@smallexample
@group
SECTIONS@{ @dots{}
.output @{
LONG (ALIGNOF (.output))
@dots{}
@}
@dots{} @}
@end group
@end smallexample
@item BLOCK(@var{exp})
@kindex BLOCK(@var{exp})
This is a synonym for @code{ALIGN}, for compatibility with older linker
scripts. It is most often seen when setting the address of an output
section.
@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
This is equivalent to either
@smallexample
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
@end smallexample
or
@smallexample
(ALIGN(@var{maxpagesize})
+ ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize})))
@end smallexample
@noindent
depending on whether the latter uses fewer @var{commonpagesize} sized pages
for the data segment (area between the result of this expression and
@code{DATA_SEGMENT_END}) than the former or not.
If the latter form is used, it means @var{commonpagesize} bytes of runtime
memory will be saved at the expense of up to @var{commonpagesize} wasted
bytes in the on-disk file.
This expression can only be used directly in @code{SECTIONS} commands, not in
any output section descriptions and only once in the linker script.
@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
be the system page size the object wants to be optimized for while still
running on system page sizes up to @var{maxpagesize}. Note however
that @samp{-z relro} protection will not be effective if the system
page size is larger than @var{commonpagesize}.
@noindent
Example:
@smallexample
. = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
@end smallexample
@item DATA_SEGMENT_END(@var{exp})
@kindex DATA_SEGMENT_END(@var{exp})
This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
evaluation purposes.
@smallexample
. = DATA_SEGMENT_END(.);
@end smallexample
@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
This defines the end of the @code{PT_GNU_RELRO} segment when
@samp{-z relro} option is used.
When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
@var{exp} + @var{offset} is aligned to the @var{commonpagesize}
argument given to @code{DATA_SEGMENT_ALIGN}. If present in the linker
script, it must be placed between @code{DATA_SEGMENT_ALIGN} and
@code{DATA_SEGMENT_END}. Evaluates to the second argument plus any
padding needed at the end of the @code{PT_GNU_RELRO} segment due to
section alignment.
@smallexample
. = DATA_SEGMENT_RELRO_END(24, .);
@end smallexample
@item DEFINED(@var{symbol})
@kindex DEFINED(@var{symbol})
@cindex symbol defaults
Return 1 if @var{symbol} is in the linker global symbol table and is
defined before the statement using DEFINED in the script, otherwise
return 0. You can use this function to provide
default values for symbols. For example, the following script fragment
shows how to set a global symbol @samp{begin} to the first location in
the @samp{.text} section---but if a symbol called @samp{begin} already
existed, its value is preserved:
@smallexample
@group
SECTIONS @{ @dots{}
.text : @{
begin = DEFINED(begin) ? begin : . ;
@dots{}
@}
@dots{}
@}
@end group
@end smallexample
@item LENGTH(@var{memory})
@kindex LENGTH(@var{memory})
Return the length of the memory region named @var{memory}.
@item LOADADDR(@var{section})
@kindex LOADADDR(@var{section})
@cindex section load address in expression
Return the absolute LMA of the named @var{section}. (@pxref{Output
Section LMA}).
@item LOG2CEIL(@var{exp})
@kindex LOG2CEIL(@var{exp})
Return the binary logarithm of @var{exp} rounded towards infinity.
@code{LOG2CEIL(0)} returns 0.
@kindex MAX
@item MAX(@var{exp1}, @var{exp2})
Returns the maximum of @var{exp1} and @var{exp2}.
@kindex MIN
@item MIN(@var{exp1}, @var{exp2})
Returns the minimum of @var{exp1} and @var{exp2}.
@item NEXT(@var{exp})
@kindex NEXT(@var{exp})
@cindex unallocated address, next
Return the next unallocated address that is a multiple of @var{exp}.
This function is closely related to @code{ALIGN(@var{exp})}; unless you
use the @code{MEMORY} command to define discontinuous memory for the
output file, the two functions are equivalent.
@item ORIGIN(@var{memory})
@kindex ORIGIN(@var{memory})
Return the origin of the memory region named @var{memory}.
@item SEGMENT_START(@var{segment}, @var{default})
@kindex SEGMENT_START(@var{segment}, @var{default})
Return the base address of the named @var{segment}. If an explicit
value has already been given for this segment (with a command-line
@samp{-T} option) then that value will be returned otherwise the value
will be @var{default}. At present, the @samp{-T} command-line option
can only be used to set the base address for the ``text'', ``data'', and
``bss'' sections, but you can use @code{SEGMENT_START} with any segment
name.
@item SIZEOF(@var{section})
@kindex SIZEOF(@var{section})
@cindex section size
Return the size in bytes of the named @var{section}, if that section has
been allocated. If the section has not been allocated when this is
evaluated, the linker will report an error. In the following example,
@code{symbol_1} and @code{symbol_2} are assigned identical values:
@smallexample
@group
SECTIONS@{ @dots{}
.output @{
.start = . ;
@dots{}
.end = . ;
@}
symbol_1 = .end - .start ;
symbol_2 = SIZEOF(.output);
@dots{} @}
@end group
@end smallexample
@item SIZEOF_HEADERS
@kindex SIZEOF_HEADERS
@cindex header size
Return the size in bytes of the output file's headers. This is
information which appears at the start of the output file. You can use
this number when setting the start address of the first section, if you
choose, to facilitate paging.
@cindex not enough room for program headers
@cindex program headers, not enough room
When producing an ELF output file, if the linker script uses the
@code{SIZEOF_HEADERS} builtin function, the linker must compute the
number of program headers before it has determined all the section
addresses and sizes. If the linker later discovers that it needs
additional program headers, it will report an error @samp{not enough
room for program headers}. To avoid this error, you must avoid using
the @code{SIZEOF_HEADERS} function, or you must rework your linker
script to avoid forcing the linker to use additional program headers, or
you must define the program headers yourself using the @code{PHDRS}
command (@pxref{PHDRS}).
@end table
@node Implicit Linker Scripts
@section Implicit Linker Scripts
@cindex implicit linker scripts
If you specify a linker input file which the linker can not recognize as
an object file or an archive file, it will try to read the file as a
linker script. If the file can not be parsed as a linker script, the
linker will report an error.
An implicit linker script will not replace the default linker script.
Typically an implicit linker script would contain only symbol
assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
commands.
Any input files read because of an implicit linker script will be read
at the position in the command line where the implicit linker script was
read. This can affect archive searching.
@node Plugins
@chapter Linker Plugins
@cindex plugins
@cindex linker plugins
The linker can use dynamically loaded plugins to modify its behavior.
For example, the link-time optimization feature that some compilers
support is implemented with a linker plugin.
Currently there is only one plugin shipped by default, but more may
be added here later.
Plugins are enabled via the use of the @option{-plugin @var{name}}
command line option. @xref{Options}
@menu
* libdep Plugin:: Static Library Dependencies Plugin
@end menu
@node libdep Plugin
@section Static Library Dependencies Plugin
@cindex static library dependencies
Originally, static libraries were contained in an archive file consisting
just of a collection of relocatable object files. Later they evolved to
optionally include a symbol table, to assist in finding the needed objects
within a library. There their evolution ended, and dynamic libraries
rose to ascendance.
One useful feature of dynamic libraries was that, more than just collecting
multiple objects into a single file, they also included a list of their
dependencies, such that one could specify just the name of a single dynamic
library at link time, and all of its dependencies would be implicitly
referenced as well. But static libraries lacked this feature, so if a
link invocation was switched from using dynamic libraries to static
libraries, the link command would usually fail unless it was rewritten to
explicitly list the dependencies of the static library.
The GNU @command{ar} utility now supports a @option{--record-libdeps} option
to embed dependency lists into static libraries as well, and the @file{libdep}
plugin may be used to read this dependency information at link time. The
dependency information is stored as a single string, carrying @option{-l}
and @option{-L} arguments as they would normally appear in a linker
command line. As such, the information can be written with any text
utility and stored into any archive, even if GNU @command{ar} is not
being used to create the archive. The information is stored in an
archive member named @samp{__.LIBDEP}.
For example, given a library @file{libssl.a} that depends on another
library @file{libcrypto.a} which may be found in @file{/usr/local/lib},
the @samp{__.LIBDEP} member of @file{libssl.a} would contain
@smallexample
-L/usr/local/lib -lcrypto
@end smallexample
@ifset GENERIC
@node Machine Dependent
@chapter Machine Dependent Features
@cindex machine dependencies
@command{ld} has additional features on some platforms; the following
sections describe them. Machines where @command{ld} has no additional
functionality are not listed.
@menu
@ifset H8300
* H8/300:: @command{ld} and the H8/300
@end ifset
@ifset M68HC11
* M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
@end ifset
@ifset ARM
* ARM:: @command{ld} and the ARM family
@end ifset
@ifset HPPA
* HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
@end ifset
@ifset M68K
* M68K:: @command{ld} and the Motorola 68K family
@end ifset
@ifset MIPS
* MIPS:: @command{ld} and the MIPS family
@end ifset
@ifset MMIX
* MMIX:: @command{ld} and MMIX
@end ifset
@ifset MSP430
* MSP430:: @command{ld} and MSP430
@end ifset
@ifset NDS32
* NDS32:: @command{ld} and NDS32
@end ifset
@ifset NIOSII
* Nios II:: @command{ld} and the Altera Nios II
@end ifset
@ifset POWERPC
* PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
@end ifset
@ifset POWERPC64
* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
@end ifset
@ifset S/390
* S/390 ELF:: @command{ld} and S/390 ELF Support
@end ifset
@ifset SPU
* SPU ELF:: @command{ld} and SPU ELF Support
@end ifset
@ifset TICOFF
* TI COFF:: @command{ld} and TI COFF
@end ifset
@ifset WIN32
* WIN32:: @command{ld} and WIN32 (cygwin/mingw)
@end ifset
@ifset XTENSA
* Xtensa:: @command{ld} and Xtensa Processors
@end ifset
@end menu
@end ifset
@ifset H8300
@ifclear GENERIC
@raisesections
@end ifclear
@node H8/300
@section @command{ld} and the H8/300
@cindex H8/300 support
For the H8/300, @command{ld} can perform these global optimizations when
you specify the @samp{--relax} command-line option.
@table @emph
@cindex relaxing on H8/300
@item relaxing address modes
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
targets are within eight bits, and turns them into eight-bit
program-counter relative @code{bsr} and @code{bra} instructions,
respectively.
@cindex synthesizing on H8/300
@item synthesizing instructions
@c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S
@command{ld} finds all @code{mov.b} instructions which use the
sixteen-bit absolute address form, but refer to the top
page of memory, and changes them to use the eight-bit address form.
(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
top page of memory).
@command{ld} finds all @code{mov} instructions which use the register
indirect with 32-bit displacement addressing mode, but use a small
displacement inside 16-bit displacement range, and changes them to use
the 16-bit displacement form. (That is: the linker turns @samp{mov.b
@code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
whenever the displacement @var{d} is in the 16 bit signed integer
range. Only implemented in ELF-format ld).
@item bit manipulation instructions
@command{ld} finds all bit manipulation instructions like @code{band, bclr,
biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
which use 32 bit and 16 bit absolute address form, but refer to the top
page of memory, and changes them to use the 8 bit address form.
(That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
the top page of memory).
@item system control instructions
@command{ld} finds all @code{ldc.w, stc.w} instructions which use the
32 bit absolute address form, but refer to the top page of memory, and
changes them to use 16 bit address form.
(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
the top page of memory).
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifclear GENERIC
@ifset Renesas
@c This stuff is pointless to say unless you're especially concerned
@c with Renesas chips; don't enable it for generic case, please.
@node Renesas
@chapter @command{ld} and Other Renesas Chips
@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
H8/500, and SH chips. No special features, commands, or command-line
options are required for these chips.
@end ifset
@end ifclear
@ifset ARM
@ifclear GENERIC
@raisesections
@end ifclear
@ifset M68HC11
@ifclear GENERIC
@raisesections
@end ifclear
@node M68HC11/68HC12
@section @command{ld} and the Motorola 68HC11 and 68HC12 families
@cindex M68HC11 and 68HC12 support
@subsection Linker Relaxation
For the Motorola 68HC11, @command{ld} can perform these global
optimizations when you specify the @samp{--relax} command-line option.
@table @emph
@cindex relaxing on M68HC11
@item relaxing address modes
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
targets are within eight bits, and turns them into eight-bit
program-counter relative @code{bsr} and @code{bra} instructions,
respectively.
@command{ld} also looks at all 16-bit extended addressing modes and
transforms them in a direct addressing mode when the address is in
page 0 (between 0 and 0x0ff).
@item relaxing gcc instruction group
When @command{gcc} is called with @option{-mrelax}, it can emit group
of instructions that the linker can optimize to use a 68HC11 direct
addressing mode. These instructions consists of @code{bclr} or
@code{bset} instructions.
@end table
@subsection Trampoline Generation
@cindex trampoline generation on M68HC11
@cindex trampoline generation on M68HC12
For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
call a far function using a normal @code{jsr} instruction. The linker
will also change the relocation to some far function to use the
trampoline address instead of the function address. This is typically the
case when a pointer to a function is taken. The pointer will in fact
point to the function trampoline.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@node ARM
@section @command{ld} and the ARM family
@cindex ARM interworking support
@kindex --support-old-code
For the ARM, @command{ld} will generate code stubs to allow functions calls
between ARM and Thumb code. These stubs only work with code that has
been compiled and assembled with the @samp{-mthumb-interwork} command
line option. If it is necessary to link with old ARM object files or
libraries, which have not been compiled with the -mthumb-interwork
option then the @samp{--support-old-code} command-line switch should be
given to the linker. This will make it generate larger stub functions
which will work with non-interworking aware ARM code. Note, however,
the linker does not support generating stubs for function calls to
non-interworking aware Thumb code.
@cindex thumb entry point
@cindex entry point, thumb
@kindex --thumb-entry=@var{entry}
The @samp{--thumb-entry} switch is a duplicate of the generic
@samp{--entry} switch, in that it sets the program's starting address.
But it also sets the bottom bit of the address, so that it can be
branched to using a BX instruction, and the program will start
executing in Thumb mode straight away.
@cindex PE import table prefixing
@kindex --use-nul-prefixed-import-tables
The @samp{--use-nul-prefixed-import-tables} switch is specifying, that
the import tables idata4 and idata5 have to be generated with a zero
element prefix for import libraries. This is the old style to generate
import tables. By default this option is turned off.
@cindex BE8
@kindex --be8
The @samp{--be8} switch instructs @command{ld} to generate BE8 format
executables. This option is only valid when linking big-endian
objects - ie ones which have been assembled with the @option{-EB}
option. The resulting image will contain big-endian data and
little-endian code.
@cindex TARGET1
@kindex --target1-rel
@kindex --target1-abs
The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
@samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
and @samp{--target1-abs} switches override the default.
@cindex TARGET2
@kindex --target2=@var{type}
The @samp{--target2=type} switch overrides the default definition of the
@samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
meanings, and target defaults are as follows:
@table @samp
@item rel
@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
@item abs
@samp{R_ARM_ABS32}
@item got-rel
@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
@end table
@cindex FIX_V4BX
@kindex --fix-v4bx
The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
specification) enables objects compiled for the ARMv4 architecture to be
interworking-safe when linked with other objects compiled for ARMv4t, but
also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
In the latter case, the switch @option{--fix-v4bx} must be passed to the
linker, which causes v4t @code{BX rM} instructions to be rewritten as
@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
relocations are ignored.
@cindex FIX_V4BX_INTERWORKING
@kindex --fix-v4bx-interworking
Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
relocations with a branch to the following veneer:
@smallexample
TST rM, #1
MOVEQ PC, rM
BX Rn
@end smallexample
This allows generation of libraries/applications that work on ARMv4 cores
and are still interworking safe. Note that the above veneer clobbers the
condition flags, so may cause incorrect program behavior in rare cases.
@cindex USE_BLX
@kindex --use-blx
The @samp{--use-blx} switch enables the linker to use ARM/Thumb
BLX instructions (available on ARMv5t and above) in various
situations. Currently it is used to perform calls via the PLT from Thumb
code using BLX rather than using BX and a mode-switching stub before
each PLT entry. This should lead to such calls executing slightly faster.
@cindex VFP11_DENORM_FIX
@kindex --vfp11-denorm-fix
The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
bug in certain VFP11 coprocessor hardware, which sometimes allows
instructions with denorm operands (which must be handled by support code)
to have those operands overwritten by subsequent instructions before
the support code can read the intended values.
The bug may be avoided in scalar mode if you allow at least one
intervening instruction between a VFP11 instruction which uses a register
and another instruction which writes to the same register, or at least two
intervening instructions if vector mode is in use. The bug only affects
full-compliance floating-point mode: you do not need this workaround if
you are using "runfast" mode. Please contact ARM for further details.
If you know you are using buggy VFP11 hardware, you can
enable this workaround by specifying the linker option
@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
mode only, or @samp{--vfp-denorm-fix=vector} if you are using
vector mode (the latter also works for scalar code). The default is
@samp{--vfp-denorm-fix=none}.
If the workaround is enabled, instructions are scanned for
potentially-troublesome sequences, and a veneer is created for each
such sequence which may trigger the erratum. The veneer consists of the
first instruction of the sequence and a branch back to the subsequent
instruction. The original instruction is then replaced with a branch to
the veneer. The extra cycles required to call and return from the veneer
are sufficient to avoid the erratum in both the scalar and vector cases.
@cindex ARM1176 erratum workaround
@kindex --fix-arm1176
@kindex --no-fix-arm1176
The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum
in certain ARM1176 processors. The workaround is enabled by default if you
are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled
unconditionally by specifying @samp{--no-fix-arm1176}.
Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S
Programmer Advice Notice'' available on the ARM documentation website at:
http://infocenter.arm.com/.
@cindex STM32L4xx erratum workaround
@kindex --fix-stm32l4xx-629360
The @samp{--fix-stm32l4xx-629360} switch enables a link-time
workaround for a bug in the bus matrix / memory controller for some of
the STM32 Cortex-M4 based products (STM32L4xx). When accessing
off-chip memory via the affected bus for bus reads of 9 words or more,
the bus can generate corrupt data and/or abort. These are only
core-initiated accesses (not DMA), and might affect any access:
integer loads such as LDM, POP and floating-point loads such as VLDM,
VPOP. Stores are not affected.
The bug can be avoided by splitting memory accesses into the
necessary chunks to keep bus reads below 8 words.
The workaround is not enabled by default, this is equivalent to use
@samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy
STM32L4xx hardware, you can enable the workaround by specifying the
linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
@samp{--fix-stm32l4xx-629360=default}.
If the workaround is enabled, instructions are scanned for
potentially-troublesome sequences, and a veneer is created for each
such sequence which may trigger the erratum. The veneer consists in a
replacement sequence emulating the behaviour of the original one and a
branch back to the subsequent instruction. The original instruction is
then replaced with a branch to the veneer.
The workaround does not always preserve the memory access order for
the LDMDB instruction, when the instruction loads the PC.
The workaround is not able to handle problematic instructions when
they are in the middle of an IT block, since a branch is not allowed
there. In that case, the linker reports a warning and no replacement
occurs.
The workaround is not able to replace problematic instructions with a
PC-relative branch instruction if the @samp{.text} section is too
large. In that case, when the branch that replaces the original code
cannot be encoded, the linker reports a warning and no replacement
occurs.
@cindex NO_ENUM_SIZE_WARNING
@kindex --no-enum-size-warning
The @option{--no-enum-size-warning} switch prevents the linker from
warning when linking object files that specify incompatible EABI
enumeration size attributes. For example, with this switch enabled,
linking of an object file using 32-bit enumeration values with another
using enumeration values fitted into the smallest possible space will
not be diagnosed.
@cindex NO_WCHAR_SIZE_WARNING
@kindex --no-wchar-size-warning
The @option{--no-wchar-size-warning} switch prevents the linker from
warning when linking object files that specify incompatible EABI
@code{wchar_t} size attributes. For example, with this switch enabled,
linking of an object file using 32-bit @code{wchar_t} values with another
using 16-bit @code{wchar_t} values will not be diagnosed.
@cindex PIC_VENEER
@kindex --pic-veneer
The @samp{--pic-veneer} switch makes the linker use PIC sequences for
ARM/Thumb interworking veneers, even if the rest of the binary
is not PIC. This avoids problems on uClinux targets where
@samp{--emit-relocs} is used to generate relocatable binaries.
@cindex STUB_GROUP_SIZE
@kindex --stub-group-size=@var{N}
The linker will automatically generate and insert small sequences of
code into a linked ARM ELF executable whenever an attempt is made to
perform a function call to a symbol that is too far away. The
placement of these sequences of instructions - called stubs - is
controlled by the command-line option @option{--stub-group-size=N}.
The placement is important because a poor choice can create a need for
duplicate stubs, increasing the code size. The linker will try to
group stubs together in order to reduce interruptions to the flow of
code, but it needs guidance as to how big these groups should be and
where they should be placed.
The value of @samp{N}, the parameter to the
@option{--stub-group-size=} option controls where the stub groups are
placed. If it is negative then all stubs are placed after the first
branch that needs them. If it is positive then the stubs can be
placed either before or after the branches that need them. If the
value of @samp{N} is 1 (either +1 or -1) then the linker will choose
exactly where to place groups of stubs, using its built in heuristics.
A value of @samp{N} greater than 1 (or smaller than -1) tells the
linker that a single group of stubs can service at most @samp{N} bytes
from the input sections.
The default, if @option{--stub-group-size=} is not specified, is
@samp{N = +1}.
Farcalls stubs insertion is fully supported for the ARM-EABI target
only, because it relies on object files properties not present
otherwise.
@cindex Cortex-A8 erratum workaround
@kindex --fix-cortex-a8
@kindex --no-fix-cortex-a8
The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
The erratum only affects Thumb-2 code. Please contact ARM for further details.
@cindex Cortex-A53 erratum 835769 workaround
@kindex --fix-cortex-a53-835769
@kindex --no-fix-cortex-a53-835769
The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
Please contact ARM for further details.
@kindex --merge-exidx-entries
@kindex --no-merge-exidx-entries
@cindex Merging exidx entries
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
@kindex --long-plt
@cindex 32-bit PLT entries
The @samp{--long-plt} option enables the use of 16 byte PLT entries
which support up to 4Gb of code. The default is to use 12 byte PLT
entries which only support 512Mb of code.
@kindex --no-apply-dynamic-relocs
@cindex AArch64 rela addend
The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
link-time values for dynamic relocations.
@cindex Placement of SG veneers
All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
Its start address must be set, either with the command-line option
@samp{--section-start} or in a linker script, to indicate where to place these
veneers in memory.
@kindex --cmse-implib
@cindex Secure gateway import library
The @samp{--cmse-implib} option requests that the import libraries
specified by the @samp{--out-implib} and @samp{--in-implib} options are
secure gateway import libraries, suitable for linking a non-secure
executable against secure code as per ARMv8-M Security Extensions.
@kindex --in-implib=@var{file}
@cindex Input import library
The @samp{--in-implib=file} specifies an input import library whose symbols
must keep the same address in the executable being produced. A warning is
given if no @samp{--out-implib} is given but new symbols have been introduced
in the executable that should be listed in its import library. Otherwise, if
@samp{--out-implib} is specified, the symbols are added to the output import
library. A warning is also given if some symbols present in the input import
library have disappeared from the executable. This option is only effective
for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is
specified.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset HPPA
@ifclear GENERIC
@raisesections
@end ifclear
@node HPPA ELF32
@section @command{ld} and HPPA 32-bit ELF Support
@cindex HPPA multiple sub-space stubs
@kindex --multi-subspace
When generating a shared library, @command{ld} will by default generate
import stubs suitable for use with a single sub-space application.
The @samp{--multi-subspace} switch causes @command{ld} to generate export
stubs, and different (larger) import stubs suitable for use with
multiple sub-spaces.
@cindex HPPA stub grouping
@kindex --stub-group-size=@var{N}
Long branch stubs and import/export stubs are placed by @command{ld} in
stub sections located between groups of input sections.
@samp{--stub-group-size} specifies the maximum size of a group of input
sections handled by one stub section. Since branch offsets are signed,
a stub section may serve two groups of input sections, one group before
the stub section, and one group after it. However, when using
conditional branches that require stubs, it may be better (for branch
prediction) that stub sections only serve one group of input sections.
A negative value for @samp{N} chooses this scheme, ensuring that
branches to stubs always use a negative offset. Two special values of
@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
@command{ld} to automatically size input section groups for the branch types
detected, with the same behaviour regarding stub placement as other
positive or negative values of @samp{N} respectively.
Note that @samp{--stub-group-size} does not split input sections. A
single input section larger than the group size specified will of course
create a larger group (of one section). If input sections are too
large, it may not be possible for a branch to reach its stub.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset M68K
@ifclear GENERIC
@raisesections
@end ifclear
@node M68K
@section @command{ld} and the Motorola 68K family
@cindex Motorola 68K GOT generation
@kindex --got=@var{type}
The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
The choices are @samp{single}, @samp{negative}, @samp{multigot} and
@samp{target}. When @samp{target} is selected the linker chooses
the default GOT generation scheme for the current target.
@samp{single} tells the linker to generate a single GOT with
entries only at non-negative offsets.
@samp{negative} instructs the linker to generate a single GOT with
entries at both negative and positive offsets. Not all environments
support such GOTs.
@samp{multigot} allows the linker to generate several GOTs in the
output file. All GOT references from a single input object
file access the same GOT, but references from different input object
files might access different GOTs. Not all environments support such GOTs.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset MIPS
@ifclear GENERIC
@raisesections
@end ifclear
@node MIPS
@section @command{ld} and the MIPS family
@cindex MIPS microMIPS instruction choice selection
@kindex --insn32
@kindex --no-insn32
The @samp{--insn32} and @samp{--no-insn32} options control the choice of
microMIPS instructions used in code generated by the linker, such as that
in the PLT or lazy binding stubs, or in relaxation. If @samp{--insn32} is
used, then the linker only uses 32-bit instruction encodings. By default
or if @samp{--no-insn32} is used, all instruction encodings are used,
including 16-bit ones where possible.
@cindex MIPS branch relocation check control
@kindex --ignore-branch-isa
@kindex --no-ignore-branch-isa
The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
control branch relocation checks for invalid ISA mode transitions. If
@samp{--ignore-branch-isa} is used, then the linker accepts any branch
relocations and any ISA mode transition required is lost in relocation
calculation, except for some cases of @code{BAL} instructions which meet
relaxation conditions and are converted to equivalent @code{JALX}
instructions as the associated relocation is calculated. By default
or if @samp{--no-ignore-branch-isa} is used a check is made causing
the loss of an ISA mode transition to produce an error.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset MMIX
@ifclear GENERIC
@raisesections
@end ifclear
@node MMIX
@section @code{ld} and MMIX
For MMIX, there is a choice of generating @code{ELF} object files or
@code{mmo} object files when linking. The simulator @code{mmix}
understands the @code{mmo} format. The binutils @code{objcopy} utility
can translate between the two formats.
There is one special section, the @samp{.MMIX.reg_contents} section.
Contents in this section is assumed to correspond to that of global
registers, and symbols referring to it are translated to special symbols,
equal to registers. In a final link, the start address of the
@samp{.MMIX.reg_contents} section corresponds to the first allocated
global register multiplied by 8. Register @code{$255} is not included in
this section; it is always set to the program entry, which is at the
symbol @code{Main} for @code{mmo} files.
Global symbols with the prefix @code{__.MMIX.start.}, for example
@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
The default linker script uses these to set the default start address
of a section.
Initial and trailing multiples of zero-valued 32-bit words in a section,
are left out from an mmo file.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset MSP430
@ifclear GENERIC
@raisesections
@end ifclear
@node MSP430
@section @code{ld} and MSP430
For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
just pass @samp{-m help} option to the linker).
@cindex MSP430 extra sections
The linker will recognize some extra sections which are MSP430 specific:
@table @code
@item @samp{.vectors}
Defines a portion of ROM where interrupt vectors located.
@item @samp{.bootloader}
Defines the bootloader portion of the ROM (if applicable). Any code
in this section will be uploaded to the MPU.
@item @samp{.infomem}
Defines an information memory section (if applicable). Any code in
this section will be uploaded to the MPU.
@item @samp{.infomemnobits}
This is the same as the @samp{.infomem} section except that any code
in this section will not be uploaded to the MPU.
@item @samp{.noinit}
Denotes a portion of RAM located above @samp{.bss} section.
The last two sections are used by gcc.
@end table
@table @option
@cindex MSP430 Options
@kindex --code-region
@item --code-region=[either,lower,upper,none]
This will transform .text* sections to [either,lower,upper].text* sections. The
argument passed to GCC for -mcode-region is propagated to the linker
using this option.
@kindex --data-region
@item --data-region=[either,lower,upper,none]
This will transform .data*, .bss* and .rodata* sections to
[either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC
for -mdata-region is propagated to the linker using this option.
@kindex --disable-sec-transformation
@item --disable-sec-transformation
Prevent the transformation of sections as specified by the @code{--code-region}
and @code{--data-region} options.
This is useful if you are compiling and linking using a single call to the GCC
wrapper, and want to compile the source files using -m[code,data]-region but
not transform the sections for prebuilt libraries and objects.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset NDS32
@ifclear GENERIC
@raisesections
@end ifclear
@node NDS32
@section @code{ld} and NDS32
@kindex relaxing on NDS32
For NDS32, there are some options to select relaxation behavior. The linker
relaxes objects according to these options.
@table @code
@item @samp{--m[no-]fp-as-gp}
Disable/enable fp-as-gp relaxation.
@item @samp{--mexport-symbols=FILE}
Exporting symbols and their address into FILE as linker script.
@item @samp{--m[no-]ex9}
Disable/enable link-time EX9 relaxation.
@item @samp{--mexport-ex9=FILE}
Export the EX9 table after linking.
@item @samp{--mimport-ex9=FILE}
Import the Ex9 table for EX9 relaxation.
@item @samp{--mupdate-ex9}
Update the existing EX9 table.
@item @samp{--mex9-limit=NUM}
Maximum number of entries in the ex9 table.
@item @samp{--mex9-loop-aware}
Avoid generating the EX9 instruction inside the loop.
@item @samp{--m[no-]ifc}
Disable/enable the link-time IFC optimization.
@item @samp{--mifc-loop-aware}
Avoid generating the IFC instruction inside the loop.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset NIOSII
@ifclear GENERIC
@raisesections
@end ifclear
@node Nios II
@section @command{ld} and the Altera Nios II
@cindex Nios II call relaxation
@kindex --relax on Nios II
Call and immediate jump instructions on Nios II processors are limited to
transferring control to addresses in the same 256MB memory segment,
which may result in @command{ld} giving
@samp{relocation truncated to fit} errors with very large programs.
The command-line option @option{--relax} enables the generation of
trampolines that can access the entire 32-bit address space for calls
outside the normal @code{call} and @code{jmpi} address range. These
trampolines are inserted at section boundaries, so may not themselves
be reachable if an input section and its associated call trampolines are
larger than 256MB.
The @option{--relax} option is enabled by default unless @option{-r}
is also specified. You can disable trampoline generation by using the
@option{--no-relax} linker option. You can also disable this optimization
locally by using the @samp{set .noat} directive in assembly-language
source files, as the linker-inserted trampolines use the @code{at}
register as a temporary.
Note that the linker @option{--relax} option is independent of assembler
relaxation options, and that using the GNU assembler's @option{-relax-all}
option interferes with the linker's more selective call instruction relaxation.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset POWERPC
@ifclear GENERIC
@raisesections
@end ifclear
@node PowerPC ELF32
@section @command{ld} and PowerPC 32-bit ELF Support
@cindex PowerPC long branches
@kindex --relax on PowerPC
Branches on PowerPC processors are limited to a signed 26-bit
displacement, which may result in @command{ld} giving
@samp{relocation truncated to fit} errors with very large programs.
@samp{--relax} enables the generation of trampolines that can access
the entire 32-bit address space. These trampolines are inserted at
section boundaries, so may not themselves be reachable if an input
section exceeds 33M in size. You may combine @samp{-r} and
@samp{--relax} to add trampolines in a partial link. In that case
both branches to undefined symbols and inter-section branches are also
considered potentially out of range, and trampolines inserted.
@cindex PowerPC ELF32 options
@table @option
@cindex PowerPC PLT
@kindex --bss-plt
@item --bss-plt
Current PowerPC GCC accepts a @samp{-msecure-plt} option that
generates code capable of using a newer PLT and GOT layout that has
the security advantage of no executable section ever needing to be
writable and no writable section ever being executable. PowerPC
@command{ld} will generate this layout, including stubs to access the
PLT, if all input files (including startup and static libraries) were
compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old
BSS PLT (and GOT layout) which can give slightly better performance.
@kindex --secure-plt
@item --secure-plt
@command{ld} will use the new PLT and GOT layout if it is linking new
@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
when linking non-PIC code. This option requests the new PLT and GOT
layout. A warning will be given if some object file requires the old
style BSS PLT.
@cindex PowerPC GOT
@kindex --sdata-got
@item --sdata-got
The new secure PLT and GOT are placed differently relative to other
sections compared to older BSS PLT and GOT placement. The location of
@code{.plt} must change because the new secure PLT is an initialized
section while the old PLT is uninitialized. The reason for the
@code{.got} change is more subtle: The new placement allows
@code{.got} to be read-only in applications linked with
@samp{-z relro -z now}. However, this placement means that
@code{.sdata} cannot always be used in shared libraries, because the
PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC
GCC doesn't use @code{.sdata} in shared libraries, so this option is
really only useful for other compilers that may do so.
@cindex PowerPC stub symbols
@kindex --emit-stub-syms
@item --emit-stub-syms
This option causes @command{ld} to label linker stubs with a local
symbol that encodes the stub type and destination.
@cindex PowerPC TLS optimization
@kindex --no-tls-optimize
@item --no-tls-optimize
PowerPC @command{ld} normally performs some optimization of code
sequences used to access Thread-Local Storage. Use this option to
disable the optimization.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset POWERPC64
@ifclear GENERIC
@raisesections
@end ifclear
@node PowerPC64 ELF64
@section @command{ld} and PowerPC64 64-bit ELF Support
@cindex PowerPC64 ELF64 options
@table @option
@cindex PowerPC64 stub grouping
@kindex --stub-group-size
@item --stub-group-size
Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
by @command{ld} in stub sections located between groups of input sections.
@samp{--stub-group-size} specifies the maximum size of a group of input
sections handled by one stub section. Since branch offsets are signed,
a stub section may serve two groups of input sections, one group before
the stub section, and one group after it. However, when using
conditional branches that require stubs, it may be better (for branch
prediction) that stub sections only serve one group of input sections.
A negative value for @samp{N} chooses this scheme, ensuring that
branches to stubs always use a negative offset. Two special values of
@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
@command{ld} to automatically size input section groups for the branch types
detected, with the same behaviour regarding stub placement as other
positive or negative values of @samp{N} respectively.
Note that @samp{--stub-group-size} does not split input sections. A
single input section larger than the group size specified will of course
create a larger group (of one section). If input sections are too
large, it may not be possible for a branch to reach its stub.
@cindex PowerPC64 stub symbols
@kindex --emit-stub-syms
@item --emit-stub-syms
This option causes @command{ld} to label linker stubs with a local
symbol that encodes the stub type and destination.
@cindex PowerPC64 dot symbols
@kindex --dotsyms
@kindex --no-dotsyms
@item --dotsyms
@itemx --no-dotsyms
These two options control how @command{ld} interprets version patterns
in a version script. Older PowerPC64 compilers emitted both a
function descriptor symbol with the same name as the function, and a
code entry symbol with the name prefixed by a dot (@samp{.}). To
properly version a function @samp{foo}, the version script thus needs
to control both @samp{foo} and @samp{.foo}. The option
@samp{--dotsyms}, on by default, automatically adds the required
dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
feature.
@cindex PowerPC64 register save/restore functions
@kindex --save-restore-funcs
@kindex --no-save-restore-funcs
@item --save-restore-funcs
@itemx --no-save-restore-funcs
These two options control whether PowerPC64 @command{ld} automatically
provides out-of-line register save and restore functions used by
@samp{-Os} code. The default is to provide any such referenced
function for a normal final link, and to not do so for a relocatable
link.
@cindex PowerPC64 TLS optimization
@kindex --no-tls-optimize
@item --no-tls-optimize
PowerPC64 @command{ld} normally performs some optimization of code
sequences used to access Thread-Local Storage. Use this option to
disable the optimization.
@cindex PowerPC64 __tls_get_addr optimization
@kindex --tls-get-addr-optimize
@kindex --no-tls-get-addr-optimize
@kindex --tls-get-addr-regsave
@kindex --no-tls-get-addr-regsave
@item --tls-get-addr-optimize
@itemx --no-tls-get-addr-optimize
These options control how PowerPC64 @command{ld} uses a special
stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
an optimization that allows the second and subsequent calls to
@code{__tls_get_addr} for a given symbol to be resolved by the special
stub without calling in to glibc. By default the linker enables
generation of the stub when glibc advertises the availability of
__tls_get_addr_opt.
Using @option{--tls-get-addr-optimize} with an older glibc won't do
much besides slow down your applications, but may be useful if linking
an application against an older glibc with the expectation that it
will normally be used on systems having a newer glibc.
@option{--tls-get-addr-regsave} forces generation of a stub that saves
and restores volatile registers around the call into glibc. Normally,
this is done when the linker detects a call to __tls_get_addr_desc.
Such calls then go via the register saving stub to __tls_get_addr_opt.
@option{--no-tls-get-addr-regsave} disables generation of the
register saves.
@cindex PowerPC64 OPD optimization
@kindex --no-opd-optimize
@item --no-opd-optimize
PowerPC64 @command{ld} normally removes @code{.opd} section entries
corresponding to deleted link-once functions, or functions removed by
the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
Use this option to disable @code{.opd} optimization.
@cindex PowerPC64 OPD spacing
@kindex --non-overlapping-opd
@item --non-overlapping-opd
Some PowerPC64 compilers have an option to generate compressed
@code{.opd} entries spaced 16 bytes apart, overlapping the third word,
the static chain pointer (unused in C) with the first word of the next
entry. This option expands such entries to the full 24 bytes.
@cindex PowerPC64 TOC optimization
@kindex --no-toc-optimize
@item --no-toc-optimize
PowerPC64 @command{ld} normally removes unused @code{.toc} section
entries. Such entries are detected by examining relocations that
reference the TOC in code sections. A reloc in a deleted code section
marks a TOC word as unneeded, while a reloc in a kept code section
marks a TOC word as needed. Since the TOC may reference itself, TOC
relocs are also examined. TOC words marked as both needed and
unneeded will of course be kept. TOC words without any referencing
reloc are assumed to be part of a multi-word entry, and are kept or
discarded as per the nearest marked preceding word. This works
reliably for compiler generated code, but may be incorrect if assembly
code is used to insert TOC entries. Use this option to disable the
optimization.
@cindex PowerPC64 inline PLT call optimization
@kindex --no-inline-optimize
@item --no-inline-optimize
PowerPC64 @command{ld} normally replaces inline PLT call sequences
marked with @code{R_PPC64_PLTSEQ}, @code{R_PPC64_PLTCALL},
@code{R_PPC64_PLT16_HA} and @code{R_PPC64_PLT16_LO_DS} relocations by
a number of @code{nop}s and a direct call when the function is defined
locally and can't be overridden by some other definition. This option
disables that optimization.
@cindex PowerPC64 multi-TOC
@kindex --no-multi-toc
@item --no-multi-toc
If given any toc option besides @code{-mcmodel=medium} or
@code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model
where TOC
entries are accessed with a 16-bit offset from r2. This limits the
total TOC size to 64K. PowerPC64 @command{ld} extends this limit by
grouping code sections such that each group uses less than 64K for its
TOC entries, then inserts r2 adjusting stubs between inter-group
calls. @command{ld} does not split apart input sections, so cannot
help if a single input file has a @code{.toc} section that exceeds
64K, most likely from linking multiple files with @command{ld -r}.
Use this option to turn off this feature.
@cindex PowerPC64 TOC sorting
@kindex --no-toc-sort
@item --no-toc-sort
By default, @command{ld} sorts TOC sections so that those whose file
happens to have a section called @code{.init} or @code{.fini} are
placed first, followed by TOC sections referenced by code generated
with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
referenced only by code generated with PowerPC64 gcc's
@code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this
results in better TOC grouping for multi-TOC. Use this option to turn
off this feature.
@cindex PowerPC64 PLT stub alignment
@kindex --plt-align
@kindex --no-plt-align
@item --plt-align
@itemx --no-plt-align
Use these options to control whether individual PLT call stubs are
aligned to a 32-byte boundary, or to the specified power of two
boundary when using @code{--plt-align=}. A negative value may be
specified to pad PLT call stubs so that they do not cross the
specified power of two boundary (or the minimum number of boundaries
if a PLT stub is so large that it must cross a boundary). By default
PLT call stubs are aligned to 32-byte boundaries.
@cindex PowerPC64 PLT call stub static chain
@kindex --plt-static-chain
@kindex --no-plt-static-chain
@item --plt-static-chain
@itemx --no-plt-static-chain
Use these options to control whether PLT call stubs load the static
chain pointer (r11). @code{ld} defaults to not loading the static
chain since there is never any need to do so on a PLT call.
@cindex PowerPC64 PLT call stub thread safety
@kindex --plt-thread-safe
@kindex --no-plt-thread-safe
@item --plt-thread-safe
@itemx --no-plt-thread-safe
With power7's weakly ordered memory model, it is possible when using
lazy binding for ld.so to update a plt entry in one thread and have
another thread see the individual plt entry words update in the wrong
order, despite ld.so carefully writing in the correct order and using
memory write barriers. To avoid this we need some sort of read
barrier in the call stub, or use LD_BIND_NOW=1. By default, @code{ld}
looks for calls to commonly used functions that create threads, and if
seen, adds the necessary barriers. Use these options to change the
default behaviour.
@cindex PowerPC64 ELFv2 PLT localentry optimization
@kindex --plt-localentry
@kindex --no-plt-localentry
@item --plt-localentry
@itemx --no-localentry
ELFv2 functions with localentry:0 are those with a single entry point,
ie. global entry == local entry, and that have no requirement on r2
(the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
Such an external function can be called via the PLT without saving r2
or restoring it on return, avoiding a common load-hit-store for small
functions. The optimization is attractive, with up to 40% reduction
in execution time for a small function, but can result in symbol
interposition failures. Also, minor changes in a shared library,
including system libraries, can cause a function that was localentry:0
to become localentry:8. This will result in a dynamic loader
complaint and failure to run. The option is experimental, use with
care. @option{--no-plt-localentry} is the default.
@cindex PowerPC64 Power10 stubs
@kindex --power10-stubs
@kindex --no-power10-stubs
@item --power10-stubs
@itemx --no-power10-stubs
When PowerPC64 @command{ld} links input object files containing
relocations used on power10 prefixed instructions it normally creates
linkage stubs (PLT call and long branch) using power10 instructions
for @code{@@notoc} PLT calls where @code{r2} is not known. The
power10 notoc stubs are smaller and faster, so are preferred for
power10. @option{--power10-stubs} and @option{--no-power10-stubs}
allow you to override the linker's selection of stub instructions.
@option{--power10-stubs=auto} allows the user to select the default
auto mode.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset S/390
@ifclear GENERIC
@raisesections
@end ifclear
@node S/390 ELF
@section @command{ld} and S/390 ELF Support
@cindex S/390 ELF options
@table @option
@cindex S/390
@kindex --s390-pgste
@item --s390-pgste
This option marks the result file with a @code{PT_S390_PGSTE}
segment. The Linux kernel is supposed to allocate 4k page tables for
binaries marked that way.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset SPU
@ifclear GENERIC
@raisesections
@end ifclear
@node SPU ELF
@section @command{ld} and SPU ELF Support
@cindex SPU ELF options
@table @option
@cindex SPU plugins
@kindex --plugin
@item --plugin
This option marks an executable as a PIC plugin module.
@cindex SPU overlays
@kindex --no-overlays
@item --no-overlays
Normally, @command{ld} recognizes calls to functions within overlay
regions, and redirects such calls to an overlay manager via a stub.
@command{ld} also provides a built-in overlay manager. This option
turns off all this special overlay handling.
@cindex SPU overlay stub symbols
@kindex --emit-stub-syms
@item --emit-stub-syms
This option causes @command{ld} to label overlay stubs with a local
symbol that encodes the stub type and destination.
@cindex SPU extra overlay stubs
@kindex --extra-overlay-stubs
@item --extra-overlay-stubs
This option causes @command{ld} to add overlay call stubs on all
function calls out of overlay regions. Normally stubs are not added
on calls to non-overlay regions.
@cindex SPU local store size
@kindex --local-store=lo:hi
@item --local-store=lo:hi
@command{ld} usually checks that a final executable for SPU fits in
the address range 0 to 256k. This option may be used to change the
range. Disable the check entirely with @option{--local-store=0:0}.
@cindex SPU
@kindex --stack-analysis
@item --stack-analysis
SPU local store space is limited. Over-allocation of stack space
unnecessarily limits space available for code and data, while
under-allocation results in runtime failures. If given this option,
@command{ld} will provide an estimate of maximum stack usage.
@command{ld} does this by examining symbols in code sections to
determine the extents of functions, and looking at function prologues
for stack adjusting instructions. A call-graph is created by looking
for relocations on branch instructions. The graph is then searched
for the maximum stack usage path. Note that this analysis does not
find calls made via function pointers, and does not handle recursion
and other cycles in the call graph. Stack usage may be
under-estimated if your code makes such calls. Also, stack usage for
dynamic allocation, e.g. alloca, will not be detected. If a link map
is requested, detailed information about each function's stack usage
and calls will be given.
@cindex SPU
@kindex --emit-stack-syms
@item --emit-stack-syms
This option, if given along with @option{--stack-analysis} will result
in @command{ld} emitting stack sizing symbols for each function.
These take the form @code{__stack_<function_name>} for global
functions, and @code{__stack_<number>_<function_name>} for static
functions. @code{<number>} is the section id in hex. The value of
such symbols is the stack requirement for the corresponding function.
The symbol size will be zero, type @code{STT_NOTYPE}, binding
@code{STB_LOCAL}, and section @code{SHN_ABS}.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset TICOFF
@ifclear GENERIC
@raisesections
@end ifclear
@node TI COFF
@section @command{ld}'s Support for Various TI COFF Versions
@cindex TI COFF versions
@kindex --format=@var{version}
The @samp{--format} switch allows selection of one of the various
TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
also supported. The TI COFF versions also vary in header byte-order
format; @command{ld} will read any version or byte order, but the output
header format depends on the default specified by the specific target.
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset WIN32
@ifclear GENERIC
@raisesections
@end ifclear
@node WIN32
@section @command{ld} and WIN32 (cygwin/mingw)
This section describes some of the win32 specific @command{ld} issues.
See @ref{Options,,Command-line Options} for detailed description of the
command-line options mentioned here.
@table @emph
@cindex import libraries
@item import libraries
The standard Windows linker creates and uses so-called import
libraries, which contains information for linking to dll's. They are
regular static archives and are handled as any other static
archive. The cygwin and mingw ports of @command{ld} have specific
support for creating such libraries provided with the
@samp{--out-implib} command-line option.
@item exporting DLL symbols
@cindex exporting DLL symbols
The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
@table @emph
@item using auto-export functionality
@cindex using auto-export functionality
By default @command{ld} exports symbols with the auto-export functionality,
which is controlled by the following command-line options:
@itemize
@item --export-all-symbols [This is the default]
@item --exclude-symbols
@item --exclude-libs
@item --exclude-modules-for-implib
@item --version-script
@end itemize
When auto-export is in operation, @command{ld} will export all the non-local
(global and common) symbols it finds in a DLL, with the exception of a few
symbols known to belong to the system's runtime and libraries. As it will
often not be desirable to export all of a DLL's symbols, which may include
private functions that are not part of any public interface, the command-line
options listed above may be used to filter symbols out from the list for
exporting. The @samp{--output-def} option can be used in order to see the
final list of exported symbols with all exclusions taken into effect.
If @samp{--export-all-symbols} is not given explicitly on the
command line, then the default auto-export behavior will be @emph{disabled}
if either of the following are true:
@itemize
@item A DEF file is used.
@item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
@end itemize
@item using a DEF file
@cindex using a DEF file
Another way of exporting symbols is using a DEF file. A DEF file is
an ASCII file containing definitions of symbols which should be
exported when a dll is created. Usually it is named @samp{<dll
name>.def} and is added as any other object file to the linker's
command line. The file's name must end in @samp{.def} or @samp{.DEF}.
@example
gcc -o <output> <objectfiles> <dll name>.def
@end example
Using a DEF file turns off the normal auto-export behavior, unless the
@samp{--export-all-symbols} option is also used.
Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
@example
LIBRARY "xyz.dll" BASE=0x20000000
EXPORTS
foo
bar
_bar = bar
another_foo = abc.dll.afoo
var1 DATA
doo = foo == foo2
eoo DATA == var1
@end example
This example defines a DLL with a non-default base address and seven
symbols in the export table. The third exported symbol @code{_bar} is an
alias for the second. The fourth symbol, @code{another_foo} is resolved
by "forwarding" to another module and treating it as an alias for
@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
@code{var1} is declared to be a data object. The @samp{doo} symbol in
export library is an alias of @samp{foo}, which gets the string name
in export table @samp{foo2}. The @samp{eoo} symbol is an data export
symbol, which gets in export table the name @samp{var1}.
The optional @code{LIBRARY <name>} command indicates the @emph{internal}
name of the output DLL. If @samp{<name>} does not include a suffix,
the default library suffix, @samp{.DLL} is appended.
When the .DEF file is used to build an application, rather than a
library, the @code{NAME <name>} command should be used instead of
@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
executable suffix, @samp{.EXE} is appended.
With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
specification @code{BASE = <number>} may be used to specify a
non-default base address for the image.
If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified,
or they specify an empty string, the internal name is the same as the
filename specified on the command line.
The complete specification of an export symbol is:
@example
EXPORTS
( ( ( <name1> [ = <name2> ] )
| ( <name1> = <module-name> . <external-name>))
[ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
@end example
Declares @samp{<name1>} as an exported symbol from the DLL, or declares
@samp{<name1>} as an exported alias for @samp{<name2>}; or declares
@samp{<name1>} as a "forward" alias for the symbol
@samp{<external-name>} in the DLL @samp{<module-name>}.
Optionally, the symbol may be exported by the specified ordinal
@samp{<integer>} alias. The optional @samp{<name3>} is the to be used
string in import/export table for the symbol.
The optional keywords that follow the declaration indicate:
@code{NONAME}: Do not put the symbol name in the DLL's export table. It
will still be exported by its ordinal alias (either the value specified
by the .def specification or, otherwise, the value assigned by the
linker). The symbol name, however, does remain visible in the import
library (if any), unless @code{PRIVATE} is also specified.
@code{DATA}: The symbol is a variable or object, rather than a function.
The import lib will export only an indirect reference to @code{foo} as
the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
@code{*_imp__foo}).
@code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
well as @code{_imp__foo} into the import library. Both refer to the
read-only import address table's pointer to the variable, not to the
variable itself. This can be dangerous. If the user code fails to add
the @code{dllimport} attribute and also fails to explicitly add the
extra indirection that the use of the attribute enforces, the
application will behave unexpectedly.
@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
it into the static import library used to resolve imports at link time. The
symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
API at runtime or by using the GNU ld extension of linking directly to
the DLL without an import library.
See ld/deffilep.y in the binutils sources for the full specification of
other DEF file statements
@cindex creating a DEF file
While linking a shared dll, @command{ld} is able to create a DEF file
with the @samp{--output-def <file>} command-line option.
@item Using decorations
@cindex Using decorations
Another way of marking symbols for export is to modify the source code
itself, so that when building the DLL each symbol to be exported is
declared as:
@example
__declspec(dllexport) int a_variable
__declspec(dllexport) void a_function(int with_args)
@end example
All such symbols will be exported from the DLL. If, however,
any of the object files in the DLL contain symbols decorated in
this way, then the normal auto-export behavior is disabled, unless
the @samp{--export-all-symbols} option is also used.
Note that object files that wish to access these symbols must @emph{not}
decorate them with dllexport. Instead, they should use dllimport,
instead:
@example
__declspec(dllimport) int a_variable
__declspec(dllimport) void a_function(int with_args)
@end example
This complicates the structure of library header files, because
when included by the library itself the header must declare the
variables and functions as dllexport, but when included by client
code the header must declare them as dllimport. There are a number
of idioms that are typically used to do this; often client code can
omit the __declspec() declaration completely. See
@samp{--enable-auto-import} and @samp{automatic data imports} for more
information.
@end table
@cindex automatic data imports
@item automatic data imports
The standard Windows dll format supports data imports from dlls only
by adding special decorations (dllimport/dllexport), which let the
compiler produce specific assembler instructions to deal with this
issue. This increases the effort necessary to port existing Un*x
code to these platforms, especially for large
c++ libraries and applications. The auto-import feature, which was
initially provided by Paul Sokolovsky, allows one to omit the
decorations to achieve a behavior that conforms to that on POSIX/Un*x
platforms. This feature is enabled with the @samp{--enable-auto-import}
command-line option, although it is enabled by default on cygwin/mingw.
The @samp{--enable-auto-import} option itself now serves mainly to
suppress any warnings that are ordinarily emitted when linked objects
trigger the feature's use.
auto-import of variables does not always work flawlessly without
additional assistance. Sometimes, you will see this message
"variable '<var>' can't be auto-imported. Please read the
documentation for ld's @code{--enable-auto-import} for details."
The @samp{--enable-auto-import} documentation explains why this error
occurs, and several methods that can be used to overcome this difficulty.
One of these methods is the @emph{runtime pseudo-relocs} feature, described
below.
@cindex runtime pseudo-relocation
For complex variables imported from DLLs (such as structs or classes),
object files typically contain a base address for the variable and an
offset (@emph{addend}) within the variable--to specify a particular
field or public member, for instance. Unfortunately, the runtime loader used
in win32 environments is incapable of fixing these references at runtime
without the additional information supplied by dllimport/dllexport decorations.
The standard auto-import feature described above is unable to resolve these
references.
The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
be resolved without error, while leaving the task of adjusting the references
themselves (with their non-zero addends) to specialized code provided by the
runtime environment. Recent versions of the cygwin and mingw environments and
compilers provide this runtime support; older versions do not. However, the
support is only necessary on the developer's platform; the compiled result will
run without error on an older system.
@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
enabled as needed.
@cindex direct linking to a dll
@item direct linking to a dll
The cygwin/mingw ports of @command{ld} support the direct linking,
including data symbols, to a dll without the usage of any import
libraries. This is much faster and uses much less memory than does the
traditional import library method, especially when linking large
libraries or applications. When @command{ld} creates an import lib, each
function or variable exported from the dll is stored in its own bfd, even
though a single bfd could contain many exports. The overhead involved in
storing, loading, and processing so many bfd's is quite large, and explains the
tremendous time, memory, and storage needed to link against particularly
large or complex libraries when using import libs.
Linking directly to a dll uses no extra command-line switches other than
@samp{-L} and @samp{-l}, because @command{ld} already searches for a number
of names to match each library. All that is needed from the developer's
perspective is an understanding of this search, in order to force ld to
select the dll instead of an import library.
For instance, when ld is called with the argument @samp{-lxxx} it will attempt
to find, in the first directory of its search path,
@example
libxxx.dll.a
xxx.dll.a
libxxx.a
xxx.lib
libxxx.lib
cygxxx.dll (*)
libxxx.dll
xxx.dll
@end example
before moving on to the next directory in the search path.
(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
where @samp{<prefix>} is set by the @command{ld} option
@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
@samp{cygxxx.dll}.
Other win32-based unix environments, such as mingw or pw32, may use other
@samp{<prefix>}es, although at present only cygwin makes use of this feature. It
was originally intended to help avoid name conflicts among dll's built for the
various win32/un*x environments, so that (for example) two versions of a zlib dll
could coexist on the same machine.
The generic cygwin/mingw path layout uses a @samp{bin} directory for
applications and dll's and a @samp{lib} directory for the import
libraries (using cygwin nomenclature):
@example
bin/
cygxxx.dll
lib/
libxxx.dll.a (in case of dll's)
libxxx.a (in case of static archive)
@end example
Linking directly to a dll without using the import library can be
done two ways:
1. Use the dll directly by adding the @samp{bin} path to the link line
@example
gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
@end example
However, as the dll's often have version numbers appended to their names
(@samp{cygncurses-5.dll}) this will often fail, unless one specifies
@samp{-L../bin -lncurses-5} to include the version. Import libs are generally
not versioned, and do not have this difficulty.
2. Create a symbolic link from the dll to a file in the @samp{lib}
directory according to the above mentioned search pattern. This
should be used to avoid unwanted changes in the tools needed for
making the app/dll.
@example
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
@end example
Then you can link without any make environment changes.
@example
gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
@end example
This technique also avoids the version number problems, because the following is
perfectly legal
@example
bin/
cygxxx-5.dll
lib/
libxxx.dll.a -> ../bin/cygxxx-5.dll
@end example
Linking directly to a dll without using an import lib will work
even when auto-import features are exercised, and even when
@samp{--enable-runtime-pseudo-relocs} is used.
Given the improvements in speed and memory usage, one might justifiably
wonder why import libraries are used at all. There are three reasons:
1. Until recently, the link-directly-to-dll functionality did @emph{not}
work with auto-imported data.
2. Sometimes it is necessary to include pure static objects within the
import library (which otherwise contains only bfd's for indirection
symbols that point to the exports of a dll). Again, the import lib
for the cygwin kernel makes use of this ability, and it is not
possible to do this without an import lib.
3. Symbol aliases can only be resolved using an import lib. This is
critical when linking against OS-supplied dll's (eg, the win32 API)
in which symbols are usually exported as undecorated aliases of their
stdcall-decorated assembly names.
So, import libs are not going away. But the ability to replace
true import libs with a simple symbolic link to (or a copy of)
a dll, in many cases, is a useful addition to the suite of tools
binutils makes available to the win32 developer. Given the
massive improvements in memory requirements during linking, storage
requirements, and linking speed, we expect that many developers
will soon begin to use this feature whenever possible.
@item symbol aliasing
@table @emph
@item adding additional names
Sometimes, it is useful to export symbols with additional names.
A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
exported as @samp{_foo} by using special directives in the DEF file
when creating the dll. This will affect also the optional created
import library. Consider the following DEF file:
@example
LIBRARY "xyz.dll" BASE=0x61000000
EXPORTS
foo
_foo = foo
@end example
The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
Another method for creating a symbol alias is to create it in the
source code using the "weak" attribute:
@example
void foo () @{ /* Do something. */; @}
void _foo () __attribute__ ((weak, alias ("foo")));
@end example
See the gcc manual for more information about attributes and weak
symbols.
@item renaming symbols
Sometimes it is useful to rename exports. For instance, the cygwin
kernel does this regularly. A symbol @samp{_foo} can be exported as
@samp{foo} but not as @samp{_foo} by using special directives in the
DEF file. (This will also affect the import library, if it is
created). In the following example:
@example
LIBRARY "xyz.dll" BASE=0x61000000
EXPORTS
_foo = foo
@end example
The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
@samp{_foo}.
@end table
Note: using a DEF file disables the default auto-export behavior,
unless the @samp{--export-all-symbols} command-line option is used.
If, however, you are trying to rename symbols, then you should list
@emph{all} desired exports in the DEF file, including the symbols
that are not being renamed, and do @emph{not} use the
@samp{--export-all-symbols} option. If you list only the
renamed symbols in the DEF file, and use @samp{--export-all-symbols}
to handle the other symbols, then the both the new names @emph{and}
the original names for the renamed symbols will be exported.
In effect, you'd be aliasing those symbols, not renaming them,
which is probably not what you wanted.
@cindex weak externals
@item weak externals
The Windows object format, PE, specifies a form of weak symbols called
weak externals. When a weak symbol is linked and the symbol is not
defined, the weak symbol becomes an alias for some other symbol. There
are three variants of weak externals:
@itemize
@item Definition is searched for in objects and libraries, historically
called lazy externals.
@item Definition is searched for only in other objects, not in libraries.
This form is not presently implemented.
@item No search; the symbol is an alias. This form is not presently
implemented.
@end itemize
As a GNU extension, weak symbols that do not specify an alternate symbol
are supported. If the symbol is undefined when linking, the symbol
uses a default value.
@cindex aligned common symbols
@item aligned common symbols
As a GNU extension to the PE file format, it is possible to specify the
desired alignment for a common symbol. This information is conveyed from
the assembler or compiler to the linker by means of GNU-specific commands
carried in the object file's @samp{.drectve} section, which are recognized
by @command{ld} and respected when laying out the common symbols. Native
tools will be able to process object files employing this GNU extension,
but will fail to respect the alignment instructions, and may issue noisy
warnings about unknown linker directives.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifset XTENSA
@ifclear GENERIC
@raisesections
@end ifclear
@node Xtensa
@section @code{ld} and Xtensa Processors
@cindex Xtensa processors
The default @command{ld} behavior for Xtensa processors is to interpret
@code{SECTIONS} commands so that lists of explicitly named sections in a
specification with a wildcard file will be interleaved when necessary to
keep literal pools within the range of PC-relative load offsets. For
example, with the command:
@smallexample
SECTIONS
@{
.text : @{
*(.literal .text)
@}
@}
@end smallexample
@noindent
@command{ld} may interleave some of the @code{.literal}
and @code{.text} sections from different object files to ensure that the
literal pools are within the range of PC-relative load offsets. A valid
interleaving might place the @code{.literal} sections from an initial
group of files followed by the @code{.text} sections of that group of
files. Then, the @code{.literal} sections from the rest of the files
and the @code{.text} sections from the rest of the files would follow.
@cindex @option{--relax} on Xtensa
@cindex relaxing on Xtensa
Relaxation is enabled by default for the Xtensa version of @command{ld} and
provides two important link-time optimizations. The first optimization
is to combine identical literal values to reduce code size. A redundant
literal will be removed and all the @code{L32R} instructions that use it
will be changed to reference an identical literal, as long as the
location of the replacement literal is within the offset range of all
the @code{L32R} instructions. The second optimization is to remove
unnecessary overhead from assembler-generated ``longcall'' sequences of
@code{L32R}/@code{CALLX@var{n}} when the target functions are within
range of direct @code{CALL@var{n}} instructions.
For each of these cases where an indirect call sequence can be optimized
to a direct call, the linker will change the @code{CALLX@var{n}}
instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
instruction, and remove the literal referenced by the @code{L32R}
instruction if it is not used for anything else. Removing the
@code{L32R} instruction always reduces code size but can potentially
hurt performance by changing the alignment of subsequent branch targets.
By default, the linker will always preserve alignments, either by
switching some instructions between 24-bit encodings and the equivalent
density instructions or by inserting a no-op in place of the @code{L32R}
instruction that was removed. If code size is more important than
performance, the @option{--size-opt} option can be used to prevent the
linker from widening density instructions or inserting no-ops, except in
a few cases where no-ops are required for correctness.
The following Xtensa-specific command-line options can be used to
control the linker:
@cindex Xtensa options
@table @option
@item --size-opt
When optimizing indirect calls to direct calls, optimize for code size
more than performance. With this option, the linker will not insert
no-ops or widen density instructions to preserve branch target
alignment. There may still be some cases where no-ops are required to
preserve the correctness of the code.
@item --abi-windowed
@itemx --abi-call0
Choose ABI for the output object and for the generated PLT code.
PLT code inserted by the linker must match ABI of the output object
because windowed and call0 ABI use incompatible function call
conventions.
Default ABI is chosen by the ABI tag in the @code{.xtensa.info} section
of the first input object.
A warning is issued if ABI tags of input objects do not match each other
or the chosen output object ABI.
@end table
@ifclear GENERIC
@lowersections
@end ifclear
@end ifset
@ifclear SingleFormat
@node BFD
@chapter BFD
@cindex back end
@cindex object file management
@cindex object formats available
@kindex objdump -i
The linker accesses object and archive files using the BFD libraries.
These libraries allow the linker to use the same routines to operate on
object files whatever the object file format. A different object file
format can be supported simply by creating a new BFD back end and adding
it to the library. To conserve runtime memory, however, the linker and
associated tools are usually configured to support only a subset of the
object file formats available. You can use @code{objdump -i}
(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
list all the formats available for your configuration.
@cindex BFD requirements
@cindex requirements for BFD
As with most implementations, BFD is a compromise between
several conflicting requirements. The major factor influencing
BFD design was efficiency: any time used converting between
formats is time which would not have been spent had BFD not
been involved. This is partly offset by abstraction payback; since
BFD simplifies applications and back ends, more time and care
may be spent optimizing algorithms for a greater speed.
One minor artifact of the BFD solution which you should bear in
mind is the potential for information loss. There are two places where
useful information can be lost using the BFD mechanism: during
conversion and during output. @xref{BFD information loss}.
@menu
* BFD outline:: How it works: an outline of BFD
@end menu
@node BFD outline
@section How It Works: An Outline of BFD
@cindex opening object files
@include bfdsumm.texi
@end ifclear
@node Reporting Bugs
@chapter Reporting Bugs
@cindex bugs in @command{ld}
@cindex reporting bugs in @command{ld}
Your bug reports play an essential role in making @command{ld} reliable.
Reporting a bug may help you by bringing a solution to your problem, or
it may not. But in any case the principal function of a bug report is
to help the entire community by making the next version of @command{ld}
work better. Bug reports are your contribution to the maintenance of
@command{ld}.
In order for a bug report to serve its purpose, you must include the
information that enables us to fix the bug.
@menu
* Bug Criteria:: Have you found a bug?
* Bug Reporting:: How to report bugs
@end menu
@node Bug Criteria
@section Have You Found a Bug?
@cindex bug criteria
If you are not sure whether you have found a bug, here are some guidelines:
@itemize @bullet
@cindex fatal signal
@cindex linker crash
@cindex crash of linker
@item
If the linker gets a fatal signal, for any input whatever, that is a
@command{ld} bug. Reliable linkers never crash.
@cindex error on valid input
@item
If @command{ld} produces an error message for valid input, that is a bug.
@cindex invalid input
@item
If @command{ld} does not produce an error message for invalid input, that
may be a bug. In the general case, the linker can not verify that
object files are correct.
@item
If you are an experienced user of linkers, your suggestions for
improvement of @command{ld} are welcome in any case.
@end itemize
@node Bug Reporting
@section How to Report Bugs
@cindex bug reports
@cindex @command{ld} bugs, reporting
A number of companies and individuals offer support for @sc{gnu}
products. If you obtained @command{ld} from a support organization, we
recommend you contact that organization first.
You can find contact information for many support companies and
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
distribution.
@ifset BUGURL
Otherwise, send bug reports for @command{ld} to
@value{BUGURL}.
@end ifset
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
fact or leave it out, state it!
Often people omit facts because they think they know what causes the
problem and assume that some details do not matter. Thus, you might
assume that the name of a symbol you use in an example does not
matter. Well, probably it does not, but one cannot be sure. Perhaps
the bug is a stray memory reference which happens to fetch from the
location where that name is stored in memory; perhaps, if the name
were different, the contents of that location would fool the linker
into doing the right thing despite the bug. Play it safe and give a
specific, complete example. That is the easiest thing for you to do,
and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix
the bug if it is new to us. Therefore, always write your bug reports
on the assumption that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?'' This cannot help us fix a bug, so it is basically useless. We
respond by asking for enough details to enable us to investigate.
You might as well expedite matters by sending them to begin with.
To enable us to fix the bug, you should include all these things:
@itemize @bullet
@item
The version of @command{ld}. @command{ld} announces it if you start it with
the @samp{--version} argument.
Without this, we will not know whether there is any point in looking for
the bug in the current version of @command{ld}.
@item
Any patches you may have applied to the @command{ld} source, including any
patches made to the @code{BFD} library.
@item
The type of machine you are using, and the operating system name and
version number.
@item
What compiler (and its version) was used to compile @command{ld}---e.g.
``@code{gcc-2.7}''.
@item
The command arguments you gave the linker to link your example and
observe the bug. To guarantee you will not omit something important,
list them all. A copy of the Makefile (or the output from make) is
sufficient.
If we were to try to guess the arguments, we would probably guess wrong
and then we might not encounter the bug.
@item
A complete input file, or set of input files, that will reproduce the
bug. It is generally most helpful to send the actual object files
provided that they are reasonably small. Say no more than 10K. For
bigger files you can either make them available by FTP or HTTP or else
state that you are willing to send the object file(s) to whomever
requests them. (Note - your email will be going to a mailing list, so
we do not want to clog it up with large attachments). But small
attachments are best.
If the source files were assembled using @code{gas} or compiled using
@code{gcc}, then it may be OK to send the source files rather than the
object files. In this case, be sure to say exactly what version of
@code{gas} or @code{gcc} was used to produce the object files. Also say
how @code{gas} or @code{gcc} were configured.
@item
A description of what behavior you observe that you believe is
incorrect. For example, ``It gets a fatal signal.''
Of course, if the bug is that @command{ld} gets a fatal signal, then we
will certainly notice it. But if the bug is incorrect output, we might
not notice unless it is glaringly wrong. You might as well not give us
a chance to make a mistake.
Even if the problem you experience is a fatal signal, you should still
say so explicitly. Suppose something strange is going on, such as, your
copy of @command{ld} is out of sync, or you have encountered a bug in the
C library on your system. (This has happened!) Your copy might crash
and ours would not. If you told us to expect a crash, then when ours
fails to crash, we would know that the bug was not happening for us. If
you had not told us to expect a crash, then we would not be able to draw
any conclusion from our observations.
@item
If you wish to suggest changes to the @command{ld} source, send us context
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
@samp{-p} option. Always send diffs from the old file to the new file.
If you even discuss something in the @command{ld} source, refer to it by
context, not by line number.
The line numbers in our development sources will not match those in your
sources. Your line numbers would convey no useful information to us.
@end itemize
Here are some things that are not necessary:
@itemize @bullet
@item
A description of the envelope of the bug.
Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.
This is often time consuming and not very useful, because the way we
will find the bug is by running a single example under the debugger
with breakpoints, not by pure deduction from a series of examples.
We recommend that you save your time for something else.
Of course, if you can find a simpler example to report @emph{instead}
of the original one, that is a convenience for us. Errors in the
output will be easier to spot, running under the debugger will take
less time, and so on.
However, simplification is not vital; if you do not want to do this,
report the bug anyway and send us the entire test case you used.
@item
A patch for the bug.
A patch for the bug does help us if it is a good one. But do not omit
the necessary information, such as the test case, on the assumption that
a patch is all we need. We might see problems with your patch and decide
to fix the problem another way, or we might not understand it at all.
Sometimes with a program as complicated as @command{ld} it is very hard to
construct an example that will make the program follow a certain path
through the code. If you do not send us the example, we will not be
able to construct one, so we will not be able to verify that the bug is
fixed.
And if we cannot understand what bug you are trying to fix, or why your
patch should be an improvement, we will not install it. A test case will
help us to understand.
@item
A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even we cannot guess right about such
things without first using the debugger to find the facts.
@end itemize
@node MRI
@appendix MRI Compatible Script Files
@cindex MRI compatibility
To aid users making the transition to @sc{gnu} @command{ld} from the MRI
linker, @command{ld} can use MRI compatible linker scripts as an
alternative to the more general-purpose linker scripting language
described in @ref{Scripts}. MRI compatible linker scripts have a much
simpler command set than the scripting language otherwise used with
@command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
linker commands; these commands are described here.
In general, MRI scripts aren't of much use with the @code{a.out} object
file format, since it only has three sections and MRI scripts lack some
features to make use of them.
You can specify a file containing an MRI-compatible script using the
@samp{-c} command-line option.
Each command in an MRI-compatible script occupies its own line; each
command line starts with the keyword that identifies the command (though
blank lines are also allowed for punctuation). If a line of an
MRI-compatible script begins with an unrecognized keyword, @command{ld}
issues a warning message, but continues processing the script.
Lines beginning with @samp{*} are comments.
You can write these commands using all upper-case letters, or all
lower case; for example, @samp{chip} is the same as @samp{CHIP}.
The following list shows only the upper-case form of each command.
@table @code
@cindex @code{ABSOLUTE} (MRI)
@item ABSOLUTE @var{secname}
@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
Normally, @command{ld} includes in the output file all sections from all
the input files. However, in an MRI-compatible script, you can use the
@code{ABSOLUTE} command to restrict the sections that will be present in
your output program. If the @code{ABSOLUTE} command is used at all in a
script, then only the sections named explicitly in @code{ABSOLUTE}
commands will appear in the linker output. You can still use other
input sections (whatever you select on the command line, or using
@code{LOAD}) to resolve addresses in the output file.
@cindex @code{ALIAS} (MRI)
@item ALIAS @var{out-secname}, @var{in-secname}
Use this command to place the data from input section @var{in-secname}
in a section called @var{out-secname} in the linker output file.
@var{in-secname} may be an integer.
@cindex @code{ALIGN} (MRI)
@item ALIGN @var{secname} = @var{expression}
Align the section called @var{secname} to @var{expression}. The
@var{expression} should be a power of two.
@cindex @code{BASE} (MRI)
@item BASE @var{expression}
Use the value of @var{expression} as the lowest address (other than
absolute addresses) in the output file.
@cindex @code{CHIP} (MRI)
@item CHIP @var{expression}
@itemx CHIP @var{expression}, @var{expression}
This command does nothing; it is accepted only for compatibility.
@cindex @code{END} (MRI)
@item END
This command does nothing whatever; it's only accepted for compatibility.
@cindex @code{FORMAT} (MRI)
@item FORMAT @var{output-format}
Similar to the @code{OUTPUT_FORMAT} command in the more general linker
language, but restricted to S-records, if @var{output-format} is @samp{S}
@cindex @code{LIST} (MRI)
@item LIST @var{anything}@dots{}
Print (to the standard output file) a link map, as produced by the
@command{ld} command-line option @samp{-M}.
The keyword @code{LIST} may be followed by anything on the
same line, with no change in its effect.
@cindex @code{LOAD} (MRI)
@item LOAD @var{filename}
@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
Include one or more object file @var{filename} in the link; this has the
same effect as specifying @var{filename} directly on the @command{ld}
command line.
@cindex @code{NAME} (MRI)
@item NAME @var{output-name}
@var{output-name} is the name for the program produced by @command{ld}; the
MRI-compatible command @code{NAME} is equivalent to the command-line
option @samp{-o} or the general script language command @code{OUTPUT}.
@cindex @code{ORDER} (MRI)
@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
@itemx ORDER @var{secname} @var{secname} @var{secname}
Normally, @command{ld} orders the sections in its output file in the
order in which they first appear in the input files. In an MRI-compatible
script, you can override this ordering with the @code{ORDER} command. The
sections you list with @code{ORDER} will appear first in your output
file, in the order specified.
@cindex @code{PUBLIC} (MRI)
@item PUBLIC @var{name}=@var{expression}
@itemx PUBLIC @var{name},@var{expression}
@itemx PUBLIC @var{name} @var{expression}
Supply a value (@var{expression}) for external symbol
@var{name} used in the linker input files.
@cindex @code{SECT} (MRI)
@item SECT @var{secname}, @var{expression}
@itemx SECT @var{secname}=@var{expression}
@itemx SECT @var{secname} @var{expression}
You can use any of these three forms of the @code{SECT} command to
specify the start address (@var{expression}) for section @var{secname}.
If you have more than one @code{SECT} statement for the same
@var{secname}, only the @emph{first} sets the start address.
@end table
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@node LD Index
@unnumbered LD Index
@printindex cp
@tex
% I think something like @@colophon should be in texinfo. In the
% meantime:
\long\def\colophon{\hbox to0pt{}\vfill
\centerline{The body of this manual is set in}
\centerline{\fontname\tenrm,}
\centerline{with headings in {\bf\fontname\tenbf}}
\centerline{and examples in {\tt\fontname\tentt}.}
\centerline{{\it\fontname\tenit\/} and}
\centerline{{\sl\fontname\tensl\/}}
\centerline{are used for emphasis.}\vfill}
\page\colophon
% Blame: doc@@cygnus.com, 28mar91.
@end tex
@bye
|