1 T_BIND(3NSL) Networking Services Library Functions T_BIND(3NSL)
2
3
4
5 NAME
6 t_bind - bind an address to a transport endpoint
7
8 SYNOPSIS
9 #include <xti.h>
10
11
12
13
14 int t_bind(int fd, const struct t_bind *req, struct t_bind *ret);
15
16
17 DESCRIPTION
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 tiuser.h
22 header file must be used. Refer to the TLI COMPATIBILITY section for
23 a description of differences between the two interfaces.
24
25
26 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
29 indications, or servicing a connection request on the transport
30 endpoint. In connectionless-mode, the transport user may send or
31 receive data units through the transport endpoint.
32
33
34 The req and ret arguments point to a t_bind structure containing the
35 following members:
36
37 struct netbuf addr;
38 unsigned qlen;
39
40
41
42 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
44 outstanding connection indications.
45
46
47 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
62
63 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
71
72 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
77 interested in the negotiated value of qlen. It is valid to set req and
78 ret 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
82
83 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
86 endpoint. An outstanding connection indication is one that has been
87 passed to the transport user by the transport provider but which has
88 not been accepted or rejected. A value of qlen greater than zero is
89 only meaningful when issued by a passive transport user that expects
90 other users to call it. The value of qlen will be negotiated by the
91 transport provider and may be changed if the transport provider cannot
92 support the specified number of outstanding connection indications.
93 However, this value of qlen will never be negotiated from a requested
94 value 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
98
99 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 It is not possible to bind more than one protocol address to the same
102 transport endpoint. However, the transport provider must also support
103 this capability. If a user binds more than one transport endpoint to
104 the same protocol address, only one endpoint can be used to listen for
105 connection indications associated with that protocol address. In other
106 words, only one t_bind() for a given protocol address may specify a
107 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
119 bound to the same protocol address from accepting connection
120 indications.
121
122
123 If fd refers to connectionless mode service, this function allows for
124 more than one transport endpoint to be associated with a protocol
125 address, where the underlying transport provider supports this
126 capability (often in conjunction with value of a protocol-specific
127 option). If a user attempts to bind a second transport endpoint to an
128 already bound protocol address when such capability is not supported
129 for a transport provider, t_bind() will return -1 and set t_errno to
130 TADDRBUSY.
131
132 RETURN VALUES
133 Upon successful completion, a value of 0 is returned. Otherwise, a
134 value of -1 is returned and t_errno is set to indicate an error.
135
136 VALID STATES
137 T_UNBND
138
139 ERRORS
140 On failure, t_errno is set to one of the following:
141
142 TACCES
143 The user does not have permission to use the specified
144 address.
145
146
147 TADDRBUSY
148 The requested address is in use.
149
150
151 TBADADDR
152 The specified protocol address was in an incorrect format
153 or contained illegal information.
154
155
156 TBADF
157 The specified file descriptor does not refer to a
158 transport endpoint.
159
160
161 TBUFOVFLW
162 The number of bytes allowed for an incoming argument
163 (maxlen) is greater than 0 but not sufficient to store the
164 value of that argument. The provider's state will change
165 to T_IDLE and the information to be returned in ret will
166 be discarded.
167
168
169 TOUTSTATE
170 The communications endpoint referenced by fd is not in
171 one of the states in which a call to this function is
172 valid.
173
174
175 TNOADDR
176 The transport provider could not allocate an address.
177
178
179 TPROTO
180 This error indicates that a communication problem has been
181 detected between XTI and the transport provider for which
182 there is no other suitable XTI error (t_errno).
183
184
185 TSYSERR
186 A system error has occurred during execution of this
187 function.
188
189
190 TLI COMPATIBILITY
191 The XTI and TLI interface definitions have common names but use
192 different header files. This, and other semantic differences between
193 the two interfaces are described in the subsections below.
194
195 Interface Header
196 The XTI interfaces use the header file, xti.h. TLI interfaces should
197 not use this header. They should use the header:
198
199
200 #include <tiuser.h>
201
202 Address Bound
203 The user can compare the addresses in req and ret to determine whether
204 the transport provider bound the transport endpoint to a different
205 address than that requested.
206
207 Error Description Values
208 The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface
209 but cannot be set by the TLI interface.
210
211
212 A t_errno value that this routine can return under different
213 circumstances than its XTI counterpart is TBUFOVFLW. It can be returned
214 even when the maxlen field of the corresponding buffer has been set to
215 zero.
216
217 ATTRIBUTES
218 See attributes(5) for descriptions of the following attributes:
219
220
221
222
223 +---------------+-----------------+
224 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
225 +---------------+-----------------+
226 |MT Level | Safe |
227 +---------------+-----------------+
228
229 SEE ALSO
230 t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
231 t_unbind(3NSL), attributes(5)
232
233 WARNINGS
234 The requirement that the value of qlen never be negotiated from a
235 requested value greater than zero to zero implies that transport
236 providers, rather than the XTI implementation itself, accept this
237 restriction.
238
239
240 An implementation need not allow an application explicitly to bind more
241 than one communications endpoint to a single protocol address, while
242 permitting more than one connection to be accepted to the same protocol
243 address. That means that although an attempt to bind a communications
244 endpoint to some address with qlen=0 might be rejected with TADDRBUSY,
245 the user may nevertheless use this (unbound) endpoint as a responding
246 endpoint in a call to t_accept(3NSL). To become independent of such
247 implementation differences, the user should supply unbound responding
248 endpoints to t_accept(3NSL).
249
250
251 The local address bound to an endpoint may change as result of a
252 t_accept(3NSL) or t_connect(3NSL) call. Such changes are not
253 necessarily reversed when the connection is released.
254
255
256
257 December 27, 2013 T_BIND(3NSL)
|
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
|