From ae6f14bdd3d33a7f1008566f3af5e26e0fb06f89 Mon Sep 17 00:00:00 2001 From: newton Date: Wed, 29 Nov 2000 09:50:11 +0000 Subject: Introduce svr4(4) and streams(4). Reviewed by: sheldonh --- share/man/man4/man4.i386/streams.4 | 77 ++++++++++++++ share/man/man4/man4.i386/svr4.4 | 209 +++++++++++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+) create mode 100644 share/man/man4/man4.i386/streams.4 create mode 100644 share/man/man4/man4.i386/svr4.4 (limited to 'share') diff --git a/share/man/man4/man4.i386/streams.4 b/share/man/man4/man4.i386/streams.4 new file mode 100644 index 0000000..8327d72 --- /dev/null +++ b/share/man/man4/man4.i386/streams.4 @@ -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. diff --git a/share/man/man4/man4.i386/svr4.4 b/share/man/man4/man4.i386/svr4.4 new file mode 100644 index 0000000..a2df082 --- /dev/null +++ b/share/man/man4/man4.i386/svr4.4 @@ -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. -- cgit v1.1