| blob | 5811b6f99392063889dfac3b617a8a613ee71b10 |
1 '\" te
2 .\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH T_CONNECT 3NSL "May 7, 1998"
11 .SH NAME
12 t_connect \- establish a connection with another transport user
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <xti.h>
18 \fBint\fR \fBt_connect\fR(\fBint\fR \fIfd\fR, \fBconst struct t_call *\fR\fIsndcall\fR,
19 \fBstruct t_call *\fR\fIrcvcall\fR);
20 .fi
22 .SH DESCRIPTION
23 .sp
24 .LP
25 This routine is part of the \fBXTI\fR interfaces which evolved from the
26 \fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these
27 interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When
28 using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the
29 \fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR
30 \fBCOMPATIBILITY\fR section for a description of differences between the two
31 interfaces. This function enables a transport user to request a connection to
32 the specified destination transport user.
33 .sp
34 .LP
35 This function can only be issued in the \fBT_IDLE\fR state. The parameter
36 \fIfd\fR identifies the local transport endpoint where communication will be
37 established, while \fIsndcall\fR and \fIrcvcall\fR point to a \fBt_call\fR
38 structure which contains the following members:
39 .sp
40 .in +2
41 .nf
42 struct netbuf addr;
43 struct netbuf opt;
44 struct netbuf udata;
45 int sequence;
46 .fi
47 .in -2
49 .sp
50 .LP
51 The parameter \fIsndcall\fR specifies information needed by the transport
52 provider to establish a connection and \fIrcvcall\fR specifies information that
53 is associated with the newly established connection.
54 .sp
55 .LP
56 In \fIsndcall\fR, \fIaddr\fR specifies the protocol address of the destination
57 transport user, \fIopt\fR presents any protocol-specific information that might
58 be needed by the transport provider, \fIudata\fR points to optional user data
59 that may be passed to the destination transport user during connection
60 establishment, and \fIsequence\fR has no meaning for this function.
61 .sp
62 .LP
63 On return, in \fIrcvcall\fR, \fIaddr\fR contains the protocol address
64 associated with the responding transport endpoint, \fIopt\fR represents any
65 protocol-specific information associated with the connection, \fIudata\fR
66 points to optional user data that may be returned by the destination transport
67 user during connection establishment, and \fIsequence\fR has no meaning for
68 this function.
69 .sp
70 .LP
71 The \fIopt\fR argument permits users to define the options that may be passed
72 to the transport provider. The user may choose not to negotiate protocol
73 options by setting the \fIlen\fR field of \fIopt\fR to zero. In this case, the
74 provider uses the option values currently set for the communications endpoint.
75 .sp
76 .LP
77 If used, \fIsndcall\(->opt.buf\fR must point to a buffer with the corresponding
78 options, and \fIsndcall\(->opt.len\fR must specify its length. The
79 \fImaxlen\fR and \fIbuf\fR fields of the \fBnetbuf\fR structure pointed by
80 \fIrcvcall\(->addr\fR and \fIrcvcall\(->opt\fR must be set before the call.
81 .sp
82 .LP
83 The \fIudata\fR argument enables the caller to pass user data to the
84 destination transport user and receive user data from the destination user
85 during connection establishment. However, the amount of user data must not
86 exceed the limits supported by the transport provider as returned in the
87 \fIconnect\fR field of the \fIinfo\fR argument of \fBt_open\fR(3NSL) or
88 \fBt_getinfo\fR(3NSL). If the \fIlen\fR of \fIudata\fR is zero in
89 \fIsndcall\fR, no data will be sent to the destination transport user.
90 .sp
91 .LP
92 On return, the \fIaddr\fR, \fIopt\fR and \fIudata\fR fields of \fIrcvcall\fR
93 will be updated to reflect values associated with the connection. Thus, the
94 \fImaxlen\fR field of each argument must be set before issuing this function to
95 indicate the maximum size of the buffer for each. However, \fImaxlen\fR can be
96 set to zero, in which case no information to this specific argument is given to
97 the user on the return from \fBt_connect()\fR. If maxlen is greater than zero
98 and less than the length of the value, \fBt_connect()\fR fails with
99 \fBt_errno\fR set to \fBTBUFOVFLW\fR. If \fIrcvcall\fR is set to \fINULL,\fR
100 no information at all is returned.
101 .sp
102 .LP
103 By default, \fBt_connect()\fR executes in synchronous mode, and will wait for
104 the destination user's response before returning control to the local user. A
105 successful return (that is, return value of zero) indicates that the requested
106 connection has been established. However, if \fBO_NONBLOCK\fR is set by means
107 of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_connect()\fR executes in
108 asynchronous mode. In this case, the call will not wait for the remote user's
109 response, but will return control immediately to the local user and return -1
110 with \fBt_errno\fR set to \fBTNODATA\fR to indicate that the connection has not
111 yet been established. In this way, the function simply initiates the connection
112 establishment procedure by sending a connection request to the destination
113 transport user. The \fBt_rcvconnect\fR(3NSL) function is used in conjunction
114 with \fBt_connect()\fR to determine the status of the requested connection.
115 .sp
116 .LP
117 When a synchronous \fBt_connect()\fR call is interrupted by the arrival of a
118 signal, the state of the corresponding transport endpoint is \fBT_OUTCON,\fR
119 allowing a further call to either \fBt_rcvconnect\fR(3NSL),
120 \fBt_rcvdis\fR(3NSL) or \fBt_snddis\fR(3NSL). When an asynchronous
121 \fBt_connect()\fR call is interrupted by the arrival of a signal, the state of
122 the corresponding transport endpoint is \fBT_IDLE.\fR
123 .SH RETURN VALUES
124 .sp
125 .LP
126 Upon successful completion, a value of \fB0\fR is returned. Otherwise, a
127 value of -1 is returned and \fBt_errno\fR is set to indicate an error.
128 .SH VALID STATES
129 .sp
130 .LP
131 \fBT_IDLE\fR
132 .SH ERRORS
133 .sp
134 .LP
135 On failure, \fBt_errno\fR is set to one of the following:
136 .sp
137 .ne 2
138 .na
139 \fB\fBTACCES\fR\fR
140 .ad
141 .RS 15n
142 The user does not have permission to use the specified address or options.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBTADDRBUSY\fR\fR
149 .ad
150 .RS 15n
151 This transport provider does not support multiple connections with the same
152 local and remote addresses. This error indicates that a connection already
153 exists.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBTBADADDR\fR\fR
160 .ad
161 .RS 15n
162 The specified protocol address was in an incorrect format or contained illegal
163 information.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBTBADDATA\fR\fR
170 .ad
171 .RS 15n
172 The amount of user data specified was not within the bounds allowed by the
173 transport provider.
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fBTBADF\fR\fR
180 .ad
181 .RS 15n
182 The specified file descriptor does not refer to a transport endpoint.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBTBADOPT\fR\fR
189 .ad
190 .RS 15n
191 The specified protocol options were in an incorrect format or contained illegal
192 information.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBTBUFOVFLW\fR\fR
199 .ad
200 .RS 15n
201 The number of bytes allocated for an incoming argument \fI(maxlen)\fR is
202 greater than 0 but not sufficient to store the value of that argument. If
203 executed in synchronous mode, the provider's state, as seen by the user,
204 changes to \fBT_DATAXFER,\fR and the information to be returned in
205 \fIrcvcall\fR is discarded.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBTLOOK\fR\fR
212 .ad
213 .RS 15n
214 An asynchronous event has occurred on this transport endpoint and requires
215 immediate attention.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fBTNODATA\fR\fR
222 .ad
223 .RS 15n
224 \fBO_NONBLOCK\fR was set, so the function successfully initiated the connection
225 establishment procedure, but did not wait for a response from the remote user.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBTNOTSUPPORT\fR\fR
232 .ad
233 .RS 15n
234 This function is not supported by the underlying transport provider.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fBTOUTSTATE\fR\fR
241 .ad
242 .RS 15n
243 The communications endpoint referenced by \fIfd\fR is not in one of the states
244 in which a call to this function is valid.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fBTPROTO\fR\fR
251 .ad
252 .RS 15n
253 This error indicates that a communication problem has been detected between XTI
254 and the transport provider for which there is no other suitable XTI error
255 \fB(t_errno)\fR.
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fBTSYSERR\fR\fR
262 .ad
263 .RS 15n
264 A system error has occurred during execution of this function.
265 .RE
267 .SH TLI COMPATIBILITY
268 .sp
269 .LP
270 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
271 different header files. This, and other semantic differences between the two
272 interfaces are described in the subsections below.
273 .SS "Interface Header"
274 .sp
275 .LP
276 The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces
277 should \fInot\fR use this header. They should use the header:
278 .sp
279 .in +2
280 .nf
281 #include <tiuser.h>
282 .fi
283 .in -2
285 .SS "Error Description Values"
286 .sp
287 .LP
288 The \fBTPROTO\fR and \fBTADDRBUSY\fR \fBt_errno\fR values can be set by the
289 \fBXTI\fR interface but not by the \fBTLI\fR interface.
290 .sp
291 .LP
292 A \fBt_errno\fR value that this routine can return under different
293 circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be
294 returned even when the \fBmaxlen\fR field of the corresponding buffer has been
295 set to zero.
296 .SS "Option Buffers"
297 .sp
298 .LP
299 The format of the options in an \fBopt\fR buffer is dictated by the transport
300 provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix
301 the buffer format.
302 .SH ATTRIBUTES
303 .sp
304 .LP
305 See \fBattributes\fR(5) for descriptions of the following attributes:
306 .sp
308 .sp
309 .TS
310 box;
311 c | c
312 l | l .
313 ATTRIBUTE TYPE ATTRIBUTE VALUE
314 _
315 MT Level Safe
316 .TE
318 .SH SEE ALSO
319 .sp
320 .LP
321 \fBfcntl\fR(2), \fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL),
322 \fBt_getinfo\fR(3NSL), \fBt_listen\fR(3NSL), \fBt_open\fR(3NSL),
323 \fBt_optmgmt\fR(3NSL), \fBt_rcvconnect\fR(3NSL), \fBt_rcvdis\fR(3NSL),
324 \fBt_snddis\fR(3NSL), \fBattributes\fR