ld: Input Section Basics

1 
1 3.6.4.1 Input Section Basics
1 ............................
1 
1 An input section description consists of a file name optionally followed
1 by a list of section names in parentheses.
1 
1    The file name and the section name may be wildcard patterns, which we
1 describe further below (⇒Input Section Wildcards).
1 
1    The most common input section description is to include all input
1 sections with a particular name in the output section.  For example, to
1 include all input '.text' sections, you would write:
1      *(.text)
1 Here the '*' is a wildcard which matches any file name.  To exclude a
1 list of files from matching the file name wildcard, EXCLUDE_FILE may be
1 used to match all files except the ones specified in the EXCLUDE_FILE
1 list.  For example:
1      EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
1 will cause all .ctors sections from all files except 'crtend.o' and
1 'otherfile.o' to be included.  The EXCLUDE_FILE can also be placed
1 inside the section list, for example:
1      *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
1 The result of this is identically to the previous example.  Supporting
1 two syntaxes for EXCLUDE_FILE is useful if the section list contains
1 more than one section, as described below.
1 
1    There are two ways to include more than one section:
1      *(.text .rdata)
1      *(.text) *(.rdata)
1 The difference between these is the order in which the '.text' and
1 '.rdata' input sections will appear in the output section.  In the first
1 example, they will be intermingled, appearing in the same order as they
1 are found in the linker input.  In the second example, all '.text' input
1 sections will appear first, followed by all '.rdata' input sections.
1 
1    When using EXCLUDE_FILE with more than one section, if the exclusion
1 is within the section list then the exclusion only applies to the
1 immediately following section, for example:
1      *(EXCLUDE_FILE (*somefile.o) .text .rdata)
1 will cause all '.text' sections from all files except 'somefile.o' to be
1 included, while all '.rdata' sections from all files, including
1 'somefile.o', will be included.  To exclude the '.rdata' sections from
1 'somefile.o' the example could be modified to:
1      *(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
1 Alternatively, placing the EXCLUDE_FILE outside of the section list,
1 before the input file selection, will cause the exclusion to apply for
1 all sections.  Thus the previous example can be rewritten as:
1      EXCLUDE_FILE (*somefile.o) *(.text .rdata)
1 
1    You can specify a file name to include sections from a particular
1 file.  You would do this if one or more of your files contain special
1 data that needs to be at a particular location in memory.  For example:
1      data.o(.data)
1 
1    To refine the sections that are included based on the section flags
1 of an input section, INPUT_SECTION_FLAGS may be used.
1 
1    Here is a simple example for using Section header flags for ELF
1 sections:
1 
1      SECTIONS {
1        .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) }
1        .text2 :  { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) }
1      }
1 
1    In this example, the output section '.text' will be comprised of any
1 input section matching the name *(.text) whose section header flags
1 'SHF_MERGE' and 'SHF_STRINGS' are set.  The output section '.text2' will
1 be comprised of any input section matching the name *(.text) whose
1 section header flag 'SHF_WRITE' is clear.
1 
1    You can also specify files within archives by writing a pattern
1 matching the archive, a colon, then the pattern matching the file, with
1 no whitespace around the colon.
1 
1 'archive:file'
1      matches file within archive
1 'archive:'
1      matches the whole archive
1 ':file'
1      matches file but not one in an archive
1 
1    Either one or both of 'archive' and 'file' can contain shell
1 wildcards.  On DOS based file systems, the linker will assume that a
1 single letter followed by a colon is a drive specifier, so 'c:myfile.o'
1 is a simple file specification, not 'myfile.o' within an archive called
1 'c'.  'archive:file' filespecs may also be used within an 'EXCLUDE_FILE'
1 list, but may not appear in other linker script contexts.  For instance,
1 you cannot extract a file from an archive by using 'archive:file' in an
1 'INPUT' command.
1 
1    If you use a file name without a list of sections, then all sections
1 in the input file will be included in the output section.  This is not
1 commonly done, but it may by useful on occasion.  For example:
1      data.o
1 
1    When you use a file name which is not an 'archive:file' specifier and
1 does not contain any wild card characters, the linker will first see if
1 you also specified the file name on the linker command line or in an
1 'INPUT' command.  If you did not, the linker will attempt to open the
1 file as an input file, as though it appeared on the command line.  Note
1 that this differs from an 'INPUT' command, because the linker will not
1 search for the file in the archive search path.
1