source: chapter08/glibc.xml@ 9658a0eb

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-system-glibc" role="wrap">
  <?dbhtml filename="glibc.html"?>

  <sect1info condition="script">
    <productname>glibc</productname>
    <productnumber>&glibc-version;</productnumber>
    <address>&glibc-url;</address>
  </sect1info>

  <title>Glibc-&glibc-version;</title>

  <indexterm zone="ch-system-glibc">
    <primary sortas="a-Glibc">Glibc</primary>
  </indexterm>

  <sect2 role="package">
    <title/>

    <para>The Glibc package contains the main C library. This library provides
    the basic routines for allocating memory, searching directories, opening and
    closing files, reading and writing files, string handling, pattern matching,
    arithmetic, and so on.</para>

    <segmentedlist>
      <segtitle>&buildtime;</segtitle>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&glibc-fin-sbu;</seg>
        <seg>&glibc-fin-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Glibc</title>

    <para>Some of the Glibc programs use the non-FHS compliant
    <filename class="directory">/var/db</filename> directory to store
    their runtime data. Apply the following patch to make such programs
    store their runtime data in the FHS-compliant locations:</para>

<screen><userinput remap="pre">patch -Np1 -i ../&glibc-fhs-patch;</userinput></screen>
<!--
    <para>Now fix two security vulnerabilities and a regression causing the
    posix_memalign() function very slow in some conditions:</para>

<screen><userinput remap="pre">patch -Np1 -i ../&glibc-upstream-fixes-patch;</userinput></screen>
-->
    <para>The Glibc documentation recommends building Glibc
    in a dedicated build directory:</para>

<screen><userinput remap="pre">mkdir -v build
cd       build</userinput></screen>

    <para>Ensure that the <command>ldconfig</command> and <command>sln</command>
    utilities will be installed into
    <filename class="directory">/usr/sbin</filename>:</para>

<screen><userinput remap="pre">echo "rootsbindir=/usr/sbin" &gt; configparms</userinput></screen>

    <para>Prepare Glibc for compilation:</para>

<screen arch="default"><userinput remap="configure">../configure --prefix=/usr                            \
             --disable-werror                         \
             --enable-kernel=&min-kernel;                     \
             --enable-stack-protector=strong          \
             --disable-nscd                           \
             libc_cv_slibdir=/usr/lib</userinput></screen>
<screen arch="ml_32,ml_x32,ml_all"><userinput remap="configure">../configure --prefix=/usr                            \
             --disable-werror                         \
             --enable-kernel=&min-kernel;                      \
             --enable-stack-protector=strong          \
             --with-headers=/usr/include              \
             --enable-multi-arch                      \
             libc_cv_slibdir=/usr/lib</userinput></screen>

    <variablelist>
      <title>The meaning of the configure options:</title>

      <varlistentry>
        <term><parameter>--disable-werror</parameter></term>
        <listitem>
          <para>This option disables the -Werror option passed to
          GCC.  This is necessary for running the test suite.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--enable-kernel=&min-kernel;</parameter></term>
        <listitem>
          <para>This option tells the build system that this Glibc may
          be used with kernels as old as &min-kernel;. This means generating
          workarounds in case a system call introduced in a later version
          cannot be used.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--enable-stack-protector=strong</parameter></term>
        <listitem>
          <para>This option increases system security by adding
          extra code to check for buffer overflows, such as stack
          smashing attacks.  Note that Glibc always explicitly overrides
          the default of GCC, so this option is still needed even though
          we've already specified <option>--enable-default-ssp</option> for
          GCC.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--disable-nscd</parameter></term>
        <listitem>
          <para>Do not build the name service cache daemon which is no 
          longer used.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>libc_cv_slibdir=/usr/lib</parameter></term>
        <listitem>
          <para>This variable sets the correct library for all
          systems.  We do not want lib64 to be used.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <important>
      <para>In this section, the test suite for Glibc is considered critical.
      Do not skip it under any circumstance.</para>
    </important>

    <para>Generally a few tests do not pass. The test failures listed below
    are usually safe to ignore.</para>

<!-- Use remap="make" here to work around a jhalfs issue. -->
<!--<screen><userinput remap="make">case $(uname -m) in
  i?86)   ln -sfnv $PWD/elf/ld-linux.so.2        /lib ;;
  x86_64) ln -sfnv $PWD/elf/ld-linux-x86-64.so.2 /lib ;;
esac</userinput></screen>

    <note><para>The symbolic link above is needed to run the tests at this
    stage of building in the chroot environment.  It will be overwritten
    in the install phase below.</para></note>
-->
<screen><userinput remap="test">make check</userinput></screen>

    <para>You may see some test failures. The Glibc test suite is
    somewhat dependent on the host system. A few failures out of
    over 5000 tests can generally be ignored. This is a list of the
    most common issues seen for recent versions of LFS:</para>

    <itemizedlist>

      <listitem>
        <para><emphasis>io/tst-lchmod</emphasis>
        is known to fail in the LFS chroot environment.</para>
      </listitem>

      <listitem>
        <para>Some tests, for example
        <emphasis>nss/tst-nss-files-hosts-multi</emphasis> and
        <emphasis>nptl/tst-thread-affinity*</emphasis>
        are known to fail due to a timeout (especially when the system is
        relatively slow and/or running the test suite with multiple
        parallel make jobs).  These tests can be identified with:</para>

        <!-- TODO: Using nodump for freeze.  Change it to role="test" after
             12.1 release so jhalfs can list these in the log.  -->
        <screen role="nodump"><userinput>grep "Timed out" -l $(find -name \*.out)</userinput></screen>

        <para>It's possible to re-run a single test with enlarged timeout
        with
        <command>TIMEOUTFACTOR=<replaceable>&lt;factor&gt;</replaceable>
        make test t=<replaceable>&lt;test name&gt;</replaceable></command>.
        For example, <command>TIMEOUTFACTOR=10 make test
        t=nss/tst-nss-files-hosts-multi</command> will re-run
        <emphasis>nss/tst-nss-files-hosts-multi</emphasis> with ten times
        the original timeout.</para>
      </listitem>

      <listitem>
        <para>Additionally, some tests may fail with a relatively old CPU
        model (for example
        <emphasis>elf/tst-cpu-features-cpuinfo</emphasis>) or host kernel
        version (for example
        <emphasis>stdlib/tst-arc4random-thread</emphasis>).</para>
      </listitem>
    </itemizedlist>

    <para>Though it is a harmless message, the install stage of Glibc will
    complain about the absence of <filename>/etc/ld.so.conf</filename>.
    Prevent this warning with:</para>

<screen><userinput remap="install">touch /etc/ld.so.conf</userinput></screen>

    <!-- https://sourceware.org/bugzilla/show_bug.cgi?id=21911 -->
    <para>Fix the Makefile to skip an outdated sanity check
    that fails with a modern Glibc configuration:</para>

<screen><userinput remap="install">sed '/test-installation/s@$(PERL)@echo not running@' -i ../Makefile</userinput></screen>

    <important>
      <para>
        If upgrading Glibc to a new minor version (for example, from
        Glibc-2.36 to Glibc-&glibc-version;) on a running LFS system, you
        need to take some extra precautions to avoid breaking the system:
      </para>

      <itemizedlist>
        <listitem>
          <!-- There are two reasons we don't support this:
               1. Upgrading on a system with separate /lib and /usr/lib is
                  tricky.
               2. With Glibc prior to 2.34 libc.so.6 etc. are symlinks to
                  libc-2.33.so etc., again causing the upgradation tricky.
                  The Glibc NEWS file explicit states they no longer use
                  symlinks for the ABI names to avoid upgradation
                  issues.  -->
          <para>
            Upgrading Glibc on a LFS system prior to 11.0 (exclusive) is
            not supported.  Rebuild LFS if you are running such an old LFS
            system but you need a newer Glibc.
          </para>
        </listitem>

        <!-- https://sourceware.org/pipermail/libc-alpha/2024-January/154095.html -->
        <listitem>
          <para>
            If upgrading on a LFS system prior to 12.0 (exclusive), install
            <application>Libxcrypt</application> following
            <xref role='.' linkend='ch-system-libxcrypt'/>  In addition to
            a normal <application>Libxcrypt</application> installation,
            <emphasis role='bold'>you MUST follow the note in Libxcrypt
            section to install
            <filename class='libraryfile'>libcrypt.so.1*</filename>
            (overwritting
            <filename class='libraryfile'>libcrypt.so.1</filename> from the
            prior Glibc installation)</emphasis>.
          </para>
        </listitem>

        <!-- Otherwise on lfs-systemd nscd will fail to start on boot,
             and on both lfs-sysv and lfs-systemd useradd etc. will try
             to start nscd, then nscd will fail to start as well and
             produce some spurious error message.  -->
        <listitem>
          <para>
            If upgrading on a LFS system prior to 12.1 (exclusive),
            remove the <command>nscd</command> program:
          </para>

          <screen role='nodump'><userinput>rm -f /usr/sbin/nscd</userinput></screen>

          <para>
            If this system (prior to LFS 12.1, exclusive) is based on
            Systemd, it's also needed to disable and stop the
            <command>nscd</command> service now:
          </para>

          <screen revision='systemd' role='nodump'><userinput>systemctl disable --now nscd</userinput></screen>
        </listitem>

        <listitem>
          <para>
            Upgrade the kernel and reboot if it's older than &min-kernel;
            (check the current version with <command>uname -r</command>)
            or if you want to upgrade it anyway, following
            <xref linkend='ch-bootable-kernel' role='.'/>
          </para>
        </listitem>

        <listitem>
          <para>
            Upgrade the kernel API headers if it's older than &min-kernel;
            (check the current version with
            <command>cat /usr/include/linux/version.h</command>)
            or if you want to upgrade it anyway, following
            <xref linkend='ch-tools-linux-headers'/> (but removing
            <envar>$LFS</envar> from the <command>cp</command> command).
          </para>
        </listitem>

        <!-- This is to ensure we don't start a process at the time point
             where some Glibc shared libraries are updated but the others
             are not.  Such mismatches can cause programs crash on startup,
             esp. a mismatch between ld-linux-x86-64.so.2 and
             libc.so.6.  Note that a crash in the installation process
             will leave the system in a state with the mismatch forever,
             unrecoverable without the help of another distro.  -->
        <listitem>
          <para>
            Perform a <envar>DESTDIR</envar> installation and upgrade
            the Glibc shared libraries on the system using one single
            <command>install</command> command:
          </para>

          <screen role='nodump'><userinput>make DESTDIR=$PWD/dest install
install -vm755 dest/usr/lib/*.so.* /usr/lib</userinput></screen>
        </listitem>
      </itemizedlist>

      <para>
        It's imperative to strictly follow these steps above unless you
        completely understand what you are doing.
        <emphasis role='bold'>Any unexpected deviation may render the
        system completely unusable.  YOU ARE WARNED.</emphasis>
      </para>

      <para>
        Then continue to run the <command>make install</command> command,
        the <command>sed</command> command against
        <filename>/usr/bin/ldd</filename>, and the commands to install
        the locales.  Once they are finished, reboot the system
        immediately.
      </para>
    </important>

    <para>Install the package:</para>

<screen><userinput remap="install">make install</userinput></screen>

    <para>Fix a hardcoded path to the executable loader in the
    <command>ldd</command> script:</para>

<screen><userinput remap="install">sed '/RTLDLIST=/s@/usr@@g' -i /usr/bin/ldd</userinput></screen>
<!--
    <para>Install the configuration file and runtime directory for
    <command>nscd</command>:</para>

<screen><userinput remap="install">cp -v ../nscd/nscd.conf /etc/nscd.conf
mkdir -pv /var/cache/nscd</userinput></screen>

    <para revision="systemd">Install the systemd support files for
    <command>nscd</command>:</para>

    <screen revision="systemd"><userinput remap="install">install -v -Dm644 ../nscd/nscd.tmpfiles /usr/lib/tmpfiles.d/nscd.conf
install -v -Dm644 ../nscd/nscd.service /usr/lib/systemd/system/nscd.service</userinput></screen>
-->
    <para>Next, install the locales that can make the system respond in a
    different language.  None of these locales are required, but if some of them
    are missing, the test suites of some packages will skip important
    test cases.</para>

    <para>Individual locales can be installed using the
    <command>localedef</command> program. E.g., the second
    <command>localedef</command> command below combines the
    <filename>/usr/share/i18n/locales/cs_CZ</filename>
    charset-independent locale definition with the
    <filename>/usr/share/i18n/charmaps/UTF-8.gz</filename>
    charmap definition and appends the result to the
    <filename>/usr/lib/locale/locale-archive</filename> file.
    The following instructions will install the minimum set of
    locales necessary for the optimal coverage of tests:</para>

<screen role="nodump"><userinput remap="locale-test">mkdir -pv /usr/lib/locale
localedef -i C -f UTF-8 C.UTF-8
localedef -i cs_CZ -f UTF-8 cs_CZ.UTF-8
localedef -i de_DE -f ISO-8859-1 de_DE
localedef -i de_DE@euro -f ISO-8859-15 de_DE@euro
localedef -i de_DE -f UTF-8 de_DE.UTF-8
localedef -i el_GR -f ISO-8859-7 el_GR
localedef -i en_GB -f ISO-8859-1 en_GB
localedef -i en_GB -f UTF-8 en_GB.UTF-8
localedef -i en_HK -f ISO-8859-1 en_HK
localedef -i en_PH -f ISO-8859-1 en_PH
localedef -i en_US -f ISO-8859-1 en_US
localedef -i en_US -f UTF-8 en_US.UTF-8
localedef -i es_ES -f ISO-8859-15 es_ES@euro
localedef -i es_MX -f ISO-8859-1 es_MX
localedef -i fa_IR -f UTF-8 fa_IR
localedef -i fr_FR -f ISO-8859-1 fr_FR
localedef -i fr_FR@euro -f ISO-8859-15 fr_FR@euro
localedef -i fr_FR -f UTF-8 fr_FR.UTF-8
localedef -i is_IS -f ISO-8859-1 is_IS
localedef -i is_IS -f UTF-8 is_IS.UTF-8
localedef -i it_IT -f ISO-8859-1 it_IT
localedef -i it_IT -f ISO-8859-15 it_IT@euro
localedef -i it_IT -f UTF-8 it_IT.UTF-8
localedef -i ja_JP -f EUC-JP ja_JP
localedef -i ja_JP -f SHIFT_JIS ja_JP.SJIS 2> /dev/null || true
localedef -i ja_JP -f UTF-8 ja_JP.UTF-8
localedef -i nl_NL@euro -f ISO-8859-15 nl_NL@euro
localedef -i ru_RU -f KOI8-R ru_RU.KOI8-R
localedef -i ru_RU -f UTF-8 ru_RU.UTF-8
localedef -i se_NO -f UTF-8 se_NO.UTF-8
localedef -i ta_IN -f UTF-8 ta_IN.UTF-8
localedef -i tr_TR -f UTF-8 tr_TR.UTF-8
localedef -i zh_CN -f GB18030 zh_CN.GB18030
localedef -i zh_HK -f BIG5-HKSCS zh_HK.BIG5-HKSCS
localedef -i zh_TW -f UTF-8 zh_TW.UTF-8</userinput></screen>

    <para>In addition, install the locale for your own country, language and
    character set.</para>

    <para>Alternatively, install all the locales listed in the
    <filename>glibc-&glibc-version;/localedata/SUPPORTED</filename> file
    (it includes every locale listed above and many more) at once with the
    following time-consuming command:</para>

<screen><userinput remap="locale-full">make localedata/install-locales</userinput></screen>

    <para>Then use the <command>localedef</command> command to create and
    install locales not listed in the
    <filename>glibc-&glibc-version;/localedata/SUPPORTED</filename> file
    when you need them. For instance, the following two locales are
    needed for some tests later in this chapter:</para>

<screen role="nodump"><userinput remap="locale-full">localedef -i C -f UTF-8 C.UTF-8
localedef -i ja_JP -f SHIFT_JIS ja_JP.SJIS 2> /dev/null || true</userinput></screen>

    <note><para>Glibc now uses libidn2 when resolving internationalized
    domain names.  This is a run time dependency.  If this capability
    is needed, the instructions for installing libidn2 are in the
    <ulink url="&blfs-book;general/libidn2.html">BLFS libidn2 page</ulink>.
    </para></note>

  </sect2>

  <sect2 id="conf-glibc" role="configuration">
    <title>Configuring Glibc</title>

    <indexterm zone="conf-glibc">
      <primary sortas="e-/etc/nsswitch.conf">/etc/nsswitch.conf</primary>
    </indexterm>

    <indexterm zone="conf-glibc">
      <primary sortas="e-/etc/localtime">/etc/localtime</primary>
    </indexterm>

  <sect3>
  <title>Adding nsswitch.conf</title>

    <para>The <filename>/etc/nsswitch.conf</filename> file needs to be created
    because the Glibc defaults do not work well in a networked environment.
    </para>

    <para>Create a new file <filename>/etc/nsswitch.conf</filename> by running the
    following:</para>

<screen revision='sysv'><userinput>cat &gt; /etc/nsswitch.conf &lt;&lt; "EOF"
<literal># Begin /etc/nsswitch.conf

passwd: files
group: files
shadow: files

hosts: files dns
networks: files

protocols: files
services: files
ethers: files
rpc: files

# End /etc/nsswitch.conf</literal>
EOF</userinput></screen>

<screen revision='systemd'><userinput>cat &gt; /etc/nsswitch.conf &lt;&lt; "EOF"
<literal># Begin /etc/nsswitch.conf

passwd: files systemd
group: files systemd
shadow: files systemd

hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns
networks: files

protocols: files
services: files
ethers: files
rpc: files

# End /etc/nsswitch.conf</literal>
EOF</userinput></screen>

    </sect3>

    <sect3>
    <title>Adding Time Zone Data</title>

    <para>Install and set up the time zone data with the following:</para>
<screen><userinput>tar -xf ../../tzdata&tzdata-version;.tar.gz

ZONEINFO=/usr/share/zoneinfo
mkdir -pv $ZONEINFO/{posix,right}

for tz in etcetera southamerica northamerica europe africa antarctica  \
          asia australasia backward; do
    zic -L /dev/null   -d $ZONEINFO       ${tz}
    zic -L /dev/null   -d $ZONEINFO/posix ${tz}
    zic -L leapseconds -d $ZONEINFO/right ${tz}
done

cp -v zone.tab zone1970.tab iso3166.tab $ZONEINFO
zic -d $ZONEINFO -p America/New_York
unset ZONEINFO</userinput></screen>

    <variablelist>
      <title>The meaning of the zic commands:</title>

      <varlistentry>
        <term><parameter>zic -L /dev/null ...</parameter></term>
        <listitem>
          <para>This creates posix time zones without any leap seconds.  It is
          conventional to put these in both
          <filename class="directory">zoneinfo</filename> and
          <filename class="directory">zoneinfo/posix</filename>. It is
          necessary to put the POSIX time zones in
          <filename class="directory">zoneinfo</filename>, otherwise various
          test suites will report errors. On an embedded system, where space is
          tight and you do not intend to ever update the time zones, you could save
          1.9 MB by not using the <filename class="directory">posix</filename>
          directory, but some applications or test suites might produce some
          failures.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>zic -L leapseconds ...</parameter></term>
        <listitem>
          <para>This creates right time zones, including leap seconds. On an
          embedded system, where space is tight and you do not intend to
          ever update the time zones, or care about the correct time, you could
          save 1.9MB by omitting the <filename class="directory">right</filename>
          directory.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>zic ... -p ...</parameter></term>
        <listitem>
          <para>This creates the <filename>posixrules</filename> file. We use
          New York because POSIX requires the daylight savings time rules
          to be in accordance with US rules.</para>
        </listitem>
      </varlistentry>
    </variablelist>


    <para>One way to determine the local time zone is to run the following
    script:</para>

<screen role="nodump"><userinput>tzselect</userinput></screen>

    <para>After answering a few questions about the location, the script will
    output the name of the time zone (e.g.,
    <emphasis>America/Edmonton</emphasis>). There are also some other possible
    time zones listed in <filename
    class='directory'>/usr/share/zoneinfo</filename> such as
    <emphasis>Canada/Eastern</emphasis> or <emphasis>EST5EDT</emphasis> that
    are not identified by the script but can be used.</para>

    <para>Then create the <filename>/etc/localtime</filename> file by
    running:</para>

<screen><userinput>ln -sfv /usr/share/zoneinfo/<replaceable>&lt;xxx&gt;</replaceable> /etc/localtime</userinput></screen>

    <para>Replace <replaceable>&lt;xxx&gt;</replaceable> with the name of the
    time zone selected (e.g., Canada/Eastern).</para>

  </sect3>

  <sect3 id="conf-ld" role="configuration">
    <title>Configuring the Dynamic Loader</title>

    <indexterm zone="conf-ld">
      <primary sortas="e-/etc/ld.so.conf">/etc/ld.so.conf</primary>
    </indexterm>

    <para>By default, the dynamic loader (<filename
    class="libraryfile">/lib/ld-linux.so.2</filename>) searches through
    <filename class="directory">/usr/lib</filename> for dynamic libraries
    that are needed by programs as they are run. However, if there are
    libraries in directories other than
    <filename class="directory">/usr/lib</filename>, these need to be added
    to the <filename>/etc/ld.so.conf</filename> file in order for the
    dynamic loader to find them. Two directories that are commonly known
    to contain additional libraries are <filename
    class="directory">/usr/local/lib</filename> and <filename
    class="directory">/opt/lib</filename>, so add those directories to the
    dynamic loader's search path.</para>

    <para>Create a new file <filename>/etc/ld.so.conf</filename> by running the
    following:</para>

<screen><userinput>cat &gt; /etc/ld.so.conf &lt;&lt; "EOF"
<literal># Begin /etc/ld.so.conf
/usr/local/lib
/opt/lib
</literal>
EOF</userinput></screen>

  <para>If desired, the dynamic loader can also search a directory and
  include the contents of files found there.  Generally the files in
  this include directory are one line specifying the desired library path.
  To add this capability run the following commands:</para>

<screen role="nodump"><userinput>cat &gt;&gt; /etc/ld.so.conf &lt;&lt; "EOF"
<literal># Add an include directory
include /etc/ld.so.conf.d/*.conf
</literal>
EOF
mkdir -pv /etc/ld.so.conf.d</userinput></screen>

  </sect3>
  </sect2>

  <!-- - - - - - - - - - -->
  <!-- Multilib - 32bit  -->
  <!-- - - - - - - - - - -->
  <sect2 arch="ml_32,ml_all">
    <title>Building Glibc - 32bit</title>

    <para>Now recompile for m32. The extracted source can be
    reused but needs to be cleaned before installing the m32
    version of Glibc.</para>

    <para>Clear the build directory and remove artefacts from
    previous build:</para>
      
<screen><userinput remap="pre">rm -rf ./*
find .. -name "*.a" -delete</userinput></screen>

    <para>Configure Glibc for m32 with the following commands:</para>

<screen><userinput remap="configure">CC="gcc -m32" CXX="g++ -m32" \
../configure                             \
      --prefix=/usr                      \
      --host=i686-pc-linux-gnu           \
      --build=$(../scripts/config.guess) \
      --enable-kernel=&min-kernel;                \
      --with-headers=/usr/include        \
      --enable-multi-arch                \
      --libdir=/usr/lib32                \
      --libexecdir=/usr/lib32            \
      libc_cv_slibdir=/usr/lib32</userinput></screen>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>Install the package:</para>

<screen><userinput remap="install">make DESTDIR=$PWD/DESTDIR install
cp -a DESTDIR/usr/lib32/* /usr/lib32/
install -vm644 DESTDIR/usr/include/gnu/{lib-names,stubs}-32.h \
               /usr/include/gnu/</userinput></screen>
<!-- no longer required as they are created in chap5
ln -svf ../lib32/ld-linux.so.2 /lib/ld-linux.so.2
-->

    <para>Add the library name to the dynamic loader config:</para>

<screen role="install"><userinput>echo "/usr/lib32" &gt;&gt; /etc/ld.so.conf</userinput></screen>

    <caution>
      <para>At this point, it is imperative to stop and ensure that the basic
      functions (compiling and linking) of the new toolchain are working as
      expected. To perform a sanity check, run the following commands:</para>

<screen><userinput>echo 'int main(){}' &gt; dummy.c
gcc -m32 dummy.c
readelf -l a.out | grep '/ld-linux'</userinput></screen>

      <para>If everything is working correctly, there should be no errors,
      and the output of the last command will be of the form:</para>

<screen><computeroutput>[Requesting program interpreter: /lib/ld-linux.so.2]</computeroutput></screen>

      <para>If the output is not shown as above or there was no output at all,
      then something is wrong. Investigate and retrace the steps to find out
      where the problem is and correct it. This issue must be resolved before
      continuing on.</para>

      <para>Once all is well, clean up the test files:</para>

<screen><userinput>rm -v dummy.c a.out</userinput></screen>

    </caution>

  </sect2><!-- m32 -->

  <!-- - - - - - - - - - -->
  <!-- Multilib - x32bit -->
  <!-- - - - - - - - - - -->
  
  <sect2 arch="ml_x32,ml_all">
    <title>Building Glibc - x32bit</title>

    <para>Now recompile for mx32. The extracted source can be
    reused but needs to be cleaned before installing the mx32
    version of Glibc.</para>

    <para>Clear the build directory and remove artefacts from
    previous build:</para>
      
<screen><userinput remap="pre">rm -rf ./*
find .. -name "*.a" -delete</userinput></screen>

    <para>Configure Glibc for mx32 with the following commands:</para>

<screen><userinput remap="configure">CC="gcc -mx32" CXX="g++ -mx32" \
../configure                             \
      --prefix=/usr                      \
      --host=x86_64-pc-linux-gnux32      \
      --build=$(../scripts/config.guess) \
      --enable-kernel=&min-kernel;                \
      --with-headers=/usr/include        \
      --enable-multi-arch                \
      --libdir=/usr/libx32               \
      --libexecdir=/usr/libx32           \
      libc_cv_slibdir=/usr/libx32</userinput></screen>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>Install the package:</para>

<screen><userinput remap="install">make DESTDIR=$PWD/DESTDIR install
cp -a DESTDIR/usr/libx32/* /usr/libx32/
install -vm644 DESTDIR/usr/include/gnu/{lib-names,stubs}-x32.h \
               /usr/include/gnu/</userinput></screen>
<!-- no longer required as they are created in chap5
ln -svf ../libx32/ld-linux-x32.so.2 /lib/ld-linux-x32.so.2
-->
    <para>Add the library name to the dynamic loader config:</para>

<screen role="install"><userinput>echo "/usr/libx32" &gt;&gt; /etc/ld.so.conf</userinput></screen>

    <caution>
      <para>At this point, it is imperative to stop and ensure that the basic
      functions (compiling and linking) of the new toolchain are working as
      expected. To perform a sanity check, run the following commands:</para>

<screen><userinput>echo 'int main(){}' &gt; dummy.c
gcc -mx32 dummy.c
readelf -l a.out | grep '/ld-linux-x32'</userinput></screen>

      <para>If everything is working correctly, there should be no errors,
      and the output of the last command will be of the form:</para>

<screen><computeroutput>[Requesting program interpreter: /libx32/ld-linux-x32.so.2]</computeroutput></screen>

      <para>If the output is not shown as above or there was no output at all,
      then something is wrong. Investigate and retrace the steps to find out
      where the problem is and correct it. This issue must be resolved before
      continuing on.</para>

      <para>Once all is well, clean up the test files:</para>

<screen><userinput>rm -v dummy.c a.out</userinput></screen>

    </caution>

  </sect2><!-- mx32 -->

  <sect2 id="contents-glibc" role="content">
    <title>Contents of Glibc</title>

    <segmentedlist>
      <segtitle>Installed programs</segtitle>
      <segtitle>Installed libraries</segtitle>
      <segtitle>Installed directories</segtitle>

      <seglistitem>
        <seg>gencat, getconf, getent, iconv, iconvconfig, ldconfig,
        ldd, lddlibc4,
        ld.so (symlink to ld-linux-x86-64.so.2 or ld-linux.so.2),
        locale, localedef, makedb, mtrace,
        pcprofiledump, pldd, sln, sotruss, sprof, tzselect, xtrace,
        zdump, and zic</seg>
        <seg>ld-linux-x86-64.so.2, ld-linux.so.2,
        libBrokenLocale.{a,so}, libanl.{a,so},
        libc.{a,so}, libc_nonshared.a, libc_malloc_debug.so,
        libdl.{a,so.2}, libg.a, libm.{a,so},
        libmcheck.a, libmemusage.so, libmvec.{a,so}, libnsl.so.1,
        libnss_compat.so, libnss_dns.so, libnss_files.so, libnss_hesiod.so,
        libpcprofile.so, libpthread.{a,so.0},
        libresolv.{a,so}, librt.{a,so.1},
        libthread_db.so, and libutil.{a,so.1}</seg>
        <seg>/usr/include/arpa, /usr/include/bits, /usr/include/gnu,
        /usr/include/net, /usr/include/netash, /usr/include/netatalk,
        /usr/include/netax25, /usr/include/neteconet, /usr/include/netinet,
        /usr/include/netipx, /usr/include/netiucv, /usr/include/netpacket,
        /usr/include/netrom, /usr/include/netrose, /usr/include/nfs,
        /usr/include/protocols, /usr/include/rpc,
        /usr/include/sys, /usr/lib/audit, /usr/lib/gconv, /usr/lib/locale,
        /usr/libexec/getconf, /usr/share/i18n, /usr/share/zoneinfo,
        and /var/lib/nss_db</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gencat">
        <term><command>gencat</command></term>
        <listitem>
          <para>Generates message catalogues</para>
          <indexterm zone="ch-system-glibc gencat">
            <primary sortas="b-gencat">gencat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="getconf">
        <term><command>getconf</command></term>
        <listitem>
          <para>Displays the system configuration values for file system
          specific variables</para>
          <indexterm zone="ch-system-glibc getconf">
            <primary sortas="b-getconf">getconf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="getent">
        <term><command>getent</command></term>
        <listitem>
          <para>Gets entries from an administrative database</para>
          <indexterm zone="ch-system-glibc getent">
            <primary sortas="b-getent">getent</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="iconv">
        <term><command>iconv</command></term>
        <listitem>
          <para>Performs character set conversion</para>
          <indexterm zone="ch-system-glibc iconv">
            <primary sortas="b-iconv">iconv</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="iconvconfig">
        <term><command>iconvconfig</command></term>
        <listitem>
          <para>Creates fastloading <command>iconv</command> module configuration
          files</para>
          <indexterm zone="ch-system-glibc iconvconfig">
            <primary sortas="b-iconvconfig">iconvconfig</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldconfig">
        <term><command>ldconfig</command></term>
        <listitem>
          <para>Configures the dynamic linker runtime bindings</para>
          <indexterm zone="ch-system-glibc ldconfig">
            <primary sortas="b-ldconfig">ldconfig</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ldd">
        <term><command>ldd</command></term>
        <listitem>
          <para>Reports which shared libraries are required
          by each given program or shared library</para>
          <indexterm zone="ch-system-glibc ldd">
            <primary sortas="b-ldd">ldd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lddlibc4">
        <term><command>lddlibc4</command></term>
        <listitem>
          <para>Assists <command>ldd</command> with object files.
          It does not exist on newer architectures like x86_64</para>
          <indexterm zone="ch-system-glibc lddlibc4">
            <primary sortas="b-lddlibc4">lddlibc4</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="locale">
        <term><command>locale</command></term>
        <listitem>
          <para>Prints various information about the current locale</para>
          <indexterm zone="ch-system-glibc locale">
            <primary sortas="b-locale">locale</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="localedef">
        <term><command>localedef</command></term>
        <listitem>
          <para>Compiles locale specifications</para>
          <indexterm zone="ch-system-glibc localedef">
            <primary sortas="b-localedef">localedef</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="makedb">
        <term><command>makedb</command></term>
        <listitem>
          <para>Creates a simple database from textual input</para>
          <indexterm zone="ch-system-glibc makedb">
            <primary sortas="b-makedb">makedb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mtrace">
        <term><command>mtrace</command></term>
        <listitem>
          <para>Reads and interprets a memory trace file and displays a summary
          in human-readable format</para>
          <indexterm zone="ch-system-glibc mtrace">
            <primary sortas="b-mtrace">mtrace</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pcprofiledump">
        <term><command>pcprofiledump</command></term>
        <listitem>
          <para>Dump information generated by PC profiling</para>
          <indexterm zone="ch-system-glibc pcprofiledump">
            <primary sortas="b-pcprofiledump">pcprofiledump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pldd">
        <term><command>pldd</command></term>
        <listitem>
          <para>Lists dynamic shared objects used by running processes</para>
          <indexterm zone="ch-system-glibc pldd">
            <primary sortas="b-pldd">pldd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sln">
        <term><command>sln</command></term>
        <listitem>
          <para>A statically linked <command>ln</command> program</para>
          <indexterm zone="ch-system-glibc sln">
            <primary sortas="b-sln">sln</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sotruss">
        <term><command>sotruss</command></term>
        <listitem>
          <para>Traces shared library procedure calls of a specified command</para>
          <indexterm zone="ch-system-glibc sotruss">
            <primary sortas="b-sotruss">sotruss</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sprof">
        <term><command>sprof</command></term>
        <listitem>
          <para>Reads and displays shared object profiling data</para>
          <indexterm zone="ch-system-glibc sprof">
            <primary sortas="b-sprof">sprof</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tzselect">
        <term><command>tzselect</command></term>
        <listitem>
          <para>Asks the user about the location of the system and reports
          the corresponding time zone description</para>
          <indexterm zone="ch-system-glibc tzselect">
            <primary sortas="b-tzselect">tzselect</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xtrace">
        <term><command>xtrace</command></term>
        <listitem>
          <para>Traces the execution of a program by printing the currently
          executed function</para>
          <indexterm zone="ch-system-glibc xtrace">
            <primary sortas="b-xtrace">xtrace</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="zdump">
        <term><command>zdump</command></term>
        <listitem>
          <para>The time zone dumper</para>
          <indexterm zone="ch-system-glibc zdump">
            <primary sortas="b-zdump">zdump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="zic">
        <term><command>zic</command></term>
        <listitem>
          <para>The time zone compiler</para>
          <indexterm zone="ch-system-glibc zic">
            <primary sortas="b-zic">zic</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ld.so">
        <term><filename class="libraryfile">ld-*.so</filename></term>
        <listitem>
          <para>The helper program for shared library executables</para>
          <indexterm zone="ch-system-glibc ld.so">
            <primary sortas="c-ld.so">ld-&glibc-version;.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libBrokenLocale">
        <term><filename class="libraryfile">libBrokenLocale</filename></term>
        <listitem>
          <para>Used internally by Glibc as a gross hack to get broken programs
          (e.g., some Motif applications) running. See comments in
          <filename>glibc-&glibc-version;/locale/broken_cur_max.c</filename>
          for more information</para>
          <indexterm zone="ch-system-glibc libBrokenLocale">
            <primary sortas="c-libBrokenLocale">libBrokenLocale</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libanl">
        <term><filename class="libraryfile">libanl</filename></term>
        <listitem>
          <para>Dummy library containing no functions.  Previously was the
          asynchronous name lookup library, whose functions are now in
          <filename class='libraryfile'>libc</filename></para>
          <indexterm zone="ch-system-glibc libanl">
            <primary sortas="c-libanl">libanl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libc">
        <term><filename class="libraryfile">libc</filename></term>
        <listitem>
          <para>The main C library</para>
          <indexterm zone="ch-system-glibc libc">
            <primary sortas="c-libc">libc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libc_malloc_debug">
        <term><filename class="libraryfile">libc_malloc_debug</filename></term>
        <listitem>
          <para>Turns on memory allocation checking when preloaded</para>
          <indexterm zone="ch-system-glibc libc_malloc_debug">
            <primary sortas="c-libc_malloc_debug">libc_malloc_debug</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdl">
        <term><filename class="libraryfile">libdl</filename></term>
        <listitem>
          <para>Dummy library containing no functions. Previously was the
          dynamic linking interface library, whose functions are now in
          <filename class="libraryfile">libc</filename></para>
          <indexterm zone="ch-system-glibc libdl">
            <primary sortas="c-libdl">libdl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libg">
        <term><filename class="libraryfile">libg</filename></term>
        <listitem>
          <para>Dummy library containing no functions. Previously was a runtime
          library for <command>g++</command></para>
          <indexterm zone="ch-system-glibc libg">
            <primary sortas="c-libg">libg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libm">
        <term><filename class="libraryfile">libm</filename></term>
        <listitem>
          <para>The mathematical library</para>
          <indexterm zone="ch-system-glibc libm">
            <primary sortas="c-libm">libm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmvec">
        <term><filename class="libraryfile">libmvec</filename></term>
        <listitem>
          <para>The vector math library, linked in as needed
          when <filename class='libraryfile'>libm</filename> is used</para>
          <indexterm zone="ch-system-glibc libmvec">
            <primary sortas="c-libmvec">libmvec</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmcheck">
        <term><filename class="libraryfile">libmcheck</filename></term>
        <listitem>
          <para>Turns on memory allocation checking when linked to</para>
          <indexterm zone="ch-system-glibc libmcheck">
            <primary sortas="c-libmcheck">libmcheck</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmemusage">
        <term><filename class="libraryfile">libmemusage</filename></term>
        <listitem>
          <para>Used by <command>memusage</command> to help collect
          information about the memory usage of a program</para>
          <indexterm zone="ch-system-glibc libmemusage">
            <primary sortas="c-libmemusage">libmemusage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libnsl">
        <term><filename class="libraryfile">libnsl</filename></term>
        <listitem>
          <para>The network services library, now deprecated</para>
          <indexterm zone="ch-system-glibc libnsl">
            <primary sortas="c-libnsl">libnsl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libnss">
        <term><filename class="libraryfile">libnss_*</filename></term>
        <listitem>
          <para>The Name Service Switch modules, containing functions for
          resolving host names, user names, group names, aliases, services,
          protocols, etc.  Loaded by
          <filename class='libraryfile'>libc</filename> according to the
          configuration in <filename>/etc/nsswitch.conf</filename></para>
          <indexterm zone="ch-system-glibc libnss">
            <primary sortas="c-libnss">libnss_*</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpcprofile">
        <term><filename class="libraryfile">libpcprofile</filename></term>
        <listitem>
          <para>Can be preloaded to PC profile an executable</para>
          <indexterm zone="ch-system-glibc libpcprofile">
            <primary sortas="c-libpcprofile">libpcprofile</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpthread">
        <term><filename class="libraryfile">libpthread</filename></term>
        <listitem>
          <para>Dummy library containing no functions. Previously contained
          functions providing most of the interfaces specified
          by the POSIX.1c Threads Extensions and the semaphore interfaces
          specified by the POSIX.1b Real-time Extensions, now the functions
          are in <filename class="libraryfile">libc</filename></para>
          <indexterm zone="ch-system-glibc libpthread">
            <primary sortas="c-libpthread">libpthread</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libresolv">
        <term><filename class="libraryfile">libresolv</filename></term>
        <listitem>
          <para>Contains functions for creating, sending, and interpreting
          packets to the Internet domain name servers</para>
          <indexterm zone="ch-system-glibc libresolv">
            <primary sortas="c-libresolv">libresolv</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="librt">
        <term><filename class="libraryfile">librt</filename></term>
        <listitem>
          <para>Contains functions providing most of the interfaces specified
          by the POSIX.1b Real-time Extensions</para>
          <indexterm zone="ch-system-glibc librt">
            <primary sortas="c-librt">librt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libthread_db">
        <term><filename class="libraryfile">libthread_db</filename></term>
        <listitem>
          <para>Contains functions useful for building debuggers for
          multi-threaded programs</para>
          <indexterm zone="ch-system-glibc libthread_db">
            <primary sortas="c-libthread_db">libthread_db</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libutil">
        <term><filename class="libraryfile">libutil</filename></term>
        <listitem>
          <para>Dummy library containing no functions. Previously contained
          code for <quote>standard</quote> functions used in
          many different Unix utilities. These functions are now in
          <filename class="libraryfile">libc</filename></para>
          <indexterm zone="ch-system-glibc libutil">
            <primary sortas="c-libutil">libutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>