paper, section 7.

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:

#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 */

A call on the user request routine is of the form,

error = (*protosw[].pr_usrreq)(so, req, m, addr, rights);
int error; struct socket *so; int req; struct mbuf *m, *addr, *rights;

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.

PRU_ATTACH: 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.
PRU_DETACH: 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.
PRU_BIND: 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.
PRU_LISTEN: 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.
PRU_CONNECT: 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.
PRU_ACCEPT: 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 connected party.
PRU_DISCONNECT: Eliminate an association created with a PRU_CONNECT request.
PRU_SHUTDOWN: 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.
PRU_RCVD: 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.
PRU_SEND: 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).
PRU_ABORT: This request indicates an abnormal termination of service. The protocol should delete any existing association(s).
PRU_CONTROL: 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.
PRU_SENSE: 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.
PRU_RCVOOB: 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.
PRU_SENDOOB: Like PRU_SEND, but for out-of-band data.
PRU_SOCKADDR: 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.
PRU_PEERADDR: 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.
PRU_CONNECT2: 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 socketpair(2) system call.

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).

PRU_FASTTIMO: 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.
PRU_SLOWTIMO: 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.
PRU_PROTORCV: 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.
PRU_PROTOSEND: 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.