usr/src/man/man3nsl/t_open.3nsl

   1 '\" te
   2 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
   3 .\"  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
   4 .\" 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
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" 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.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" 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.
   9 .\" 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.
  10 .\" 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]
  11 .TH T_OPEN 3NSL "Jan 27, 2015"
  12 .SH NAME
  13 t_open \- establish a transport endpoint
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 #include <xti.h>
  18 #include <fcntl.h>
  19
  20
  21
  22
  23 \fBint\fR \fBt_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, \fBstruct t_info *\fR\fIinfo\fR);
  24 .fi
  25
  26 .SH DESCRIPTION
  27 .LP
  28 This routine is part of the \fBXTI\fR interfaces which evolved from the
  29 \fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these
  30 interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When
  31 using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the
  32 \fBtiuser.h\fR header file must be used.  Refer to the  \fBTLI\fR
  33 \fBCOMPATIBILITY\fR section for a description of differences between the two
  34 interfaces.
  35 .sp
  36 .LP
  37 The \fBt_open()\fR function must be called as the first step in the
  38 initialization of a transport endpoint. This function establishes a transport
  39 endpoint by supplying a transport provider identifier that indicates a
  40 particular transport provider, that is, transport protocol, and returning a
  41 file descriptor that identifies that endpoint.
  42 .sp
  43 .LP
  44 The argument \fIname\fR points to a transport provider identifier and
  45 \fIoflag\fR identifies any open flags, as in \fBopen\fR(2). The argument
  46 \fIoflag\fR is constructed from  \fBO_RDWR\fR optionally bitwise
  47 inclusive-OR'ed with  \fBO_NONBLOCK.\fR These flags are defined by the header
  48 \fB<fcntl.h>\fR\&. The file descriptor returned by \fBt_open()\fR will be used
  49 by all subsequent functions to identify the particular local transport
  50 endpoint.
  51 .sp
  52 .LP
  53 This function also returns various default characteristics of the underlying
  54 transport protocol by setting fields in the \fBt_info\fR structure. This
  55 argument points to a \fBt_info\fR which contains the following members:
  56 .sp
  57 .in +2
  58 .nf
  59 t_scalar_t addr;        /* max size of the transport protocol address */
  60 t_scalar_t options;     /* max number of bytes of  */
  61                                 /* protocol-specific options  */
  62 t_scalar_t tsdu;        /* max size of a transport service data  */
  63                                 /* unit (TSDU)  */
  64 t_scalar_t etsdu;       /* max size of an expedited transport  */
  65                                 /* service data unit (ETSDU)  */
  66 t_scalar_t connect;     /* max amount of data allowed on  */
  67                         /* connection establishment functions  */
  68 t_scalar_t discon;      /* max amount of data allowed on  */
  69                         /* t_snddis() and t_rcvdis() functions  */
  70 t_scalar_t servtype;    /* service type supported by the  */
  71                                 /* transport provider  */
  72 t_scalar_t flags;       /* other info about the transport provider  */
  73 .fi
  74 .in -2
  75
  76 .sp
  77 .LP
  78 The values of the fields have the following meanings:
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIaddr\fR\fR
  83 .ad
  84 .RS 12n
  85 A value greater than zero (\fBT_NULL\fR) indicates the maximum size of a
  86 transport protocol address and a value of -2 (\fBT_INVALID\fR) specifies that
  87 the transport provider does not provide user access to transport protocol
  88 addresses.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIoptions\fR\fR
  95 .ad
  96 .RS 12n
  97 A value greater than zero (\fBT_NULL\fR) indicates the maximum number of bytes
  98 of protocol-specific options supported by the provider, and a value of -2
  99 (\fBT_INVALID\fR) specifies that the transport provider does not support
 100 user-settable options.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fItsdu\fR\fR
 107 .ad
 108 .RS 12n
 109 A value greater than zero (\fBT_NULL\fR specifies the maximum size of a
 110 transport service data unit (TSDU); a value of zero (\fBT_NULL\fR) specifies
 111 that the transport provider does not support the concept of TSDU, although it
 112 does support the sending of a data stream with no logical boundaries preserved
 113 across a connection; a value of -1 (\fBT_INFINITE\fR) specifies that there is
 114 no limit to the size of a TSDU; and a value of -2 (\fBT_INVALID\fR) specifies
 115 that the transfer of normal data is not supported by the transport provider.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fIetsdu\fR\fR
 122 .ad
 123 .RS 12n
 124 A value greater than zero (\fBT_NULL\fR) specifies the maximum size of an
 125 expedited transport service data unit (ETSDU); a value of zero (\fBT_NULL\fR)
 126 specifies that the transport provider does not support the concept of ETSDU,
 127 although it does support the sending of an expedited data stream with no
 128 logical boundaries preserved across a connection; a value of -1
 129 (\fBT_INFINITE\fR)  specifies that there is no limit on the size of an ETSDU;
 130 and a value of -2 (\fBT_INVALID\fR) specifies that the transfer of expedited
 131 data is not supported by the transport provider. Note that the semantics of
 132 expedited data may be quite different for different transport providers.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fIconnect\fR\fR
 139 .ad
 140 .RS 12n
 141 A value greater than zero (\fBT_NULL\fR) specifies the maximum amount of data
 142 that may be associated with connection establishment functions, and a value of
 143 -2 (\fBT_INVALID\fR) specifies that the transport provider does not allow data
 144 to be sent with connection establishment functions.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fIdiscon\fR\fR
 151 .ad
 152 .RS 12n
 153 If the  \fBT_ORDRELDATA\fR bit in flags is clear, a value greater than zero
 154 (\fBT_NULL\fR) specifies the maximum amount of data that may be associated with
 155 the \fBt_snddis\fR(3NSL) and \fBt_rcvdis\fR(3NSL) functions, and a value of -2
 156 (\fBT_INVALID\fR) specifies that the transport provider does not allow data to
 157 be sent with the abortive release functions. If the  \fBT_ORDRELDATA\fR bit is
 158 set in flags, a value greater than zero (\fBT_NULL\fR) specifies the maximum
 159 number of octets that may be associated with the \fBt_sndreldata()\fR,
 160 \fBt_rcvreldata()\fR, \fBt_snddis\fR(3NSL) and  \fBt_rcvdis\fR(3NSL) functions.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fIservtype\fR\fR
 167 .ad
 168 .RS 12n
 169 This field specifies the service type supported by the transport provider, as
 170 described below.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fIflags\fR\fR
 177 .ad
 178 .RS 12n
 179 This is a bit field used to specify other information about the  communications
 180 provider.  If the  \fBT_ORDRELDATA\fR bit is set, the communications provider
 181 supports user data to be sent with an orderly release. If the  \fBT_SENDZERO\fR
 182 bit is set in flags, this indicates the underlying transport provider supports
 183 the sending of zero-length TSDUs.
 184 .RE
 185
 186 .sp
 187 .LP
 188 If a transport user is concerned with protocol independence, the above sizes
 189 may be accessed to determine how large the buffers must be to hold each piece
 190 of information. Alternatively, the \fBt_alloc\fR(3NSL) function may be used to
 191 allocate these buffers. An error will result if a transport user exceeds the
 192 allowed data size on any function.
 193 .sp
 194 .LP
 195 The \fIservtype\fR field of \fIinfo\fR specifies one of the following values on
 196 return:
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBT_COTS\fR \fR
 201 .ad
 202 .RS 15n
 203 The transport provider supports a connection-mode service but does not support
 204 the optional orderly release facility.
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBT_COTS_ORD\fR \fR
 211 .ad
 212 .RS 15n
 213 The transport provider supports a connection-mode service with the optional
 214 orderly release facility.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBT_CLTS\fR \fR
 221 .ad
 222 .RS 15n
 223 The transport provider supports a connectionless-mode service. For this service
 224 type, \fBt_open()\fR will return -2 (\fBT_INVALID\fR) for \fIetsdu\fR,
 225 \fIconnect\fR and \fIdiscon\fR.
 226 .RE
 227
 228 .sp
 229 .LP
 230 A single transport endpoint may support only one of the above services at one
 231 time.
 232 .sp
 233 .LP
 234 If \fIinfo\fR is set to a null pointer by the transport user, no protocol
 235 information is returned by \fBt_open()\fR.
 236 .SH RETURN VALUES
 237 .LP
 238 A valid file descriptor is returned upon successful completion.  Otherwise, a
 239 value of -1 is returned and \fBt_errno\fR is set to indicate an error.
 240 .SH VALID STATES
 241 .LP
 242 \fBT_UNINIT\fR.
 243 .SH ERRORS
 244 .LP
 245 On failure, \fBt_errno\fR is set to the following:
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBTBADFLAG\fR\fR
 250 .ad
 251 .RS 12n
 252 An invalid flag is specified.
 253 .RE
 254
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBTBADNAME\fR\fR
 259 .ad
 260 .RS 12n
 261 Invalid transport provider name.
 262 .RE
 263
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fBTPROTO\fR\fR
 268 .ad
 269 .RS 12n
 270 This error indicates that a communication problem has been detected between XTI
 271 and the transport provider for which there is no other suitable XTI error
 272 \fB(t_errno)\fR.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBTSYSERR\fR\fR
 279 .ad
 280 .RS 12n
 281 A system error has occurred during execution of this function.
 282 .RE
 283
 284 .SH TLI COMPATIBILITY
 285 .LP
 286 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
 287 different header files. This and other semantic differences between the two
 288 interfaces are described in the subsections below.
 289 .SS "Interface Header"
 290 .LP
 291 The \fBXTI\fR interfaces use the \fBxti.h\fR. \fBTLI\fR interfaces should
 292 \fInot\fR use this header.  They should use the header:
 293 .br
 294 .in +2
 295 #include <tiuser.h>
 296 .in -2
 297 .SS "Error Description Values"
 298 .LP
 299 The \fBt_errno\fR values \fBTPROTO\fR and \fBTBADNAME\fR can be set by the
 300 \fBXTI\fR interface but cannot be set by the \fBTLI\fR interface.
 301 .SS "Notes"
 302 .LP
 303 For \fBTLI\fR , the \fBt_info\fR structure referenced by \fIinfo\fR lacks the
 304 following structure member:
 305 .sp
 306 .in +2
 307 .nf
 308 t_scalar_t flags;    /* other info about the transport provider */
 309 .fi
 310 .in -2
 311
 312 .sp
 313 .LP
 314 This member was added to \fBstruct\fR \fBt_info\fR in the \fBXTI\fR interfaces.
 315 .sp
 316 .LP
 317 When a value of -1 is observed as the return value in various \fBt_info\fR
 318 structure members, it signifies that the transport provider can handle an
 319 infinite length buffer for a corresponding attribute, such as address data,
 320 option data, \fBTSDU\fR (octet size), \fBETSDU\fR (octet size), connection
 321 data, and disconnection data. The corresponding structure members are
 322 \fBaddr\fR, \fBoptions\fR, \fBtsdu\fR, \fBestdu\fR, \fBconnect\fR, and
 323 \fBdiscon\fR, respectively.
 324 .SH ATTRIBUTES
 325 .LP
 326 See \fBattributes\fR(5)  for descriptions of the following attributes:
 327 .sp
 328
 329 .sp
 330 .TS
 331 box;
 332 c | c
 333 l | l .
 334 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 335 _
 336 MT Level        Safe
 337 .TE
 338
 339 .SH SEE ALSO
 340 .LP
 341 \fBopen\fR(2), \fBattributes\fR(5)