Binutils

https://sourceware.org/binutils/docs/
Admin
Binutils is a collection of programming tools for creating and managing binary programs, including...
Tokens:156,790
Snippets:1,420
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### OVERLAY example with .text0 and .text1

Source: https://sourceware.org/binutils/docs/ld/Overlay-Description.html

Example of an OVERLAY command inside a SECTIONS construct. Defines .text0 and .text1 to start at 0x1000, loaded at 0x4000 and immediately after. Automatically defines __load_start_text0, __load_stop_text0, __load_start_text1, __load_stop_text1.

```linker script
  OVERLAY 0x1000 : AT (0x4000)
   {
     .text0 { o1/*.o(.text) }
     .text1 { o2/*.o(.text) }
   }
```

--------------------------------

### Section ordering file example

Source: https://sourceware.org/binutils/docs/ld/Options.html

Shows a section ordering file that maps input sections to output sections, placing them at the start of the output sections. This file uses the same SECTIONS syntax as a linker script but only places input sections into output sections.

```linker script
  .text : { *(.text.first) ; *(.text.z*) }
  .data : { foo.o(.data.first) ; *(.data.small) }
```

--------------------------------

### MEMORY command example with rom and ram regions

Source: https://sourceware.org/binutils/docs/ld/MEMORY.html

Defines two memory regions: rom starting at 0 with 256K size, and ram starting at 0x40000000 with 4M size. The rom region uses attributes rx, and ram uses !rx. Sections not explicitly mapped are placed based on these attributes.

```linker script
MEMORY
  {
    rom (rx)  : ORIGIN = 0, LENGTH = 256K
    ram (!rx) : org = 0x40000000, l = 4M
  }
```

--------------------------------

### System V format output example

Source: https://sourceware.org/binutils/docs/binutils/size.html

Example of the System V format output from size, showing section sizes and addresses for each file.

```text
$ size --format=SysV ranlib size
ranlib  :
section         size         addr
.text         294880         8192
.data          81920       303104
.bss           11592       385024
Total         388392


size  :
section         size         addr
.text         294880         8192
.data          81920       303104
.bss           11888       385024
Total         388688
```

--------------------------------

### Equivalent basic commands for OVERLAY example

Source: https://sourceware.org/binutils/docs/ld/Overlay-Description.html

Shows how the OVERLAY example can be written using basic section definitions and PROVIDE commands. This is the manual equivalent of the OVERLAY command.

```linker script
  .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));
```

--------------------------------

### Complete linker script with input section placement

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Example.html

This linker script places all sections from all.o at the start of output section 'outputa' at address 0x10000, then places .input1 from foo.o in the same section. It then places .input2 from foo.o and .input1 from foo1.o into output section 'outputb', and finally uses wildcards to place all remaining .input1 and .input2 sections into output section 'outputc'. The script is shown as a single example split across three code blocks for readability.

```ld
SECTIONS {
  outputa 0x10000 :
    {
    all.o
    foo.o (.input1)
    }
```

```ld
  outputb :
    {
    foo.o (.input2)
    foo1.o (.input1)
    }
```

```ld
  outputc :
    {
    *(.input1)
    *(.input2)
    }
}
```

--------------------------------

### Berkeley format output example

Source: https://sourceware.org/binutils/docs/binutils/size.html

Example of the default Berkeley output format from size, showing text, data, bss, dec, and hex columns for the files ranlib and size.

```text
$ size --format=Berkeley ranlib size
   text    data     bss     dec     hex filename
 294880   81920   11592  388392   5ed28 ranlib
 294880   81920   11888  388688   5ee50 size
```

--------------------------------

### objcopy --remove-relocations example

Source: https://sourceware.org/binutils/docs/binutils/objcopy.html

Example command line showing how to remove relocations for all sections matching the pattern '.text.*' using --remove-relocations.

```shell
  --remove-relocations=.text.*
```

--------------------------------

### strip wildcard example: -w -K !foo -K fo*

Source: https://sourceware.org/binutils/docs/binutils/strip.html

Example of using the -w/--wildcard option with -K to keep symbols matching a pattern while excluding a specific symbol. The command keeps symbols starting with 'fo' but discards 'foo'.

```shell
  -w -K !foo -K fo*
```

--------------------------------

### Setting section addresses and sizes with the location counter

Source: https://sourceware.org/binutils/docs/ld/Location-Counter.html

Demonstrates using '.' to set the starting address and size of output sections. The '.text' section is assigned a start of 0x100 and a size of exactly 0x200 bytes; if input data exceeds this, an error occurs because '.' would move backwards. The '.data' section starts at 0x500 and gets an extra 0x600 bytes of space after its input data.

```ld
SECTIONS
{
    . = 0x100
    .text: {
      *(.text)
      . = 0x200
    }
    . = 0x500
    .data: {
      *(.data)
      . += 0x600
    }
}
```

--------------------------------

### Create a two-part executable with --only-keep-debug

Source: https://sourceware.org/binutils/docs/binutils/objcopy.html

The suggested procedure to create a stripped binary and a separate debug info file using objcopy. Steps: link the executable, run 'objcopy --only-keep-debug foo foo.dbg' to create the debug file, run 'objcopy --strip-debug foo' to strip the executable, and run 'objcopy --add-gnu-debuglink=foo.dbg foo' to add the debug link.

```shell
objcopy --only-keep-debug foo foo.dbg
```

```shell
objcopy --strip-debug foo
```

```shell
objcopy --add-gnu-debuglink=foo.dbg foo
```

--------------------------------

### Use --push-state and --pop-state with pkg-config --libs

Source: https://sourceware.org/binutils/docs/ld/Options.html

Recommended command-line sequence for pkg-config specifications to preserve and restore input file handling flags. The example shows wrapping -libone and -libtwo with --push-state and --pop-state to avoid linking all libraries all the time.

```shell
-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
```

--------------------------------

### Linker script with non-constant expression causing error

Source: https://sourceware.org/binutils/docs/ld/Evaluation.html

This example shows a linker script that attempts to use a non-constant expression for the start address of the .text section. The linker will report the error 'non constant expression for initial address' because the expression '9+this_isnt_constant' cannot be evaluated at the required time.

```linker script
SECTIONS
  {
    .text 9+this_isnt_constant :
      { *(.text) }
  }
```

--------------------------------

### Extended statistics output from ld --stats

Source: https://sourceware.org/binutils/docs/ld/Options.html

Example output when extended information is reported, showing linker version, start time, arguments, and a table of phase statistics. The output includes lines prefixed with 'Stats:' and a table with columns for phase, cpu time, rss, user time, system time, and memory.

```text
Stats: linker version: (GNU Binutils) 2.44.50.20250401
Stats: linker started: Wed Apr  2 09:36:41 2025
Stats: args: ld -z norelro -z nomemory-seal -z no-separate-code -o a.out [...]

Stats: phase               cpu time       rss      user time    system time     memory
Stats: name                (microsec)   (KiB)      (seconds)      (seconds)      (KiB)
Stats: ALL                   390082    217740              0              0   25219440
Stats: ctf processing            12         0              0              0          0
Stats: string merge            1324         0              0              0     406544
Stats: parsing                  349       288              0              0     119792
Stats: plugins                    1         0              0              0          0
Stats: processing files      259616    214524              0              0   31569120
Stats: write                 116493         0              0              0      48096
```

--------------------------------

### Fill pattern examples for hex and decimal values

Source: https://sourceware.org/binutils/docs/ld/Output-Section-Fill.html

Table showing how different fill expressions map to repeated byte patterns. For simple hex numbers (starting with 0x, no trailing k or M), the hex digits are repeated as-is, including leading zeros. For other expressions, the four least significant bytes are used, zero-extended if needed, in big-endian order.

```plaintext
Fill Value     Fill Pattern
0x90           90 90 90 90
0x0090         00 90 00 90
144            00 00 00 90
```

--------------------------------

### Create a DLL and a program that uses it

Source: https://sourceware.org/binutils/docs/binutils/dlltool.html

Shows the sequence of commands to compile a DLL source file, create an export file and import library with dlltool, link the DLL, and link a program against the DLL. The -e option creates the export file, -l creates the import library, and the resulting program uses the DLL.

```shell
  gcc -c dll.c
  dlltool -e exports.o -l dll.lib dll.o
  gcc dll.o exports.o -o dll.dll
  gcc program.o dll.lib -o program
```

--------------------------------

### Example DEF file for xyz.dll

Source: https://sourceware.org/binutils/docs/ld/WIN32.html

This DEF file defines a DLL with a non-default base address and seven symbols in the export table. It shows aliases, forwarding, data exports, and symbol renaming. The file name must end in .def or .DEF.

```def
LIBRARY "xyz.dll" BASE=0x20000000

EXPORTS
foo
bar
_bar = bar
another_foo = abc.dll.afoo
var1 DATA
doo = foo == foo2
eoo DATA == var1
```

--------------------------------

### GNU format output example

Source: https://sourceware.org/binutils/docs/binutils/size.html

Example of the GNU format output from size, which counts read-only data in the data column and shows a total column.

```text
$ size --format=GNU ranlib size
      text       data        bss      total filename
    279880      96920      11592     388392 ranlib
    279880      96920      11888     388688 size
```

--------------------------------

### Linker script example using =0x90909090

Source: https://sourceware.org/binutils/docs/ld/Output-Section-Fill.html

A simple linker script that sets the fill pattern for the .text output section to 0x90909090. Any unspecified gaps in the section will be filled with this pattern.

```linker-script
SECTIONS { .text : { *(.text) } =0x90909090 }
```
Tokens:
Raw