Basic compat_aout explanations.

A few nits from jmc@
okay miod@

1 files changed, 89 insertions, 0 deletions

diff --git a/share/man/man8/compat_aout.8 b/share/man/man8/compat_aout.8
new file mode 100644
index 00000000000..380c4491e64
--- /dev/null
+++ b/share/man/man8/compat_aout.8
@@ -0,0 +1,89 @@
+.\"	$OpenBSD: compat_aout.8,v 1.1 2003/06/29 10:54:05 espie Exp $
+.\"
+.\" Copyright (c) 2003 Marc Espie
+.\"
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd June 25, 2003
+.Dt COMPAT_AOUT 8
+.Os
+.Sh NAME
+.Nm compat_aout
+.Nd setup for running a.out OpenBSD binaries on ELF systems under emulation
+.Sh DESCRIPTION
+.Ox
+supports running legacy a.out binaries.
+This only applies to i386 systems for now.
+Most programs should work.
+.Pp
+The a.out compatibility feature is active
+for kernels compiled with the
+.Nm COMPAT_AOUT
+option enabled.
+.Pp
+A lot of programs are dynamically linked.
+This means that the shared libraries that the programs depend on
+and the runtime linker are also needed.
+A "shadow root" directory for these files
+on the
+.Ox
+system will have to be created.
+This directory is named
+.Pa /emul/a.out .
+Selected file operations done by legacy a.out programs run under
+.Ox
+will look in this directory first.
+.Ss Setting up shared libraries
+Up until
+.Ox 3.3 ,
+programs were using the a.out file format.
+When migrating to a current ELF system,
+some old binaries may still be used.
+Before installing a current system, all the necessary shared libraries
+in the
+.Pa /usr/lib ,
+.Pa /usr/X11R6/lib ,
+.Pa /usr/local/lib
+and the a.out dynamic linker system, namely
+.Pa /usr/libexec/ld.so ,
+.Pa /usr/bin/ldd ,
+and
+.Pa /sbin/ldconfig
+should be copied to the corresponding location in the shadow tree.
+(e.g., copy
+.Pa /sbin/ldconfig
+into
+.Pa /emul/a.out/sbin/ldconfig ) .
+The directory
+.Pa /emul/a.out/var/run
+should also be created.
+.Pp
+Before running a.out binaries, the
+.Nm ld.so
+cache must be prepared, by running
+.Pa /emul/a.out/sbin/ldconfig .
+.Pp
+Once everything is set up properly, a.out programs will look for shared
+libraries under
+.Pa /emul/a.out
+and ELF programs will not see the a.out shared libraries.