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