1 .\" 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 2 .\" 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 3 .\" http://www.opengroup.org/bookstore/. 4 .\" 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. 5 .\" This notice shall appear on any product containing this material. 6 .\" 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. 7 .\" 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. 8 .\" 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] 9 .\" 10 .\" Copyright 2017 Joyent, Inc. 11 .\" 12 .Dd May 1, 2017 13 .Dt T_BIND 3NSL 14 .Os 15 .Sh NAME 16 .Nm t_bind 17 .Nd bind an address to a tansport endpoint 18 .Sh SYNOPSIS 19 .Lb libnsl 20 .In xti.h 21 .Ft int 22 .Fo t_bind 23 .Fa "int fd" 24 .Fa "const struct t_bind *req" 25 .Fa "stuct t_bind *ret" 26 .Fc 27 .Sh DESCRIPTION 28 This routine is part of the 29 .Sy XTI 30 interfaces that evolved from the 31 .Sy TLI 32 interfaces. 33 .Sy XTI 34 represents the future evolution of these 35 interfaces. However, 36 .Sy TLI 37 interfaces are supported for compatibility. When 38 using a 39 .Sy TLI 40 routine that has the same name as an 41 .Sy XTI 42 routine, the 43 .In tiuser.h 44 header file must be used. Refer to the 45 .Sx "TLI COMPATIBILITY" 46 section for a description of differences between the two interfaces. 47 .Pp 48 This function associates a protocol address with the transport endpoint 49 specified by 50 .Fa fd 51 and activates that transport endpoint. In connection 52 mode, the transport provider may begin enqueuing incoming connect indications, 53 or servicing a connection request on the transport endpoint. In 54 connectionless-mode, the transport user may send or receive data units through 55 the transport endpoint. 56 .Pp 57 The 58 .Fa req 59 and 60 .Fa ret 61 arguments point to a 62 .Vt t_bind 63 structure containing the following members: 64 .Pp 65 .Bl -item -compact 66 .It 67 struct netbuf addr; 68 .It 69 unsigned qlen; 70 .El 71 .Pp 72 The 73 .Sy addr 74 field of the 75 .Vt t_bind 76 structure specifies a protocol address, and the 77 .Sy qlen 78 field is used to indicate the maximum number of outstanding connection 79 indications. 80 .Pp 81 The parameter 82 .Fa req 83 is used to request that an address, represented by the 84 .Vt netbuf 85 structure, be bound to the given transport endpoint. The parameter 86 .Sy len 87 specifies the number of bytes in the address, and 88 .Sy buf 89 points to the address buffer. For 90 .Xr tcp 7P 91 and 92 .Xr udp 7P 93 transports, 94 .Sy buf 95 points to either a 96 .Vt "struct sockaddr_in" 97 or 98 .Vt "struct sockaddr_in6" 99 buffer (depending on if IPv4 or IPv6 is being used). The parameter 100 .Sy maxlen 101 has no meaning for the 102 .Fa req 103 argument. 104 .Pp 105 On return, 106 .Fa ret 107 contains an encoding for the address that the transport provider actually 108 bound to the transport endpoint; if an address was specified in 109 .Fa req , 110 this will be an encoding of the same address. In 111 .Fa ret , 112 the user specifies 113 .Sy maxlen , 114 which is the maximum size of the address buffer, and 115 .Sy buf 116 which points to the buffer where the address is to be placed. On return, 117 .Sy len 118 specifies the number of bytes in the bound address, and 119 .Sy buf 120 points to the bound address. If 121 .Sy maxlen 122 equals zero, no address is returned. If 123 .Sy maxlen 124 is greater than zero and less than the length of the address, 125 .Fn t_bind 126 fails with 127 .Va t_errno 128 set to 129 .Er TBUFOVFLW . 130 .Pp 131 If the requested address is not available, 132 .Fn t_bind 133 will return -1 with 134 .Va t_errno 135 set as appropriate. If no address is specified in 136 .Fa req 137 (the 138 .Sy len 139 field of 140 .Sy addr 141 in 142 .Fa req 143 is zero or 144 .Fa req 145 is 146 .Sy NULL ) , 147 the transport provider will assign an appropriate address to be 148 bound, and will return that address in the 149 .Sy addr 150 field of 151 .Fa ret . 152 If the transport provider could not allocate an address, 153 .Fn t_bind 154 will fail 155 with 156 .Va t_errno 157 set to 158 .Er TNOADDR . 159 .Pp 160 The parameter 161 .Fa req 162 may be a null pointer if the user does not wish to 163 specify an address to be bound. Here, the value of 164 .Sy qlen 165 is assumed to be zero, and the transport provider will assign an address to 166 the transport endpoint. Similarly, 167 .Fa ret 168 may be a null pointer if the user does not care 169 what address was bound by the provider and is not interested in the negotiated 170 value of 171 .Sy qlen . 172 It is valid to set 173 .Fa req 174 and 175 .Fa ret 176 to the null pointer for the same call, in which case the provider chooses the 177 address to bind to the transport endpoint and does not return that information 178 to the user. 179 .Pp 180 The 181 .Sy qlen 182 field has meaning only when initializing a connection-mode 183 service. It specifies the number of outstanding connection indications that the 184 transport provider should support for the given transport endpoint. An 185 outstanding connection indication is one that has been passed to the transport 186 user by the transport provider but which has not been accepted or rejected. A 187 value of 188 .Sy qlen 189 greater than zero is only meaningful when issued by a 190 passive transport user that expects other users to call it. The value of 191 .Sy qlen 192 will be negotiated by the transport provider and may be changed if 193 the transport provider cannot support the specified number of outstanding 194 connection indications. However, this value of 195 .Sy qlen 196 will never be negotiated from a requested value greater than zero to zero. 197 This is a requirement on transport providers; see 198 .Sx WARNINGS 199 below. On return, the 200 .Sy qlen 201 field in 202 .Fa ret 203 will contain the negotiated value. 204 .Pp 205 If 206 .Fa fd 207 refers to a connection-mode service, this function allows more than 208 one transport endpoint to be bound to the same protocol address. It is not 209 possible to bind more than one protocol address to the same transport endpoint. 210 However, the transport provider must also support this capability. If a user 211 binds more than one transport endpoint to the same protocol address, only one 212 endpoint can be used to listen for connection indications associated with that 213 protocol address. In other words, only one 214 .Fn t_bind 215 for a given protocol address may specify a value of 216 .Sy qlen 217 greater than zero. In this way, the 218 transport provider can identify which transport endpoint should be notified of 219 an incoming connection indication. If a user attempts to bind a protocol 220 address to a second transport endpoint with a value of 221 .Sy qlen 222 greater than zero, 223 .Fn t_bind 224 will return -1 and set 225 .Va t_errno 226 to 227 .Er TADDRBUSY . 228 When a user accepts a connection on the transport endpoint that is being used 229 as the listening endpoint, the bound protocol address will be found to be busy 230 for the duration of the connection, until a 231 .Xr t_unbind 3NSL 232 or 233 .Xr t_close 3NSL 234 call has been issued. No other transport endpoints may be 235 bound for listening on that same protocol address while that initial listening 236 endpoint is active (in the data transfer phase or in the 237 .Sy T_IDLE 238 state). This will prevent more than one transport endpoint bound to the same 239 protocol address from accepting connection indications. 240 .Pp 241 If 242 .Fa fd 243 refers to connectionless mode service, this function allows for 244 more than one transport endpoint to be associated with a protocol address, 245 where the underlying transport provider supports this capability (often in 246 conjunction with value of a protocol-specific option). If a user attempts to 247 bind a second transport endpoint to an already bound protocol address when such 248 capability is not supported for a transport provider, 249 .Fn t_bind 250 will 251 return -1 and set 252 .Va t_errno 253 to 254 .Er TADDRBUSY . 255 .Sh RETURN VALUES 256 Upon successful completion, a value of 0 is returned. Otherwise, a value of 257 -1 is returned and 258 .Va t_errno 259 is set to indicate an error. 260 .Sh VALID STATES 261 .Sy T_UNBND 262 .Sh ERRORS 263 On failure, 264 .Va t_errno 265 is set to one of the following: 266 .Bl -tag -width Er 267 .It Er TACCES 268 The user does not have permission to use the specified address. 269 .It Er TADDRBUSY 270 The requested address is in use. 271 .It Er TBADADDR 272 The specified protocol address was in an incorrect format or contained illegal 273 information. 274 .It Er TBADF 275 The specified file descriptor does not refer to a transport endpoint. 276 .It Er TBUFOVFLW 277 The number of bytes allowed for an incoming argument 278 .Pa Sy maxlen 279 is greater than 0 but not sufficient to store the value of that argument. The 280 provider's state will change to 281 .Sy T_IDLE 282 and the information to be returned in 283 .Fa ret 284 will be discarded. 285 .It Er TOUTSTATE 286 The communications endpoint referenced by 287 .Fa fd 288 is not in one of the states in which a call to this function is valid. 289 .It Er TNOADDR 290 The transport provider could not allocate an address. 291 .It Er TPROTO 292 This error indicates that a communication problem has been detected between XTI 293 and the transport provider for which there is no other suitable XTI error 294 .Pq Va t_errno . 295 .It Er TSYSERR 296 A system error has occurred during execution of this function. 297 .El 298 .Sh TLI COMPATIBILITY 299 The 300 .Sy XTI 301 and 302 .Sy TLI 303 interface definitions have common names but use different header files. This, 304 and other semantic differences between the two interfaces are described in the 305 subsections below. 306 .Ss "Interface Header" 307 The 308 .Sy XTI 309 interfaces use the header file, 310 .In xti.h . 311 .Sy TLI 312 interfaces should 313 .Em not 314 use this header. They should use the header: 315 .In tiuser.h 316 .Ss "Address Bound" 317 The user can compare the addresses in 318 .Fa req 319 and 320 .Fa ret 321 to determine whether the transport provider bound the transport endpoint to a 322 different address than that requested. 323 .Ss "Error Description Values" 324 The 325 .Va t_errno 326 values 327 .Er TPROTO 328 and 329 .Er TADDRBUSY 330 can be set by the 331 .Sy XTI 332 interface but cannot be set by the 333 .Sy TLI 334 interface. 335 .Pp 336 A 337 .Va t_errno 338 value that this routine can return under different circumstances than its 339 .Sy XTI 340 counterpart is 341 .Er TBUFOVFLW . 342 It can be returned even when the 343 .Sy maxlen 344 field of the corresponding buffer has been set to zero. 345 .Sh MT-LEVEL 346 Safe 347 .Sh SEE ALSO 348 .Xr t_accept 3NSL , 349 .Xr t_alloc 3NSL , 350 .Xr t_close 3NSL , 351 .Xr t_connect 3NSL , 352 .Xr t_unbind 3NSL , 353 .Xr attributes 5 354 .Sh WARNINGS 355 The requirement that the value of 356 .Sy qlen 357 never be negotiated from a requested value greater than zero to zero implies 358 that transport providers, rather than the XTI implementation itself, accept 359 this restriction. 360 .Pp 361 An implementation need not allow an application explicitly to bind more than 362 one communications endpoint to a single protocol address, while permitting more 363 than one connection to be accepted to the same protocol address. That means 364 that although an attempt to bind a communications endpoint to some address with 365 .Sy qlen=0 366 might be rejected with 367 .Er TADDRBUSY , 368 the user may nevertheless 369 use this (unbound) endpoint as a responding endpoint in a call to 370 .Xr t_accept 3NSL . 371 To become independent of such implementation differences, 372 the user should supply unbound responding endpoints to 373 .Xr t_accept 3NSL . 374 .Pp 375 The local address bound to an endpoint may change as result of a 376 .Xr t_accept 3NSL 377 or 378 .Xr t_connect 3NSL 379 call. Such changes are not necessarily reversed when the connection is released.