| blob | d2b8559200f4712acd80bb2d73e72c102f9ccce2 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright 1989 AT&T
44 .\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved.
45 .\" Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved
46 .\"
47 .TH T_ACCEPT 3NSL "May 1, 1998"
48 .SH NAME
49 t_accept \- accept a connection request
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <xti.h>
58 \fBint\fR \fBt_accept\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIresfd\fR, \fBconst struct t_call *\fR\fIcall\fR);
59 .fi
61 .SH DESCRIPTION
62 .sp
63 .LP
64 This routine is part of the \fBXTI\fR interfaces that evolved from the
65 \fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these
66 interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When
67 using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, a
68 different header file, \fBtiuser.h\fR, must be used. Refer to the \fBTLI\fR
69 \fBCOMPATIBILITY\fR section for a description of differences between the two
70 interfaces.
71 .sp
72 .LP
73 This function is issued by a transport user to accept a connection request.
74 The parameter \fIfd\fR identifies the local transport endpoint where the
75 connection indication arrived; \fIresfd\fR specifies the local transport
76 endpoint where the connection is to be established, and \fIcall\fR contains
77 information required by the transport provider to complete the connection. The
78 parameter \fIcall\fR points to a \fBt_call\fR structure which contains the
79 following members:
80 .sp
81 .in +2
82 .nf
83 struct netbuf addr;
84 struct netbuf opt;
85 struct netbuf udata;
86 int sequence;
87 .fi
88 .in -2
90 .sp
91 .LP
92 In \fIcall\fR, \fIaddr\fR is the protocol address of the calling transport
93 user, \fIopt\fR indicates any options associated with the connection,
94 \fIudata\fR points to any user data to be returned to the caller, and
95 \fIsequence\fR is the value returned by \fBt_listen\fR(3NSL) that uniquely
96 associates the response with a previously received connection indication. The
97 address of the caller, \fIaddr\fR may be null (length zero). Where \fIaddr\fR
98 is not null then it may optionally be checked by XTI.
99 .sp
100 .LP
101 A transport user may accept a connection on either the same, or on a different,
102 local transport endpoint than the one on which the connection indication
103 arrived. Before the connection can be accepted on the same endpoint
104 (\fIresfd==fd\fR), the user must have responded to any previous connection
105 indications received on that transport endpoint by means of \fBt_accept()\fR or
106 \fBt_snddis\fR(3NSL). Otherwise, \fBt_accept()\fR will fail and set
107 \fBt_errno\fR to \fBTINDOUT\fR.
108 .sp
109 .LP
110 If a different transport endpoint is specified (\fIresfd!=fd\fR), then the user
111 may or may not choose to bind the endpoint before the \fBt_accept()\fR is
112 issued. If the endpoint is not bound prior to the \fBt_accept()\fR, the
113 endpoint must be in the \fBT_UNBND\fR state before the \fBt_accept()\fR is
114 issued, and the transport provider will automatically bind it to an address
115 that is appropriate for the protocol concerned. If the transport user chooses
116 to bind the endpoint it must be bound to a protocol address with a \fIqlen\fR
117 of zero and must be in the \fBT_IDLE\fR state before the \fBt_accept()\fR is
118 issued.
119 .sp
120 .LP
121 Responding endpoints should be supplied to \fBt_accept()\fR in the state
122 \fBT_UNBND.\fR
123 .sp
124 .LP
125 The call to \fBt_accept()\fR may fail with t_errno set to \fBTLOOK\fR if there
126 are indications (for example connect or disconnect) waiting to be received on
127 endpoint \fIfd\fR. Applications should be prepared for such a failure.
128 .sp
129 .LP
130 The \fIudata\fR argument enables the called transport user to send user data to
131 the caller and the amount of user data must not exceed the limits supported by
132 the transport provider as returned in the \fIconnect\fR field of the \fIinfo\fR
133 argument of \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the \fIlen\fR field
134 of \fIudata\fR is zero, no data will be sent to the caller. All the
135 \fImaxlen\fR fields are meaningless.
136 .sp
137 .LP
138 When the user does not indicate any option (\fIcall\(->opt.len\fR = 0) the
139 connection shall be accepted with the option values currently set for the
140 responding endpoint \fIresfd\fR.
141 .SH RETURN VALUES
142 .sp
143 .LP
144 Upon successful completion, a value of \fB0\fR is returned. Otherwise, a
145 value of -1 is returned and \fBt_errno\fR is set to indicate an error.
146 .SH VALID STATES
147 .sp
148 .LP
149 \fBfd: T_INCON\fR
150 .sp
151 .LP
152 \fBresfd (fd!=resfd): T_IDLE, T_UNBND\fR
153 .SH ERRORS
154 .sp
155 .LP
156 On failure, \fBt_errno\fR is set to one of the following:
157 .sp
158 .ne 2
159 .na
160 \fB\fBTACCES\fR\fR
161 .ad
162 .RS 17n
163 The user does not have permission to accept a connection on the responding
164 transport endpoint or to use the specified options.
165 .RE
167 .sp
168 .ne 2
169 .na
170 \fB\fBTBADADDR\fR\fR
171 .ad
172 .RS 17n
173 The specified protocol address was in an incorrect format or contained illegal
174 information.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fBTBADDATA\fR\fR
181 .ad
182 .RS 17n
183 The amount of user data specified was not within the bounds allowed by the
184 transport provider.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBTBADF\fR\fR
191 .ad
192 .RS 17n
193 The file descriptor \fIfd\fR or \fIresfd\fR does not refer to a transport
194 endpoint.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fBTBADOPT\fR\fR
201 .ad
202 .RS 17n
203 The specified options were in an incorrect format or contained illegal
204 information.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBTBADSEQ\fR\fR
211 .ad
212 .RS 17n
213 Either an invalid sequence number was specified, or a valid sequence number was
214 specified but the connection request was aborted by the peer. In the latter
215 case, its \fBT_DISCONNECT\fR event will be received on the listening endpoint.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fBTINDOUT\fR\fR
222 .ad
223 .RS 17n
224 The function was called with \fIfd==resfd\fR but there are outstanding
225 connection indications on the endpoint. Those other connection indications
226 must be handled either by rejecting them by means of \fBt_snddis\fR(3NSL) or
227 accepting them on a different endpoint by means of \fBt_accept\fR.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBTLOOK\fR\fR
234 .ad
235 .RS 17n
236 An asynchronous event has occurred on the transport endpoint referenced by
237 \fIfd\fR and requires immediate attention.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fBTNOTSUPPORT\fR\fR
244 .ad
245 .RS 17n
246 This function is not supported by the underlying transport provider.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fBTOUTSTATE\fR\fR
253 .ad
254 .RS 17n
255 The communications endpoint referenced by \fIfd\fR or \fIresfd\fR is not in
256 one of the states in which a call to this function is valid.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBTPROTO\fR\fR
263 .ad
264 .RS 17n
265 This error indicates that a communication problem has been detected between XTI
266 and the transport provider for which there is no other suitable XTI error
267 (\fBt_errno\fR).
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBTPROVMISMATCH\fR\fR
274 .ad
275 .RS 17n
276 The file descriptors \fIfd\fR and \fIresfd\fR do not refer to the same
277 transport provider.
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fBTRESADDR\fR\fR
284 .ad
285 .RS 17n
286 This transport provider requires both \fIfd\fR and \fIresfd\fR to be bound to
287 the same address. This error results if they are not.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fB\fBTRESQLEN\fR\fR
294 .ad
295 .RS 17n
296 The endpoint referenced by \fIresfd\fR (where \fIresfd\fR != \fIfd\fR) was
297 bound to a protocol address with a \fIqlen\fR that is greater than zero.
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fB\fBTSYSERR\fR\fR
304 .ad
305 .RS 17n
306 A system error has occurred during execution of this function.
307 .RE
309 .SH TLI COMPATIBILITY
310 .sp
311 .LP
312 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
313 different header files. This, and other semantic differences between the two
314 interfaces are described in the subsections below.
315 .SS "Interface Header"
316 .sp
317 .LP
318 The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces
319 should \fInot\fR use this header. They should use the header:
320 .sp
321 .in +2
322 .nf
323 #include <tiuser.h>
324 .fi
325 .in -2
327 .SS "Error Description Values"
328 .sp
329 .LP
330 The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot
331 be set by the \fBTLI\fR interface are:
332 .sp
333 .ne 2
334 .na
335 \fB\fBTPROTO\fR \fR
336 .ad
337 .RS 18n
339 .RE
341 .sp
342 .ne 2
343 .na
344 \fB\fBTINDOUT\fR \fR
345 .ad
346 .RS 18n
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBTPROVMISMATCH\fR \fR
354 .ad
355 .RS 18n
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBTRESADDR\fR \fR
363 .ad
364 .RS 18n
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBTRESQLEN\fR \fR
372 .ad
373 .RS 18n
375 .RE
377 .SS "Option Buffer"
378 .sp
379 .LP
380 The format of the options in an \fBopt\fR buffer is dictated by the transport
381 provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not
382 specify the buffer format.
383 .SH ATTRIBUTES
384 .sp
385 .LP
386 See \fBattributes\fR(5) for descriptions of the following attributes:
387 .sp
389 .sp
390 .TS
391 box;
392 c | c
393 l | l .
394 ATTRIBUTE TYPE ATTRIBUTE VALUE
395 _
396 MT Level Safe
397 .TE
399 .SH SEE ALSO
400 .sp
401 .LP
402 \fBt_connect\fR(3NSL), \fBt_getinfo\fR(3NSL), \fBt_getstate\fR(3NSL),
403 \fBt_listen\fR(3NSL), \fBt_open\fR(3NSL), \fBt_optmgmt\fR(3NSL),
404 \fBt_rcvconnect\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5)
405 .SH WARNINGS
406 .sp
407 .LP
408 There may be transport provider-specific restrictions on address binding.
409 .sp
410 .LP
411 Some transport providers do not differentiate between a connection indication
412 and the connection itself. If the connection has already been established
413 after a successful return of \fBt_listen\fR(3NSL), \fBt_accept()\fR will assign
414 the existing connection to the transport endpoint specified by \fIresfd\fR.