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