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