home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / bsd_srcs / share / doc / smm / 15.net / 7.t < prev    next >
Encoding:
Text File  |  1991-04-17  |  11.3 KB  |  257 lines
  1. .\" Copyright (c) 1983, 1986 The Regents of the University of California.
  2. .\" 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    6.5 (Berkeley) 4/17/91
  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.
  257.