socksys.4.man

This a separate release of the OpenSS7 X/Open XTI/TLI library, TLI modules (timod, tirdwr) and the I

'\" rtp
.\" -*- nroff -*- vim: ft=nroff noautoindent nocindent nosmartindent
.\"
.\" @(#) socksys.4.man,v 1.1.2.1 2004/05/16 02:35:40 brian Exp
.\"
.\" =========================================================================
.\"
.\" Copyright (C) 2001-2004  OpenSS7 Corporation <www.openss7.com>
.\"
.\" All Rights Reserved.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" -------------------------------------------------------------------------
.\"
.\" 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 success
.\" regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
.\" NASA Supplement to the FAR (or any successor regulations).
.\"
.\" =========================================================================
.\" 
.\" Commercial licensing and support of this software is available from
.\" OpenSS7 Corporation at a fee.  See http://www.openss7.com/
.\" 
.\" =========================================================================
.\"
.\" Last Modified 2004/05/16 02:35:40 by brian
.\"
.\" =========================================================================
.so strxnet.macros
.R1
bracket-label "\fR[\fB" "\fR]" "\fR, \fB"
no-default-database
database strxnet.refs
accumulate
move-punctuation
abbreviate A
join-authors ", " ", " " and "
et-al " et al" 2 3
abbreviate-label-ranges ".."
sort-adjacent-labels
.R2
.\"
.\"
.TH SOCKSYS 4 "2004/05/16 02:35:40" "strxnet-0_9_2-4" "Linux Fast-STREAMS Devices"
.\"
.\"
.SH NAME
.B socksys
\- socket systems driver
.\"
.\"
.SH SYNOPSIS
.PP
.B #include <sys/sockets.h>
.sp
.BI int " fd" " = open(" \*(lq/dev/socksys\*(rq ", " flags );
.\"
.\"
.SH DESCRIPTION
.PP
The
.B socksys
driver is a
.IR STREAMS (4)
based pseudo-driver which provides a set of I/O controls that provide socket
compatible interface to
.IR STREAMS (4)
drivers based on the Transport Provider Interface
.[
TPI Revision 2.0.0
.]
(see
.BR tpi (7)).
.\"
.\"
.SH IOCTLS
.PP
These ioctls can be accessed using
.BR ioctl (2):
.RS
.HP
.BI "int " retval " = ioctl(" socket ", " cmd ", " arg );
.RE
.SS SIOCSHIWAT
.PP
Sets the high water mark.
.I arg
is an integer number of octets.
.SS SIOCGHIWAT
.PP
Gets the high water mark.
.I arg
is a pointer to an integer that will return the high water mark as an integer
number of octets.
.SS SIOCSLOWAT
.PP
Sets the low water mark.
.I arg
is an integer number of octets.
.SS SIOCGLOWAT
.PP
Gets the low water mark.
.I arg
is a pointer to an integer that will return the low water mark as an integer
number of octets.
.SS SIOCATMARK
.PP
This performs the same function as the
.B I_ATMARK
command described under
.BR streamio (7s).
This control returns true when all the urgent data has been already received
by the user program.
.I arg
is a pointer to an integer that will return the integer test result.
.SS SIOCSPGRP or FIOCSPGRP
.PP
Sets the process group id for the socket.
.I arg
is an integer
.B gid_t
process number.
.SS SIOCGPGRP or FIOCGPRGP
.PP
Gets the process group id for the socket.
.I arg
is a pointer to an integer to hold the
.B gid_t
result.
.SS FIONREAD or TIOCINQ
.PP
Returns the amount of queued unread data on the read queue.
.I arg
is a pointer to an integer that will hold the result in octets.
.SS TIOCOUTQ
.PP
Returns the amount of queue unsent data on the write queue.
.I arg
is a pointer to an integer that will hold the result in octets.
.SS FIONBIO
.PP
.SS SIOCPROTO
.PP
Set a protocol.
.I arg
is a pointer to a
.B socknewproto
structure formatted as follows:
.sp
.nf
\fC\s-1\
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 */
};
\fR\s+1
.fi
.TP
.I family
Specifies the address family or protocol family.
.TP
.I type
Specifies the
.BR socket (3)
type.  Socket type can be one of the following:
.RS
.TP
.B SOCK_STREAM
.TP
.B SOCK_DGRAM
.TP
.B SOCK_SEQPACKET
.TP
.B SOCK_RDM
.TP
.B SOCK_RAW
.TP
.B SOCK_PACKET
.RE
.TP
.I proto
Specifies the protocol number within the protocol family.  This number is
protocol family specific.  For example, for IP protocols, this could be
.BR IPPROTO_TCP .
.TP
.I dev
The device number of the real device for the
.B socksys
pseudo-driver to open.  This must be a clone device in that it must assign new
major or minor numbers upon
.BR qopen (9).
.TP
.I flags
Protocol switch table flags.
.SS SIOCGETNAME
.PP
Gets the name associated with the socket.
.I arg
is a pointer to a
.B sockaddr
structure that will hold the returned address.
.SS SIOCGETPEER
.PP
Gets the peer name associated with the socket.
.I arg
is a pointer to a
.B sockaddr
structure that will hold the returned address.
.SS SIOCXPROTO
.PP
Empty the
.B socksys
protocol table.
.I arg
is ignored.

.SS SIOCSOCKSYS
.PP
.PP
This I/O control provided by the
.B socksys
driver is intended to be used by the
.BR socket (3)
library and should normally be accessed by that library.
.I arg
is a pointer to a
.B socksysreq
structure that is formatted as follows:
.sp
.nf
\fC\s-1\
struct socksysreq {
    long args[7];               /* arguments */
};
\fR\s+1
.fi
.TP
.I args[0]
Contains the
.B socksys
command.  The
.B socksys
command is one of the following values:
.RS
.PP
.TS
tab(:);
lll.
\fBCommand\fR:\fBlibsocket\fR:\fBlibc\fR
_
SO_SOCKET:\fBsocket\fR(3):\(em
SO_ACCEPT:\fBaccept\fR(3):\fBaccept\fR(2)
SO_BIND:\fBbind\fR(3):\fBbind\fR(2)
SO_CONNECT:\fBconnect\fR(3):\fBconnect\fR(2)
SO_GETPEERNAME:\fBgetpeername\fR(3):\fBgetpeername\fR(2)
SO_GETSOCKNAME:\fBgetsockname\fR(3):\fBgetsockname\fR(2)
SO_GETSOCKOPT:\fBgetsockopt\fR(3):\fBgetsockopt\fR(2)
SO_LISTEN:\fBlisten\fR(3):\fBlisten\fR(2)
SO_RECV:\fBrecv\fR(3):\fBrecv\fR(2)
SO_RECVFROM:\fBrecvfrom\fR(3):\fBrecvfrom\fR(2)
SO_SEND:\fBsend\fR(3):\fBsend\fR(2)
SO_SENDTO:\fBsendto\fR(3):\fBsendto\fR(2)
SO_SETSOCKOPT:\fBsetsockopt\fR(3):\fBsetsockopt\fR(2)
SO_SHUTDOWN:\fBshutdown\fR(3):\fBshutdown\fR(2)
SO_GETIPDOMAIN:\(em:\fBgetipdomain\fR(2)
SO_SETIPDOMAIN:\(em:\fBsetipdomain\fR(2)
SO_SETREUID:\(em:\fBsetreuid\fR(2)
SO_SETREGID:\(em:\fBsetregid\fR(2)
SO_GETTIME:\(em:\fBgettime\fR(2)
SO_SETTIME:\(em:\fBsettime\fR(2)
SO_GETITIMER:\(em:\fBgetitimer\fR(2)
SO_SETITIMER:\(em:\fBsetitimer\fR(2)
SO_SELECT:\(em:\fBselect\fR(2)
SO_ADJTIME:\(em:\fBadjtimex\fR(2)
SO_RECVMSG:\fBrecvmsg\fR(3):\fBrecvmsg\fR(2)
SO_SENDMSG:\fBsendmsg\fR(3):\fBsendmsg\fR(2)
SO_SOCKPAIR:\fBsocketpair\fR(3):\fBsocketpair\fR(2)
.TE
.RE
.TP
.I args[1]
For the emulated
.BR socket (7)
commands listed above, the first argument in the argument list is alway the
file descriptor associated with the socket.
.TP
.I args[2] ... args[6]
The remaining arguments depend upon the
.BR socket (7)
call.  See the appropriate
.BR socket (7)
call in section 2 or 3 listed above.
.PP
The
.B socksys
socket commands above implement the
.BR socket (7)
calls on
Transport Provider Interface
.RB ( tpi (7))
based
.IR STREAMS (4).
These socket calls are made accessible on both
.IR STREAMS (4)
and the Linux NET4
.BR socket (7)
implementation simultaneously by including the
.BR libsocket (3)
library when compiling as follows:
.RS
.HP
.BI "gcc -lsocket -o " test_program " " test_program.c
.RE
.PP
Although the set of BSD-compatible
.B socksys
calls that are implemented in
.B libc
are not implemented in
.BR libsocket (3)
the IO controls are implemented in
.BR socksys ,
for compatability with SVR4.2
.[
svr42
.]
programs that might access these IO controls directly using
.BR ioctl (2).
These IO controls simply call the internal
.B Linux\(rg
system call.
.PP
The only
.B socksys
command that is used by the
.BR libsocket (3)
library is the
.BR socket (3)
system call.  This call is made on an already opened
.IR STREAMS (4)
file descriptor.  When the Linux NET4 implementation of the socket is to be
opened, the
.B socksys
driver transforms the character special device file descriptor into a socket
file descriptor and performs the equivalent of a
.BR sock_create ()
on the requested socket.
This has the effect of providing a wrapper around the Linux
.BR socket (2)
system call, without affecting any other
.BR socket (7)
system calls.
.\"
.\"
.SH NOTICES
.PP
.PP
The
.B socksys
driver is a pseudo-driver in the sense that when the
.B SIOCSOCKSYS
IO control is executed with the
.B SO_SOCKET
command, it converts the
.IR STREAMS (4)
file descriptor from a character special device associated with a stream head,
to a
.BR socket (7)
file descriptor internal to the kernel.  All subsequent
.BR socket (7)
system calls are interfaced directly by the Linux kernel socket code and
internally invokes the
.BR socket (7)
functions also accessible with the
.B SIOCSOCKSYS
IO control.
This technique ensures that the
.BR socket (7)
interface is compatible with all Linux system calls.
.\"
.\"
.SH NOTICES
.PP
.PP
When writing or converting a
.BR tpi (7)
driver for use with the
.B socksys
driver, there are several considerations that must be made in the design and
implementation of the
.BR tpi (7)
driver, as follows:
.SS "ADDRESS FORMAT"
.PP
.IP " 1." 4
The
.B socksys
driver uses the
.B sockaddr
structure to
.BR socket (7)
calls.  Therefore, the
.BR tpi (7)
driver must accept a
.B sockaddr
structure as the transport endpoint address.
.SS "OPTIONS"
.PP
.IP " 2." 4
All
.BR tpi (7)
options will be converted directly into
.BR socket (7)
options without any
modifications.  That is, there must be an identity relationship between
.BR socket (7)
option levels and
.BR tpi (7)
option levels.  Also, there must be an identity relationship between
.BR socket (7)
options and
.BR tpi (7)
options.  The argument format of
.BR socket (7)
options must be the same as the argument format of the
.BR tpi (7)
option.
.IP " 3." 4
All
.BR socket (7)
options using the
.BR getsockopt (3)
and
.BR setsockopt (3)
.BR socket (7)
calls, will generate
.BR T_OPTMGMT_REQ (7)
primitives with the either the
.B T_GET
or
.B T_SET
management flags set.  Socket options passed as an argument to
.BR setsockopt (3)
and
.BR getsockopt (3)
will be passed directly in the
.IR OPT_length " and " OPT_offset
fields of the
.BR T_OPTMGMT_REQ (7)
primitive.
.IP " 4." 4
Options passed as ancilliary data in a control message to
.BR sendmsg (3)
will be directly converted directly into
.BR tpi (7)
options and passed
to
.BR T_OPTDATA_REQ (7)
or
.BR T_UNITDATA_REQ (7)
depending on the mode of the transport service provider.
.IP " 5." 4
.BR tpi (7)
options received in a
.BR T_OPTDATA_IND (7)
or
.BR T_UNITDATA_IND (7)
primtive will be converted directly and passed as an ancillary control message to
.BR recvmsg (7).
.SS IOCTLS
.PP
.IP " 6." 4
All non-socket IO controls will be passed directly to the
.BR tpi (7)
driver.
.IP " 7." 4
.BR tpi (7)
drivers must be installed for use with the
.B socksys
driver using the
.BR SIOCPROTO
IO control.
.SS "ERROR HANDLING"
.PP
.IP " 8." 4
The
.BR tpi (7)
driver must be written to always return a
.IR UNIX \(rg
system error in the
.I UNIX_error
field of the
.BR T_ERROR_ACK (7)
primitive.  This error will be used to set the system error number,
.IR errno (3),
upon error return from
.BR socket (7)
calls.
If the
.I UNIX_error
field is not set to a non-zero value in
.BR T_ERROR_ACK (7),
the
.BR socket (7)
call will return
.RB [ EINVAL ]
only, if
.B socksys
cannot determine a better error number.
.IP " 9." 4
The following
.BR tpi (7)
error numbers returned in the
.I TLI_error
field of the
.BR T_ERROR_ACK (7)
primitive, will return the following
.IR UNIX \(rg
errors when the
.I UNIX_error
field is zero:
.sp
.TS
tab(:);
lblb
lblb.
TPI Error:UNIX\(rg Error
_
TBADADDR:EINVAL
TBADOPT:EINVAL
TACCES:EPERM
TBADF:EBADF
TNOADDR:EADDRNOTAVAIL
TOUTSTATE:EPROTO
TBADSEQ:EIO
TSYSERR:\fIUNIX_error\fB
TBADDATA:EMSGSIZE
TBADFLAG:EINVAL
TNOREL:EOPNOTSUPP
TNOTSUPPORT:EOPNOTSUPP
TBADQLEN:EIO
TADDRBUSY:EADDRINUSE
TPROVMISMATCH:EIO
TRESQLEN:EIO
TRESADDR:EIO
TPROTO:EPROTO
.TE
.SS MISCELLANEOUS
.PP
.IP 10. 4
.BR tpi (7)
drivers will be opened with the
.B CLONEOPEN
flag set.  See
.BR qopen (9).
.\"
.\"
.SH "SEE ALSO"
.PP
.BR sockmod (4),
.BR inet (4).
.\"
.\"
.SH BUGS
.PP
.B socksys
has no known bugs.
.\"
.\"
.SH COMPATIBILITY
.PP
.B /dev/socksys
is compatible with
.IR UnixWare \(rg,
.IR Solaris \(rg
and
.B LiS
.[
LiS
.]
with the following exceptions:
.IP \(em \w'\(em\(em'u
.B LiS
does not provide a usable
.B socksys
driver yet.
.IP \(em
The
.B LiS
stream head should recognize the
.B TIOCINQ
I/O control but it does not.
.IP \(em
The
.B LiS
stream head should recognize this
.B TIOCOUTQ
I/O control but it does not.
.\"
.\"
.SH CONFORMANCE
.PP
XNS 5
.[
xns
.]
.\"
.\"
.SH HISTORY
.PP
.B socksys
first appeared in
SVR 4.
.[
svr4
.]
.\"
.\"
.[
$LIST$
.]
.TI