In this section we describe the simple linker script commands.
The first instruction to execute in a program is called the entry point. You can use the ENTRY linker script command to set the entry point. The argument is a symbol name:
ENTRY(symbol) |
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:
the -e entry command-line option;
the ENTRY(symbol) command in a linker script;
the value of the symbol start, if defined;
the address of the first byte of the .text section, if present;
The address 0.
Several linker script commands deal with files.
Include the linker script filename at this point. The file will be searched for in the current directory, and in any directory specified with the -L option. You can nest calls to INCLUDE up to 10 levels deep.
The 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 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 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 -T option.
In case a sysroot prefix is configured, and the filename starts with the / character, and the script being processed was located inside the sysroot prefix, the filename will be looked for in the sysroot prefix. Otherwise, the linker will try to open the file in the current directory. If it is not found, the linker will search through the archive library search path. See the description of -L in Section 3.1 Command Line Options.
If you use INPUT (-lfile), ld will transform the name to libfile.a, as with the command line argument -l.
When you use the 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.
The GROUP command is like 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 -( in Section 3.1 Command Line Options.
The OUTPUT command names the output file. Using OUTPUT(filename) in the linker script is exactly like using -o filename on the command line (refer to Section 3.1 Command Line Options). If both are used, the command line option takes precedence.
You can use the OUTPUT command to define a default name for the output file other than the usual default of a.out.
The SEARCH_DIR command adds path to the list of paths where ld looks for archive libraries. Using SEARCH_DIR(path) is exactly like using -L path on the command line (refer to Section 3.1 Command Line Options). If both are used, then the linker will search both paths. Paths specified using the command line option are searched first.
The STARTUP command is just like the INPUT command, except that 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.
A couple of linker script commands deal with object file formats.
The OUTPUT_FORMAT command names the BFD format to use for the output file (refer to Chapter 6 BFD). Using OUTPUT_FORMAT(bfdname) is exactly like using -oformat bfdname on the command line (refer to Section 3.1 Command Line Options). If both are used, the command line option takes precedence.
You can use OUTPUT_FORMAT with three arguments to use different formats based on the -EB and -EL command line options. This permits the linker script to set the output format based on the desired endianness.
If neither -EB nor -EL are used, then the output format will be the first argument, default. If -EB is used, the output format will be the second argument, big. If -EL is used, the output format will be the third argument, little.
For example, the default linker script for the MIPS ELF target uses this command:
UTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) |
This says that the default format for the output file is elf32-bigmips, but if the user uses the -EL command line option, the output file will be created in the elf32-littlemips format.
The TARGET command names the BFD format to use when reading input files. It affects subsequent INPUT and GROUP commands. This command is like using -b bfdname on the command line (refer to Section 3.1 Command Line Options). If the TARGET command is used but OUTPUT_FORMAT is not, then the last TARGET command is also used to set the format for the output file. Refer to Chapter 6 BFD.
There are a few other linker scripts commands.
Ensure that exp is non-zero. If it is zero, then exit the linker with an error code, and print message.
Force 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 symbols for each EXTERN, and you may use EXTERN multiple times. This command has the same effect as the -u command-line option.
This command has the same effect as the -d command-line option: to make ld assign space to common symbols even if a relocatable output file is specified (-r).
This command has the same effect as the -no-define-common command-line option: to make ld omit the assignment of addresses to common symbols even for a non-relocatable output file.
This command may be used to tell 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 NOCROSSREFS command takes a list of output section names. If ld detects any cross references between the sections, it reports an error and returns a non-zero exit status. Note that the NOCROSSREFS command uses output section names, not input section names.
Specify a particular output machine architecture. The argument is one of the names used by the BFD library (refer to Chapter 6 BFD). You can see the architecture of an object file by using the objdump program with the -f option.