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