Index: head/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml	(revision 47090)
+++ head/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml	(revision 47091)
@@ -1,1240 +1,1240 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 <chapter xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:id="linuxemu">
 
   <info>
     <title>&linux; Binary Compatibility</title>
 
     <authorgroup>
       <author>
 	<personname>
 	  <firstname>Jim</firstname>
 	  <surname>Mock</surname>
 	</personname>
 	<contrib>Restructured and parts updated by </contrib>
       </author>
       <!-- 22 Mar 2000 -->
     </authorgroup>
 
     <authorgroup>
       <author>
 	<personname>
 	  <firstname>Brian N.</firstname>
 	  <surname>Handy</surname>
 	</personname>
 	<contrib>Originally contributed by </contrib>
       </author>
 
       <author>
 	<personname>
 	  <firstname>Rich</firstname>
 	  <surname>Murphey</surname>
 	</personname>
       </author>
     </authorgroup>
   </info>
 
   <sect1 xml:id="linuxemu-synopsis">
     <title>Synopsis</title>
 
     <indexterm>
       <primary>Linux binary compatibility</primary>
     </indexterm>
     <indexterm>
       <primary>binary compatibility</primary>
       <secondary>Linux</secondary>
     </indexterm>
 
     <para>&os; provides 32-bit binary compatibility with &linux;,
       allowing users to install and run most 32-bit &linux; binaries
       on a &os; system without having to first modify the binary.  It
       has even been reported that, in some situations, 32-bit &linux;
       binaries perform better on &os; than they do on &linux;.</para>
 
     <para>However, some &linux;-specific operating system features
       are not supported under &os;.  For example, &linux; binaries
       will not work on &os; if they overly use &i386; specific calls,
       such as enabling virtual 8086 mode.  In addition, 64-bit &linux;
       binaries are not supported at this time.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to enable &linux; binary compatibility on a &os;
 	  system.</para>
       </listitem>
 
       <listitem>
 	<para>How to install additional &linux; shared
 	  libraries.</para>
       </listitem>
 
       <listitem>
 	<para>How to install &linux; applications on a &os;
 	  system.</para>
       </listitem>
 
       <listitem>
 	<para>The implementation details of &linux; compatibility in
 	  &os;.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Know how to install <link linkend="ports">additional
 	    third-party software</link>.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 xml:id="linuxemu-lbc-install">
     <title>Configuring &linux; Binary Compatibility</title>
 
     <indexterm><primary>Ports Collection</primary></indexterm>
 
     <para>By default, &linux; libraries are not installed and &linux;
       binary compatibility is not enabled.  &linux; libraries can
       either be installed manually or from the &os; Ports
       Collection.</para>
 
     <para>Before attempting to build the port, load the &linux; kernel
       module, otherwise the build will fail:</para>
 
     <screen>&prompt.root; <userinput>kldload linux</userinput></screen>
 
     <para>To verify that the module 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>
 
     <para>The <package>emulators/linux_base-c6</package> package or
       port is the easiest way to install a base set of &linux;
       libraries and binaries on a &os; system.  To install the
       port:</para>
 
-  <screen>&prompt.root; <userinput>printf "compat.linux.osrelease=2.6.18\n" >> /etc/sysctl.conf</userinput>
+    <screen>&prompt.root; <userinput>printf "compat.linux.osrelease=2.6.18\n" >> /etc/sysctl.conf</userinput>
 &prompt.root; <userinput>sysctl compat.linux.osrelease=2.6.18</userinput>
 &prompt.root; <userinput>pkg install emulators/linux_base-c6</userinput></screen>
 
     <para>For &linux; compatibility to be enabled at boot time,
       add this line to <filename>/etc/rc.conf</filename>:</para>
 
     <programlisting>linux_enable="YES"</programlisting>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>COMPAT_LINUX</secondary>
     </indexterm>
 
     <para>Users who prefer to statically link &linux; binary
       compatibility into a custom kernel should add
       <literal>options COMPAT_LINUX</literal> to their custom kernel
       configuration file.  Compile and install the new kernel as
       described in <xref linkend="kernelconfig"/>.</para>
 
     <sect2 xml:id="linuxemu-libs-manually">
       <title>Installing Additional Libraries Manually</title>
 
       <indexterm>
 	<primary>shared libraries</primary>
       </indexterm>
 
       <para>If a &linux; application complains about missing shared
 	libraries after configuring &linux; binary compatibility,
 	determine which shared libraries the &linux; binary needs and
 	install them manually.</para>
 
       <para>From a &linux; system, <command>ldd</command> can be used
 	to determine which shared libraries the application needs.
 	For example, to check which shared libraries
 	<command>linuxdoom</command> needs, run this command from a
 	&linux; system that has <application>Doom</application>
 	installed:</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>Then, copy all the files in the last column of the output
 	from the &linux; system into
 	<filename>/compat/linux</filename> on the &os; system.  Once
 	copied, create symbolic links to the names in the first
 	column.  This example will result in the following files on
 	the &os; 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>
 
       <para>If a &linux; shared library already exists with a
 	matching major revision number to the first column of the
 	<command>ldd</command> output, it does not need to be copied
 	to the file named in the last column, as the existing library
 	should work.  It is advisable to copy the shared library if it
 	is a newer version, though.  The old one can be removed, as
 	long as the symbolic link points to the new one.</para>
 
       <para>For example, these libraries already exist on the &os;
 	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 <command>ldd</command> indicates that a binary
 	requires a later version:</para>
 
       <screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
 
       <para>Since the existing library is only one or two versions out
 	of date in the last digit, the program should still work with
 	the slightly older version.  However, it is safe to replace
 	the existing <filename>libc.so</filename> with the newer
 	version:</para>
 
       <screen>/compat/linux/lib/libc.so.4.6.29
 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
 
       <para>Generally, one will need to look for the shared libraries
 	that &linux; binaries depend on only the first few times that
 	a &linux; program is installed on &os;.  After a while, there
 	will be a sufficient set of &linux; shared libraries on the
 	system to be able to run newly installed &linux; binaries
 	without any extra work.</para>
     </sect2>
 
     <sect2>
       <title>Installing &linux; <acronym>ELF</acronym>
 	Binaries</title>
 
       <indexterm>
 	<primary>Linux</primary>
 	<secondary>ELF binaries</secondary>
       </indexterm>
 
       <para><acronym>ELF</acronym> binaries sometimes require an extra
 	step.  When an unbranded <acronym>ELF</acronym> binary is
 	executed, it will generate an error message:</para>
 
       <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
 ELF binary type not known
 Abort</screen>
 
       <para>To help the &os; kernel distinguish between a &os;
 	<acronym>ELF</acronym> binary and a &linux; binary, use
 	&man.brandelf.1;:</para>
 
       <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
 
       <indexterm>
 	<primary>GNU toolchain</primary>
       </indexterm>
 
       <para>Since the GNU toolchain places the appropriate branding
 	information into <acronym>ELF</acronym> binaries
 	automatically, this step is usually not necessary.</para>
     </sect2>
 
     <sect2>
       <title>Installing a &linux; <acronym>RPM</acronym> Based
 	Application</title>
 
       <para>In order to install a &linux; <acronym>RPM</acronym>-based
 	application, first install the
 	<package>archivers/rpm</package> package or port.  Once
 	installed, <systemitem class="username">root</systemitem> can
 	use this command to install a
 	<filename>.rpm</filename>:</para>
 
       <screen>&prompt.root; <userinput>cd /compat/linux</userinput>
 &prompt.root; <userinput>rpm2cpio &lt; /path/to/linux.archive.rpm | cpio -id</userinput></screen>
 
       <para>If necessary, <command>brandelf</command> the installed
 	<acronym>ELF</acronym> binaries.  Note that this will prevent
 	a clean uninstall.</para>
     </sect2>
 
     <sect2>
       <title>Configuring the Hostname Resolver</title>
 
       <para>If <acronym>DNS</acronym> does not work or this error
 	appears:</para>
 
       <screen>resolv+: "bind" is an invalid keyword resolv+:
 "hosts" is an invalid keyword</screen>
 
       <para>configure <filename>/compat/linux/etc/host.conf</filename>
 	as follows:</para>
 
       <programlisting>order hosts, bind
 multi on</programlisting>
 
       <para>This specifies that <filename>/etc/hosts</filename> is
 	searched first and <acronym>DNS</acronym> is searched second.
 	When <filename>/compat/linux/etc/host.conf</filename> does not
 	exist, &linux; applications use
 	<filename>/etc/host.conf</filename> and complain about the
 	incompatible &os; syntax.  Remove <literal>bind</literal> if a
 	name server is not configured using
 	<filename>/etc/resolv.conf</filename>.</para>
     </sect2>
   </sect1>
 
   <?ignore
 
   While the installer works, the binaries do not.  As of Oct 2013,
   Linux emulation is 32-bit but the trial version of Mathematica is
   only available as 64-bit.  This section should be revisited if Linux
   emulation gets 64-bit binary support.
 
   <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 section describes the process of installing the &linux;
       version of <application>&mathematica; 9.X</application> onto a
       &os; system.  <application>&mathematica;</application> is a
       commercial, computational software program used in scientific,
       engineering, and mathematical fields.  A 30 day trial version is
       available for download from <ulink
 	url="http://www.wolfram.com/mathematica/">wolfram.com/mathematica</ulink>.</para>
 
     <sect2>
       <title>Running the &mathematica; Installer</title>
 
       <para>Before installing &mathematica;, make sure that the
 	<filename role="package">textproc/linux-c6-aspell</filename>
 	package or port is installed and that the &man.linprocfs.5;
 	file system is mounted.</para>
 
       <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>
 
       <para>&os; will now assume that unbranded ELF binaries use the
 	&linux; <acronym>ABI</acronym> which should allow the
 	installer to execute from the CDROM.</para>
 
       <para>The downloaded file will be saved to
 	<filename>/tmp/Mathematica_9.0.1_LINUX.sh</filename>.  Become
 	the superuser and run this installer file:</para>
 
       <programlisting>&prompt.root; <userinput>sh /tmp/Mathematica_9.0.1_LINUX.sh</userinput>
 Mathematica Secured 9.0.1 for LINUX Installer Archive
 
 Verifying archive integrity.
 Extracting installer. ...
                                Wolfram Mathematica 9 Installer
 Copyright (c) 1988-2013 Wolfram Research, Inc. All rights reserved.
 
 WARNING: Wolfram Mathematica is protected by copyright law and international treaties. Unauthorized
 reproduction or distribution may result in severe civil and criminal
 penalties and will be prosecuted to the maximum extent possible under law.
 
 Enter the installation directory, or press ENTER to select /usr/local/Wolfram/Mathematica/9.0:
 >
 Now installing...
 ***********************
 Installation complete.</programlisting>
     </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.  <application>Xorg</application> requires these
 	fonts to be installed locally.  This means that these fonts
 	need to be copied from the CDROM or from a host with
 	<application>&mathematica;</application> installed to the
 	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 the 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 the fonts into one of the
 	existing font directories in <filename
 	  >/usr/local/lib/X11/fonts</filename> then
 	running &man.mkfontdir.1; within the directory containing the
 	new fonts.</para>
 
       <para>The second way to do this is to copy the directories to
 	<filename
 	  >/usr/local/lib/X11/fonts</filename>:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/local/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/local/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>cp Type1/* /usr/local/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>cd /usr/local/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 the font path:</para>
 
       <screen>&prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>xset fp rehash</userinput></screen>
 
       <para>When using the <application>&xorg;</application> server,
 	these font directories can be loaded automatically by adding
 	them to <filename>/etc/X11/xorg.conf</filename>.</para>
 
       <indexterm><primary>fonts</primary></indexterm>
 
       <para>If <filename
 	  >/usr/local/lib/X11/fonts/Type1</filename>
 	does not already exist, change the name of the <filename
 	  >MathType1</filename> directory in the
 	example above to <filename
 	  >Type1</filename>.</para>
     </sect2>
   </sect1>
   -->
 
   <!--
   As of October 2013, the trial version is only available in the
   Professional and Academic editions (not the Student or Personal
   editions) and requires a contact with a product specialist before
   the evaluation download link is made available.
   <sect1 id="linuxemu-maple">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Aaron</firstname>
 	  <surname>Kaplan</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Robert</firstname>
 	  <surname>Getschmann</surname>
 	  <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>.  This software must be
       purchased and licensed from <ulink
 	url="http://www.maplesoft.com/products/maple/">Maplesoft</ulink>.
       To install the &linux; version of this software on &os;, follow
       these 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
 	  >/usr/local/maple</filename>.</para></step>
 
       <step>
 	<para>Copy the license 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 the machine for the license server.</para>
       </step>
 
       <step>
 	<para>Patch
 	  <filename>/usr/local/maple/bin/maple.system.type</filename>
 	  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>Note that no whitespace should be present after
 	  <literal>"FreeBSD"|\</literal>.</para>
 
 	<para>This patch instructs <application>&maple;</application>
 	  to recognize &os; 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/rtc/rc.d/lmgrd</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
 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 that <application>&maple;</application>
 	  starts:</para>
 
 	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
 &prompt.user; <userinput>./xmaple</userinput></screen>
 
 	<para>Once everything is working, consider writing Maplesoft
 	  to let them know you would like a native &os;
 	  version!</para>
       </step>
     </procedure>
 
     <sect2>
       <title>Common Pitfalls</title>
 
       <itemizedlist>
 	<listitem>
 	  <para><command>lmgrd</command> is known to be picky about
 	    the license file and to dump core 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>In this example, the serial number and key were
 	      replaced with <literal>X</literal>.
 	      <hostid>chillig</hostid> is the hostname.</para>
 	  </note>
 
 	  <para>Editing the license file works as long as the
 	    <quote>FEATURE</quote> line is not edited.  That line is
 	    protected by the license key.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
   -->
   <!--
   As of October, 2013, the Linux version of Matlab is only available
   for 64-bit.
 
   <sect1 id="linuxemu-matlab">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Dan</firstname>
 	  <surname>Pelleg</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </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> which is
       described further in <xref linkend="matlab-jre"/>.</para>
 
     <para>The &linux; version of <application>&matlab;</application>
       can be purchased and licensed from <ulink
 	url="http://www.mathworks.com/products/matlab/">
 	MathWorks</ulink>.  Consider letting the company know that
       you would like a native &os; version of this software.</para>
 
     <sect2>
       <title>Installing &matlab;</title>
 
       <para>To install <application>&matlab;</application>:</para>
 
       <procedure>
 	<step>
 	  <para>Become <username>root</username>, as recommended by
 	    the installation script.  Insert the installation CD and
 	    mount it.  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 it is not able to
 	      open a display, type <command>setenv HOME
 		~<replaceable>USER</replaceable></command>,
 	      where <replaceable>USER</replaceable> is the user who
 	      ran &man.su.1;.</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 the 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>This file can be prepared in advance using an
 	      editor, and copied to
 	      <filename>$MATLAB/license.dat</filename> before the
 	      installer asks to edit it.</para>
 	  </tip>
 	</step>
 
 	<step>
 	  <para>Complete the installation process.</para>
 	</step>
       </procedure>
 
       <para>At this point the <application>&matlab;</application>
 	installation is complete.  The following steps apply
 	<quote>glue</quote> to connect it to the &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 named
 	    <filename>/usr/local/etc/rc.d/flexlm</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</userinput></screen>
 
 	    <para>Replace <replaceable>username</replaceable> with the
 	      name of a valid user on the system which is not
 	      <username>root</username>.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <para>Start the license manager with the command:</para>
 
 	  <screen>&prompt.root; <userinput>service flexlm 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 (<acronym>JRE</acronym>) 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 the version of
 	  <filename role="package">emulators/linux_base</filename>,
 	  running this script may result in errors.  To avoid errors,
 	  edit
 	  <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>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
 	    <filename>$MATLAB/toolbox/local/finish.m</filename>
 	    containing the single line:</para>
 
 	  <programlisting>! $MATLAB/bin/finish.sh</programlisting>
 
 	  <note>
 	    <para>The <literal>$MATLAB</literal> is literal.</para>
 	  </note>
 
 	  <tip>
 	    <para>The same directory contains
 	      <filename>finishsav.m</filename> and
 	      <filename>finishdlg.m</filename>, which allow the
 	      workspace to be saved before quitting.  If either file
 	      is used, insert the line above immediately after the
 	      <literal>save</literal> command.</para>
 	  </tip>
 	</step>
 
 	<step>
 	  <para>Create <filename>$MATLAB/bin/finish.sh</filename>
 	    which contains the following:</para>
 
 	  <programlisting>#!/compat/linux/bin/sh
 (sleep 5; killall -1 matlab_helper) &amp;
 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, <command>matlab</command> is ready for
 	use.</para>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-oracle">
     While the Oracle website is unclear, the installation script is:
     You are attempting to install 64-bit Oracle on a 32-bit operating
     system.  This is not supported and will not work.
 
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Marcel</firstname>
 	  <surname>Moolenaar</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Installing &oracle;</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Oracle</application></secondary>
     </indexterm>
 
     <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 &os; machine.</para>
 
     <sect2>
       <title>Installing the &linux; Environment</title>
 
       <para>Make sure <filename
 	  role='package'>emulators/linux_base</filename>
 	has been installed from the Ports Collection.</para>
 
       <para>To run the intelligent agent, install the Red Hat Tcl
 	package:  <filename>tcl-8.0.3-20.i386.rpm</filename>.  The
 	general command for installing RPMs with the
 	<filename role='package'>archivers/rpm</filename> port
 	is:</para>
 
       <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
 
       <para>This command should not generate any errors.</para>
     </sect2>
 
     <sect2>
       <title>Creating the &oracle; Environment</title>
 
       <para>Before installing <application>&oracle;</application>, set
 	up a proper environment.  This section only describes how to
 	install <application>&oracle;</application> for &linux; on
 	&os;, 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, the maximum size of shared memory needs
 	  to be set.  Do not use <literal>SHMMAX</literal> under &os;
 	  as it is calculated from <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 the intended use of
 	  <application>&oracle;</application>.</para>
 
 	<para>Also, make sure the following options are in the
 	  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 a user account to be used as the
 	  <username>oracle</username> account.  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> 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> as follows:</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>Before starting the installer, create a directory named
 	<filename>/var/tmp/.oracle</filename> which
 	is owned by the <username>oracle</username> user.  The
 	installation of <application>&oracle;</application> should
 	work without any problems.  If errors are encountered, check
 	the <application>&oracle;</application> distribution and
 	configuration.  Once <application>&oracle;</application> is
 	installed, apply the patches described in the next two
 	subsections.</para>
 
       <para>A frequent error is that the TCP protocol adapter is not
 	installed correctly.  As a consequence, no TCP listeners can
 	be started.  The following actions help to 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 <filename>root.sh</filename></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
 	found in <filename>orainst</filename>.
 	Apply the following patch to <filename>root.sh</filename>
 	so that it can find the &os; location of
 	<command>chown</command>.  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>If <application>&oracle;</application> is not installed
 	from CD, patch the source for <filename>root.sh</filename>.
 	It is called <filename>rthd.sh</filename> and is located in
 	<filename>orainst</filename> in the source
 	tree.</para>
     </sect3>
 
     <sect3 id="linuxemu-patch-tcl">
       <title>Patching <filename>genclntsh</filename></title>
 
       <para>The script <command>genclntsh</command> is used to create
 	a single shared client library 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 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: export PATH
 #
 # each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running &oracle;</title>
 
       <para>After following these instructions,
 	<application>&oracle;</application> should run as if it was
 	running on &linux;.</para>
     </sect2>
   </sect1>
   ?>
 
   <sect1 xml:id="linuxemu-advanced">
     <title>Advanced Topics</title>
 
     <para>This section describes how &linux; binary compatibility
       works and is based 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>
 
     <indexterm><primary>execution class loader</primary></indexterm>
 
     <para>&os; has an abstraction called an
       <quote>execution class loader</quote>.  This is a wedge into the
       &man.execve.2; system call.</para>
 
     <para>Historically, the &unix; loader 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.  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>, it
       invoked the &man.csh.1; shell instead.</para>
 
     <para>&os; has a list of loaders, instead of a single loader, with
       a fallback to the <literal>#!</literal> loader for running shell
       interpreters or shell scripts.</para>
 
     <indexterm>
       <primary>ELF</primary>
     </indexterm>
 
     <indexterm>
       <primary>Solaris</primary>
     </indexterm>
 
     <para>For the &linux; <acronym>ABI</acronym> support, &os; sees
       the magic number as an ELF binary.  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>
       using &man.brandelf.1;:</para>
 
     <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
 
     <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 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
       &os;, system call entry points.</para>
 
     <para>&linux; mode dynamically <emphasis>reroots</emphasis>
       lookups.  This is, in effect, equivalent to the
       <option>union</option> option to file system mounts.  First, an
       attempt is made to lookup the file in <filename
 	>/compat/linux/<replaceable>original-path</replaceable></filename>.
       If that fails, the lookup is done in <filename
 	>/<replaceable>original-path</replaceable></filename>.
       This makes sure that binaries that require other binaries can
       run.  For example, the &linux; toolchain can all run under
       &linux; <acronym>ABI</acronym> support.  It also means that the
       &linux; binaries can load and execute &os; binaries, if there
       are no corresponding &linux; binaries present, and that a
       &man.uname.1; command can be placed in the
       <filename>/compat/linux</filename> directory tree to ensure that
       the &linux; binaries can not tell they are not running on
       &linux;.</para>
 
     <para>In effect, there is a &linux; kernel in the &os; kernel.
       The various underlying functions that implement all of the
       services provided by the kernel are identical to both the &os;
       system call table entries, and the &linux; system call table
       entries: file system operations, virtual memory operations,
       signal delivery, and System V IPC.  The only difference is that
       &os; binaries get the &os; <emphasis>glue</emphasis> functions,
       and &linux; binaries get the &linux; <emphasis>glue</emphasis>
       functions.  The &os; <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>Technically, this is not really emulation, it is an
       <acronym>ABI</acronym> implementation.  It is sometimes called
       <quote>&linux; emulation</quote> because the implementation was
       done at a time when there was no other word to describe what was
       going on.  Saying that &os; ran &linux; binaries was not true,
       since the code was not compiled in.</para>
   </sect1>
 </chapter>