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