OpenSS7 STREAMS Sockets

OpenSS7 STREAMS Sockets Installation and Reference Manual

About This Manual

This is Edition 3, last updated 2007-06-24, of The OpenSS7 STREAMS Sockets Installation and Reference Manual, for Version 0.9.2 release 3 of the OpenSS7 STREAMS Sockets package.

Preface

Notice

This package is released and distributed under the GPL (see GNU General Public License). Please note, however, that there are different licensing terms for the manual pages and some of the documentation (derived from OpenGroup¹ publications and other sources). Consult the permission notices contained in the documentation for more information.

Also note that parts of this software, as identified in Possible BSD Sources, may be derived from software developed by the University of California, Berkeley covered under the Combined USL BSD License (see BSD/USL Combined License).

This manual is released under the FDL (see GNU Free Documentation License) with all sections invariant.

Abstract

This manual provides a Installation and Reference Manual for OpenSS7 STREAMS Sockets.

Objective

The objective of this manual is to provide a guide for the STREAMS programmer when developing STREAMS modules, drivers and application programs for OpenSS7 STREAMS Sockets.

This guide provides information to developers on the use of the STREAMS mechanism at user and kernel levels.

STREAMS was incorporated in UNIX System V Release 3 to augment the character input/output (I/O) mechanism and to support development of communication services.

STREAMS provides developers with integral functions, a set of utility routines, and facilities that expedite software design and implementation.

Intent

The intent of this manual is to act as an introductory guide to the STREAMS programmer. It is intended to be read alone and is not intended to replace or supplement the OpenSS7 STREAMS Sockets manual pages. For a reference for writing code, the manual pages (see STREAMS(9)) provide a better reference to the programmer. Although this describes the features of the OpenSS7 STREAMS Sockets package, OpenSS7 Corporation is under no obligation to provide any software, system or feature listed herein.

Audience

This manual is intended for a highly technical audience. The reader should already be familiar with Linux kernel programming, the Linux file system, character devices, driver input and output, interrupts, software interrupt handling, scheduling, process contexts, multiprocessor locks, etc.

The guide is intended for network and systems programmers, who use the STREAMS mechanism at user and kernel levels for Linux and UNIX system communication services.

Readers of the guide are expected to possess prior knowledge of the Linux and UNIX system, programming, networking, and data communication.

Revisions

Take care that you are working with a current version of this manual: you will not be notified of updates. To ensure that you are working with a current version, contact the Author, or check The OpenSS7 Project website for a current version.

A current version of this manual is normally distributed with the OpenSS7 STREAMS Sockets package, strsock-0.9.2.3.²

Version Control

     
     strsock.texi,v
     Revision 0.9.2.10  2007/06/23 01:38:27  brian
     - updates for release
     
     Revision 0.9.2.9  2007/02/28 06:31:28  brian
     - updates and corrections, #ifdef instead of #if
     
     Revision 0.9.2.8  2006/09/18 01:07:16  brian
     - updated manuals and release texi docs
     
     Revision 0.9.2.7  2006/09/01 08:55:40  brian
     - added headers and working up code
     
     Revision 0.9.2.6  2006/08/29 11:44:05  brian
     - added manual pages, working up docs
     
     Revision 0.9.2.5  2006/08/28 10:47:10  brian
     - correction
     
     Revision 0.9.2.4  2006/08/28 10:32:58  brian
     - updated references
     
     Revision 0.9.2.3  2006/08/27 12:27:12  brian
     - finalizing auto release files
     
     Revision 0.9.2.2  2006/08/26 09:19:22  brian
     - better release file generation
     
     Revision 0.9.2.1  2006/08/23 10:03:59  brian
     - started STREAMS Sockets package
     
     

ISO 9000 Compliance

Only the TeX, texinfo, or roff source for this manual is controlled. An opaque (printed, postscript or portable document format) version of this manual is an UNCONTROLLED VERSION.

Disclaimer

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the manual are suitable for any purpose, or that the implementation of such contents will not infringe on any third party patents, copyrights, trademarks or other rights. In no event shall OpenSS7 Corporation be liable for any direct, indirect, special or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with any use of this manual or the performance or implementation of the contents thereof.

OpenSS7 Corporation reserves the right to revise this software and documentation for any reason, including but not limited to, conformity with standards promulgated by various agencies, utilization of advances in the state of the technical arts, or the reflection of changes in the design of any techniques, or procedures embodied, described, or referred to herein. OpenSS7 Corporation is under no obligation to provide any feature listed herein.

U.S. Government Restricted Rights

If you are licensing this Software on behalf of the U.S. Government ("Government"), the following provisions apply to you. If the Software is supplied by the Department of Defense ("DoD"), it is classified as "Commercial Computer Software" under paragraph 252.227-7014 of the DoD Supplement to the Federal Acquisition Regulations ("DFARS") (or any successor regulations) and the Government is acquiring only the license rights granted herein (the license rights customarily provided to non-Government users). If the Software is supplied to any unit or agency of the Government other than DoD, it is classified as "Restricted Computer Software" and the Government's rights in the Software are defined in paragraph 52.227-19 of the Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the FAR (or any successor regulations).

Acknowledgements

As with most open source projects, this project would not have been possible without the valiant efforts and productive software of the Free Software Foundation and the Linux Kernel Community.

Sponsors

Funding for completion of the OpenSS7 OpenSS7 STREAMS Sockets package was provided in part by:

Additional funding for The OpenSS7 Project was provided by:

Contributors

The primary contributor to the OpenSS7 OpenSS7 STREAMS Sockets package is Brian F. G. Bidulock. The following is a list of significant contributors to The OpenSS7 Project:

Authors

The authors of the OpenSS7 OpenSS7 STREAMS Sockets package include:

See Author Index, for a complete listing and cross-index of authors to sections of this manual.

Maintainer

The maintainer of the OpenSS7 OpenSS7 STREAMS Sockets package is:

Please send bug reports to bugs@openss7.org using the send-pr script included in the package, only after reading the BUGS file in the release, or See Problem Reports.

Web Resources

The OpenSS7 Project provides a website dedicated to the software packages released by the OpenSS7 Project.

Bug Reports

Please send bug reports to bugs@openss7.org using the send-pr script included in the OpenSS7 STREAMS Sockets package, only after reading the BUGS file in the release, or See Problem Reports. You can access the OpenSS7 GNATS database directly via the web, however, the preferred method for sending new bug reports is via mail with the send-pr script.

Mailing Lists

The OpenSS7 Project provides a number of general discussion Mailing Lists for discussion concerning the OpenSS7 OpenSS7 STREAMS Sockets package as well as other packages released by The OpenSS7 Project.

These are mailman mailing lists and so have convenient web interfaces for subscribers to control their settings. See http://www.openss7.org/mailinglist.html.

The mailing lists are as follows:

openss7

The openss7 mailing list is for general enquiries, information exchange and announcements regarding the OpenSS7 Project. This is our original mailing list and takes the highest amount of traffic.

openss7-announce

The openss7-announce mailing list is for announcements related to the OpenSS7 Project. This list will accept announcements posted by subscribers. Subscribe to this list if you are interested in announcements from the OpenSS7 Project, subscribers and sponsors, related to the OpenSS7 Project or STREAMS, SS7, SIGTRAN or SCTP in general.

openss7-cvs

The openss7-cvs mailing list is for automatic CVS log reporting. You must get permission of the owner to subscribe to this list. Subscribers are not allowed to post to this list, this is merely for distributing notification of changes to the CVS repository.h

openss7-develop

The openss7-develop mailing list is for email exchange related to the development projects under the OpenSS7 Project. This includes development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the OpenSS7 Project.

openss7-test

The openss7-test mailing list is for email exchange related to the testing of code under the OpenSS7 Project. This specifically relates to conformance testing, verification testing, interoperability testing and beta testing. Subscribe to this list if you are interested in participating in and receiving ongoing details of test activities under the OpenSS7 Project.

openss7-bugs

The openss7-bugs mailing list is specifically tailored to bug tracking. The mailing list takes a feed from the OpenSS7 GNATS bug tracking system and accepts posting of responses to bug reports, tracking and resolution. Subscribe to this list if you are interested in receiving detailed OpenSS7 release code bug tracking information. This list is not archived; for historical information on problem reports, see our GNATS databases.

openss7-updates

The openss7-updates mailing list provides updates on OpenSS7 Project code releases and ongoing activities. Subscribers are not allowed to post to this list; this list is for official OpenSS7 Project announcements only. Subscribe to this list if you are interested in receiving updates concerning official releases and activities of the OpenSS7 Project.

openss7-streams

The openss7-streams mailing list is for email exchange related to the STREAMS development projects under the OpenSS7 Project. This includes development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the OpenSS7 Project STREAMS components.

linux-streams

The linux-streams mailing list is for mail exchange related to Linux Fast-STREAMS or Linux STREAMS. This includes patches, development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the STREAMS for Linux components. This is the the new (September 2006) home of the linux-streams list formerly of <gsyc.escet.urjc.es>.

Spam

To avoid spam being sent to the members of the OpenSS7 mailing list(s), we have blocked mail from non-subscribers. Please subscribe to the mailing list before attempting to post to them. (Attempts to post when not subscribed get bounced.)

As an additional measure against spam, subscriber lists for all OpenSS7 mailing lists are not accessible to non-subscribers; for most lists subscriber lists are only accessible to the list administrator. This keeps your mailing address from being picked off our website by bulk mailers.

Acceptable Use Policy

It is acceptable to post professional and courteous messages regarding the OpenSS7 package or any general information or questions concerning STREAMS, SS7, SIGTRAN, SCTP or telecommunications applications in general.

Large Attachments

The mailing list is blocked from messages of greater than 40k. If you have attachments (patches, test programs, etc.) and you mail them to the list, it will bounce to the list administrator. If you are interested in making your patches, test programs, test results or other large attachments available to the members of the mailing list, state in the message that you would like them posted and the list administrator will place them in the mail archives.

Quick Start Guide

OpenSS7 STREAMS Sockets

Package strsock-0.9.2.3 was released under GPLv2 2007-06-24.

The OpenSS7 STREAMS Sockets package provides STREAMS modules and drivers, libraries, programs, initialization scripts, and daemons.

The OpenSS7 STREAMS Sockets package contains header files and a number of modules and drivers and the associated documentation originally contained in the Linux Fast-STREAMS release, but not contained in the Linux STREAMS (LiS) releases.

The package uses the following standard Open Systems Interconnect (OSI) conforming header files from the strxnet package:

The package currently provides the following STREAMS modules and drivers:

• sockmod(4) The sockmod(4) module, when pushed on a TPI Stream, attempts to provide as wide a range of support for traditional SVR 4.2 socket module and socket system support.

  It does so by recognizing input-output controls from three sets:
  sockmod(4) input-output controls; socksys(4) input-output controls, and even socket(7) system calls.

• socksys(4) The socksys(4) driver, when opened, provides a TPI Stream that attempts to provide as wide a range of support for traditional SVR 4.2 socket module and socket system support.

  It does so by recognizing input-output controls from three sets:
  sockmod(4) input-output controls; socksys(4) input-output controls, and even socket(7) system calls.

The package currently provides the following STREAMS libraries:

The libsocket library implements the following library calls:

The libsocket library only needs to implement the single library call because file descriptors that are returned from the socket(3) call have been transformed into real sockets (from the viewpoint of the system call interface) and standard glibc calls for the remaining functions are used.

The libsocklib library implements the following library calls:

The libsocklib library is the older compatibility library approach to providing sockets for STREAMS and implements the system calls as library calls for STREAMS devices, while calling the glibc versions for true sockets.

The OpenSS7 STREAMS Sockets package includes kernel modules, SVR 4.2 STREAMS drivers, modules, libraries, utilities, test programs, daemons, and development environment for the development and execution of OpenSS7 STREAMS Sockets modules and drivers.

This distribution is only currently applicable to Linux 2.4 and 2.6 kernels and was targeted at ix86, x86_64, ppc and ppc64 architectures, but should build and install for other architectures as well.

Release

This is the strsock-0.9.2.3 package, released 2007-06-24. This `0.9.2.3' release, and the latest version, can be obtained from the download area of The OpenSS7 Project website using a command such as:

     $> wget http://www.openss7.org/tarballs/strsock-0.9.2.3.tar.bz2

The release is available as an autoconf(1) tarball, src.rpm or dsc, or as a set of binary rpms or debs. See the download page for the autoconf(1) tarballs, src.rpms or dscs. See the strsock package page for tarballs, source and binary packages.

Please see the NEWS file for release notes and history of user visible changes for the current version, and the ChangeLog file for a more detailed history of implementation changes. The TODO file lists features not yet implemented and other outstanding items.

Please see the INSTALL, INSTALL-strsock and README-make, files (or see Installation) for installation instructions.

When working from cvs(1) or git(1), please see the README-cvs, file (or see Downloading from CVS). An abbreviated installation procedure that works for most applications appears below.

This release of the package is published strictly under Version 2 of the GNU Public License which can be found in the file COPYING. Package specific licensing terms (if any) can be found in the file LICENSES. Please respect these licensing arrangements. If you are interested in different licensing terms, please contact the copyright holder, or OpenSS7 Corporation <sales@openss7.com>.

See README-alpha (if it exists) for alpha release information.

Prerequisites

The quickest and easiest way to ensure that all prerequisites are met is to download and install this package from within the OpenSS7 Master Package, openss7-0.9.2.F, instead of separately.

Prerequisites for the OpenSS7 STREAMS Sockets package are as follows:

1. Linux distribution, somewhat Linux Standards Base compliant, with a 2.4 or 2.6 kernel and the appropriate tool chain for compiling out-of-tree kernel modules. Most recent Linux distributions are usable out of the box, but some development packages must be installed. For more information, see Compatibility.

   	− A fairly LSB compliant GNU/Linux distribution.3
   	− Linux 2.4 kernel (2.4.10 - 2.4.27), or
   	− Linux 2.6 kernel (2.6.3 - 2.6.21);
   	− glibc2 or better.
   	− GNU info (for info files).
   	− GNU groff (for man pages).4

(Note: If you acquired strsock a part of the OpenSS7 Master Package, then the dependencies listed below will already have been met by unpacking the master package.)

2. OpenSS7 Linux Fast-STREAMS, streams-0.9.2.3. ⁵
3. OpenSS7 STREAMS Compatibility Modules, strcompat-0.9.2.6.
4. OpenSS7 STREAMS XNS, strxns-0.9.2.6.
5. OpenSS7 STREAMS XTI/TLI, strxnet-0.9.2.11.

When configuring and building multiple OpenSS7 Project release packages, place all of the source packages (unpacked tarballs) at the same directory level and all build directories at the same directory level (e.g. all source packages under /usr/src).

When installing packages that install as kernel modules, it is necessary to have the correct kernel development package installed. For the following distributions, use the following commands:

     Ubuntu:  $> apt-get install linux-headers
     Debian:  $> apt-get install kernel-headers
     Fedora:  $> yum install kernel-devel

You also need the same version of gcc(1) compiler with which the kernel was built. If it is not the default, add `CC=kgcc' on the line after `./configure', for example:

     $> ../strsock-0.9.2.3/configure CC='gcc-3.4'

Installation

The following commands will download, configure, build, check, install, validate, uninstall and remove the package:

     $> wget http://www.openss7.org/tarballs/strsock-0.9.2.3.tar.bz2
     $> tar -xjvf strsock-0.9.2.3.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../strsock-0.9.2.3/configure --enable-autotest
     $> make
     $> make check
     $> sudo make install
     $> sudo make installcheck
     $> sudo make uninstall
     $> popd
     $> sudo rm -rf build
     $> rm -rf strsock-0.9.2.3
     $> rm -f strsock-0.9.2.3.tar.bz2

If you have problems, try building with the logging targets instead. If the make of a logging target fails, an automatic problem report will be generated that can be mailed to The OpenSS7 Project.⁶ Installation steps using the logging targets proceed as follows:

     $> wget http://www.openss7.org/tarballs/strsock-0.9.2.3.tar.bz2
     $> tar -xjvf strsock-0.9.2.3.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../strsock-0.9.2.3/configure --enable-autotest
     $> make compile.log
     $> make check.log
     $> sudo make install.log
     $> sudo make installcheck.log
     $> sudo make uninstall.log
     $> popd
     $> sudo rm -rf build
     $> rm -rf strsock-0.9.2.3
     $> rm -f strsock-0.9.2.3.tar.bz2

See README-make for additional specialized make targets.

For custom applications, see the INSTALL and INSTALL-strsock files or the see Installation, as listed below. If you encounter troubles, see Troubleshooting, before issuing a bug report.

Brief Installation Instructions

The OpenSS7 STREAMS Sockets package is available from the downloads area of The OpenSS7 Project website using a command such as:

     $> wget http://www.openss7.org/tarballs/strsock-0.9.2.3.tar.bz2

Unpack the tarball using a command such as:

     $> tar -xjvf strsock-0.9.2.3.tar.bz2

The tarball will unpack into the relative subdirectory named after the package name: strsock-0.9.2.3.

The package builds using the GNU autoconf utilities and the configure script. To build the package, we recommend using a separate build directory as follows:

     $> mkdir build
     $> cd build
     $> ../strsock-0.9.2.3/configure

In general, the package configures and builds without adding any special options to the configure script. For general options to the configure script, see the GNU INSTALL file in the distribution:

     $> less ../strsock-0.9.2.3/INSTALL

For specific options to the configure script, see the INSTALL-strsock file in the distribution, or simply execute the configure script with the --help option like so:

     $> ../strsock-0.9.2.3/configure --help

After configuring the package, the package can be compiled simply by issuing the `make' command:

     $> make

Some specialized makefile targets exists, see the README-make file in the distribution or simply invoke the `help' target like so:

     $> make help | less

After successfully building the package, the package can be checked by invoking the `check' make target like so:

     $> make check

After successfully checking the package, the package can be installed by invoking the `install' make target (as root) like so:

     $> sudo make install

The test suites that ship with the package can be invoked after the package has been installed by invoking the `installcheck' target. This target can either be invoked as root, or as a normal user, like so:

     $> make installcheck

(Note: you must add the --enable-autotest flag to configure, above for the test suites to be invoked with `make installcheck'.)

The package can be cleanly removed by invoking the `uninstall' target (as root):

     $> sudo make uninstall

Then the build directory and tarball can be simply removed:

     $> cd ..
     $> rm -rf build
     $> rm -rf strsock-0.9.2.3
     $> rm -f strsock-0.9.2.3.tar.bz2

Detailed Installation Instructions

More detailed installation instructions can be found in the Installation, contained in the distribution in `text', `info', `html' and `pdf' formats:

     $> cd ../strsock-0.9.2.3
     $> less doc/manual/strsock.txt
     $> lynx doc/manual/strsock.html
     $> info doc/manual/strsock.info
     $> xpdf doc/manual/strsock.pdf

The `text' version of the manual is always available in the MANUAL file in the release.

The current manual is also always available online from The OpenSS7 Project website at:

     $> lynx http://www.openss7.org/strsock_manual.html

1 Introduction

This manual documents the design, implementation, installation, operation and future development schedule of the OpenSS7 STREAMS Sockets package.

1.1 Overview

This manual documents the design, implementation, installation, operation and future development of the OpenSS7 STREAMS Sockets package.

1.2 Organization of this Manual

This manual is organized (loosely) into several sections as follows:

1.3 Conventions and Definitions

This manual uses texinfo typographic conventions.

2 Objective

The objective of the OpenSS7 STREAMS Sockets package is to provide Sockets capability for STREAMS in a similar manner as provided by SVR 4.2 and later Solaris implementations. To accomplish this there are three (3) approaches that can be taken to implementing Sockets over STREAMS:

2.1 Socket Module

This approach implements the SVR 4.2 sockmod(4) module and cooperating libsocket(3) library. The library and cooperating STREAMS module behave in a similar fashion to the libxnet(3) library and timod(4) module for XTI.

There are a set of input-output controls defined for sockets (explicitly for compatibility with SVR 4.2) that can be accepted by the sockmod(4) module. These input-output controls permit direct conversion between sockets function and kernel-space facilities.

The original sockmod(4) approach keep much of the socket state in user space in the fashion of xti(3); however, this approach is just asking for trouble. Also, Linux also implements the SVR 4.2 input-output controls for native Sockets and the resulting libsocket(3) library would then work for both STREAMS-based sockets and Linux native sockets.

Socket input-output controls defined for SVR 4.2 are:

2.2 Socket System

This approach implements the SVR 4.2 socksys(4) driver. Opening Streams via the socksys(4) driver causes them to be transformed into native Sockets against which standard libc socket system calls are sufficient. For compatibility with the sockmod(4) approach, the pushing the sockmod(4) module can be made to cause the same effect.

Before Linux Fast-STREAMS was developed, taking this approach was next to impossible due to the obfuscated nature and non-standard behaviour of the LiS Stream head. Now that LiS is completely deprecated, this approach is now possible.

SVR 4.2 behaviour for the Stream head dictates that it respond to both termio(7) and sockio(7) input-output controls in addition to
streamio(7) controls. That is, each Stream head can be a fifo(4), a pipe(4), a tty(4), a socket or a stream. LiS never followed this behaviour: Linux Fast-STREAMS was built with it from the start.

Socket input-output controls recognized and intercepted by the Linux Fast-STREAMS Stream head are:

Additional Sockets input-output controls are passed to the Stream as TRANSPARENT or I_STR(7) (see streamio(7)) input-output controls.

2.3 Socket Integration

With this approach, Streams that are usable for sockets are given the IF_SOCK attribute during registration. The Stream head is aware of this and creates a socket structure for each Stream head opened for the driver.

2.4 Solaris Approaches

The following is reprinted from an article in UNIX® Insider issue `3/9/01' written by Jim Mauro.

Prior to Solaris 2.6, sockets were an abstraction that existed at the library level. That is, much of the socket state and socket semantics support were provided with the libsocket library. The kernel's view of a process's socket connection entailed a file descriptor and linkage to a Stream head, which provided the path to the underlying transport. The disparity between the library socket state and the kernel's view was one of several reasons a new implementation was introduced in Solaris 2.6.

To provide a relevant basis for comparison, we will start by looking at what happens in the pre-Solaris 2.6 release (this is, releases up to and including Solaris 2.5.1) when a socket is created. The major software layers are shown in Figure XXX for reference.

The primary software components are the socket library and the sockmod(4) STREAMS module. The specfs(5) layer is shown for completeness and is part of the layering, due to the use of pseudo-devices as an entry point into the networking layers. To digress for a moment, the special file system, specfs(5) came out of SVR 4 UNIX® as a means of addressing the issue of device special files that exist on UNIX® on-disk file systems (e.g. UFS). UNIX® system have always abstracted I/O (input/output) devices through device special files. The /dev directory name space stores files that represent physical devices and pseudo-devices on the system. Using device major numbers, those device files provide an entry point into the appropriate device driver, and using minor numbers, they are able to uniquely identify one of potentially many devices of the same type. (That is something of an oversimplification, but it is sufficient for our purpose here in describing specfs(5)).

The /dev directory resides on the root file system, which is an instance of UFS. As such, references to the file system and its files and directories are handed using the UFS file system operations and UFS file operations. That is usually sufficient, but not desired behaviour for device special files. I/O to a device special file requires entry into a device driver. That is, issuing an open(2) system call on /dev/rmt/0 means someone wishes to open the tape device represented by /dev/rmt/0, thereby entering the appropriate driver's xx_open() routine. As a file on a UFS file system, the typical open routine called would be the ufs_open() code, but that is not what we want for devices. The specfs(5) file system was designed to address such situations; it provides a straightforward mechanism for linking the underlying structures for file support in the kernel to the required device driver interfaces. Like all file systems in Solaris (and any SVR4-based UNIX®) it is based on the VFS/vnode infrastructure. (See Solaris Internals and UNIX® Internals in the Resources section for detailed information on VFS.)

Getting back to sockets in Solaris 2.5.1, the specfs(5) layer comes into play because the socket open ultimately results in an open(2) system call issued on the tcp(4) or udp(4) pseudo-device. More precisely, the socket library passes the arguments given to the socket(3) call to a lookup function that searches an internal (internal to libsocket.so) array to match the domain argument and retrieve a corresponding character string. It then uses the character string to find a match in the /etc/netconfig file, which is used for transport selection and describes all the available transport protocols in Solaris. (See netconfig(5).) This transport selection mechanism is an essential part of a network programming implementation; it allows for the interfaces to be protocol-independent, so the programmer is not required to maintain a different source base for Ethernet-based networks versus FDDI-based networks, etc.

A netconfig(5) data structure (defined in /usr/include/sys/netconfig.h) is populated based on the line entries in /etc/netconfig that match the domain (as per the character string retrieved from the internal table), type, and protocol family specified in the socket(3) call. Among the netconfig(5) parameters, a device is defined that provides the entry point into the transport provider kernel module. For example, a call to `socket(AF_INET, SOCK_STREAM, 0)' indicates an Internet transport that provides reliable, connection-oriented behaviour is desired. The TCP layer of the TCP/IP protocol family provides such a service, and the /etc/netconfig entry defines `/dev/tcp' as the device to open for entry into that transport layer. The socket library code will issue an open(2) on `/dev/tcp' accordingly. If one were developing a network-based application using the X/Open Transport Interface (XTI) – a superset of what was the Transport Layer Interface (TLI) – the t_open(3) call would receive the `/dev/tcp' argument explicitly for a connection using TCP as a transport protocol.

The block sitting below the specfs(5) in Figure XXX, the Stream head, is a generic part of a STREAMS-based communication path. The Stream head is created when a STREAMS device is opened. In Figure XXX, the open(2) to the `/dev/tcp' transport layer, which is a STREAMS device, resulted in the creation of the Stream head. The Stream head translates the interface calls made by the socket library into STREAMS messages (the STREAMS framework is message-based and uses queues to move data downstream [from the user process to the STREAMS driver] and upstream [from the driver to the user process]). The STREAMS facility provides for the insertion (pushing) and removal (popping) of STREAMS modules in the data flow, between the Stream head and the underlying driver. Each module implements a set of queues – a read queue and a write queue – for processing the data and messages. The generic picture is shown in Figure YYY.

In the context of Solaris 2.5.1 sockets, the STREAMS module shown in Figure YYY is a kernel sockmod(4) module (located in the /kernel/strmod directory). sockmod(4) provides, in conjunction with libsocket.so, support for socket semantics using the STREAMS facility. That is, socket calls are handled initially by the socket library, then passed down to the Stream head, which transforms the calls into STREAMS messages and passes them down to sockmod(4). Upstream messages are passed from the underlying device driver and transport provider through sockmod(4) and back up to the process. Thus, the functions contained in the sockmod(4) module include STREAMS queue reading and writing in the form of queue `read put' and `write put' code for moving data up and down the Stream as data is read and written from the socket. The sockmod(4) module communicates with the underlying transport using primitives and structures defines in the /usr/include/sys/tihdr.h header file.

The socket state maintained at the library level is in the form of a library-internal data structure, _si_user, which maintains various bits of information about the socket, and is what the internal socket create function returns on a socket call. Yes, it is the file descriptor that represents the socket that is returned to the user code _si_user is visible only to the library. You will find the structure definition for _si_user and associated structures that it links to (si_udata and si_sockparams) in /usr/include/sys/sockmod.h. If you look at the structure definition, you will see that the _si_user embeds the si_udata and si_sockparams structures, which maintain stat information (e.g. connected, bound), socket options (accept connection), information on the transport provider (e.g. service type), and family, type, and protocol used for the socket.

At the sockmod(4) layer, a socket is internally represented in the so_so data structure. Fields of interest there include an embedded ti_info structure (/usr/include/sys/tiuser.h) that manages transport provider information, a network buffer (netbuf) for data transfer, a si_udata structure that replicates the socket state (among other things), and message blocks (mblk_t), which are the basic unit of communication across STREAMS.

In Solaris 2.6, we did away with the sockmod(4) STREAMS module and trimmed a lot of code from libsocket. Most of the socket-related library interfaces result in system call traps into the kernel, without any library-level code executing. A few of the interfaces (socket(3) and sockpair(3)) execute some library-level code before entering the kernel. However, all the state information is maintained in the kernel, where it belongs. This creates a nice visibility feature – we can now see file descriptors that represent sockets.

          sunsys> uname -a
          SunOS sunsys 5.8 Generic_108528-01 sun4u sparc SUNW, Ultra-60
          sunsys> srv &
          [1]     7153
          Socket port: # 34940
          Send bug: 16384, Rcv buf: 24576
          
          sunsys> pfiles 7153
          7153:   srv
            Current rlimit: 1024 file descriptors
             0: S_IFCHR mode:0620 dev:32,0 ino:91176 uid:19822 gid:7 rdev:24,14
                O_RDWR|O_LARGEFILE
             1: S_IFCHR mode:0620 dev:32,0 ino:91176 uid:19822 gid:7 rdev:24,14
                O_RDWR|O_LARGEFILE
             2: S_IFCHR mode:0620 dev:32,0 ino:91176 uid:19822 gid:7 rdev:24,14
                O_RDWR|O_LARGEFILE
             3: S_IFSOCK mode:0666 dev:186,0 ino:63137 uid:0 gid:0 size:0
                O_RDWR
                  sockname: AF_INET 0.0.0.0  port: 34940
          sunsys>
     

In the above example, a simple TCP socket server process is started (srv, PID 7153). (The `Socket port' and `Send buf' lines are output from the srv process when it starts.) Using the pfiles(1) command to dump the process's open file descriptors, we see that the file descriptor is identified as a socket, and we even get the socket type (AF_INET) and port number. (The freeware command, lsof(1), is a great utility for extracting process file descriptor information if you are on an older Sun OS that does not have pfiles(1). You can get lsof(1) from ftp://vic.cc.purdue.edu/pub/tools/unix/lsof/.)

The libsocket changes associated with sockfs(5) maintain the documented interfaces. Both source and binary compatibility are maintained, as socket code compiled on early version of Solaris should work without recompilation on Solaris 6 and later releases. Source code should move over and recompile with no changes as well.

The trimming down of the library-level socket code required providing a new means to map the domain type passed as an argument to socket(3) to facility lookup in /etc/netconfig. Recall that the Solaris 2.5.1 socket library did this using an internal table. In Solaris 6 and later, a new configuration file and command is introduced to provide that functionality. The /etc/sock2path contains the necessary information to map the socket(3) call parameters to the appropriate transport provider and device. A new command, soconfig(8), is used to maintain /etc/sock2path. It is executed automatically at boot time via an entry in the /etc/inittab file. Reference the sock2path(4) and soconfig(8) manual pages for specifics. For most applications, the default entries in sock2path(5) are sufficient.

As a file system (pseudo-file system), sockfs(5) implements the generic VFS/vnode related support structures and exports the required file-system-specific functions. However, the entry into the sockfs(5)-specific functions does not necessarily follow the typical flow of a regular file open, which is vectored to the file-type-specific function through the use of macros and an operations table. That is, the issuing of an open(2) system call on a file enters a generic vnode code path and ultimately resolves through a VOP_OPEN() macro to the appropriate file-system-specific open code (e.g. ufs_open for a file an a UFS file system).

Sockets are created an opened using the socket(3) API. A call to socket(3) from user code enters the libsocket library, which handles the mapping to the transport provider device, then enters the sockfs(5) kernel module through an internal so_create() system call. The sock_open() (file system specific open routine) is invoked through the so_create() call, which is how other necessary create functions, such as an initialization function for the socket Stream, are called.

Other conventional system calls, such as read(2) or write(2) on a socket, are vectored into the sockfs(5) specific read and write code (sock_read() and sock_write()) through the standard VFS/vnode mechanism. Once entered, the sockfs(5) read/write code makes lower-level calls into the sockfs(5) subsystem designed to interface with the transport provider. For example, a read(2) system call on a socket vectors into sock_read(), which does some basic housekeeping and calls an internal sorecvmsg() (socket receive message) function. In sorecvmsg(), socket stat is tested and the request is moved downstream via a call to the STREAMS get-message function.

The most compelling part of the sockfs(5) implementation is that consolidation of all socket stat information is in a single structure, maintained in one place: the kernel. Sockets are represented internally as a sonode, defined in /usr/include/sys/socketvar.h. All operations on a sonode take place within the kernel sockfs(5) subsystem, isolating state changes and eliminating the need to replicate state for consistency.

3 Reference

3.1 Files

STRSOCK creates the following kernel modules files in the kernel modules directory, /lib/modules/2.4.20-28.7/:⁷

modules.strsock

STRSOCK installs the following kernel module files in the k