11.7. Option Commands

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 that 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 CONSTRUCTORS command tells the linker where this information should be placed. The CONSTRUCTORS command is ignored for other object file formats.

The symbol __CTOR_LIST__ marks the start of the global constructors, and the symbol __DTOR_LIST marks the end. 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 xgc C++ calls constructors from a subroutine __main; a call to __main is automatically inserted into the startup code for main. xgc C++ runs destructors either by using atexit, or directly from the function exit.

For object file formats such as COFF or ELF that support multiple sections, XGC C++ will normally arrange to put the addresses of global constructors and destructors into the .ctors and .dtors sections. Placing the following sequence into your linker script will build the sort of table that the C++ runtime code expects to see.

      __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__ = .;

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.

These keywords were used in some older linkers to request a particular math subroutine library. The linker doesn't use the keywords, assuming instead that any necessary subroutines are in libraries specified using the general mechanisms for linking to archives; but to permit the use of scripts that were written for the older linkers, the keywords FLOAT and NOFLOAT are accepted and ignored.

This command has the same effect as the -d command-line option: to make the linker assign space to common symbols even if a relocatable output file is specified (-r).

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.

Use this command to include binary input files in the link, without including them in a particular section definition. Specify the full name for each file, including ".a" if required.

The linker searches for each file through the archive-library search path, just as for files you specify on the command line. See the description of -L in Section 10.1.

If you use "-l file", the linker will transform the name to libfile.a as with the command line argument -l.

This 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 10.1.

Use this command to name the link output file filename. The effect of OUTPUT(filename) is identical to the effect of "-o filename", which overrides it. You can use this command to supply a default output-file name other than a.out.

Specify a particular output machine architecture, with one of the names used by the BFD back-end routines (see Appendix A). This command is often unnecessary; the architecture is most often set implicitly by either the system BFD configuration or as a side effect of the OUTPUT_FORMAT command.

When the linker is configured to support multiple object code formats, you can use this command to specify a particular output format. bfdname is one of the names used by the BFD back-end routines (see Appendix A). The effect is identical to the effect of the --oformat command-line option. This selection affects only the output file; the related command PREFIX affects primarily input files.

Add path to the list of paths where the linker looks for archive libraries. SEARCH_DIR(path) has the same effect as "-L path" on the command line.

Ensure that filename is the first input file used in the link process.

When the linker is configured to support multiple object code formats, you can use this command to change the input-file object code format (like the command-line option -b or its synonym --format). The argument format is one of the strings used by BFD to name binary formats. If PREFIX is specified but OUTPUT_FORMAT is not, the last PREFIX argument is also used as the default format for the the linker output file. See Appendix A.

If you don't use the PREFIX command, the linker uses the value of the environment variable GNUPREFIX, if available, to select the output file format. If that variable is also absent, the linker uses the default format configured for your machine in the BFD libraries.

This command may be used to tell the linker to issue an error about any references among certain sections.

In certain types of programs, particularly on embedded systems, 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 section names. If the linker detects any cross references between the sections, it reports an error and returns a non-zero exit status. The NOCROSSREFS command uses output section names, defined in the SECTIONS command. It does not use the names of input sections.