1 T_BIND(3NSL) Networking Services Library Functions T_BIND(3NSL) 2 3 NAME 4 t_bind - bind an address to a tansport endpoint 5 6 SYNOPSIS 7 Network Services Library (libnsl, -lnsl) 8 #include <xti.h> 9 10 int 11 t_bind(int fd, const struct t_bind *req, stuct t_bind *ret); 12 13 DESCRIPTION 14 This routine is part of the XTI interfaces that evolved from the TLI 15 interfaces. XTI represents the future evolution of these interfaces. 16 However, TLI interfaces are supported for compatibility. When using a TLI 17 routine that has the same name as an XTI routine, the <tiuser.h> header 18 file must be used. Refer to the TLI COMPATIBILITY section for a 19 description of differences between the two interfaces. 20 21 This function associates a protocol address with the transport endpoint 22 specified by fd and activates that transport endpoint. In connection 23 mode, the transport provider may begin enqueuing incoming connect 24 indications, or servicing a connection request on the transport endpoint. 25 In connectionless-mode, the transport user may send or receive data units 26 through the transport endpoint. 27 28 The req and ret arguments point to a t_bind structure containing the 29 following members: 30 31 struct netbuf addr; 32 unsigned qlen; 33 34 The addr field of the t_bind structure specifies a protocol address, and 35 the qlen field is used to indicate the maximum number of outstanding 36 connection indications. 37 38 The parameter req is used to request that an address, represented by the 39 netbuf structure, be bound to the given transport endpoint. The parameter 40 len specifies the number of bytes in the address, and buf points to the 41 address buffer. For tcp(7P) and udp(7P) transports, buf points to either 42 a struct sockaddr_in or struct sockaddr_in6 buffer (depending on if IPv4 43 or IPv6 is being used). The parameter maxlen has no meaning for the req 44 argument. 45 46 On return, ret contains an encoding for the address that the transport 47 provider actually bound to the transport endpoint; if an address was 48 specified in req, this will be an encoding of the same address. In ret, 49 the user specifies maxlen, which is the maximum size of the address 50 buffer, and buf which points to the buffer where the address is to be 51 placed. On return, len specifies the number of bytes in the bound 52 address, and buf points to the bound address. If maxlen equals zero, no 53 address is returned. If maxlen is greater than zero and less than the 54 length of the address, t_bind() fails with t_errno set to TBUFOVFLW. 55 56 If the requested address is not available, t_bind() will return -1 with 57 t_errno set as appropriate. If no address is specified in req (the len 58 field of addr in req is zero or req is NULL), the transport provider will 59 assign an appropriate address to be bound, and will return that address 60 in the addr field of ret. If the transport provider could not allocate 61 an address, t_bind() will fail with t_errno set to TNOADDR. 62 63 The parameter req may be a null pointer if the user does not wish to 64 specify an address to be bound. Here, the value of qlen is assumed to be 65 zero, and the transport provider will assign an address to the transport 66 endpoint. Similarly, ret may be a null pointer if the user does not care 67 what address was bound by the provider and is not interested in the 68 negotiated value of qlen. It is valid to set req and ret to the null 69 pointer for the same call, in which case the provider chooses the address 70 to bind to the transport endpoint and does not return that information to 71 the user. 72 73 The qlen field has meaning only when initializing a connection-mode 74 service. It specifies the number of outstanding connection indications 75 that the transport provider should support for the given transport 76 endpoint. An outstanding connection indication is one that has been 77 passed to the transport user by the transport provider but which has not 78 been accepted or rejected. A value of qlen greater than zero is only 79 meaningful when issued by a passive transport user that expects other 80 users to call it. The value of qlen will be negotiated by the transport 81 provider and may be changed if the transport provider cannot support the 82 specified number of outstanding connection indications. However, this 83 value of qlen will never be negotiated from a requested value greater 84 than zero to zero. This is a requirement on transport providers; see 85 WARNINGS below. On return, the qlen field in ret will contain the 86 negotiated value. 87 88 If fd refers to a connection-mode service, this function allows more than 89 one transport endpoint to be bound to the same protocol address. It is 90 not possible to bind more than one protocol address to the same transport 91 endpoint. However, the transport provider must also support this 92 capability. If a user binds more than one transport endpoint to the same 93 protocol address, only one endpoint can be used to listen for connection 94 indications associated with that protocol address. In other words, only 95 one t_bind() for a given protocol address may specify a value of qlen 96 greater than zero. In this way, the transport provider can identify which 97 transport endpoint should be notified of an incoming connection 98 indication. If a user attempts to bind a protocol address to a second 99 transport endpoint with a value of qlen greater than zero, t_bind() will 100 return -1 and set t_errno to TADDRBUSY. When a user accepts a 101 connection on the transport endpoint that is being used as the listening 102 endpoint, the bound protocol address will be found to be busy for the 103 duration of the connection, until a t_unbind(3NSL) or t_close(3NSL) call 104 has been issued. No other transport endpoints may be bound for listening 105 on that same protocol address while that initial listening endpoint is 106 active (in the data transfer phase or in the T_IDLE state). This will 107 prevent more than one transport endpoint bound to the same protocol 108 address from accepting connection indications. 109 110 If fd refers to connectionless mode service, this function allows for 111 more than one transport endpoint to be associated with a protocol 112 address, where the underlying transport provider supports this capability 113 (often in conjunction with value of a protocol-specific option). If a 114 user attempts to bind a second transport endpoint to an already bound 115 protocol address when such capability is not supported for a transport 116 provider, t_bind() will return -1 and set t_errno to TADDRBUSY. 117 118 RETURN VALUES 119 Upon successful completion, a value of 0 is returned. Otherwise, a value 120 of -1 is returned and t_errno is set to indicate an error. 121 122 VALID STATES 123 T_UNBND 124 125 ERRORS 126 On failure, t_errno is set to one of the following: 127 128 TACCES The user does not have permission to use the specified 129 address. 130 131 TADDRBUSY The requested address is in use. 132 133 TBADADDR The specified protocol address was in an incorrect 134 format or contained illegal information. 135 136 TBADF The specified file descriptor does not refer to a 137 transport endpoint. 138 139 TBUFOVFLW The number of bytes allowed for an incoming argument ~ 140 maxlen is greater than 0 but not sufficient to store 141 the value of that argument. The provider's state will 142 change to T_IDLE and the information to be returned in 143 ret will be discarded. 144 145 TOUTSTATE The communications endpoint referenced by fd is not in 146 one of the states in which a call to this function is 147 valid. 148 149 TNOADDR The transport provider could not allocate an address. 150 151 TPROTO This error indicates that a communication problem has 152 been detected between XTI and the transport provider 153 for which there is no other suitable XTI error 154 (t_errno). 155 156 TSYSERR A system error has occurred during execution of this 157 function. 158 159 TLI COMPATIBILITY 160 The XTI and TLI interface definitions have common names but use different 161 header files. This, and other semantic differences between the two 162 interfaces are described in the subsections below. 163 164 Interface Header 165 The XTI interfaces use the header file, <xti.h>. TLI interfaces should 166 not use this header. They should use the header: <tiuser.h> 167 168 Address Bound 169 The user can compare the addresses in req and ret to determine whether 170 the transport provider bound the transport endpoint to a different 171 address than that requested. 172 173 Error Description Values 174 The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface 175 but cannot be set by the TLI interface. 176 177 A t_errno value that this routine can return under different 178 circumstances than its XTI counterpart is TBUFOVFLW. It can be returned 179 even when the maxlen field of the corresponding buffer has been set to 180 zero. 181 182 MT-LEVEL 183 Safe 184 185 SEE ALSO 186 t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL), 187 t_unbind(3NSL), attributes(5) 188 189 WARNINGS 190 The requirement that the value of qlen never be negotiated from a 191 requested value greater than zero to zero implies that transport 192 providers, rather than the XTI implementation itself, accept this 193 restriction. 194 195 An implementation need not allow an application explicitly to bind more 196 than one communications endpoint to a single protocol address, while 197 permitting more than one connection to be accepted to the same protocol 198 address. That means that although an attempt to bind a communications 199 endpoint to some address with qlen=0 might be rejected with TADDRBUSY, 200 the user may nevertheless use this (unbound) endpoint as a responding 201 endpoint in a call to t_accept(3NSL). To become independent of such 202 implementation differences, the user should supply unbound responding 203 endpoints to t_accept(3NSL). 204 205 The local address bound to an endpoint may change as result of a 206 t_accept(3NSL) or t_connect(3NSL) call. Such changes are not necessarily 207 reversed when the connection is released. 208 209 illumos May 1, 2017 illumos