share/man/man4/man4.i386/svr4.4

   1 .\" Copyright (c) 2000 Mark Newton
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .Dd November 6, 2000
  27 .Dt SVR4 4 i386
  28 .Os
  29 .Sh NAME
  30 .Nm svr4
  31 .Nd System V Release 4 ABI support
  32 .Sh SYNOPSIS
  33 To link System V Release 4 (SVR4) ABI support into the kernel:
  34 .Cd options COMPAT_SVR4
  35 .Pp
  36 To load the SVR4 ABI support kernel module:
  37 .Dl kldload svr4
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 module provides limited
  42 System V Release 4 ABI (application binary interface) compatibility
  43 for userland applications.
  44 The module provides the following significant facilities:
  45 .Bl -bullet
  46 .It
  47 An image activator
  48 for correctly branded
  49 .Xr elf 5
  50 executable images
  51 .It
  52 Special signal handling for activated images
  53 .It
  54 SVR4 to native system call translation
  55 .It
  56 STREAMS network API emulation (via the
  57 .Xr streams 4
  58 loadable module, or by means of
  59 .Dl device streams
  60 in a kernel configuration file)
  61 .It
  62 Mappings between
  63 .Fx
  64 and SVR4
  65 .Xr ioctl 2
  66 calls, or, where no such mappings exist, reverse-engineered implementations
  67 of the SVR4 calls.
  68 .El
  69 .Pp
  70 It is important to note that the SVR4 ABI support
  71 it not provided through an emulator.
  72 Rather, a true (albeit limited) "clean room" reverse-engineered ABI
  73 implementation is provided.
  74 .Sh LIMITATIONS
  75 Because the provided ABI has been developed in ignorance of actual SVR4
  76 source code, there are bound to be unforseen interactions between SVR4
  77 client applications and the emulated ABI which cause applications to
  78 malfunction.
  79 .Pp
  80 Additionally, some SVR4 operating systems do not adhere to the SVR4
  81 ELF standard.
  82 In particular, Solaris does not set the ELF interpreter field in the
  83 ELF header to a value which would allow the kernel to correctly
  84 identify a client executable as an SVR4 application.
  85 Thus, in certain instances it is necessary to use the
  86 .Xr brandelf 1
  87 utility to explicitly brand the executable, or to set the
  88 kern.fallback_elf_brand
  89 .Xr sysctl 8
  90 variable to define a "default" ABI for unbranded executables.
  91 Value ELFOSABI_SOLARIS represents Solaris; ELFOSABI_SYSV represents other
  92 SysVR4 operating systems.
  93 See
  94 .Pa /usr/include/sys/elf_common.h
  95 for ELFOSABI branding definitions, and
  96 .Xr brandelf 1
  97 for information on branding executables.
  98 .Pp
  99 The
 100 .Nm
 101 module can be linked into the kernel statically with the
 102 .Dv COMPAT_SVR4
 103 kernel configuration option
 104 or loaded as required.
 105 The following command will load the module
 106 if it is neither linked into the kernel
 107 nor already loaded as a module:
 108 .Bd -literal -offset indent
 109 if ! kldstat -v | grep -E 'svr4elf' > /dev/null; then
 110         /usr/bin/svr4 > /dev/null 2>&1
 111 fi
 112 .Ed
 113 .Pp
 114 The kernel
 115 will check for the presence of the
 116 .Xr streams 4
 117 module, and load it if necessary.
 118 .Pp
 119 Note that dynamically linked SVR4 executables
 120 will require a suitable environment in
 121 .Pa /compat/svr4 .
 122 .Pp
 123 For information on loading the
 124 .Nm
 125 kernel loadable module automatically on system startup,
 126 see
 127 .Xr rc.conf 5 .
 128 This information applies
 129 regardless of whether the
 130 .Nm
 131 module is statically linked into the kernel
 132 or loaded as a module.
 133 .Pp
 134 STREAMS emulation is limited but (largely) functional.
 135 Assuming the
 136 .Xr streams 4
 137 module is loaded, a STREAMS handle can be obtained by opening one of the
 138 relevent files in
 139 .Pa /dev
 140 or
 141 .Pa /compat/svr4/dev .
 142 Internally, the
 143 .Xr streams 4
 144 driver produces a socket descriptor and "tags" it with additional STREAMS
 145 state information before returning it to the client application.
 146 The
 147 .Nm
 148 environment uses the additional state information to recognize and
 149 manipulate emulated STREAMS handles when STREAMS-specific
 150 .Xr ioctl 2
 151 calls are executed.
 152 .Pp
 153 The subset of STREAMS functionality which is provided is small, probably
 154 little more than what is required to enable programs on the Solaris CD
 155 sets to run.
 156 .Sh BUGS
 157 Emulation of signal handlers is buggy.
 158 .Pp
 159 Emulated connectionless STREAMS fail to receive data from the network in
 160 some circumstances (but succeed in others -- probably due to particular
 161 ways of initializing them which the
 162 .Xr streams 4
 163 module is mishandling, and interaction between STREAMS and
 164 .Xr poll 2 ) .
 165 Connection-oriented STREAMS appear to be functional.
 166 .Pp
 167 Ironically, this SVR4 emulator does not (yet) support SVR4 semaphores or
 168 shared memory.
 169 .Pp
 170 .Xr ports 7
 171 to automatically create the
 172 .Pa /compat/svr4
 173 environment do not exist.
 174 .Xr tar 1
 175 archives containing pre-populated trees can be obtained from
 176 .Pa http://people.freebsd.org/~newton/freebsd-svr4/ .
 177 .Pp
 178 Extensive testing has only really been carried out with Solaris 2.x binaries,
 179 with anecdotal reports of limited success coming from testers with
 180 early-revision SCO media.  In theory, the basic SVR4 ABI should be constant
 181 across the set of vendors who produce SVR4 operating systems, but in
 182 practice that's probably not the case.  If necessary, future work can
 183 either implement additional
 184 .Xr kld 4
 185 modules which produce functionality which contains OS-dependent
 186 departures from the behaviour which has been implemented in this
 187 ABI implementation.
 188 Alternatively,
 189 .Xr sysctl 8
 190 variables could set the "personality" the environment should present to
 191 client applications.
 192 .Sh FILES
 193 .Bl -tag -width /sys/compat/svr4/syscalls.master -compact
 194 .It Pa /compat/svr4
 195 minimal SVR4 run-time environment
 196 .It Pa /sys/compat/svr4/syscalls.master
 197 mappings between SVR4 syscalls and
 198 .Nm
 199 module entrypoints.
 200 .El
 201 .Sh SEE ALSO
 202 .Xr brandelf 1 ,
 203 .Xr streams 4 ,
 204 .Xr elf 5
 205 .Sh HISTORY
 206 System V Release 4 ABI support first appeared in
 207 .Fx 4.0 .
 208 The ABI was ported from an equivalent facility present in
 209 .Nx 1.3
 210 written by Christos Zoulas.