Print this page
OS-6101 t_bind(3NSL) could mention data types for transports
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3nsl/t_bind.3nsl.man.txt
+++ new/usr/src/man/man3nsl/t_bind.3nsl.man.txt
1 1 T_BIND(3NSL) Networking Services Library Functions T_BIND(3NSL)
2 2
3 -
4 -
5 3 NAME
6 - t_bind - bind an address to a transport endpoint
4 + t_bind - bind an address to a tansport endpoint
7 5
8 6 SYNOPSIS
9 - #include <xti.h>
7 + Network Services Library (libnsl, -lnsl)
8 + #include <xti.h>
10 9
10 + int
11 + t_bind(int fd, const struct t_bind *req, stuct t_bind *ret);
11 12
12 -
13 -
14 - int t_bind(int fd, const struct t_bind *req, struct t_bind *ret);
15 -
16 -
17 13 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.
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.
24 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.
25 27
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.
28 + The req and ret arguments point to a t_bind structure containing the
29 + following members:
32 30
31 + struct netbuf addr;
32 + unsigned qlen;
33 33
34 - The req and ret arguments point to a t_bind structure containing the
35 - following members:
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.
36 37
37 - struct netbuf addr;
38 - unsigned qlen;
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.
39 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.
40 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.
41 62
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.
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.
45 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.
46 87
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.
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.
61 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.
62 117
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 118 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.
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.
135 121
136 122 VALID STATES
137 - T_UNBND
123 + T_UNBND
138 124
139 125 ERRORS
140 - On failure, t_errno is set to one of the following:
126 + On failure, t_errno is set to one of the following:
141 127
142 - TACCES
143 - The user does not have permission to use the specified
144 - address.
128 + TACCES The user does not have permission to use the specified
129 + address.
145 130
131 + TADDRBUSY The requested address is in use.
146 132
147 - TADDRBUSY
148 - The requested address is in use.
133 + TBADADDR The specified protocol address was in an incorrect
134 + format or contained illegal information.
149 135
136 + TBADF The specified file descriptor does not refer to a
137 + transport endpoint.
150 138
151 - TBADADDR
152 - The specified protocol address was in an incorrect format
153 - or contained illegal information.
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.
154 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.
155 148
156 - TBADF
157 - The specified file descriptor does not refer to a
158 - transport endpoint.
149 + TNOADDR The transport provider could not allocate an address.
159 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).
160 155
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.
156 + TSYSERR A system error has occurred during execution of this
157 + function.
167 158
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 159 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.
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.
194 163
195 164 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:
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>
198 167
199 -
200 - #include <tiuser.h>
201 -
202 168 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.
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.
206 172
207 173 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.
174 + The t_errno values TPROTO and TADDRBUSY can be set by the XTI interface
175 + but cannot be set by the TLI interface.
210 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.
211 181
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.
182 +MT-LEVEL
183 + Safe
216 184
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 185 SEE ALSO
230 - t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
231 - t_unbind(3NSL), attributes(5)
186 + t_accept(3NSL), t_alloc(3NSL), t_close(3NSL), t_connect(3NSL),
187 + t_unbind(3NSL), attributes(5)
232 188
233 189 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.
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.
238 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).
239 204
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).
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.
249 208
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)
209 +illumos May 1, 2017 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX