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.
|