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 .\"     $FreeBSD$
  31 .\"
  32 .nr H2 1
  33 .br
  34 .ne 30v
  35 .\".ds RH "Socket/protocol interface
  36 .NH
  37 \s+2Socket/protocol interface\s0
  38 .PP
  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
  42 module are possible:
  43 .DS
  44 ._d
  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 */
  68 .DE
  69 A call on the user request routine is of the form,
  70 .DS
  71 ._f
  72 error = (*protosw[].pr_usrreq)(so, req, m, addr, rights);
  73 int error; struct socket *so; int req; struct mbuf *m, *addr, *rights;
  74 .DE
  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.
  87 .IP PRU_ATTACH
  88 .br
  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
  95 occur more than once.
  96 .IP PRU_DETACH
  97 .br
  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.
 101 .IP PRU_BIND
 102 .br
 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.
 107 .IP PRU_LISTEN
 108 .br
 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.
 114 .IP PRU_CONNECT
 115 .br
 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
 130 a new socket.
 131 .IP PRU_ACCEPT
 132 .br
 133 Following a successful PRU_LISTEN request and the arrival
 134 of one or more connections, this request is made to
 135 indicate the user
 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
 139 connected party.
 140 .IP PRU_DISCONNECT
 141 .br
 142 Eliminate an association created with a PRU_CONNECT request.
 143 .IP PRU_SHUTDOWN
 144 .br
 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
 150 of the shutdown.
 151 .IP PRU_RCVD
 152 .br
 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
 158 data transfer, etc.
 159 .IP PRU_SEND
 160 .br
 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).
 170 .IP PRU_ABORT
 171 .br
 172 This request indicates an abnormal termination of service.  The
 173 protocol should delete any existing association(s).
 174 .IP PRU_CONTROL
 175 .br
 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.
 186 .IP PRU_SENSE
 187 .br
 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.
 196 .IP PRU_RCVOOB
 197 .br
 198 Any ``out-of-band'' data presently available is to be returned.  An
 199 mbuf is passed to the protocol module, and the protocol
 200 should either place
 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.
 207 .IP PRU_SENDOOB
 208 .br
 209 Like PRU_SEND, but for out-of-band data.
 210 .IP PRU_SOCKADDR
 211 .br
 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.
 215 .IP PRU_PEERADDR
 216 .br
 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.
 221 .IP PRU_CONNECT2
 222 .br
 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
 226 the
 227 .IR socketpair (2)
 228 system call.
 229 .PP
 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).
 234 .IP PRU_FASTTIMO
 235 .br
 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.
 239 .IP PRU_SLOWTIMO
 240 .br
 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.
 244 .IP PRU_PROTORCV
 245 .br
 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.
 249 .IP PRU_PROTOSEND
 250 .br
 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.