- Rename .sgml files to .xml

- Reflect the rename in referencing files

Approved by:	doceng (implicit)

1 files changed, 1345 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml
new file mode 100644
index 0000000000..b9c42c0b42
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml
@@ -0,0 +1,1345 @@
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="linuxemu">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Jim</firstname>
+	<surname>Mock</surname>
+	<contrib>Restructured and parts updated by </contrib>
+      </author>
+      <!-- 22 Mar 2000 -->
+    </authorgroup>
+    <authorgroup>
+      <author>
+	<firstname>Brian N.</firstname>
+	<surname>Handy</surname>
+	<contrib>Originally contributed by </contrib>
+      </author>
+      <author>
+	<firstname>Rich</firstname>
+	<surname>Murphey</surname>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Linux Binary Compatibility</title>
+
+  <sect1 id="linuxemu-synopsis">
+    <title>Synopsis</title>
+    <indexterm><primary>Linux binary compatibility</primary></indexterm>
+    <indexterm>
+      <primary>binary compatibility</primary>
+      <secondary>Linux</secondary>
+    </indexterm>
+
+    <para>FreeBSD provides binary compatibility with several other
+      &unix; like operating systems, including Linux.  At this point,
+      you may be asking yourself why exactly, does
+      FreeBSD need to be able to run Linux binaries?  The answer to that
+      question is quite simple.  Many companies and developers develop
+      only for Linux, since it is the latest <quote>hot thing</quote> in
+      the computing world.  That leaves the rest of us FreeBSD users
+      bugging these same companies and developers to put out native
+      FreeBSD versions of their applications.  The problem is, that most
+      of these companies do not really realize how many people would use
+      their product if there were FreeBSD versions too, and most continue
+      to only develop for Linux.  So what is a FreeBSD user to do?  This
+      is where the Linux binary compatibility of FreeBSD comes into
+      play.</para>
+
+    <para>In a nutshell, the compatibility allows FreeBSD users to run
+      about 90% of all Linux applications without modification.  This
+      includes applications such as <application>&staroffice;</application>,
+      the Linux version of <application>&netscape;</application>,
+      <application>&adobe;&nbsp;&acrobat;</application>,
+      <application>&realplayer;</application>,
+      <application>&oracle;</application>,
+      <application>&wordperfect;</application>, <application>Doom</application>,
+      <application>Quake</application>, and more.  It is also reported
+      that in some situations, Linux binaries perform better on FreeBSD
+      than they do under Linux.</para>
+
+    <para>There are, however, some Linux-specific operating system
+      features that are not supported under FreeBSD.  Linux binaries will
+      not work on FreeBSD if they overly use &i386; specific
+      calls, such as enabling virtual 8086 mode.</para>
+
+    <para>After reading this chapter, you will know:</para>
+    <itemizedlist>
+      <listitem>
+	<para>How to enable Linux binary compatibility on your system.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to install additional Linux shared
+	  libraries.</para>
+	</listitem>
+
+      <listitem>
+	<para>How to install Linux applications on your FreeBSD system.</para>
+      </listitem>
+
+      <listitem>
+	<para>The implementation details of Linux compatibility in FreeBSD.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Know how to install additional third-party
+        software (<xref linkend="ports"/>).</para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="linuxemu-lbc-install">
+    <title>Installation</title>
+
+    <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>
+
+    <para>Linux binary compatibility is not turned on by default.  The
+      easiest way to enable this functionality is to load the
+      <literal>linux</literal> KLD object (<quote>Kernel LoaDable
+      object</quote>).  You can load this module by typing the
+      following as <username>root</username>:</para>
+
+    <screen>&prompt.root; <userinput>kldload linux</userinput></screen>
+
+    <para>If you would like Linux compatibility to always be enabled,
+      then you should add the following line to
+      <filename>/etc/rc.conf</filename>:</para>
+
+    <programlisting>linux_enable="YES"</programlisting>
+
+    <para>The &man.kldstat.8; command can be used to verify that the
+      KLD is loaded:</para>
+
+    <screen>&prompt.user; <userinput>kldstat</userinput>
+Id Refs Address    Size     Name
+ 1    2 0xc0100000 16bdb8   kernel
+ 7    1 0xc24db000 d000     linux.ko</screen>
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>COMPAT_LINUX</secondary>
+    </indexterm>
+
+    <para>If for some reason you do not want to or cannot load the KLD,
+      then you may statically link Linux binary compatibility into the kernel
+      by adding <literal>options COMPAT_LINUX</literal> to your kernel
+      configuration file.  Then install your new kernel as described in
+      <xref linkend="kernelconfig"/>.</para>
+
+    <sect2>
+      <title>Installing Linux Runtime Libraries</title>
+      <indexterm>
+	<primary>Linux</primary>
+	<secondary>installing Linux libraries</secondary>
+      </indexterm>
+
+      <para>This can be done one of two ways, either by using the
+	<link linkend="linuxemu-libs-port">linux_base</link> port, or
+	by installing them <link
+	linkend="linuxemu-libs-manually">manually</link>.</para>
+
+      <sect3 id="linuxemu-libs-port">
+	<title>Installing Using the linux_base Port</title>
+	<indexterm><primary>Ports Collection</primary></indexterm>
+
+	<para>This is by far the easiest method to use when installing the
+	  runtime libraries.  It is just like installing any other port
+	  from the <link linkend="ports">Ports Collection</link>:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base-f10</userinput>
+&prompt.root; <userinput>make install distclean</userinput></screen>
+
+	<note>
+	  <para>On &os; systems prior to &os;&nbsp;8.0, you will have
+	    to use the <filename
+	    role="package">emulators/linux_base-fc4</filename> port
+	    instead of <filename
+	    role="package">emulators/linux_base-f10</filename>.</para>
+	</note>
+
+	<para>You should now have working Linux binary compatibility.
+	  Some programs may complain about incorrect minor versions of the
+	  system libraries.  In general, however, this does not seem to be
+	  a problem.</para>
+
+	<note><para>There may be multiple versions of the <filename
+	  role="package">emulators/linux_base</filename> port available,
+	  corresponding to different versions of various Linux distributions.
+	  You should install the port most closely resembling the
+	  requirements of the Linux applications you would like to
+	  install.</para></note>
+
+      </sect3>
+
+      <sect3 id="linuxemu-libs-manually">
+	<title>Installing Libraries Manually</title>
+
+	<para>If you do not have the <quote>ports</quote> collection
+	  installed, you can install the libraries by hand instead.  You
+	  will need the Linux shared libraries that the program depends on
+	  and the runtime linker.  Also, you will need to create a
+	  <quote>shadow root</quote> directory,
+	  <filename>/compat/linux</filename>, for Linux libraries on your
+	  FreeBSD system.  Any shared libraries opened by Linux programs
+	  run under FreeBSD will look in this tree first.  So, if a Linux
+	  program loads, for example, <filename>/lib/libc.so</filename>,
+	  FreeBSD will first try to open
+	  <filename>/compat/linux/lib/libc.so</filename>, and if that does
+	  not exist, it will then try <filename>/lib/libc.so</filename>.
+	  Shared libraries should be installed in the shadow tree
+	  <filename>/compat/linux/lib</filename> rather than the paths
+	  that the Linux <command>ld.so</command> reports.</para>
+
+	<para>Generally, you will need to look for the shared libraries
+	  that Linux binaries depend on only the first few times that you
+	  install a Linux program on your FreeBSD system.  After a while,
+	  you will have a sufficient set of Linux shared libraries on your
+	  system to be able to run newly imported Linux binaries without
+	  any extra work.</para>
+      </sect3>
+
+      <sect3>
+	<title>How to Install Additional Shared Libraries</title>
+	<indexterm><primary>shared libraries</primary></indexterm>
+
+	<para>What if you install the <filename>linux_base</filename> port
+	  and your application still complains about missing shared
+	  libraries?  How do you know which shared libraries Linux
+	  binaries need, and where to get them?  Basically, there are 2
+	  possibilities (when following these instructions you will need
+	  to be <username>root</username> on your FreeBSD system).</para>
+
+	<para>If you have access to a Linux system, see what shared
+	  libraries the application needs, and copy them to your FreeBSD
+	  system.  Look at the following example:</para>
+
+	<informalexample>
+	  <para>Let us assume you used FTP to get the Linux binary of
+	    <application>Doom</application>, and put it on a Linux system you have access to.  You
+	    then can check which shared libraries it needs by running
+	    <command>ldd linuxdoom</command>, like so:</para>
+
+	  <screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
+libXt.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libXt.so.3.1.0
+libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
+libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
+
+	  <indexterm><primary>symbolic links</primary></indexterm>
+	  <para>You would need to get all the files from the last column,
+	    and put them under <filename>/compat/linux</filename>, with
+	    the names in the first column as symbolic links pointing to
+	    them.  This means you eventually have these files on your
+	    FreeBSD system:</para>
+
+	  <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
+/compat/linux/usr/X11/lib/libXt.so.3 -&gt; libXt.so.3.1.0
+/compat/linux/usr/X11/lib/libX11.so.3.1.0
+/compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
+/compat/linux/lib/libc.so.4.6.29
+/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
+
+	  <blockquote>
+	    <note>
+	      <para>Note that if you already have a Linux shared library
+		with a matching major revision number to the first column
+		of the <command>ldd</command> output, you will not need to
+		copy the file named in the last column to your system, the
+		one you already have should work.  It is advisable to copy
+		the shared library anyway if it is a newer version,
+		though.  You can remove the old one, as long as you make
+		the symbolic link point to the new one.  So, if you have
+		these libraries on your system:</para>
+
+	      <screen>/compat/linux/lib/libc.so.4.6.27
+/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>
+
+	      <para>and you find a new binary that claims to require a
+		later version according to the output of
+		<command>ldd</command>:</para>
+
+	      <screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
+
+	      <para>If it is only one or two versions out of date in the
+		trailing digit then do not worry about copying
+		<filename>/lib/libc.so.4.6.29</filename> too, because the
+		program should work fine with the slightly older version.
+		However, if you like, you can decide to replace the
+		<filename>libc.so</filename> anyway, and that should leave
+		you with:</para>
+
+	      <screen>/compat/linux/lib/libc.so.4.6.29
+/compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
+	    </note>
+	  </blockquote>
+
+	  <blockquote>
+	    <note>
+	      <para>The symbolic link mechanism is
+		<emphasis>only</emphasis> needed for Linux binaries.  The
+		FreeBSD runtime linker takes care of looking for matching
+		major revision numbers itself and you do not need to worry
+		about it.</para>
+	    </note>
+	  </blockquote>
+	</informalexample>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Installing Linux ELF Binaries</title>
+      <indexterm>
+	<primary>Linux</primary>
+	<secondary>ELF binaries</secondary>
+      </indexterm>
+
+      <para>ELF binaries sometimes require an extra step of
+	<quote>branding</quote>.  If you attempt to run an unbranded ELF
+	binary, you will get an error message like the following:</para>
+
+      <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
+ELF binary type not known
+Abort</screen>
+
+      <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
+	binary and a Linux binary, use the &man.brandelf.1;
+	utility.</para>
+
+      <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
+
+      <indexterm><primary>GNU toolchain</primary></indexterm>
+      <para>The GNU toolchain now places the appropriate branding
+	information into ELF binaries automatically, so this step
+	should become increasingly unnecessary in the future.</para>
+    </sect2>
+
+    <sect2>
+      <title>Installing a Random Linux RPM Based Application</title>
+
+      <para>FreeBSD has its own package database and it is used to track
+	all ports (&linux; ports as well).  So the &linux; RPM database is not
+	used (not supported).</para>
+
+      <para>However if you need to install a random &linux; RPM-based
+	application it can be achieved by:</para>
+
+      <screen>&prompt.root; <userinput>cd /compat/linux</userinput>
+&prompt.root; <userinput>rpm2cpio -q &lt; /path/to/linux.archive.rpm | cpio -id</userinput></screen>
+
+      <para>Then brandelf installed ELF binaries (not libraries!).
+	You will not be able to do a clean uninstall, but it may help you
+	to do tests.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuring the Hostname Resolver</title>
+
+      <para>If DNS does not work or you get this message:</para>
+
+      <screen>resolv+: "bind" is an invalid keyword resolv+:
+"hosts" is an invalid keyword</screen>
+
+      <para>You will need to configure a
+	<filename>/compat/linux/etc/host.conf</filename> file
+	containing:</para>
+
+      <programlisting>order hosts, bind
+multi on</programlisting>
+
+      <para>The order here specifies that <filename>/etc/hosts</filename>
+	is searched first and DNS is searched second.  When
+	<filename>/compat/linux/etc/host.conf</filename> is not
+	installed, Linux applications find FreeBSD's
+	<filename>/etc/host.conf</filename> and complain about the
+	incompatible FreeBSD syntax.  You should remove
+	<literal>bind</literal> if you have not configured a name server
+	using the <filename>/etc/resolv.conf</filename> file.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="linuxemu-mathematica">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Boris</firstname>
+	  <surname>Hollas</surname>
+	  <contrib>Updated for Mathematica 5.X by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Installing &mathematica;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>Mathematica</application></secondary>
+    </indexterm>
+
+    <para>This document describes the process of installing the Linux
+      version of <application>&mathematica; 5.X</application> onto
+      a FreeBSD system.</para>
+
+    <para>The Linux version of <application>&mathematica;</application>
+      or <application>&mathematica; for Students</application> can
+      be ordered directly from Wolfram at
+      <ulink url="http://www.wolfram.com/"></ulink>.</para>
+
+    <sect2>
+      <title>Running the &mathematica; Installer</title>
+
+      <para>First, you have to tell &os; that
+	<application>&mathematica;</application>'s Linux
+	binaries use the Linux ABI.  The easiest way to do so is to
+	set the default ELF brand
+	to Linux for all unbranded binaries with the command:</para>
+
+      <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>
+
+      <para>This will make &os; assume that unbranded ELF binaries
+	use the Linux ABI and so you should be able to run the
+	installer straight from the CDROM.</para>
+
+      <para>Now, copy the file <filename>MathInstaller</filename> to
+	your hard drive:</para>
+
+      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen>
+
+      <para>and in this file, replace <literal>/bin/sh</literal> in
+	the first line by <literal>/compat/linux/bin/sh</literal>.
+	This makes sure that the installer is executed by the Linux
+	version of &man.sh.1;.  Next, replace all occurrences of
+	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
+	a text editor or the script below in the next section.  This
+	tells the <application>&mathematica;</application> installer,
+	who calls <command>uname -s</command> to determine the
+	operating system, to treat &os; as a Linux-like operating
+	system.  Invoking <command>MathInstaller</command> will now
+	install <application>&mathematica;</application>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Modifying the &mathematica; Executables</title>
+
+      <para>The shell scripts that
+	<application>&mathematica;</application> created during
+	installation have to be modified before you can use them.  If
+	you chose <filename class="directory">/usr/local/bin</filename>
+	as the directory to place the
+	<application>&mathematica;</application> executables in, you
+	will find symlinks in this directory to files called
+	<filename>math</filename>, <filename>mathematica</filename>,
+	<filename>Mathematica</filename>, and
+	<filename>MathKernel</filename>.  In each of these, replace
+	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
+	a text editor or the following shell script:</para>
+
+      <programlisting>#!/bin/sh
+cd /usr/local/bin
+for i in math mathematica Mathematica MathKernel
+  do sed 's/Linux)/FreeBSD)/g' $i &gt; $i.tmp
+  sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp &gt; $i
+  rm $i.tmp
+  chmod a+x $i
+done</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Obtaining Your &mathematica; Password</title>
+
+      <indexterm>
+	<primary>Ethernet</primary>
+	<secondary>MAC address</secondary>
+      </indexterm>
+
+      <para>When you start <application>&mathematica;</application>
+	for the first time, you will be asked for a password.  If you
+	have not yet obtained a password from Wolfram, run the program
+	<command>mathinfo</command> in the installation directory to
+	obtain your <quote>machine ID</quote>.  This machine ID is
+	based solely on the MAC address of your first Ethernet card,
+	so you cannot run your copy of
+	<application>&mathematica;</application> on different
+	machines.</para>
+
+      <para>When you register with Wolfram, either by email, phone or fax,
+	you will give them the <quote>machine ID</quote> and they will
+	respond with a corresponding password consisting of groups of
+	numbers.</para>
+    </sect2>
+
+    <sect2>
+      <title>Running the &mathematica; Frontend over a Network</title>
+
+      <para><application>&mathematica;</application> uses some special
+	fonts to display characters not
+	present in any of the standard font sets (integrals, sums, Greek
+	letters, etc.).  The X protocol requires these fonts to be install
+	<emphasis>locally</emphasis>.  This means you will have to copy
+	these fonts from the CDROM or from a host with
+	<application>&mathematica;</application>
+	installed to your local machine.  These fonts are normally stored
+	in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the
+	CDROM, or
+	<filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on
+	your hard drive.  The actual fonts are in the subdirectories
+	<filename>Type1</filename> and <filename>X</filename>.  There are
+	several ways to use them, as described below.</para>
+
+      <para>The first way is to copy them into one of the existing font
+	directories in <filename>/usr/X11R6/lib/X11/fonts</filename>.
+	This will require editing the <filename>fonts.dir</filename> file,
+	adding the font names to it, and changing the number of fonts on
+	the first line.  Alternatively, you should also just be able to
+	run &man.mkfontdir.1; in the directory you have copied
+	them to.</para>
+
+      <para>The second way to do this is to copy the directories to
+	<filename>/usr/X11R6/lib/X11/fonts</filename>:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput>
+&prompt.root; <userinput>mkdir X</userinput>
+&prompt.root; <userinput>mkdir MathType1</userinput>
+&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
+&prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput>
+&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
+&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput>
+&prompt.root; <userinput>mkfontdir</userinput>
+&prompt.root; <userinput>cd ../MathType1</userinput>
+&prompt.root; <userinput>mkfontdir</userinput></screen>
+
+      <para>Now add the new font directories to your font path:</para>
+
+      <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
+&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
+&prompt.root; <userinput>xset fp rehash</userinput></screen>
+
+      <para>If you are using the <application>&xorg;</application> server, you can have these font
+	directories loaded automatically by adding them to your
+	<filename>xorg.conf</filename> file.</para>
+
+      <indexterm><primary>fonts</primary></indexterm>
+
+      <para>If you <emphasis>do not</emphasis> already have a directory
+	called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
+	can change the name of the <filename>MathType1</filename>
+	directory in the example above to
+	<filename>Type1</filename>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="linuxemu-maple">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Aaron</firstname>
+	  <surname>Kaplan</surname>
+<!--	  <address><email>aaron@lo-res.org</email></address>-->
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Robert</firstname>
+	  <surname>Getschmann</surname>
+<!--	  <address><email>rob@getschmann.org</email></address>-->
+	  <contrib>Thanks to </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Installing &maple;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>Maple</application></secondary>
+    </indexterm>
+
+    <para><application>&maple;</application> is a commercial mathematics program similar to
+      <application>&mathematica;</application>.  You must purchase this software from <ulink
+      url="http://www.maplesoft.com/"></ulink> and then register there
+      for a license file.  To install this software on FreeBSD, please
+      follow these simple steps.</para>
+
+      <procedure>
+	<step><para>Execute the <filename>INSTALL</filename> shell
+	  script from the product distribution.  Choose the
+	  <quote>RedHat</quote> option when prompted by the
+	  installation program.  A typical installation directory
+	  might be <filename
+	  class="directory">/usr/local/maple</filename>.</para></step>
+
+        <step><para>If you have not done so, order a license for <application>&maple;</application>
+	  from Maple Waterloo Software (<ulink url="http://register.maplesoft.com/"></ulink>)
+	  and copy it to
+	  <filename>/usr/local/maple/license/license.dat</filename>.</para></step>
+
+        <step><para>Install the <application>FLEXlm</application>
+	  license manager by running the
+	  <filename>INSTALL_LIC</filename> install shell script that
+	  comes with <application>&maple;</application>.  Specify the
+	  primary hostname for your machine for the license
+	  server.</para></step>
+
+        <step><para>Patch the
+          <filename>/usr/local/maple/bin/maple.system.type</filename>
+          file with the following:</para>
+<programlisting>   ----- snip ------------------
+*** maple.system.type.orig      Sun Jul  8 16:35:33 2001
+--- maple.system.type   Sun Jul  8 16:35:51 2001
+***************
+*** 72,77 ****
+--- 72,78 ----
+          # the IBM RS/6000 AIX case
+          MAPLE_BIN="bin.IBM_RISC_UNIX"
+          ;;
++     "FreeBSD"|\
+      "Linux")
+          # the Linux/x86 case
+        # We have two Linux implementations, one for Red Hat and
+   ----- snip end of patch -----</programlisting>
+
+	<para>Please note that after the <literal>"FreeBSD"|\</literal> no other
+	  whitespace should be present.</para>
+
+	<para>This patch instructs <application>&maple;</application> to
+	  recognize <quote>FreeBSD</quote> as a type of Linux system.
+	  The <filename>bin/maple</filename> shell script calls the
+	  <filename>bin/maple.system.type</filename> shell script
+	  which in turn calls <command>uname -a</command> to find out the operating
+	  system name. Depending on the OS name it will find out which
+	  binaries to use.</para></step>
+
+      <step><para>Start the license server.</para>
+
+	<para>The following script, installed as
+	  <filename>/usr/local/etc/rc.d/lmgrd.sh</filename> is a
+	  convenient way to start up <command>lmgrd</command>:</para>
+
+	<programlisting>   ----- snip ------------
+
+#! /bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
+PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
+export PATH
+
+LICENSE_FILE=/usr/local/maple/license/license.dat
+LOG=/var/log/lmgrd.log
+
+case "$1" in
+start)
+	lmgrd -c ${LICENSE_FILE} 2&gt;&gt; ${LOG} 1&gt;&amp;2
+	echo -n " lmgrd"
+	;;
+stop)
+	lmgrd -c ${LICENSE_FILE} -x lmdown 2&gt;&gt; ${LOG} 1&gt;&amp;2
+	;;
+*)
+	echo "Usage: `basename $0` {start|stop}" 1&gt;&amp;2
+	exit 64
+	;;
+esac
+
+exit 0
+   ----- snip ------------</programlisting></step>
+
+
+      <step><para>Test-start <application>&maple;</application>:</para>
+	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
+&prompt.user; <userinput>./xmaple</userinput></screen>
+
+	<para>You should be up and running. Make sure to write
+	  Maplesoft to let them know you would like a native FreeBSD
+	  version!</para></step>
+    </procedure>
+
+    <sect2>
+      <title>Common Pitfalls</title>
+
+      <itemizedlist>
+	<listitem><para>The <application>FLEXlm</application> license manager can be a difficult
+	  tool to work with.  Additional documentation on the subject
+	  can be found at <ulink
+	  url="http://www.globetrotter.com/"></ulink>.</para></listitem>
+
+	<listitem><para><command>lmgrd</command> is known to be very picky
+	  about the license file and to core dump if there are any
+	  problems.  A correct license file should look like this:</para>
+
+<programlisting># =======================================================
+# License File for UNIX Installations ("Pointer File")
+# =======================================================
+SERVER chillig ANY
+#USE_SERVER
+VENDOR maplelmg
+
+FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
+         PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
+         ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
+         SN=XXXXXXXXX</programlisting>
+
+	  <note><para>Serial number and key 'X''ed out. <hostid>chillig</hostid> is a
+	    hostname.</para></note>
+
+  	  <para>Editing the license file works as long as you do not
+ 	    touch the <quote>FEATURE</quote> line (which is protected by the
+ 	    license key).</para></listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="linuxemu-matlab">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Dan</firstname>
+	  <surname>Pelleg</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- daniel+handbook@pelleg.org -->
+      </authorgroup>
+    </sect1info>
+    <title>Installing &matlab;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>MATLAB</application></secondary>
+    </indexterm>
+
+    <para>This document describes the process of installing the Linux
+      version of <application>&matlab; version 6.5</application> onto
+      a &os; system.  It works quite well, with the exception of the
+      <application>&java.virtual.machine;</application> (see
+      <xref linkend="matlab-jre"/>).</para>
+
+    <para>The Linux version of <application>&matlab;</application> can be
+      ordered directly from The MathWorks at <ulink
+      url="http://www.mathworks.com"></ulink>.  Make sure you also get
+      the license file or instructions how to create it.  While you
+      are there, let them know you would like a native &os;
+      version of their software.</para>
+
+    <sect2>
+      <title>Installing &matlab;</title>
+
+      <para>To install <application>&matlab;</application>, do the
+	following:</para>
+
+      <procedure>
+	<step>
+	  <para>Insert the installation CD and mount it.
+	    Become <username>root</username>, as recommended by the
+	    installation script.  To start the installation script
+	    type:</para>
+
+	  <screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen>
+
+	  <tip>
+	    <para>The installer is graphical.  If you get errors about
+	      not being able to open a display, type
+	      <command>setenv HOME ~<replaceable>USER</replaceable></command>,
+	      where <replaceable>USER</replaceable> is the user you did a
+	      &man.su.1; as.</para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>
+	    When asked for the <application>&matlab;</application> root
+	    directory, type:
+	    <userinput>/compat/linux/usr/local/matlab</userinput>.</para>
+
+	  <tip>
+	    <para>For easier typing on the rest of the installation
+	      process, type this at your shell prompt:
+	      <command>set MATLAB=/compat/linux/usr/local/matlab</command></para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>Edit the license file as instructed when
+	    obtaining the <application>&matlab;</application> license.</para>
+
+	  <tip>
+	    <para>You can prepare this file in advance using your
+	      favorite editor, and copy it to
+	      <filename>$MATLAB/license.dat</filename> before the
+	      installer asks you to edit it.</para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>Complete the installation process.</para>
+	</step>
+      </procedure>
+
+      <para>At this point your <application>&matlab;</application>
+	installation is complete.  The following steps apply
+	<quote>glue</quote> to connect it to your &os; system.</para>
+    </sect2>
+
+    <sect2>
+      <title>License Manager Startup</title>
+      <procedure>
+	<step>
+	  <para>Create symlinks for the license manager scripts:</para>
+
+	  <screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput>
+&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Create a startup file at
+	    <filename>/usr/local/etc/rc.d/flexlm.sh</filename>.  The
+	    example below is a modified version of the distributed
+	    <filename>$MATLAB/etc/rc.lm.glnx86</filename>.  The changes
+	    are file locations, and startup of the license manager
+	    under Linux emulation.</para>
+
+	  <programlisting>#!/bin/sh
+case "$1" in
+  start)
+        if [ -f /usr/local/etc/lmboot_TMW ]; then
+              /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> &amp;&amp; echo 'MATLAB_lmgrd'
+        fi
+        ;;
+  stop)
+	if [ -f /usr/local/etc/lmdown_TMW ]; then
+            /compat/linux/bin/sh /usr/local/etc/lmdown_TMW  &gt; /dev/null 2&gt;&amp;1
+	fi
+        ;;
+  *)
+	echo "Usage: $0 {start|stop}"
+	exit 1
+	;;
+esac
+
+exit 0</programlisting>
+
+	  <important>
+	    <para>The file must be made executable:</para>
+
+	    <screen>&prompt.root; <userinput>chmod +x /usr/local/etc/rc.d/flexlm.sh</userinput></screen>
+
+	    <para>You must also replace
+	      <replaceable>username</replaceable> above with the name
+	      of a valid user on your system (and not
+	      <username>root</username>).</para>
+	  </important>
+	</step>
+
+	<step>
+	  <para>Start the license manager with the command:</para>
+
+	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/flexlm.sh start</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="matlab-jre">
+      <title>Linking the &java; Runtime Environment</title>
+
+      <para>Change the <application>&java;</application> Runtime
+	Environment (JRE) link to one working under &os;:</para>
+
+      <screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput>
+&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Creating a &matlab; Startup Script</title>
+
+      <procedure>
+	<step>
+	  <para>Place the following startup script in
+	    <filename>/usr/local/bin/matlab</filename>:
+	  </para>
+
+	  <programlisting>#!/bin/sh
+/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting>
+	</step>
+
+	<step>
+	  <para>Then type the command
+	    <command>chmod +x /usr/local/bin/matlab</command>.</para>
+	</step>
+      </procedure>
+
+      <tip>
+	<para>Depending on your version of
+	  <filename role="package">emulators/linux_base</filename>, you
+	  may run into errors when running this script.  To avoid that,
+	  edit the file
+	  <filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
+	  and change the line that says:</para>
+
+	<programlisting>if [ `expr "$lscmd" : '.*-&gt;.*'` -ne 0 ]; then</programlisting>
+
+	<para>(in version 13.0.1 it is on line 410) to this
+	  line:</para>
+
+	<programlisting>if test -L $newbase; then</programlisting>
+      </tip>
+    </sect2>
+
+    <sect2>
+      <title>Creating a &matlab; Shutdown Script</title>
+
+      <para>The following is needed to solve a problem with &matlab;
+	not exiting correctly.</para>
+
+      <procedure>
+	<step>
+	  <para>Create a file
+	    <filename>$MATLAB/toolbox/local/finish.m</filename>, and
+	    in it put the single line:</para>
+
+	  <programlisting>! $MATLAB/bin/finish.sh</programlisting>
+
+	  <note><para>The <literal>$MATLAB</literal> is
+	    literal.</para></note>
+
+	  <tip>
+	    <para>In the same directory, you will find the files
+	      <filename>finishsav.m</filename> and
+	      <filename>finishdlg.m</filename>, which let you save
+	      your workspace before quitting.  If you use either of
+	      them, insert the line above immediately after the
+	      <literal>save</literal> command.</para></tip>
+	</step>
+
+	<step>
+	  <para>Create a file
+	    <filename>$MATLAB/bin/finish.sh</filename>, which will
+	    contain the following:</para>
+
+	  <programlisting>#!/compat/linux/bin/sh
+(sleep 5; killall -1 matlab_helper) &
+exit 0</programlisting>
+	</step>
+
+	<step>
+	  <para>Make the file executable:</para>
+
+	  <screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="matlab-using">
+      <title>Using &matlab;</title>
+
+      <para>At this point you are ready to type
+	<command>matlab</command> and start using it.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="linuxemu-oracle">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marcel</firstname>
+	  <surname>Moolenaar</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- marcel@cup.hp.com -->
+      </authorgroup>
+    </sect1info>
+    <title>Installing &oracle;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>Oracle</application></secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Preface</title>
+      <para>This document describes the process of installing <application>&oracle; 8.0.5</application> and
+	<application>&oracle; 8.0.5.1 Enterprise Edition</application> for Linux onto a FreeBSD
+	machine.</para>
+    </sect2>
+
+    <sect2>
+      <title>Installing the Linux Environment</title>
+
+      <para>Make sure you have both <filename role='package'>emulators/linux_base</filename> and
+	<filename role='package'>devel/linux_devtools</filename> from the Ports Collection
+	installed.  If you run into difficulties with these ports,
+	you may have to use
+	the packages or older versions available in the Ports Collection.</para>
+
+      <para>If you want to run the intelligent agent, you will
+	also need to install the Red Hat Tcl package:
+	<filename>tcl-8.0.3-20.i386.rpm</filename>.  The general command
+	for installing packages with the official <application>RPM</application> port (<filename role='package'>archivers/rpm</filename>) is:</para>
+
+      <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
+
+      <para>Installation of the <replaceable>package</replaceable> should not generate any errors.</para>
+    </sect2>
+
+    <sect2>
+      <title>Creating the &oracle; Environment</title>
+
+      <para>Before you can install <application>&oracle;</application>, you need to set up a proper
+	environment.  This document only describes what to do
+	<emphasis>specially</emphasis> to run <application>&oracle;</application> for Linux on FreeBSD, not
+	what has been described in the <application>&oracle;</application> installation guide.</para>
+
+      <sect3 id="linuxemu-kernel-tuning">
+        <title>Kernel Tuning</title>
+	<indexterm><primary>kernel tuning</primary></indexterm>
+
+	<para>As described in the <application>&oracle;</application> installation guide, you need to set
+	  the maximum size of shared memory.  Do not use
+	  <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal>
+	  is merely calculated out of <literal>SHMMAXPGS</literal> and
+	  <literal>PGSIZE</literal>.  Therefore define
+	  <literal>SHMMAXPGS</literal>.  All other options can be used as
+	  described in the guide.  For example:</para>
+
+	<programlisting>options SHMMAXPGS=10000
+options SHMMNI=100
+options SHMSEG=10
+options SEMMNS=200
+options SEMMNI=70
+options SEMMSL=61</programlisting>
+
+	<para>Set these options to suit your intended use of <application>&oracle;</application>.</para>
+
+	<para>Also, make sure you have the following options in your kernel
+	  configuration file:</para>
+
+<programlisting>options SYSVSHM #SysV shared memory
+options SYSVSEM #SysV semaphores
+options SYSVMSG #SysV interprocess communication</programlisting>
+      </sect3>
+
+      <sect3 id="linuxemu-oracle-account">
+
+        <title>&oracle; Account</title>
+
+	<para>Create an <username>oracle</username> account just as you would create any other
+	  account. The  <username>oracle</username> account is special only that you need to give
+	  it a Linux shell.  Add <literal>/compat/linux/bin/bash</literal> to
+	  <filename>/etc/shells</filename> and set the shell for the <username>oracle</username>
+	  account to <filename>/compat/linux/bin/bash</filename>.</para>
+      </sect3>
+
+      <sect3 id="linuxemu-environment">
+        <title>Environment</title>
+
+	<para>Besides the normal <application>&oracle;</application> variables, such as
+	  <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must
+	  set the following environment variables:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+          <colspec colwidth="1*"/>
+          <colspec colwidth="2*"/>
+	    <thead>
+	      <row>
+		<entry>Variable</entry>
+
+		<entry>Value</entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+		<entry><envar>LD_LIBRARY_PATH</envar></entry>
+
+		<entry><literal>$ORACLE_HOME/lib</literal></entry>
+	      </row>
+
+	      <row>
+		<entry><envar>CLASSPATH</envar></entry>
+
+		<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
+	      </row>
+
+	      <row>
+		<entry><envar>PATH</envar></entry>
+
+		<entry><literal>/compat/linux/bin
+/compat/linux/sbin
+/compat/linux/usr/bin
+/compat/linux/usr/sbin
+/bin
+/sbin
+/usr/bin
+/usr/sbin
+/usr/local/bin
+$ORACLE_HOME/bin</literal></entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+
+        <para>It is advised to set all the environment variables in
+	  <filename>.profile</filename>.  A complete example is:</para>
+
+<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
+ORACLE_HOME=/oracle; export ORACLE_HOME
+LD_LIBRARY_PATH=$ORACLE_HOME/lib
+export LD_LIBRARY_PATH
+ORACLE_SID=ORCL; export ORACLE_SID
+ORACLE_TERM=386x; export ORACLE_TERM
+CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
+export CLASSPATH
+PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
+PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
+PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
+export PATH</programlisting>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Installing &oracle;</title>
+
+      <para>Due to a slight inconsistency in the Linux emulator, you need to
+	create a directory named <filename>.oracle</filename> in
+	<filename>/var/tmp</filename> before you start the installer.
+	Let it be owned by the <username>oracle</username> user.  You
+	should be able to install <application>&oracle;</application> without any problems.  If you have
+	problems, check your <application>&oracle;</application> distribution and/or configuration first!
+	After you have installed <application>&oracle;</application>, apply the patches described in the
+	next two subsections.</para>
+
+      <para>A frequent problem is that the TCP protocol adapter is not
+	installed right. As a consequence, you cannot start any TCP listeners.
+	The following actions help solve this problem:</para>
+
+      <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
+&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
+&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
+&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
+&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
+&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>
+
+      <para>Do not forget to run <filename>root.sh</filename> again!</para>
+
+    <sect3 id="linuxemu-patch-root">
+      <title>Patching root.sh</title>
+
+	<para>When installing <application>&oracle;</application>, some actions, which need to be performed
+	  as <username>root</username>, are recorded in a shell script called
+	  <filename>root.sh</filename>.  This script is
+	  written in the <filename>orainst</filename> directory.  Apply the
+	  following patch to <filename>root.sh</filename>, to have it use to proper location of
+	  <command>chown</command> or alternatively run the script under a
+	  Linux native shell.</para>
+
+	<programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
+--- orainst/root.sh Mon Dec 28 15:58:53 1998
+***************
+*** 31,37 ****
+# This is the default value for CHOWN
+# It will redefined later in this script for those ports
+# which have it conditionally defined in ss_install.h
+! CHOWN=/bin/chown
+#
+# Define variables to be used in this script
+--- 31,37 ----
+# This is the default value for CHOWN
+# It will redefined later in this script for those ports
+# which have it conditionally defined in ss_install.h
+! CHOWN=/usr/sbin/chown
+#
+# Define variables to be used in this script</programlisting>
+
+	<para>When you do not install <application>&oracle;</application> from CD, you can patch the source
+	  for <filename>root.sh</filename>.  It is called
+	  <filename>rthd.sh</filename> and is located in the
+	  <filename>orainst</filename> directory in the source tree.</para>
+      </sect3>
+
+      <sect3 id="linuxemu-patch-tcl">
+	<title>Patching genclntsh</title>
+
+	<para>The script <command>genclntsh</command> is used to create
+	  a single shared client
+	  library.  It is used when building the demos.  Apply the following
+	  patch to comment out the definition of <envar>PATH</envar>:</para>
+
+	<programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
+--- bin/genclntsh Tue Dec 22 15:36:49 1998
+***************
+*** 32,38 ****
+#
+# Explicit path to ensure that we're using the correct commands
+#PATH=/usr/bin:/usr/ccs/bin export PATH
+! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
+#
+# each product MUST provide a $PRODUCT/admin/shrept.lst
+--- 32,38 ----
+#
+# Explicit path to ensure that we're using the correct commands
+#PATH=/usr/bin:/usr/ccs/bin export PATH
+! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
+#
+# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Running &oracle;</title>
+
+      <para>When you have followed the instructions, you should be able to run
+	<application>&oracle;</application> as if it was run on Linux
+	itself.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="linuxemu-advanced">
+    <title>Advanced Topics</title>
+
+    <para>If you are curious as to how the Linux binary compatibility
+      works, this is the section you want to read.  Most of what follows
+      is based heavily on an email written to &a.chat; by Terry Lambert
+      <email>tlambert@primenet.com</email> (Message ID:
+      <literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>
+
+    <sect2>
+      <title>How Does It Work?</title>
+      <indexterm><primary>execution class loader</primary></indexterm>
+
+      <para>FreeBSD has an abstraction called an <quote>execution class
+	loader</quote>.  This is a wedge into the &man.execve.2; system
+	call.</para>
+
+      <para>What happens is that FreeBSD has a list of loaders, instead of
+	a single loader with a fallback to the <literal>#!</literal>
+	loader for running any shell interpreters or shell scripts.</para>
+
+      <para>Historically, the only loader on the &unix; platform examined
+	the magic number (generally the first 4 or 8 bytes of the file) to
+	see if it was a binary known to the system, and if so, invoked the
+	binary loader.</para>
+
+      <para>If it was not the binary type for the system, the
+	&man.execve.2; call returned a failure, and the shell attempted to
+	start executing it as shell commands.</para>
+
+      <para>The assumption was a default of <quote>whatever the current
+	shell is</quote>.</para>
+
+      <para>Later, a hack was made for &man.sh.1; to examine the first two
+	characters, and if they were <literal>:\n</literal>, then it
+	invoked the &man.csh.1; shell instead (we believe SCO first made
+	this hack).</para>
+
+      <para>What FreeBSD does now is go through a list of loaders, with a
+	generic <literal>#!</literal> loader that knows about interpreters
+	as the characters which follow to the next whitespace next to
+	last, followed by a fallback to
+	<filename>/bin/sh</filename>.</para>
+      <indexterm><primary>ELF</primary></indexterm>
+
+      <para>For the Linux ABI support, FreeBSD sees the magic number as an
+	ELF binary (it makes no distinction between FreeBSD, &solaris;,
+	Linux, or any other OS which has an ELF image type, at this
+	point).</para>
+      <indexterm><primary>Solaris</primary></indexterm>
+
+      <para>The ELF loader looks for a specialized
+	<emphasis>brand</emphasis>, which is a comment section in the ELF
+	image, and which is not present on SVR4/&solaris; ELF
+	binaries.</para>
+
+      <para>For Linux binaries to function, they must be
+	<emphasis>branded</emphasis> as type <literal>Linux</literal>
+	from &man.brandelf.1;:</para>
+
+      <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
+
+      <para>When this is done, the ELF loader will see the
+	<literal>Linux</literal> brand on the file.</para>
+      <indexterm>
+        <primary>ELF</primary>
+	<secondary>branding</secondary>
+      </indexterm>
+
+      <para>When the ELF loader sees the <literal>Linux</literal> brand,
+	the loader replaces a pointer in the <literal>proc</literal>
+	structure.  All system calls are indexed through this pointer (in
+	a traditional &unix; system, this would be the
+	<literal>sysent[]</literal> structure array, containing the system
+	calls).  In addition, the process is flagged for special handling of
+	the trap vector for the signal trampoline code, and several other
+	(minor) fix-ups that are handled by the Linux kernel
+	module.</para>
+
+      <para>The Linux system call vector contains, among other things, a
+	list of <literal>sysent[]</literal> entries whose addresses reside
+	in the kernel module.</para>
+
+      <para>When a system call is called by the Linux binary, the trap
+	code dereferences the system call function pointer off the
+	<literal>proc</literal> structure, and gets the Linux, not the
+	FreeBSD, system call entry points.</para>
+
+      <para>In addition, the Linux mode dynamically
+	<emphasis>reroots</emphasis> lookups; this is, in effect, what the
+	<option>union</option> option to file system mounts
+	(<emphasis>not</emphasis> the <literal>unionfs</literal> file system type!) does.  First, an attempt
+	is made to lookup the file in the
+	<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
+	directory, <emphasis>then</emphasis> only if that fails, the
+	lookup is done in the
+	<filename>/<replaceable>original-path</replaceable></filename>
+	directory.  This makes sure that binaries that require other
+	binaries can run (e.g., the Linux toolchain can all run under
+	Linux ABI support).  It also means that the Linux binaries can
+	load and execute FreeBSD binaries, if there are no corresponding
+	Linux binaries present, and that you could place a &man.uname.1;
+	command in the <filename>/compat/linux</filename> directory tree
+	to ensure that the Linux binaries could not tell they were not
+	running on Linux.</para>
+
+      <para>In effect, there is a Linux kernel in the FreeBSD kernel; the
+	various underlying functions that implement all of the services
+	provided by the kernel are identical to both the FreeBSD system
+	call table entries, and the Linux system call table entries: file
+	system operations, virtual memory operations, signal delivery,
+	System V IPC, etc&hellip;  The only difference is that FreeBSD
+	binaries get the FreeBSD <emphasis>glue</emphasis> functions, and
+	Linux binaries get the Linux <emphasis>glue</emphasis> functions
+	(most older OS's only had their own <emphasis>glue</emphasis>
+	functions: addresses of functions in a static global
+	<literal>sysent[]</literal> structure array, instead of addresses
+	of functions dereferenced off a dynamically initialized pointer in
+	the <literal>proc</literal> structure of the process making the
+	call).</para>
+
+      <para>Which one is the native FreeBSD ABI?  It does not matter.
+	Basically the only difference is that (currently; this could
+	easily be changed in a future release, and probably will be after
+	this) the FreeBSD <emphasis>glue</emphasis> functions are
+	statically linked into the kernel, and the Linux <emphasis>glue</emphasis> functions
+	can be statically linked, or they can be accessed via a kernel
+	module.</para>
+
+      <para>Yeah, but is this really emulation?  No.  It is an ABI
+	implementation, not an emulation.  There is no emulator (or
+	simulator, to cut off the next question) involved.</para>
+
+      <para>So why is it sometimes called <quote>Linux emulation</quote>?
+	To make it hard to sell FreeBSD!  Really, it
+	is because the historical implementation was done at a time when
+	there was really no word other than that to describe what was
+	going on; saying that FreeBSD ran Linux binaries was not true, if
+	you did not compile the code in or load a module, and there needed
+	to be a word to describe what was being loaded&mdash;hence
+	<quote>the Linux emulator</quote>.</para>
+    </sect2>
+  </sect1>
+</chapter>