doc/ld.html/PHDRS.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the GNU linker LD
(GNU Toolchain for the A-profile Architecture 10.3-2021.07 (arm-10.29))
version 2.36.1.

Copyright (C) 1991-2021 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". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>LD: PHDRS</title>

<meta name="description" content="LD: PHDRS">
<meta name="keywords" content="LD: PHDRS">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Scripts.html#Scripts" rel="up" title="Scripts">
<link href="VERSION.html#VERSION" rel="next" title="VERSION">
<link href="MEMORY.html#MEMORY" rel="previous" title="MEMORY">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="PHDRS"></a>
<div class="header">
<p>
Next: <a href="VERSION.html#VERSION" accesskey="n" rel="next">VERSION</a>, Previous: <a href="MEMORY.html#MEMORY" accesskey="p" rel="previous">MEMORY</a>, Up: <a href="Scripts.html#Scripts" accesskey="u" rel="up">Scripts</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="PHDRS-Command"></a>
<h3 class="section">3.8 PHDRS Command</h3>
<a name="index-PHDRS"></a>
<a name="index-program-headers"></a>
<a name="index-ELF-program-headers"></a>
<a name="index-program-segments"></a>
<a name="index-segments_002c-ELF"></a>
<p>The ELF object file format uses <em>program headers</em>, also knows as
<em>segments</em>.  The program headers describe how the program should be
loaded into memory.  You can print them out by using the <code>objdump</code>
program with the &lsquo;<samp>-p</samp>&rsquo; option.
</p>
<p>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.
</p>
<p>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</code> command for this purpose.  When
the linker sees the <code>PHDRS</code> command in the linker script, it will
not create any program headers other than the ones specified.
</p>
<p>The linker only pays attention to the <code>PHDRS</code> command when
generating an ELF output file.  In other cases, the linker will simply
ignore <code>PHDRS</code>.
</p>
<p>This is the syntax of the <code>PHDRS</code> command.  The words <code>PHDRS</code>,
<code>FILEHDR</code>, <code>AT</code>, and <code>FLAGS</code> are keywords.
</p>
<div class="smallexample">
<pre class="smallexample">PHDRS
{
  <var>name</var> <var>type</var> [ FILEHDR ] [ PHDRS ] [ AT ( <var>address</var> ) ]
        [ FLAGS ( <var>flags</var> ) ] ;
}
</pre></div>

<p>The <var>name</var> is used only for reference in the <code>SECTIONS</code> 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.
</p>
<p>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 &lsquo;<samp>:<var>phdr</var></samp>&rsquo; output section
attribute to place a section in a particular segment.  See <a href="Output-Section-Phdr.html#Output-Section-Phdr">Output Section Phdr</a>.
</p>
<p>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 &lsquo;<samp>:<var>phdr</var></samp>&rsquo;, using it once for each segment which should
contain the section.
</p>
<p>If you place a section in one or more segments using &lsquo;<samp>:<var>phdr</var></samp>&rsquo;,
then the linker will place all subsequent allocatable sections which do
not specify &lsquo;<samp>:<var>phdr</var></samp>&rsquo; 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</code> to override the
default segment and tell the linker to not put the section in any
segment at all.
</p>
<a name="index-FILEHDR"></a>
<a name="index-PHDRS-1"></a>
<p>You may use the <code>FILEHDR</code> and <code>PHDRS</code> keywords after
the program header type to further describe the contents of the segment.
The <code>FILEHDR</code> keyword means that the segment should include the ELF
file header.  The <code>PHDRS</code> keyword means that the segment should
include the ELF program headers themselves.  If applied to a loadable
segment (<code>PT_LOAD</code>), all prior loadable segments must have one of
these keywords.
</p>
<p>The <var>type</var> may be one of the following.  The numbers indicate the
value of the keyword.
</p>
<dl compact="compact">
<dt><code>PT_NULL</code> (0)</dt>
<dd><p>Indicates an unused program header.
</p>
</dd>
<dt><code>PT_LOAD</code> (1)</dt>
<dd><p>Indicates that this program header describes a segment to be loaded from
the file.
</p>
</dd>
<dt><code>PT_DYNAMIC</code> (2)</dt>
<dd><p>Indicates a segment where dynamic linking information can be found.
</p>
</dd>
<dt><code>PT_INTERP</code> (3)</dt>
<dd><p>Indicates a segment where the name of the program interpreter may be
found.
</p>
</dd>
<dt><code>PT_NOTE</code> (4)</dt>
<dd><p>Indicates a segment holding note information.
</p>
</dd>
<dt><code>PT_SHLIB</code> (5)</dt>
<dd><p>A reserved program header type, defined but not specified by the ELF
ABI.
</p>
</dd>
<dt><code>PT_PHDR</code> (6)</dt>
<dd><p>Indicates a segment where the program headers may be found.
</p>
</dd>
<dt><code>PT_TLS</code> (7)</dt>
<dd><p>Indicates a segment containing thread local storage.
</p>
</dd>
<dt><var>expression</var></dt>
<dd><p>An expression giving the numeric type of the program header.  This may
be used for types not defined above.
</p></dd>
</dl>

<p>You can specify that a segment should be loaded at a particular address
in memory by using an <code>AT</code> expression.  This is identical to the
<code>AT</code> command used as an output section attribute (see <a href="Output-Section-LMA.html#Output-Section-LMA">Output Section LMA</a>).  The <code>AT</code> command for a program header overrides the
output section attribute.
</p>
<p>The linker will normally set the segment flags based on the sections
which comprise the segment.  You may use the <code>FLAGS</code> keyword to
explicitly specify the segment flags.  The value of <var>flags</var> must be
an integer.  It is used to set the <code>p_flags</code> field of the program
header.
</p>
<p>Here is an example of <code>PHDRS</code>.  This shows a typical set of program
headers used on a native ELF system.
</p>
<div class="example">
<pre class="example">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 */
  &hellip;
  . = . + 0x1000; /* move to a new page in memory */
  .data : { *(.data) } :data
  .dynamic : { *(.dynamic) } :data :dynamic
  &hellip;
}
</pre></div>

<hr>
<div class="header">
<p>
Next: <a href="VERSION.html#VERSION" accesskey="n" rel="next">VERSION</a>, Previous: <a href="MEMORY.html#MEMORY" accesskey="p" rel="previous">MEMORY</a>, Up: <a href="Scripts.html#Scripts" accesskey="u" rel="up">Scripts</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>