7. Socket/protocol interface
The interface between the socket routines and the communication
protocols is through the pr_usrreq routine defined in the
protocol switch table. The following requests to a protocol
module are possible:
A call on the user request routine is of the form,
#define PRU_ATTACH 0 /* attach protocol */
#define PRU_DETACH 1 /* detach protocol */
#define PRU_BIND 2 /* bind socket to address */
#define PRU_LISTEN 3 /* listen for connection */
#define PRU_CONNECT 4 /* establish connection to peer */
#define PRU_ACCEPT 5 /* accept connection from peer */
#define PRU_DISCONNECT 6 /* disconnect from peer */
#define PRU_SHUTDOWN 7 /* won't send any more data */
#define PRU_RCVD 8 /* have taken data; more room now */
#define PRU_SEND 9 /* send this data */
#define PRU_ABORT 10 /* abort (fast DISCONNECT, DETATCH) */
#define PRU_CONTROL 11 /* control operations on protocol */
#define PRU_SENSE 12 /* return status into m */
#define PRU_RCVOOB 13 /* retrieve out of band data */
#define PRU_SENDOOB 14 /* send out of band data */
#define PRU_SOCKADDR 15 /* fetch socket's address */
#define PRU_PEERADDR 16 /* fetch peer's address */
#define PRU_CONNECT2 17 /* connect two sockets */
/* begin for protocols internal use */
#define PRU_FASTTIMO 18 /* 200ms timeout */
#define PRU_SLOWTIMO 19 /* 500ms timeout */
#define PRU_PROTORCV 20 /* receive from below */
#define PRU_PROTOSEND 21 /* send to below */
The mbuf data chain m is supplied for output operations
and for certain other operations where it is to receive a result.
The address addr is supplied for address-oriented requests
such as PRU_BIND and PRU_CONNECT.
The rights parameter is an optional pointer to an mbuf
chain containing user-specified capabilities (see the sendmsg
and recvmsg system calls). The protocol is responsible for
disposal of the data mbuf chains on output operations.
A non-zero return value gives a
UNIX error number which should be passed to higher level software.
The following paragraphs describe each
of the requests possible.
error = (*protosw.pr_usrreq)(so, req, m, addr, rights);
int error; struct socket *so; int req; struct mbuf *m, *addr, *rights;
When a protocol is bound to a socket (with the socket
system call) the protocol module is called with this
request. It is the responsibility of the protocol module to
allocate any resources necessary.
The ``attach'' request
will always precede any of the other requests, and should not
occur more than once.
This is the antithesis of the attach request, and is used
at the time a socket is deleted. The protocol module may
deallocate any resources assigned to the socket.
When a socket is initially created it has no address bound
to it. This request indicates that an address should be bound to
an existing socket. The protocol module must verify that the
requested address is valid and available for use.
The ``listen'' request indicates the user wishes to listen
for incoming connection requests on the associated socket.
The protocol module should perform any state changes needed
to carry out this request (if possible). A ``listen'' request
always precedes a request to accept a connection.
The ``connect'' request indicates the user wants to a establish
an association. The addr parameter supplied describes
the peer to be connected to. The effect of a connect request
may vary depending on the protocol. Virtual circuit protocols,
such as TCP [Postel81b], use this request to initiate establishment of a
TCP connection. Datagram protocols, such as UDP [Postel80], simply
record the peer's address in a private data structure and use
it to tag all outgoing packets. There are no restrictions
on how many times a connect request may be used after an attach.
If a protocol supports the notion of multi-casting, it
is possible to use multiple connects to establish a multi-cast
group. Alternatively, an association may be broken by a
PRU_DISCONNECT request, and a new association created with a
subsequent connect request; all without destroying and creating
a new socket.
Following a successful PRU_LISTEN request and the arrival
of one or more connections, this request is made to
indicate the user
has accepted the first connection on the queue of
pending connections. The protocol module should fill
in the supplied address buffer with the address of the
Eliminate an association created with a PRU_CONNECT request.
This call is used to indicate no more data will be sent and/or
received (the addr parameter indicates the direction of
the shutdown, as encoded in the soshutdown system call).
The protocol may, at its discretion, deallocate any data
structures related to the shutdown and/or notify a connected peer
of the shutdown.
This request is made only if the protocol entry in the protocol
switch table includes the PR_WANTRCVD flag.
When a user removes data from the receive queue this request
will be sent to the protocol module. It may be used to trigger
acknowledgements, refresh windowing information, initiate
data transfer, etc.
Each user request to send data is translated into one or more
PRU_SEND requests (a protocol may indicate that a single user
send request must be translated into a single PRU_SEND request by
specifying the PR_ATOMIC flag in its protocol description).
The data to be sent is presented to the protocol as a list of
mbufs and an address is, optionally, supplied in the addr
parameter. The protocol is responsible for preserving the data
in the socket's send queue if it is not able to send it immediately,
or if it may need it at some later time (e.g. for retransmission).
This request indicates an abnormal termination of service. The
protocol should delete any existing association(s).
The ``control'' request is generated when a user performs a
UNIX ioctl system call on a socket (and the ioctl is not
intercepted by the socket routines). It allows protocol-specific
operations to be provided outside the scope of the common socket
interface. The addr parameter contains a pointer to a static
kernel data area where relevant information may be obtained or returned.
The m parameter contains the actual ioctl request code
(note the non-standard calling convention).
The rights parameter contains a pointer to an ifnet structure
if the ioctl operation pertains to a particular network interface.
The ``sense'' request is generated when the user makes an fstat
system call on a socket; it requests status of the associated socket.
This currently returns a standard stat structure.
It typically contains only the
optimal transfer size for the connection (based on buffer size,
windowing information and maximum packet size).
The m parameter contains a pointer
to a static kernel data area where the status buffer should be placed.
Any ``out-of-band'' data presently available is to be returned. An
mbuf is passed to the protocol module, and the protocol
should either place
data in the mbuf or attach new mbufs to the one supplied if there is
insufficient space in the single mbuf.
An error may be returned if out-of-band data is not (yet) available
or has already been consumed.
The addr parameter contains any options such as MSG_PEEK
to examine data without consuming it.
Like PRU_SEND, but for out-of-band data.
The local address of the socket is returned, if any is currently
bound to it. The address (with protocol specific format) is returned
in the addr parameter.
The address of the peer to which the socket is connected is returned.
The socket must be in a SS_ISCONNECTED state for this request to
be made to the protocol. The address format (protocol specific) is
returned in the addr parameter.
The protocol module is supplied two sockets and requested to
establish a connection between the two without binding any
addresses, if possible. This call is used in implementing
The following requests are used internally by the protocol modules
and are never generated by the socket routines. In certain instances,
they are handed to the pr_usrreq routine solely for convenience
in tracing a protocol's operation (e.g. PRU_SLOWTIMO).
A ``fast timeout'' has occurred. This request is made when a timeout
occurs in the protocol's pr_fastimo routine. The addr
parameter indicates which timer expired.
A ``slow timeout'' has occurred. This request is made when a timeout
occurs in the protocol's pr_slowtimo routine. The addr
parameter indicates which timer expired.
This request is used in the protocol-protocol interface, not by the
routines. It requests reception of data destined for the protocol and
not the user. No protocols currently use this facility.
This request allows a protocol to send data destined for another
protocol module, not a user. The details of how data is marked
``addressed to protocol'' instead of ``addressed to user'' are
left to the protocol modules. No protocols currently use this facility.