Print this page
4344 Minor typos in the 3nsl man pages
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man3nsl/t_bind.3nsl
+++ new/usr/src/man/man3nsl/t_bind.3nsl
1 1 '\" te
2 2 .\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved
3 3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 4 .\" http://www.opengroup.org/bookstore/.
5 5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 6 .\" This notice shall appear on any product containing this material.
7 7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 -.TH T_BIND 3NSL "May 7, 1998"
10 +.TH T_BIND 3NSL "Dec 27, 2013"
11 11 .SH NAME
12 12 t_bind \- bind an address to a transport endpoint
13 13 .SH SYNOPSIS
14 14 .LP
15 15 .nf
16 16 #include <xti.h>
17 17
18 18
19 19
20 20
21 21 \fBint\fR \fBt_bind\fR(\fBint\fR \fIfd\fR, \fBconst struct t_bind *\fR\fIreq\fR, \fBstruct t_bind *\fR\fIret\fR);
22 22 .fi
23 23
24 24 .SH DESCRIPTION
25 25 .sp
26 26 .LP
27 27 This routine is part of the \fBXTI\fR interfaces that evolved from the
28 28 \fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these
29 29 interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When
30 30 using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the
31 -\fBtiuser.h\fRheader file must be used. Refer to the \fBTLI\fR
31 +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR
32 32 \fBCOMPATIBILITY\fR section for a description of differences between the two
33 33 interfaces.
34 34 .sp
35 35 .LP
36 36 This function associates a protocol address with the transport endpoint
37 37 specified by \fIfd\fR and activates that transport endpoint. In connection
38 38 mode, the transport provider may begin enqueuing incoming connect indications,
39 39 or servicing a connection request on the transport endpoint. In
40 40 connectionless-mode, the transport user may send or receive data units through
41 41 the transport endpoint.
42 42 .sp
43 43 .LP
44 44 The \fIreq\fR and \fIret\fR arguments point to a \fBt_bind\fR structure
45 45 containing the following members:
46 46 .sp
47 47 .in +2
48 48 .nf
49 49 struct netbuf addr;
50 50 unsigned qlen;
51 51 .fi
52 52 .in -2
53 53
54 54 .sp
55 55 .LP
56 56 The \fIaddr\fR field of the \fBt_bind\fR structure specifies a protocol
57 57 address, and the \fIqlen\fR field is used to indicate the maximum number of
58 58 outstanding connection indications.
59 59 .sp
60 60 .LP
61 61 The parameter \fIreq\fR is used to request that an address, represented by the
62 62 \fBnetbuf\fR structure, be bound to the given transport endpoint. The parameter
63 63 \fIlen\fR specifies the number of bytes in the address, and \fIbuf\fR points to
64 64 the address buffer. The parameter \fImaxlen\fR has no meaning for the \fIreq\fR
65 65 argument. On return, \fIret\fR contains an encoding for the address that the
66 66 transport provider actually bound to the transport endpoint; if an address was
67 67 specified in \fIreq\fR, this will be an encoding of the same address. In
68 68 \fIret\fR, the user specifies \fImaxlen,\fR which is the maximum size of the
69 69 address buffer, and \fIbuf\fR which points to the buffer where the address is
70 70 to be placed. On return, \fIlen\fR specifies the number of bytes in the bound
71 71 address, and \fIbuf\fR points to the bound address. If \fImaxlen\fR equals
72 72 zero, no address is returned. If \fImaxlen\fR is greater than zero and less
73 73 than the length of the address, \fBt_bind()\fR fails with \fBt_errno\fR set to
74 74 \fBTBUFOVFLW\fR.
75 75 .sp
76 76 .LP
77 77 If the requested address is not available, \fBt_bind()\fR will return -1 with
78 78 \fBt_errno\fR set as appropriate. If no address is specified in \fIreq\fR (the
79 79 \fIlen\fR field of \fIaddr\fR in \fIreq\fR is zero or \fIreq\fR is
80 80 \fBNULL),\fR the transport provider will assign an appropriate address to be
81 81 bound, and will return that address in the \fIaddr\fR field of \fIret\fR. If
82 82 the transport provider could not allocate an address, \fBt_bind()\fR will fail
83 83 with \fBt_errno\fR set to \fBTNOADDR\fR.
84 84 .sp
85 85 .LP
86 86 The parameter \fIreq\fR may be a null pointer if the user does not wish to
87 87 specify an address to be bound. Here, the value of \fIqlen\fR is assumed to be
88 88 zero, and the transport provider will assign an address to the transport
89 89 endpoint. Similarly, \fIret\fR may be a null pointer if the user does not care
90 90 what address was bound by the provider and is not interested in the negotiated
91 91 value of \fIqlen\fR. It is valid to set \fIreq\fR and \fIret\fR to the null
92 92 pointer for the same call, in which case the provider chooses the address to
93 93 bind to the transport endpoint and does not return that information to the
94 94 user.
95 95 .sp
96 96 .LP
97 97 The \fIqlen\fR field has meaning only when initializing a connection-mode
98 98 service. It specifies the number of outstanding connection indications that the
99 99 transport provider should support for the given transport endpoint. An
100 100 outstanding connection indication is one that has been passed to the transport
101 101 user by the transport provider but which has not been accepted or rejected. A
102 102 value of \fIqlen\fR greater than zero is only meaningful when issued by a
↓ open down ↓ |
61 lines elided |
↑ open up ↑ |
103 103 passive transport user that expects other users to call it. The value of
104 104 \fIqlen\fR will be negotiated by the transport provider and may be changed if
105 105 the transport provider cannot support the specified number of outstanding
106 106 connection indications. However, this value of \fIqlen\fR will never be
107 107 negotiated from a requested value greater than zero to zero. This is a
108 108 requirement on transport providers; see \fBWARNINGS\fR below. On return, the
109 109 \fIqlen\fR field in \fIret\fR will contain the negotiated value.
110 110 .sp
111 111 .LP
112 112 If \fIfd\fR refers to a connection-mode service, this function allows more than
113 -one transport endpoint to be bound to the same protocol address. but it is not
113 +one transport endpoint to be bound to the same protocol address. But it is not
114 114 possible to bind more than one protocol address to the same transport endpoint.
115 115 However, the transport provider must also support this capability. If a user
116 116 binds more than one transport endpoint to the same protocol address, only one
117 117 endpoint can be used to listen for connection indications associated with that
118 118 protocol address. In other words, only one \fBt_bind()\fR for a given protocol
119 119 address may specify a value of \fIqlen\fR greater than zero. In this way, the
120 120 transport provider can identify which transport endpoint should be notified of
121 121 an incoming connection indication. If a user attempts to bind a protocol
122 122 address to a second transport endpoint with a value of \fIqlen\fR greater than
123 123 zero, \fBt_bind()\fR will return -1 and set \fBt_errno\fR to \fBTADDRBUSY\fR.
124 124 When a user accepts a connection on the transport endpoint that is being used
125 125 as the listening endpoint, the bound protocol address will be found to be busy
126 126 for the duration of the connection, until a \fBt_unbind\fR(3NSL) or
127 127 \fBt_close\fR(3NSL) call has been issued. No other transport endpoints may be
128 128 bound for listening on that same protocol address while that initial listening
129 129 endpoint is active (in the data transfer phase or in the \fBT_IDLE\fR state).
130 130 This will prevent more than one transport endpoint bound to the same protocol
131 131 address from accepting connection indications.
132 132 .sp
133 133 .LP
134 134 If \fIfd\fR refers to connectionless mode service, this function allows for
135 135 more than one transport endpoint to be associated with a protocol address,
136 136 where the underlying transport provider supports this capability (often in
137 137 conjunction with value of a protocol-specific option). If a user attempts to
138 138 bind a second transport endpoint to an already bound protocol address when such
139 139 capability is not supported for a transport provider, \fBt_bind()\fR will
140 140 return -1 and set \fBt_errno\fR to \fBTADDRBUSY\fR.
141 141 .SH RETURN VALUES
142 142 .sp
143 143 .LP
144 144 Upon successful completion, a value of 0 is returned. Otherwise, a value of
145 145 -1 is returned and \fBt_errno\fR is set to indicate an error.
146 146 .SH VALID STATES
147 147 .sp
148 148 .LP
149 149 \fBT_UNBND\fR
150 150 .SH ERRORS
151 151 .sp
152 152 .LP
153 153 On failure, \fBt_errno\fR is set to one of the following:
154 154 .sp
155 155 .ne 2
156 156 .na
157 157 \fB\fBTACCES\fR\fR
158 158 .ad
159 159 .RS 13n
160 160 The user does not have permission to use the specified address.
161 161 .RE
162 162
163 163 .sp
164 164 .ne 2
165 165 .na
166 166 \fB\fBTADDRBUSY\fR\fR
167 167 .ad
168 168 .RS 13n
169 169 The requested address is in use.
170 170 .RE
171 171
172 172 .sp
173 173 .ne 2
174 174 .na
175 175 \fB\fBTBADADDR\fR\fR
176 176 .ad
177 177 .RS 13n
178 178 The specified protocol address was in an incorrect format or contained illegal
179 179 information.
180 180 .RE
181 181
182 182 .sp
183 183 .ne 2
184 184 .na
185 185 \fB\fBTBADF\fR\fR
186 186 .ad
187 187 .RS 13n
188 188 The specified file descriptor does not refer to a transport endpoint.
189 189 .RE
190 190
191 191 .sp
192 192 .ne 2
193 193 .na
194 194 \fB\fBTBUFOVFLW\fR\fR
195 195 .ad
196 196 .RS 13n
197 197 The number of bytes allowed for an incoming argument \fI(maxlen)\fR is greater
198 198 than 0 but not sufficient to store the value of that argument. The provider's
199 199 state will change to \fBT_IDLE\fR and the information to be returned in
200 200 \fIret\fR will be discarded.
201 201 .RE
202 202
203 203 .sp
204 204 .ne 2
205 205 .na
206 206 \fB\fBTOUTSTATE\fR\fR
207 207 .ad
208 208 .RS 13n
209 209 The communications endpoint referenced by \fIfd\fR is not in one of the states
210 210 in which a call to this function is valid.
211 211 .RE
212 212
213 213 .sp
214 214 .ne 2
215 215 .na
216 216 \fB\fBTNOADDR\fR\fR
217 217 .ad
218 218 .RS 13n
219 219 The transport provider could not allocate an address.
220 220 .RE
221 221
222 222 .sp
223 223 .ne 2
224 224 .na
225 225 \fB\fBTPROTO\fR\fR
226 226 .ad
227 227 .RS 13n
228 228 This error indicates that a communication problem has been detected between XTI
229 229 and the transport provider for which there is no other suitable XTI error
230 230 \fB(t_errno)\fR.
231 231 .RE
232 232
233 233 .sp
234 234 .ne 2
235 235 .na
236 236 \fB\fBTSYSERR\fR\fR
237 237 .ad
238 238 .RS 13n
239 239 A system error has occurred during execution of this function.
240 240 .RE
241 241
242 242 .SH TLI COMPATIBILITY
243 243 .sp
244 244 .LP
245 245 The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use
246 246 different header files. This, and other semantic differences between the two
247 247 interfaces are described in the subsections below.
248 248 .SS "Interface Header"
249 249 .sp
250 250 .LP
251 251 The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces
252 252 should \fInot\fR use this header. They should use the header:
253 253 .sp
254 254 .LP
255 255 \fB#include\fR \fB<tiuser.h>\fR
256 256 .SS "Address Bound"
257 257 .sp
258 258 .LP
259 259 The user can compare the addresses in \fIreq\fR and \fIret\fR to determine
260 260 whether the transport provider bound the transport endpoint to a different
261 261 address than that requested.
262 262 .SS "Error Description Values"
263 263 .sp
264 264 .LP
265 265 The \fBt_errno\fR values \fBTPROTO\fR and \fBTADDRBUSY\fR can be set by the
266 266 \fBXTI\fR interface but cannot be set by the \fBTLI\fR interface.
267 267 .sp
268 268 .LP
269 269 A \fBt_errno\fR value that this routine can return under different
270 270 circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be
271 271 returned even when the \fBmaxlen\fR field of the corresponding buffer has been
272 272 set to zero.
273 273 .SH ATTRIBUTES
274 274 .sp
275 275 .LP
276 276 See \fBattributes\fR(5) for descriptions of the following attributes:
277 277 .sp
278 278
279 279 .sp
280 280 .TS
281 281 box;
282 282 c | c
283 283 l | l .
284 284 ATTRIBUTE TYPE ATTRIBUTE VALUE
285 285 _
286 286 MT Level Safe
287 287 .TE
288 288
289 289 .SH SEE ALSO
290 290 .sp
291 291 .LP
292 292 \fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL), \fBt_close\fR(3NSL),
293 293 \fBt_connect\fR(3NSL), \fBt_unbind\fR(3NSL), \fBattributes\fR(5)
294 294 .SH WARNINGS
295 295 .sp
296 296 .LP
297 297 The requirement that the value of \fIqlen\fR never be negotiated from a
298 298 requested value greater than zero to zero implies that transport providers,
299 299 rather than the XTI implementation itself, accept this restriction.
300 300 .sp
301 301 .LP
302 302 An implementation need not allow an application explicitly to bind more than
303 303 one communications endpoint to a single protocol address, while permitting more
304 304 than one connection to be accepted to the same protocol address. That means
305 305 that although an attempt to bind a communications endpoint to some address with
306 306 \fIqlen=0\fR might be rejected with \fBTADDRBUSY\fR, the user may nevertheless
307 307 use this (unbound) endpoint as a responding endpoint in a call to
308 308 \fBt_accept\fR(3NSL). To become independent of such implementation differences,
309 309 the user should supply unbound responding endpoints to \fBt_accept\fR(3NSL).
310 310 .sp
311 311 .LP
312 312 The local address bound to an endpoint may change as result of a
313 313 \fBt_accept\fR(3NSL) or \fBt_connect\fR(3NSL) call. Such changes are not
314 314 necessarily reversed when the connection is released.
↓ open down ↓ |
191 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX