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: src/share/man/man4/man4.i386/svr4.4,v 1.12 2005/02/13 23:45:49 ru Exp $
  26 .\" $DragonFly: src/share/man/man4/man4.i386/Attic/svr4.4,v 1.2 2006/05/01 09:06:33 swildner Exp $
  27 .Dd October 28, 2003
  28 .Dt SVR4 4 i386
  29 .Os
  30 .Sh NAME
  31 .Nm svr4
  32 .Nd System V Release 4 ABI support
  33 .Sh SYNOPSIS
  34 To link System V Release 4 (SVR4) ABI support into the kernel:
  35 .Cd options COMPAT_SVR4
  36 .Pp
  37 To load the SVR4 ABI support kernel module:
  38 .Bd -literal -offset indent
  39 kldload streams
  40 kldload svr4
  41 .Ed
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 module provides limited
  46 System V Release 4 ABI (application binary interface) compatibility
  47 for userland applications.
  48 The module provides the following significant facilities:
  49 .Bl -bullet
  50 .It
  51 An image activator
  52 for correctly branded
  53 .Xr elf 5
  54 executable images
  55 .It
  56 Special signal handling for activated images
  57 .It
  58 SVR4 to native system call translation
  59 .It
  60 STREAMS network API emulation (via the
  61 .Xr streams 4
  62 loadable module, or by means of
  63 .Dl pseudo-device streams
  64 in a kernel configuration file)
  65 .It
  66 Mappings between
  67 .Fx
  68 and SVR4
  69 .Xr ioctl 2
  70 calls, or, where no such mappings exist, reverse-engineered implementations
  71 of the SVR4 calls.
  72 .El
  73 .Pp
  74 It is important to note that the SVR4 ABI support
  75 it not provided through an emulator.
  76 Rather, a true (albeit limited) "clean room" reverse-engineered ABI
  77 implementation is provided.
  78 .Sh LIMITATIONS
  79 Because the provided ABI has been developed in ignorance of actual SVR4
  80 source code, there are bound to be unforeseen interactions between SVR4
  81 client applications and the emulated ABI which cause applications to
  82 malfunction.
  83 .Pp
  84 Additionally, some SVR4 operating systems do not adhere to the SVR4
  85 ELF standard.
  86 In particular, Solaris does not set the ELF interpreter field in the
  87 ELF header to a value which would allow the kernel to correctly
  88 identify a client executable as an SVR4 application.
  89 Thus, in certain instances it is necessary to use the
  90 .Xr brandelf 1
  91 utility to explicitly brand the executable, or to set the
  92 kern.fallback_elf_brand
  93 .Xr sysctl 8
  94 variable to define a "default" ABI for unbranded executables.
  95 Value ELFOSABI_SOLARIS represents Solaris; ELFOSABI_SYSV represents other
  96 SysVR4 operating systems.
  97 See
  98 .In sys/elf_common.h
  99 for ELFOSABI branding definitions, and
 100 .Xr brandelf 1
 101 for information on branding executables.
 102 .Pp
 103 The
 104 .Nm
 105 module can be linked into the kernel statically with the
 106 .Dv COMPAT_SVR4
 107 kernel configuration option
 108 or loaded as required.
 109 The following command will load the module
 110 if it is neither linked into the kernel
 111 nor already loaded as a module:
 112 .Bd -literal -offset indent
 113 if ! kldstat -V | grep -E 'streams.ko' > /dev/null; then
 114         kldload streams > /dev/null 2>&1
 115 fi
 116
 117 if ! kldstat -v | grep -E 'svr4.ko' > /dev/null; then
 118         kldload svr4 > /dev/null 2>&1
 119 fi
 120 .Ed
 121 .Pp
 122 The kernel
 123 will check for the presence of the
 124 .Xr streams 4
 125 module, and load it if necessary.
 126 .Pp
 127 Note that dynamically linked SVR4 executables
 128 will require a suitable environment in
 129 .Pa /compat/svr4 .
 130 .Pp
 131 For information on loading the
 132 .Nm
 133 kernel loadable module automatically on system startup,
 134 see
 135 .Xr rc.conf 5 .
 136 This information applies
 137 regardless of whether the
 138 .Nm
 139 module is statically linked into the kernel
 140 or loaded as a module.
 141 .Pp
 142 STREAMS emulation is limited but (largely) functional.
 143 Assuming the
 144 .Xr streams 4
 145 module is loaded, a STREAMS handle can be obtained by opening one of the
 146 relevant files in
 147 .Pa /dev
 148 or
 149 .Pa /compat/svr4/dev .
 150 Internally, the
 151 .Xr streams 4
 152 driver produces a socket descriptor and
 153 .Dq tags
 154 it with additional STREAMS
 155 state information before returning it to the client application.
 156 The
 157 .Nm
 158 environment uses the additional state information to recognize and
 159 manipulate emulated STREAMS handles when STREAMS-specific
 160 .Xr ioctl 2
 161 calls are executed.
 162 .Pp
 163 The subset of STREAMS functionality which is provided is small, probably
 164 little more than what is required to enable programs on the Solaris CD
 165 sets to run.
 166 .Sh FILES
 167 .Bl -tag -width /sys/emulation/svr4/syscalls.master -compact
 168 .It Pa /compat/svr4
 169 minimal SVR4 run-time environment
 170 .It Pa /sys/emulation/svr4/syscalls.master
 171 mappings between SVR4 syscalls and
 172 .Nm
 173 module entrypoints.
 174 .El
 175 .Sh SEE ALSO
 176 .Xr brandelf 1 ,
 177 .Xr streams 4 ,
 178 .Xr elf 5
 179 .Sh HISTORY
 180 System V Release 4 ABI support first appeared in
 181 .Fx 4.0 .
 182 The ABI was ported from an equivalent facility present in
 183 .Nx 1.3
 184 written by Christos Zoulas.
 185 .Sh BUGS
 186 Emulation of signal handlers is buggy.
 187 .Pp
 188 Emulated connectionless STREAMS fail to receive data from the network in
 189 some circumstances (but succeed in others -- probably due to particular
 190 ways of initializing them which the
 191 .Xr streams 4
 192 module is mishandling, and interaction between STREAMS and
 193 .Xr poll 2 ) .
 194 Connection-oriented STREAMS appear to be functional.
 195 .Pp
 196 Ironically, this SVR4 emulator does not (yet) support SVR4 semaphores or
 197 shared memory.
 198 .Pp
 199 .Xr tar 1
 200 archives containing pre-populated
 201 .Pa /compat/svr4
 202 trees can be obtained from
 203 .Pa http://people.FreeBSD.org/~newton/freebsd-svr4/ .
 204 .Pp
 205 Extensive testing has only really been carried out with Solaris 2.x binaries,
 206 with anecdotal reports of limited success coming from testers with
 207 early-revision SCO media.
 208 In theory, the basic SVR4 ABI should be constant
 209 across the set of vendors who produce SVR4 operating systems, but in
 210 practice that is probably not the case.
 211 If necessary, future work can
 212 either implement additional
 213 .Xr kld 4
 214 modules which produce functionality which contains OS-dependent
 215 departures from the behaviour which has been implemented in this
 216 ABI implementation.
 217 Alternatively,
 218 .Xr sysctl 8
 219 variables could set the
 220 .Dq personality
 221 the environment should present to
 222 client applications.