share/doc/smm/18.net/7.t

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