.\"	$OpenBSD: compat_aout.8,v 1.4 2007/05/31 19:19:58 jmc 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 $Mdocdate: May 31 2007 $
.Dt COMPAT_AOUT 8
.Os
.Sh NAME
.Nm compat_aout
.Nd setup for running a.out OpenBSD binaries on ELF systems
.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 and kern.emul.aout
.Xr sysctl 8
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.