NAME

       svr4 — System V Release 4 ABI support

SYNOPSIS

       To  compile  support  for this ABI into the kernel, place the following line in your kernel configuration
       file:

             options COMPAT_SVR4

       Alternatively, to load the ABI as a module at boot time, place the following line in loader.conf(5):

             svr4_load="YES"

DESCRIPTION

       The svr4 module provides limited System V Release 4 ABI (application binary interface) compatibility  for
       userland applications.  The module provides the following significant facilities:

       •   An image activator for correctly branded elf(5) executable images

       •   Special signal handling for activated images

       •   SVR4 to native system call translation

       •   STREAMS network API emulation (via the streams(4) loadable module, or by means of
                 device streams
           in a kernel configuration file)

       •   Mappings  between  FreeBSD  and  SVR4  ioctl(2)  calls,  or,  where  no such mappings exist, reverse-
           engineered implementations of the SVR4 calls.

       It is important to note that the SVR4 ABI support it not provided through an emulator.   Rather,  a  true
       (albeit limited) "clean room" reverse-engineered ABI implementation is provided.

LIMITATIONS

       Because  the  provided ABI has been developed in ignorance of actual SVR4 source code, there are bound to
       be unforeseen interactions between SVR4 client applications and the emulated ABI which cause applications
       to malfunction.

       Additionally, some SVR4 operating systems do not adhere to the SVR4 ELF standard.  In particular, Solaris
       does not set the ELF interpreter field in the ELF header to a value  which  would  allow  the  kernel  to
       correctly  identify  a  client  executable  as  an  SVR4  application.   Thus, in certain instances it is
       necessary  to  use  the  brandelf(1)  utility  to  explicitly  brand  the  executable,  or  to  set   the
       kern.fallback_elf_brand  sysctl(8)  variable  to define a "default" ABI for unbranded executables.  Value
       ELFOSABI_SOLARIS represents Solaris;  ELFOSABI_SYSV  represents  other  SysVR4  operating  systems.   See
       <sys/elf_common.h>  for  ELFOSABI  branding  definitions,  and  brandelf(1)  for  information on branding
       executables.

       The svr4 module can be linked into the kernel statically with the COMPAT_SVR4 kernel configuration option
       or loaded as required.  The following command will load the module if  it  is  neither  linked  into  the
       kernel nor already loaded as a module:

             if ! kldstat -v | grep -E 'svr4elf' > /dev/null; then
                     kldload svr4 > /dev/null 2>&1
             fi

       The kernel will check for the presence of the streams(4) module, and load it if necessary.

       Note that dynamically linked SVR4 executables will require a suitable environment in /compat/svr4.

       For  information  on  loading  the  svr4  kernel  loadable  module  automatically  on system startup, see
       rc.conf(5).  This information applies regardless of whether the svr4 module is statically linked into the
       kernel or loaded as a module.

       STREAMS emulation is limited but (largely) functional.  Assuming  the  streams(4)  module  is  loaded,  a
       STREAMS  handle  can  be  obtained  by  opening  one  of  the relevant files in /dev or /compat/svr4/dev.
       Internally, the streams(4) driver produces a socket descriptor and  “tags”  it  with  additional  STREAMS
       state  information  before  returning  it  to  the  client  application.   The  svr4 environment uses the
       additional state information to recognize and manipulate emulated STREAMS handles  when  STREAMS-specific
       ioctl(2) calls are executed.

       The  subset  of  STREAMS  functionality  which  is  provided  is small, probably little more than what is
       required to enable programs on the Solaris CD sets to run.

FILES

       /compat/svr4                      minimal SVR4 run-time environment
       /sys/compat/svr4/syscalls.master  mappings between SVR4 syscalls and svr4 module entrypoints.

SEE ALSO

       brandelf(1), streams(4), elf(5)

HISTORY

       System V Release 4 ABI support first appeared in FreeBSD 4.0.  The ABI  was  ported  from  an  equivalent
       facility present in NetBSD 1.3 written by Christos Zoulas.

BUGS

       Emulation of signal handlers is buggy.

       Emulated  connectionless STREAMS fail to receive data from the network in some circumstances (but succeed
       in others -- probably due to particular  ways  of  initializing  them  which  the  streams(4)  module  is
       mishandling,  and  interaction  between  STREAMS  and poll(2)).  Connection-oriented STREAMS appear to be
       functional.

       Ironically, this SVR4 emulator does not (yet) support SVR4 semaphores or shared memory.

       ports(7) to automatically create the /compat/svr4 environment do not exist.  tar(1)  archives  containing
       pre-populated trees can be obtained from http://people.FreeBSD.org/~newton/freebsd-svr4/.

       Extensive  testing  has only really been carried out with Solaris 2.x binaries, with anecdotal reports of
       limited success coming from testers with early-revision SCO media.  In theory, the basic SVR4 ABI  should
       be  constant  across  the  set  of  vendors  who  produce SVR4 operating systems, but in practice that is
       probably not the case.  If necessary, future work can either implement additional  kld(4)  modules  which
       produce  functionality  which  contains  OS-dependent  departures  from  the  behaviour  which  has  been
       implemented in this ABI implementation.  Alternatively, sysctl(8) variables could set  the  “personality”
       the environment should present to client applications.

Debian                                           March 17, 2008                                          SVR4(4)