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 October 28, 2003
  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 unforeseen 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 .In 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         kldload 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 relevant 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
 145 .Dq tags
 146 it with additional STREAMS
 147 state information before returning it to the client application.
 148 The
 149 .Nm
 150 environment uses the additional state information to recognize and
 151 manipulate emulated STREAMS handles when STREAMS-specific
 152 .Xr ioctl 2
 153 calls are executed.
 154 .Pp
 155 The subset of STREAMS functionality which is provided is small, probably
 156 little more than what is required to enable programs on the Solaris CD
 157 sets to run.
 158 .Sh FILES
 159 .Bl -tag -width /sys/compat/svr4/syscalls.master -compact
 160 .It Pa /compat/svr4
 161 minimal SVR4 run-time environment
 162 .It Pa /sys/compat/svr4/syscalls.master
 163 mappings between SVR4 syscalls and
 164 .Nm
 165 module entrypoints.
 166 .El
 167 .Sh SEE ALSO
 168 .Xr brandelf 1 ,
 169 .Xr streams 4 ,
 170 .Xr elf 5
 171 .Sh HISTORY
 172 System V Release 4 ABI support first appeared in
 173 .Fx 4.0 .
 174 The ABI was ported from an equivalent facility present in
 175 .Nx 1.3
 176 written by Christos Zoulas.
 177 .Sh BUGS
 178 Emulation of signal handlers is buggy.
 179 .Pp
 180 Emulated connectionless STREAMS fail to receive data from the network in
 181 some circumstances (but succeed in others -- probably due to particular
 182 ways of initializing them which the
 183 .Xr streams 4
 184 module is mishandling, and interaction between STREAMS and
 185 .Xr poll 2 ) .
 186 Connection-oriented STREAMS appear to be functional.
 187 .Pp
 188 Ironically, this SVR4 emulator does not (yet) support SVR4 semaphores or
 189 shared memory.
 190 .Pp
 191 .Xr ports 7
 192 to automatically create the
 193 .Pa /compat/svr4
 194 environment do not exist.
 195 .Xr tar 1
 196 archives containing pre-populated trees can be obtained from
 197 .Pa http://people.FreeBSD.org/~newton/freebsd-svr4/ .
 198 .Pp
 199 Extensive testing has only really been carried out with Solaris 2.x binaries,
 200 with anecdotal reports of limited success coming from testers with
 201 early-revision SCO media.
 202 In theory, the basic SVR4 ABI should be constant
 203 across the set of vendors who produce SVR4 operating systems, but in
 204 practice that is probably not the case.
 205 If necessary, future work can
 206 either implement additional
 207 .Xr kld 4
 208 modules which produce functionality which contains OS-dependent
 209 departures from the behaviour which has been implemented in this
 210 ABI implementation.
 211 Alternatively,
 212 .Xr sysctl 8
 213 variables could set the
 214 .Dq personality
 215 the environment should present to
 216 client applications.