1 .\" Copyright (c) 1983, 1986, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)7.t 8.1 (Berkeley) 6/8/93
35 .\".ds RH "Socket/protocol interface
37 \s+2Socket/protocol interface\s0
39 The interface between the socket routines and the communication
40 protocols is through the \fIpr_usrreq\fP routine defined in the
41 protocol switch table. The following requests to a protocol
45 #define PRU_ATTACH 0 /* attach protocol */
46 #define PRU_DETACH 1 /* detach protocol */
47 #define PRU_BIND 2 /* bind socket to address */
48 #define PRU_LISTEN 3 /* listen for connection */
49 #define PRU_CONNECT 4 /* establish connection to peer */
50 #define PRU_ACCEPT 5 /* accept connection from peer */
51 #define PRU_DISCONNECT 6 /* disconnect from peer */
52 #define PRU_SHUTDOWN 7 /* won't send any more data */
53 #define PRU_RCVD 8 /* have taken data; more room now */
54 #define PRU_SEND 9 /* send this data */
55 #define PRU_ABORT 10 /* abort (fast DISCONNECT, DETATCH) */
56 #define PRU_CONTROL 11 /* control operations on protocol */
57 #define PRU_SENSE 12 /* return status into m */
58 #define PRU_RCVOOB 13 /* retrieve out of band data */
59 #define PRU_SENDOOB 14 /* send out of band data */
60 #define PRU_SOCKADDR 15 /* fetch socket's address */
61 #define PRU_PEERADDR 16 /* fetch peer's address */
62 #define PRU_CONNECT2 17 /* connect two sockets */
63 /* begin for protocols internal use */
64 #define PRU_FASTTIMO 18 /* 200ms timeout */
65 #define PRU_SLOWTIMO 19 /* 500ms timeout */
66 #define PRU_PROTORCV 20 /* receive from below */
67 #define PRU_PROTOSEND 21 /* send to below */
69 A call on the user request routine is of the form,
72 error = (*protosw[].pr_usrreq)(so, req, m, addr, rights);
73 int error; struct socket *so; int req; struct mbuf *m, *addr, *rights;
75 The mbuf data chain \fIm\fP is supplied for output operations
76 and for certain other operations where it is to receive a result.
77 The address \fIaddr\fP is supplied for address-oriented requests
78 such as PRU_BIND and PRU_CONNECT.
79 The \fIrights\fP parameter is an optional pointer to an mbuf
80 chain containing user-specified capabilities (see the \fIsendmsg\fP
81 and \fIrecvmsg\fP system calls). The protocol is responsible for
82 disposal of the data mbuf chains on output operations.
83 A non-zero return value gives a
84 UNIX error number which should be passed to higher level software.
85 The following paragraphs describe each
86 of the requests possible.
89 When a protocol is bound to a socket (with the \fIsocket\fP
90 system call) the protocol module is called with this
91 request. It is the responsibility of the protocol module to
92 allocate any resources necessary.
93 The ``attach'' request
94 will always precede any of the other requests, and should not
98 This is the antithesis of the attach request, and is used
99 at the time a socket is deleted. The protocol module may
100 deallocate any resources assigned to the socket.
103 When a socket is initially created it has no address bound
104 to it. This request indicates that an address should be bound to
105 an existing socket. The protocol module must verify that the
106 requested address is valid and available for use.
109 The ``listen'' request indicates the user wishes to listen
110 for incoming connection requests on the associated socket.
111 The protocol module should perform any state changes needed
112 to carry out this request (if possible). A ``listen'' request
113 always precedes a request to accept a connection.
116 The ``connect'' request indicates the user wants to establish
117 an association. The \fIaddr\fP parameter supplied describes
118 the peer to be connected to. The effect of a connect request
119 may vary depending on the protocol. Virtual circuit protocols,
120 such as TCP [Postel81b], use this request to initiate establishment of a
121 TCP connection. Datagram protocols, such as UDP [Postel80], simply
122 record the peer's address in a private data structure and use
123 it to tag all outgoing packets. There are no restrictions
124 on how many times a connect request may be used after an attach.
125 If a protocol supports the notion of \fImulti-casting\fP, it
126 is possible to use multiple connects to establish a multi-cast
127 group. Alternatively, an association may be broken by a
128 PRU_DISCONNECT request, and a new association created with a
129 subsequent connect request; all without destroying and creating
133 Following a successful PRU_LISTEN request and the arrival
134 of one or more connections, this request is made to
136 has accepted the first connection on the queue of
137 pending connections. The protocol module should fill
138 in the supplied address buffer with the address of the
142 Eliminate an association created with a PRU_CONNECT request.
145 This call is used to indicate no more data will be sent and/or
146 received (the \fIaddr\fP parameter indicates the direction of
147 the shutdown, as encoded in the \fIsoshutdown\fP system call).
148 The protocol may, at its discretion, deallocate any data
149 structures related to the shutdown and/or notify a connected peer
153 This request is made only if the protocol entry in the protocol
154 switch table includes the PR_WANTRCVD flag.
155 When a user removes data from the receive queue this request
156 will be sent to the protocol module. It may be used to trigger
157 acknowledgements, refresh windowing information, initiate
161 Each user request to send data is translated into one or more
162 PRU_SEND requests (a protocol may indicate that a single user
163 send request must be translated into a single PRU_SEND request by
164 specifying the PR_ATOMIC flag in its protocol description).
165 The data to be sent is presented to the protocol as a list of
166 mbufs and an address is, optionally, supplied in the \fIaddr\fP
167 parameter. The protocol is responsible for preserving the data
168 in the socket's send queue if it is not able to send it immediately,
169 or if it may need it at some later time (e.g. for retransmission).
172 This request indicates an abnormal termination of service. The
173 protocol should delete any existing association(s).
176 The ``control'' request is generated when a user performs a
177 UNIX \fIioctl\fP system call on a socket (and the ioctl is not
178 intercepted by the socket routines). It allows protocol-specific
179 operations to be provided outside the scope of the common socket
180 interface. The \fIaddr\fP parameter contains a pointer to a static
181 kernel data area where relevant information may be obtained or returned.
182 The \fIm\fP parameter contains the actual \fIioctl\fP request code
183 (note the non-standard calling convention).
184 The \fIrights\fP parameter contains a pointer to an \fIifnet\fP structure
185 if the \fIioctl\fP operation pertains to a particular network interface.
188 The ``sense'' request is generated when the user makes an \fIfstat\fP
189 system call on a socket; it requests status of the associated socket.
190 This currently returns a standard \fIstat\fP structure.
191 It typically contains only the
192 optimal transfer size for the connection (based on buffer size,
193 windowing information and maximum packet size).
194 The \fIm\fP parameter contains a pointer
195 to a static kernel data area where the status buffer should be placed.
198 Any ``out-of-band'' data presently available is to be returned. An
199 mbuf is passed to the protocol module, and the protocol
201 data in the mbuf or attach new mbufs to the one supplied if there is
202 insufficient space in the single mbuf.
203 An error may be returned if out-of-band data is not (yet) available
204 or has already been consumed.
205 The \fIaddr\fP parameter contains any options such as MSG_PEEK
206 to examine data without consuming it.
209 Like PRU_SEND, but for out-of-band data.
212 The local address of the socket is returned, if any is currently
213 bound to it. The address (with protocol specific format) is returned
214 in the \fIaddr\fP parameter.
217 The address of the peer to which the socket is connected is returned.
218 The socket must be in a SS_ISCONNECTED state for this request to
219 be made to the protocol. The address format (protocol specific) is
220 returned in the \fIaddr\fP parameter.
223 The protocol module is supplied two sockets and requested to
224 establish a connection between the two without binding any
225 addresses, if possible. This call is used in implementing
230 The following requests are used internally by the protocol modules
231 and are never generated by the socket routines. In certain instances,
232 they are handed to the \fIpr_usrreq\fP routine solely for convenience
233 in tracing a protocol's operation (e.g. PRU_SLOWTIMO).
236 A ``fast timeout'' has occurred. This request is made when a timeout
237 occurs in the protocol's \fIpr_fastimo\fP routine. The \fIaddr\fP
238 parameter indicates which timer expired.
241 A ``slow timeout'' has occurred. This request is made when a timeout
242 occurs in the protocol's \fIpr_slowtimo\fP routine. The \fIaddr\fP
243 parameter indicates which timer expired.
246 This request is used in the protocol-protocol interface, not by the
247 routines. It requests reception of data destined for the protocol and
248 not the user. No protocols currently use this facility.
251 This request allows a protocol to send data destined for another
252 protocol module, not a user. The details of how data is marked
253 ``addressed to protocol'' instead of ``addressed to user'' are
254 left to the protocol modules. No protocols currently use this facility.