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