1t_bind(3NSL) Networking Services Library Functions t_bind(3NSL)
2
6 t_bind - bind an address to a transport endpoint
7
9 #include <xti.h>
10 int t_bind(int fd, const struct t_bind *req, struct t_bind *ret);
15
18 This routine is part of the XTI interfaces that evolved from the TLI
19 interfaces. XTI represents the future evolution of these interfaces.
20 However, TLI interfaces are supported for compatibility. When using a
21 TLI routine that has the same name as an XTI routine, the
22 tiuser.hheader file must be used. Refer to the TLI COMPATIBILITY sec‐
23 tion for a description of differences between the two interfaces.
24 This function associates a protocol address with the transport endpoint
27 specified by fd and activates that transport endpoint. In connection
28 mode, the transport provider may begin enqueuing incoming connect indi‐
29 cations, or servicing a connection request on the transport endpoint.
30 In connectionless-mode, the transport user may send or receive data
31 units through the transport endpoint.
32 The req and ret arguments point to a t_bind structure containing the
35 following members:
36 struct netbuf addr;
38 unsigned qlen;
39 The addr field of the t_bind structure specifies a protocol address,
43 and the qlen field is used to indicate the maximum number of outstand‐
44 ing connection indications.
45 The parameter req is used to request that an address, represented by
48 the netbuf structure, be bound to the given transport endpoint. The
49 parameter len specifies the number of bytes in the address, and buf
50 points to the address buffer. The parameter maxlen has no meaning for
51 the req argument. On return, ret contains an encoding for the address
52 that the transport provider actually bound to the transport endpoint;
53 if an address was specified in req, this will be an encoding of the
54 same address. In ret, the user specifies maxlen, which is the maximum
55 size of the address buffer, and buf which points to the buffer where
56 the address is to be placed. On return, len specifies the number of
57 bytes in the bound address, and buf points to the bound address. If
58 maxlen equals zero, no address is returned. If maxlen is greater than
59 zero and less than the length of the address, t_bind() fails with
60 t_errno set to TBUFOVFLW.
61 If the requested address is not available, t_bind() will return -1
64 with t_errno set as appropriate. If no address is specified in req (the
65 len field of addr in req is zero or req is NULL), the transport
66 provider will assign an appropriate address to be bound, and will
67 return that address in the addr field of ret. If the transport provider
68 could not allocate an address, t_bind() will fail with t_errno set to
69 TNOADDR.
70 The parameter req may be a null pointer if the user does not wish to
73 specify an address to be bound. Here, the value of qlen is assumed to
74 be zero, and the transport provider will assign an address to the
75 transport endpoint. Similarly, ret may be a null pointer if the user
76 does not care what address was bound by the provider and is not inter‐
77 ested in the negotiated value of qlen. It is valid to set req and ret
78 to the null pointer for the same call, in which case the provider
79 chooses the address to bind to the transport endpoint and does not
80 return that information to the user.
81 The qlen field has meaning only when initializing a connection-mode
84 service. It specifies the number of outstanding connection indications
85 that the transport provider should support for the given transport end‐
86 point. An outstanding connection indication is one that has been passed
87 to the transport user by the transport provider but which has not been
88 accepted or rejected. A value of qlen greater than zero is only mean‐
89 ingful when issued by a passive transport user that expects other users
90 to call it. The value of qlen will be negotiated by the transport
91 provider and may be changed if the transport provider cannot support
92 the specified number of outstanding connection indications. However,
93 this value of qlen will never be negotiated from a requested value
94 greater than zero to zero. This is a requirement on transport
95 providers; see WARNINGS below. On return, the qlen field in ret will
96 contain the negotiated value.
97 If fd refers to a connection-mode service, this function allows more
100 than one transport endpoint to be bound to the same protocol address.
101 but it is not possible to bind more than one protocol address to the
102 same transport endpoint. However, the transport provider must also sup‐
103 port this capability. If a user binds more than one transport endpoint
104 to the same protocol address, only one endpoint can be used to listen
105 for connection indications associated with that protocol address. In
106 other words, only one t_bind() for a given protocol address may specify
107 a value of qlen greater than zero. In this way, the transport provider
108 can identify which transport endpoint should be notified of an incoming
109 connection indication. If a user attempts to bind a protocol address to
110 a second transport endpoint with a value of qlen greater than zero,
111 t_bind() will return -1 and set t_errno to TADDRBUSY. When a user
112 accepts a connection on the transport endpoint that is being used as
113 the listening endpoint, the bound protocol address will be found to be
114 busy for the duration of the connection, until a t_unbind(3NSL) or
115 t_close(3NSL) call has been issued. No other transport endpoints may be
116 bound for listening on that same protocol address while that initial
117 listening endpoint is active (in the data transfer phase or in the
118 T_IDLE state). This will prevent more than one transport endpoint bound
119 to the same protocol address from accepting connection indications.
120 If fd refers to connectionless mode service, this function allows for
123 more than one transport endpoint to be associated with a protocol
124 address, where the underlying transport provider supports this capabil‐
125 ity (often in conjunction with value of a protocol-specific option). If
126 a user attempts to bind a second transport endpoint to an already bound
127 protocol address when such capability is not supported for a transport
128 provider, t_bind() will return -1 and set t_errno to TADDRBUSY.
129
131 Upon successful completion, a value of 0 is returned. Otherwise, a
132 value of -1 is returned and t_errno is set to indicate an error.
133
135 T_UNBND
136
138 On failure, t_errno is set to one of the following:
139 TACCES The user does not have permission to use the specified
141 address.
142 TADDRBUSY The requested address is in use.
145 TBADADDR The specified protocol address was in an incorrect format
148 or contained illegal information.
149 TBADF The specified file descriptor does not refer to a trans‐
152 port endpoint.
153 TBUFOVFLW The number of bytes allowed for an incoming argument
156 (maxlen) is greater than 0 but not sufficient to store the
157 value of that argument. The provider's state will change
158 to T_IDLE and the information to be returned in ret will
159 be discarded.
160 TOUTSTATE The communications endpoint referenced by fd is not in
163 one of the states in which a call to this function is
164 valid.
165 TNOADDR The transport provider could not allocate an address.
168 TPROTO This error indicates that a communication problem has been
171 detected between XTI and the transport provider for which
172 there is no other suitable XTI error (t_errno).
173 TSYSERR A system error has occurred during execution of this func‐
176 tion.
177
180 The XTI and TLI interface definitions have common names but use differ‐
181 ent header files. This, and other semantic differences between the two
182 interfaces are described in the subsections below.
183 Interface Header
185 The XTI interfaces use the header file, xti.h. TLI interfaces should
186 not use this header. They should use the header:
187 #include <tiuser.h>
190 Address Bound
192 The user can compare the addresses in req and ret to determine whether
193 the transport provider bound the transport endpoint to a different
194 address than that requested.
195 Error Description Values
197 The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface
198 but cannot be set by the TLI interface.
199 A t_errno value that this routine can return under different circum‐
202 stances than its XTI counterpart is TBUFOVFLW. It can be returned even
203 when the maxlen field of the corresponding buffer has been set to zero.
204
206 See attributes(5) for descriptions of the following attributes:
207 ┌─────────────────────────────┬─────────────────────────────┐
212 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
213 ├─────────────────────────────┼─────────────────────────────┤
214 │MT Level │Safe │
215 └─────────────────────────────┴─────────────────────────────┘
216
218 t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
219 t_unbind(3NSL), attributes(5)
220
222 The requirement that the value of qlen never be negotiated from a
223 requested value greater than zero to zero implies that transport
224 providers, rather than the XTI implementation itself, accept this
225 restriction.
226 An implementation need not allow an application explicitly to bind more
229 than one communications endpoint to a single protocol address, while
230 permitting more than one connection to be accepted to the same protocol
231 address. That means that although an attempt to bind a communications
232 endpoint to some address with qlen=0 might be rejected with TADDRBUSY,
233 the user may nevertheless use this (unbound) endpoint as a responding
234 endpoint in a call to t_accept(3NSL). To become independent of such
235 implementation differences, the user should supply unbound responding
236 endpoints to t_accept(3NSL).
237 The local address bound to an endpoint may change as result of a
240 t_accept(3NSL) or t_connect(3NSL) call. Such changes are not necessar‐
241 ily reversed when the connection is released.
242SunOS 5.11 7 May 1998 t_bind(3NSL)