Manpage of SOCKSYS

SOCKSYS

Section: OpenSS7 STREAMS Sockets Devices (4)
Updated: 2008-10-31
Index Return to Main Contents

NAME

socksys - socket systems driver

SYNOPSIS

int fd = open(``/dev/socksys'', flags);

DESCRIPTION

The socksys driver is a STREAMS(4) based pseudo-driver which provides a set of I/O controls that provide socket compatible interface to STREAMS(4) drivers based on the Transport Provider Interface[1] (see tpi(7)).

USAGE

socksys is not normally opened by a user program: it is opened by the libsocket(3) library as part of the socket(3) or socketpair(3) library calls. Also, none of the input-output controls provided by the driver (with the exception of a few of the sockio(7) input-output controls) are meant to be directly invoked by the user. In particular, the SIOCSOCKSYS input-output control is intended to be used only by the libsocket(3) library to emulate the socket(3) and socketpair(3) system calls.

When the user invokes the socket(3) or socketpair(3) library call, the libsocket(3) library opens the /dev/socksys driver and invokes the SO_SOCKET or SO_SOCKPAIR command. This transforms the open file descriptor into the requested socket using the kernel mapping of socket family, type and protocol into transport provider Stream. The opened transport provider Stream is transformed into a sockfs(5) socket. Subsequent sockets API calls made on the file descriptor directly invoke the associated system calls on the sockfs(5) file descriptor. Internal to the kernel, socksys socket procedures are invoked that translate the socket operations into tpi(7) messages that are exchaged with the underlying Stream.

The remaining input-output controls are provided for backward compatibility to previous library implementations only. In particular, a application compiled against the less capable LiS libsocket(3) must have access to the other SIOCSOCKSYS commands to emulate system calls. See sockmod(4) for more information in this regard.

IOCTLS

These ioctls can be accessed using ioctl(2):

int retval = ioctl(socket, cmd, arg);

SIOCSHIWAT

Sets the high water mark. arg is an integer number of octets.

SIOCGHIWAT

Gets the high water mark. arg is a pointer to an integer that will return the high water mark as an integer number of octets.

SIOCSLOWAT

Sets the low water mark. arg is an integer number of octets.

SIOCGLOWAT

Gets the low water mark. arg is a pointer to an integer that will return the low water mark as an integer number of octets.

SIOCATMARK

This performs the same function as the I_ATMARK command described under streamio(7s). This control returns true when all the urgent data has been already received by the user program. arg is a pointer to an integer that will return the integer test result.

SIOCSPGRP or FIOCSPGRP

Sets the process group id for the socket. arg is an integer gid_t process number.

SIOCGPGRP or FIOCGPRGP

Gets the process group id for the socket. arg is a pointer to an integer to hold the gid_t result.

FIONREAD or TIOCINQ

Returns the amount of queued unread data on the read queue. arg is a pointer to an integer that will hold the result in octets.

TIOCOUTQ

Returns the amount of queue unsent data on the write queue. arg is a pointer to an integer that will hold the result in octets.

FIONBIO

SIOCPROTO

Set a protocol. arg is a pointer to a socknewproto structure formatted as follows:

struct socknewproto {
    int family;                 /* address family */
    int type;                   /* socket type */
    int proto;                  /* protocol number */
    dev_t dev;                  /* real device (must be clone) */
    int flags;                  /* protosw flags */
};

family

Specifies the address family or protocol family. For exampe, this could be AF_INET or PF_INET.

type

Specifies the socket(3) type. Socket type can be one of the following:

SOCK_STREAM	1
SOCK_DGRAM	2
SOCK_SEQPACKET	3
SOCK_RDM	4
SOCK_RAW	5
SOCK_PACKET	10

proto

Specifies the protocol number within the protocol family. This number is protocol family specific. For example, for IP protocols, this could be IPPROTO_TCP.

dev

The device number of the real device for the socksys pseudo-driver to open. This must be a clone device in that it must assign new major or minor numbers upon qopen(9).

flags

Protocol switch table flags.

See soconfig(8) for additional information.

SIOCGETNAME

Gets the name associated with the socket. arg is a pointer to a sockaddr structure that will hold the returned address.

SIOCGETPEER

Gets the peer name associated with the socket. arg is a pointer to a sockaddr structure that will hold the returned address.

SIOCXPROTO

Empty the socksys protocol table. arg is ignored. See soconfig(8) for additional information.

SIOCSOCKSYS

This I/O control provided by the socksys driver is intended to be used by the socket(3) library and should normally be accessed by that library. arg is a pointer to a socksysreq structure that is formatted as follows:

struct socksysreq {
    long args[7];               /* arguments */
};

args[0]

Contains the socksys command. The socksys command is one of the following values:

Command	libsocket	libc

SO_SOCKET	socket(3)	socket(2)
SO_ACCEPT	accept(3)	accept(2)
SO_BIND	bind(3)	bind(2)
SO_CONNECT	connect(3)	connect(2)
SO_GETPEERNAME	getpeername(3)	getpeername(2)
SO_GETSOCKNAME	getsockname(3)	getsockname(2)
SO_GETSOCKOPT	getsockopt(3)	getsockopt(2)
SO_LISTEN	listen(3)	listen(2)
SO_RECV	recv(3)	recv(2)
SO_RECVFROM	recvfrom(3)	recvfrom(2)
SO_SEND	send(3)	send(2)
SO_SENDTO	sendto(3)	sendto(2)
SO_SETSOCKOPT	setsockopt(3)	setsockopt(2)
SO_SHUTDOWN	shutdown(3)	shutdown(2)
SO_GETIPDOMAIN	---	getipdomain(2)
SO_SETIPDOMAIN	---	setipdomain(2)
SO_SETREUID	---	setreuid(2)
SO_SETREGID	---	setregid(2)
SO_GETTIME	---	gettimeofday(2)
SO_SETTIME	---	settimeofday(2)
SO_GETITIMER	---	getitimer(2)
SO_SETITIMER	---	setitimer(2)
SO_SELECT	---	select(2)
SO_ADJTIME	---	adjtimex(2)
SO_RECVMSG	recvmsg(3)	recvmsg(2)
SO_SENDMSG	sendmsg(3)	sendmsg(2)
SO_SOCKPAIR	socketpair(3)	socketpair(2)

args[1]

For the emulated socket(7) commands listed above, the first argument in the argument list is alway the file descriptor associated with the socket.

args[2] ... args[6]

The remaining arguments depend upon the socket(7) call. See the appropriate socket(7) call in section 2 or 3 listed above.

The socksys socket commands above implement the socket(7) calls on Transport Provider Interface (tpi(7)) based STREAMS(4). These socket calls are made accessible on both STREAMS(4) and the Linux NET4 socket(7) implementation simultaneously by including the libsocket(3) library when compiling as follows:

gcc -lsocket -o test_program test_program.c

Although the set of BSD-compatible socksys calls that are implemented in libc are not implemented in libsocket(3) the IO controls are implemented in socksys, for compatability with SVR4.2[2] programs that might access these IO controls directly using ioctl(2). These IO controls simply call the internal Linux® system call.

The only socksys command that is used by the libsocket(3) library is the socket(3) system call. This call is made on an already opened STREAMS(4) file descriptor. When the Linux NET4 implementation of the socket is to be opened, the socksys driver transforms the character special device file descriptor into a socket file descriptor and performs the equivalent of a sock_create() on the requested socket. This has the effect of providing a wrapper around the Linux socket(2) system call, without affecting any other socket(7) system calls.

NOTICES

The socksys driver is a pseudo-driver in the sense that when the SIOCSOCKSYS IO control is executed with the SO_SOCKET command, it converts the STREAMS(4) file descriptor from a character special device associated with a stream head, to a socket(7) file descriptor internal to the kernel. All subsequent socket(7) system calls are interfaced directly by the Linux kernel socket code and internally invokes the socket(7) functions also accessible with the SIOCSOCKSYS IO control. This technique ensures that the socket(7) interface is compatible with all Linux system calls.

NOTICES

When writing or converting a tpi(7) driver for use with the socksys driver, there are several considerations that must be made in the design and implementation of the tpi(7) driver, as follows:

ADDRESS FORMAT

1.: The socksys driver uses the sockaddr structure to socket(7) calls. Therefore, the tpi(7) driver must accept a sockaddr structure as the transport endpoint address.

OPTIONS

2.: All tpi(7) options will be converted directly into socket(7) options without any modifications. That is, there must be an identity relationship between socket(7) option levels and tpi(7) option levels. Also, there must be an identity relationship between socket(7) options and tpi(7) options. The argument format of socket(7) options must be the same as the argument format of the tpi(7) option.
3.: All socket(7) options using the getsockopt(3) and setsockopt(3) socket(7) calls, will generate T_OPTMGMT_REQ(7) primitives with the either the T_CURRENT or T_NEGOTIATE management flags set. Socket options passed as an argument to setsockopt(3) and getsockopt(3) will be passed directly in the OPT_length and OPT_offset fields of the T_OPTMGMT_REQ(7) primitive.
4.: Options passed as ancilliary data in a control message to sendmsg(3) will be directly converted directly into tpi(7) options and passed to T_OPTDATA_REQ(7) or T_UNITDATA_REQ(7) depending on the mode of the transport service provider.
5.: tpi(7) options received in a T_OPTDATA_IND(7) or T_UNITDATA_IND(7) primtive will be converted directly and passed as an ancillary control message to recvmsg(7).

IOCTLS

6.: All non-socket IO controls receive by the socksys driver will be passed directly to the tpi(7) driver.
7.: tpi(7) drivers must be installed for use with the socksys driver using the SIOCPROTO IO control: an entry in the /etc/sock2path file is required.

ERROR HANDLING

8.

The tpi(7) driver must be written to always return a UNIX® system error in the UNIX_error field of the T_ERROR_ACK(7) primitive. This error will be used to set the system error number, errno(3), upon error return from socket(7) calls. If the UNIX_error field is not set to a non-zero value in T_ERROR_ACK(7), the socket(7) call will return [EINVAL] only, if socksys cannot determine a better error number.

9.

The following tpi(7) error numbers returned in the TLI_error field of the T_ERROR_ACK(7) primitive, will return the following UNIX® errors when the UNIX_error field is zero:

TPI Error	UNIX® Error

TBADADDR	EINVAL
TBADOPT	EINVAL
TACCES	EPERM
TBADF	EBADF
TNOADDR	EADDRNOTAVAIL
TOUTSTATE	EPROTO
TBADSEQ	EIO
TSYSERR	*UNIX_error*
TBADDATA	EMSGSIZE
TBADFLAG	EINVAL
TNOREL	EOPNOTSUPP
TNOTSUPPORT	EOPNOTSUPP
TBADQLEN	EIO
TADDRBUSY	EADDRINUSE
TPROVMISMATCH	EIO
TRESQLEN	EIO
TRESADDR	EIO
TPROTO	EPROTO

MISCELLANEOUS

10.: tpi(7) drivers will be opened with the CLONEOPEN flag set. See qopen(9).

BUGS

socksys has no known bugs.

COMPATIBILITY

/dev/socksys is compatible with UnixWare®, Solaris® and LiS[3] with the following exceptions:

---: LiS does not provide a usable socksys driver yet.
---: The LiS stream head should recognize the TIOCINQ I/O control but it does not.
---: The LiS stream head should recognize this TIOCOUTQ I/O control but it does not.

CONFORMANCE

SVID[4], XID[5], XNS 5.2[6], SUSv2[7], SUSv3/POSIX[8],

HISTORY

socksys first appeared in SVR 4[9].

REFERENCES

[1]: TPI Revision 2.0.0, Open Group CAE Specification: Transport Provider Interface (TPI) Specification, Revision 2.0.0, Draft 2, 1999, (Berkshire, UK), OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[2]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[4]: SVID, System V, Interface Definition, Fourth Edition.
[5]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[6]: XNS, Open Group CAE Specification: Technical Standard: Network Services (XNS), Issue 5.2, Draft 2, 1999, (Berkshire, UK), OpenGroup, Open Group Publication. [ISBN 1-85912-241-8] <http://www.opengroup.org/onlinepubs/>
[7]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[8]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[9]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.