Introduce svr4(4) and streams(4).
Reviewed by: sheldonh
This commit is contained in:
Mark Newton
parent
a953ed108b
commit
0553a1b07b
77
share/man/man4/man4.i386/streams.4
Normal file
77
share/man/man4/man4.i386/streams.4
Normal file
@ -0,0 +1,77 @@
|
||||
.\" Copyright (c) 2000 Mark Newton
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.Dd November 6, 2000
|
||||
.Dt STREAMS 4 i386
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm streams
|
||||
.Nd System V STREAMS networking ABI support
|
||||
.Sh SYNOPSIS
|
||||
To link System V Release 4 (SVR4) STREAMS interprocess communication ABI
|
||||
support into the kernel:
|
||||
.Cd device streams
|
||||
.Pp
|
||||
To load the SVR4 STREAMS interprocess communication ABI support kernel
|
||||
module:
|
||||
.Dl kldload streams
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
module provides limited
|
||||
System V Release 4 STREAMS interprocess communication ABI
|
||||
(application binary interface) compatibility
|
||||
for userland applications.
|
||||
.Pp
|
||||
Internally,
|
||||
.Nm
|
||||
provides STREAMS handles by using socket creation kernel routines, and
|
||||
adding state-tracking information to the socket to permit manipulation
|
||||
by STREAMS emulation code in
|
||||
.Xr svr4 4 .
|
||||
Hence, opening a stream device produces a result similar to what would be
|
||||
obtained by calling
|
||||
.Xr socket 2 .
|
||||
.Pp
|
||||
Applications should never use this interface directly: STREAMS
|
||||
emulation is only provided as a service to support ABI requirements in
|
||||
the SVR4 environment which
|
||||
.Xr svr4 4
|
||||
needs to present to client binaries.
|
||||
.Sh BUGS
|
||||
This whole interface is a crude hack to produce STREAMS semantics
|
||||
through emulation over sockes.
|
||||
.Pp
|
||||
Programmers who hope to be able to use this interface to provide
|
||||
SVR4 STREAMS services to BSD applications will be sorely disappointed.
|
||||
.Sh SEE ALSO
|
||||
.Xr svr4 4
|
||||
.Sh HISTORY
|
||||
System V Release 4 ABI support first appeared in FreeBSD
|
||||
.Fx 4.0 .
|
||||
The ABI was ported from an equivalent facility present in
|
||||
NetBSD
|
||||
.Fx 1.3
|
||||
written by Christos Zoulas.
|
||||
209
share/man/man4/man4.i386/svr4.4
Normal file
209
share/man/man4/man4.i386/svr4.4
Normal file
@ -0,0 +1,209 @@
|
||||
.\" Copyright (c) 2000 Mark Newton
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.Dd November 6, 2000
|
||||
.Dt SVR4 4 i386
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm svr4
|
||||
.Nd System V Release 4 ABI support
|
||||
.Sh SYNOPSIS
|
||||
To link System V Release 4 (SVR4) ABI support into the kernel:
|
||||
.Cd options COMPAT_SVR4
|
||||
.Pp
|
||||
To load the SVR4 ABI support kernel module:
|
||||
.Dl kldload svr4
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
module provides limited
|
||||
System V Release 4 ABI (application binary interface) compatibility
|
||||
for userland applications.
|
||||
The module provides the following significant facilities:
|
||||
.Bl -bullet
|
||||
.It
|
||||
An image activator
|
||||
for correctly branded
|
||||
.Xr elf 5
|
||||
executable images
|
||||
.It
|
||||
Special signal handling for activated images
|
||||
.It
|
||||
SVR4 to native system call translation
|
||||
.It
|
||||
STREAMS network API emulation (via the
|
||||
.Xr streams 5
|
||||
loadable module, or by means of
|
||||
.Dl device streams
|
||||
in a kernel configuration file)
|
||||
.It
|
||||
Mappings between FreeBSD and SVR4
|
||||
.Xr ioctl 2
|
||||
calls, or, where no such mappings exist, reverse-engineered implementations
|
||||
of the SVR4 calls.
|
||||
.El
|
||||
.Pp
|
||||
It is important to note that the SVR4 ABI support
|
||||
it not provided through an emulator.
|
||||
Rather, a true (albeit limited) "clean room" reverse-engineered ABI
|
||||
implementation is provided.
|
||||
.Sh LIMITATIONS
|
||||
Because the provided ABI has been developed in ignorance of actual SVR4
|
||||
source code, there are bound to be unforseen interactions between SVR4
|
||||
client applications and the emulated ABI which cause applications to
|
||||
malfunction.
|
||||
.Pp
|
||||
Additionally, some SVR4 operating systems do not adhere to the SVR4
|
||||
ELF standard.
|
||||
In particular, Solaris does not set the ELF interpreter field in the
|
||||
ELF header to a value which would allow the kernel to correctly
|
||||
identify a client executable as an SVR4 application.
|
||||
Thus, in certain instances it is necessary to use the
|
||||
.Xr brandelf 1
|
||||
utility to explicitly brand the executable, or to set the
|
||||
kern.fallback_elf_brand
|
||||
.Xr sysctl 8
|
||||
variable to define a "default" ABI for unbranded executables.
|
||||
Value ELFOSABI_SOLARIS represents Solaris; ELFOSABI_SYSV represents other
|
||||
SysVR4 operating systems.
|
||||
See
|
||||
.Pa /usr/include/sys/elf_common.h
|
||||
for ELFOSABI branding definitions, and
|
||||
.Xr brandelf 1
|
||||
for information on branding executables.
|
||||
.Pp
|
||||
The
|
||||
.Nm
|
||||
module can be linked into the kernel statically with the
|
||||
.Dv COMPAT_SVR4
|
||||
kernel configuration option
|
||||
or loaded as required.
|
||||
The following command will load the module
|
||||
if it is neither linked into the kernel
|
||||
nor already loaded as a module:
|
||||
.Bd -literal -offset indent
|
||||
if ! kldstat -v | grep -E 'svr4elf' > /dev/null; then
|
||||
/usr/bin/svr4 > /dev/null 2>&1
|
||||
fi
|
||||
.Ed
|
||||
.Pp
|
||||
.Xr svr4 8
|
||||
will check for the presence of the
|
||||
.Xr streams 5
|
||||
module, and load it if necessary.
|
||||
.Pp
|
||||
Note that dynamically linked SVR4 executables
|
||||
will require a suitable environment in
|
||||
.Pa /compat/svr4 .
|
||||
.Pp
|
||||
For information on loading the
|
||||
.Nm
|
||||
kernel loadable module automatically on system startup,
|
||||
see
|
||||
.Xr rc.conf 5 .
|
||||
This information applies
|
||||
regardless of whether the
|
||||
.Nm
|
||||
module is statically linked into the kernel
|
||||
or loaded as a module.
|
||||
.Pp
|
||||
STREAMS emulation is limited but (largely) functional.
|
||||
Assuming the
|
||||
.Xr streams 5
|
||||
module is loaded, a STREAMS handle can be obtained by opening one of the
|
||||
relevent files in
|
||||
.Pa /dev
|
||||
or
|
||||
.Pa /compat/svr4/dev .
|
||||
Internally, the
|
||||
.Xr streams 5
|
||||
driver produces a socket descriptor and "tags" it with additional STREAMS
|
||||
state information before returning it to the client application.
|
||||
The
|
||||
.Nm
|
||||
environment uses the additional state information to recognize and
|
||||
manipulate emulated STREAMS handles when STREAMS-specific
|
||||
.Xr ioctl 2
|
||||
calls are executed.
|
||||
.Pp
|
||||
The subset of STREAMS functionality which is provided is small, probably
|
||||
little more than what is required to enable programs on the Solaris CD
|
||||
sets to run.
|
||||
.Sh BUGS
|
||||
Emulation of signal handlers is buggy.
|
||||
.Pp
|
||||
Emulated connectionless STREAMS fail to receive data from the network in
|
||||
some circumstances (but succeed in others -- probably due to particular
|
||||
ways of initializing them which the
|
||||
.Xr streams 5
|
||||
module is mishandling, and interaction between STREAMS and
|
||||
.Xr poll 2 ) .
|
||||
Connection-oriented STREAMS appear to be functional.
|
||||
.Pp
|
||||
Ironically, this SVR4 emulator does not (yet) support SVR4 semaphores or
|
||||
shared memory.
|
||||
.Pp
|
||||
.Xr ports 7
|
||||
to automatically create the
|
||||
.Pa /compat/svr4
|
||||
environment do not exist.
|
||||
.Xr tar 1
|
||||
archives containing pre-populated trees can be obtained from
|
||||
.Pa http://people.freebsd.org/~newton/freebsd-svr4/ .
|
||||
.Pp
|
||||
Extensive testing has only really been carried out with Solaris 2.x binaries,
|
||||
with anecdotal reports of limited success coming from testers with
|
||||
early-revision SCO media. In theory, the basic SVR4 ABI should be constant
|
||||
across the set of vendors who produce SVR4 operating systems, but in
|
||||
practice that's probably not the case. If necessary, future work can
|
||||
either implement additional
|
||||
.Xr kld 4
|
||||
modules which produce functionality which contains OS-dependent
|
||||
departures from the behaviour which has been implemented in this
|
||||
ABI implementation.
|
||||
Alternatively,
|
||||
.Xr sysctl 8
|
||||
variables could set the "personality" the environment should present to
|
||||
client applications.
|
||||
.Sh FILES
|
||||
.Bl -tag -width /sys/compat/svr4/syscalls.master -compact
|
||||
.It Pa /compat/svr4
|
||||
minimal SVR4 run-time environment
|
||||
.It Pa /sys/compat/svr4/syscalls.master
|
||||
mappings between SVR4 syscalls and
|
||||
.Nm
|
||||
module entrypoints.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr brandelf 1 ,
|
||||
.Xr elf 5 ,
|
||||
.Xr streams 4
|
||||
.Sh HISTORY
|
||||
System V Release 4 ABI support first appeared in FreeBSD
|
||||
.Fx 4.0 .
|
||||
The ABI was ported from an equivalent facility present in
|
||||
NetBSD
|
||||
.Fx 1.3
|
||||
written by Christos Zoulas.
|
||||
Loading…
x
Reference in New Issue
Block a user