Add some missing manual pages.
[dragonfly.git] / 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.1 2006/04/30 18:46:39 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 ports 7
200 to automatically create the
201 .Pa /compat/svr4
202 environment do not exist.
203 .Xr tar 1
204 archives containing pre-populated trees can be obtained from
205 .Pa http://people.FreeBSD.org/~newton/freebsd-svr4/ .
206 .Pp
207 Extensive testing has only really been carried out with Solaris 2.x binaries,
208 with anecdotal reports of limited success coming from testers with
209 early-revision SCO media.
210 In theory, the basic SVR4 ABI should be constant
211 across the set of vendors who produce SVR4 operating systems, but in
212 practice that is probably not the case.
213 If necessary, future work can
214 either implement additional
215 .Xr kld 4
216 modules which produce functionality which contains OS-dependent
217 departures from the behaviour which has been implemented in this
218 ABI implementation.
219 Alternatively,
220 .Xr sysctl 8
221 variables could set the
222 .Dq personality
223 the environment should present to
224 client applications.