1t_optmgmt(3NSL) Networking Services Library Functions t_optmgmt(3NSL)
2
3
4
6 t_optmgmt - manage options for a transport endpoint
7
9 #include <xti.h>
10
11
12
13 int t_optmgmt(int fd, const struct t_optmgmt *req, struct t_optmgmt *ret);
14
15
17 This routine is part of the XTI interfaces which evolved from the TLI
18 interfaces. XTI represents the future evolution of these interfaces.
19 However, TLI interfaces are supported for compatibility. When using a
20 TLI routine that has the same name as an XTI routine, the tiuser.h
21 header file must be used. Refer to the TLI COMPATIBILITY section for
22 a description of differences between the two interfaces.
23
24
25 The t_optmgmt() function enables a transport user to retrieve, verify
26 or negotiate protocol options with the transport provider. The argument
27 fd identifies a transport endpoint.
28
29
30 The req and ret arguments point to a t_optmgmt structure containing the
31 following members:
32
33 struct netbuf opt;
34 t_scalar_t flags;
35
36
37
38 The opt field identifies protocol options and the flags field is used
39 to specify the action to take with those options.
40
41
42 The options are represented by a netbuf structure in a manner similar
43 to the address in t_bind(3NSL). The argument req is used to request a
44 specific action of the provider and to send options to the provider.
45 The argument len specifies the number of bytes in the options, buf
46 points to the options buffer, and maxlen has no meaning for the req
47 argument. The transport provider may return options and flag values to
48 the user through ret. For ret, maxlen specifies the maximum size of the
49 options buffer and buf points to the buffer where the options are to be
50 placed. If maxlen in ret is set to zero, no options values are
51 returned. On return, len specifies the number of bytes of options
52 returned. The value in maxlen has no meaning for the req argument, but
53 must be set in the ret argument to specify the maximum number of bytes
54 the options buffer can hold.
55
56
57 Each option in the options buffer is of the form struct t_opthdr possi‐
58 bly followed by an option value.
59
60
61 The level field of struct t_opthdr identifies the XTI level or a proto‐
62 col of the transport provider. The name field identifies the option
63 within the level, and len contains its total length; that is, the
64 length of the option header t_opthdr plus the length of the option
65 value. If t_optmgmt() is called with the action T_NEGOTIATE set, the
66 status field of the returned options contains information about the
67 success or failure of a negotiation.
68
69
70 Several options can be concatenated. The option user has, however to
71 ensure that each options header and value part starts at a boundary
72 appropriate for the architecture‐specific alignment rules. The macros
73 T_OPT_FIRSTHDR(nbp), T_OPT_NEXTHDR (nbp,tohp), T_OPT_DATA(tohp) are
74 provided for that purpose.
75
76 T_OPT_DATA(nhp) If argument is a pointer to a t_opthdr
77 structure, this macro returns an unsigned
78 character pointer to the data associated
79 with the t_opthdr.
80
81
82 T_OPT_NEXTHDR(nbp, tohp) If the first argument is a pointer to a
83 netbuf structure associated with an option
84 buffer and second argument is a pointer to
85 a t_opthdr structure within that option
86 buffer, this macro returns a pointer to
87 the next t_opthdr structure or a null
88 pointer if this t_opthdr is the last
89 t_opthdr in the option buffer.
90
91
92 T_OPT_FIRSTHDR(tohp) If the argument is a pointer to a netbuf
93 structure associated with an option buf‐
94 fer, this macro returns the pointer to the
95 first t_opthdr structure in the associated
96 option buffer, or a null pointer if there
97 is no option buffer associated with this
98 netbuf or if it is not possible or the
99 associated option buffer is too small to
100 accommodate even the first aligned option
101 header.
102
103 T_OPT_FIRSTHDR is useful for finding an
104 appropriately aligned start of the option
105 buffer. T_OPT_NEXTHDR is useful for moving
106 to the start of the next appropriately
107 aligned option in the option buffer. Note
108 that OPT_NEXTHDR is also available for
109 backward compatibility requirements.
110 T_OPT_DATA is useful for finding the start
111 of the data part in the option buffer
112 where the contents of its values start on
113 an appropriately aligned boundary.
114
115 If the transport user specifies several
116 options on input, all options must address
117 the same level.
118
119 If any option in the options buffer does
120 not indicate the same level as the first
121 option, or the level specified is unsup‐
122 ported, then the t_optmgmt() request will
123 fail with TBADOPT. If the error is
124 detected, some options have possibly been
125 successfully negotiated. The transport
126 user can check the current status by call‐
127 ing t_optmgmt() with the T_CURRENT flag
128 set.
129
130 The flags field of req must specify one of
131 the following actions:
132
133
134 T_NEGOTIATE This action enables the transport user to
135 negotiate option values.
136
137 The user specifies the options of interest
138 and their values in the buffer specified
139 by req→opt.buf and req→opt.len. The nego‐
140 tiated option values are returned in the
141 buffer pointed to by ret->opt.buf. The
142 status field of each returned option is
143 set to indicate the result of the negotia‐
144 tion. The value is T_SUCCESS if the pro‐
145 posed value was negotiated, T_PARTSUCCESS
146 if a degraded value was negotiated,
147 T_FAILURE if the negotiation failed
148 (according to the negotiation rules),
149 T_NOTSUPPORT if the transport provider
150 does not support this option or illegally
151 requests negotiation of a privileged
152 option, and T_READONLY if modification of
153 a read-only option was requested. If the
154 status is T_SUCCESS, T_FAILURE, T_NOTSUP‐
155 PORT or T_READONLY, the returned option
156 value is the same as the one requested on
157 input.
158
159 The overall result of the negotiation is
160 returned in ret→flags.
161
162 This field contains the worst single
163 result, whereby the rating is done accord‐
164 ing to the order T_NOTSUPPORT, T_READ‐
165 ONLY, T_FAILURE, T_PARTSUCCESS, T_SUCCESS.
166 The value T_NOTSUPPORT is the worst
167 result and T_SUCCESS is the best.
168
169 For each level, the option T_ALLOPT can
170 be requested on input. No value is given
171 with this option; only the t_opthdr part
172 is specified. This input requests to nego‐
173 tiate all supported options of this level
174 to their default values. The result is
175 returned option by option in ret→opt.buf.
176 Note that depending on the state of the
177 transport endpoint, not all requests to
178 negotiate the default value may be suc‐
179 cessful.
180
181
182 T_CHECK This action enables the user to verify
183 whether the options specified in req are
184 supported by the transport provider.If an
185 option is specified with no option value
186 (it consists only of a t_opthdr struc‐
187 ture), the option is returned with its
188 status field set to T_SUCCESS if it is
189 supported, T_NOTSUPPORT if it is not or
190 needs additional user privileges, and
191 T_READONLY if it is read-only (in the cur‐
192 rent XTI state). No option value is
193 returned.
194
195 If an option is specified with an option
196 value, the status field of the returned
197 option has the same value, as if the user
198 had tried to negotiate this value with
199 T_NEGOTIATE. If the status is T_SUCCESS,
200 T_FAILURE, T_NOTSUPPORT or T_READONLY,
201 the returned option value is the same as
202 the one requested on input.
203
204 The overall result of the option checks is
205 returned in ret→flags. This field contains
206 the worst single result of the option
207 checks, whereby the rating is the same as
208 for T_NEGOTIATE .
209
210 Note that no negotiation takes place. All
211 currently effective option values remain
212 unchanged.
213
214
215 T_DEFAULT This action enables the transport user to
216 retrieve the default option values. The
217 user specifies the options of interest in
218 req→opt.buf. The option values are irrele‐
219 vant and will be ignored; it is sufficient
220 to specify the t_opthdr part of an option
221 only. The default values are then returned
222 in ret→opt.buf.
223
224 The status field returned is T_NOTSUPPORT
225 if the protocol level does not support
226 this option or the transport user ille‐
227 gally requested a privileged option,
228 T_READONLY if the option is read-only, and
229 set to T_SUCCESS in all other cases. The
230 overall result of the request is returned
231 in ret→flags. This field contains the
232 worst single result, whereby the rating is
233 the same as for T_NEGOTIATE.
234
235 For each level, the option T_ALLOPT can
236 be requested on input. All supported
237 options of this level with their default
238 values are then returned. In this case,
239 ret→opt.maxlen must be given at least the
240 value info→options before the call. See
241 t_getinfo(3NSL) and t_open(3NSL).
242
243
244 T_CURRENT This action enables the transport user to
245 retrieve the currently effective option
246 values. The user specifies the options of
247 interest in req→opt.buf. The option values
248 are irrelevant and will be ignored; it is
249 sufficient to specifiy the t_opthdr part
250 of an option only. The currently effective
251 values are then returned in req→opt.buf.
252
253 The status field returned is T_NOTSUPPORT
254 if the protocol level does not support
255 this option or the transport user ille‐
256 gally requested a privileged option,
257 T_READONLY if the option is read-only, and
258 set to T_SUCCESS in all other cases. The
259 overall result of the request is returned
260 in ret→flags. This field contains the
261 worst single result, whereby the rating is
262 the same as for T_NEGOTIATE.
263
264 For each level, the option T_ALLOPT can
265 be requested on input. All supported
266 options of this level with their currently
267 effective values are then returned.
268
269 The option T_ALLOPT can only be used with
270 t_optmgmt() and the actions T_NEGOTIATE,
271 T_DEFAULT and T_CURRENT. It can be used
272 with any supported level and addresses all
273 supported options of this level. The
274 option has no value; it consists of a
275 t_opthdr only. Since in a t_optmgmt()
276 call only options of one level may be
277 addressed, this option should not be
278 requested together with other options. The
279 function returns as soon as this option
280 has been processed.
281
282 Options are independently processed in the
283 order they appear in the input option buf‐
284 fer. If an option is multiply input, it
285 depends on the implementation whether it
286 is multiply output or whether it is
287 returned only once.
288
289 Transport providers may not be able to
290 provide an interface capable of supporting
291 T_NEGOTIATE and/or T_CHECK functionali‐
292 ties. When this is the case, the error
293 TNOTSUPPORT is returned.
294
295 The function t_optmgmt() may block under
296 various circumstances and depending on the
297 implementation. The function will block,
298 for instance, if the protocol addressed by
299 the call resides on a separate controller.
300 It may also block due to flow control con‐
301 straints; that is, if data sent previously
302 across this transport endpoint has not yet
303 been fully processed. If the function is
304 interrupted by a signal, the option nego‐
305 tiations that have been done so far may
306 remain valid. The behavior of the function
307 is not changed if O_NONBLOCK is set.
308
309
311 Upon successful completion, a value of 0 is returned. Otherwise, a
312 value of −1 is returned and t_errno is set to indicate an error.
313
315 ALL - apart from T_UNINIT.
316
318 On failure, t_errno is set to one of the following:
319
320 TBADF The specified file descriptor does not refer to a trans‐
321 port endpoint.
322
323
324 TBADFLAG An invalid flag was specified.
325
326
327 TBADOPT The specified options were in an incorrect format or
328 contained illegal information.
329
330
331 TBUFOVFLW The number of bytes allowed for an incoming argument
332 (maxlen) is greater than 0 but not sufficient to store
333 the value of that argument. The information to be
334 returned in ret will be discarded.
335
336
337 TNOTSUPPORT This action is not supported by the transport provider.
338
339
340 TOUTSTATE The communications endpoint referenced by fd is not in
341 one of the states in which a call to this function is
342 valid.
343
344
345 TPROTO This error indicates that a communication problem has
346 been detected between XTI and the transport provider for
347 which there is no other suitable XTI error (t_errno).
348
349
350 TSYSERR A system error has occurred during execution of this
351 function.
352
353
355 The XTI and TLI interface definitions have common names but use differ‐
356 ent header files. This, and other semantic differences between the two
357 interfaces are described in the subsections below.
358
359 Interface Header
360 The XTI interfaces use the header file, xti.h. TLI interfaces should
361 not use this header. They should use the header:
362
363 #include <tiuser.h>
364
365
366 Error Description Values
367 The t_errno value TPROTO can be set by the XTI interface but not by the
368 TLI interface.
369
370
371 The t_errno values that this routine can return under different circum‐
372 stances than its XTI counterpart are TACCES and TBUFOVFLW.
373
374 TACCES can be returned to indicate that the user does not have
375 permission to negotiate the specified options.
376
377
378 TBUFOVFLW can be returned even when the maxlen field of the corre‐
379 sponding buffer has been set to zero.
380
381
382 Option Buffers
383 The format of the options in an opt buffer is dictated by the transport
384 provider. Unlike the XTI interface, the TLI interface does not fix the
385 buffer format. The macros T_OPT_DATA, T_OPT_NEXTHDR, and T_OPT_FIRSTHDR
386 described for XTI are not available for use by TLI interfaces.
387
388 Actions
389 The semantic meaning of various action values for the flags field of
390 req differs between the TLI and XTI interfaces. TLI interface users
391 should heed the following descriptions of the actions:
392
393 T_NEGOTIATE This action enables the user to negotiate the values of
394 the options specified in req with the transport
395 provider. The provider will evaluate the requested
396 options and negotiate the values, returning the negoti‐
397 ated values through ret.
398
399
400 T_CHECK This action enables the user to verify whether the
401 options specified in req are supported by the transport
402 provider. On return, the flags field of ret will have
403 either T_SUCCESS or T_FAILURE set to indicate to the
404 user whether the options are supported. These flags are
405 only meaningful for the T_CHECK request.
406
407
408 T_DEFAULT This action enables a user to retrieve the default
409 options supported by the transport provider into the
410 opt field of ret. In req, the len field of opt must be
411 zero and the buf field may be NULL.
412
413
414 Connectionless Mode
415 If issued as part of the connectionless mode service, t_optmgmt() may
416 block due to flow control constraints. The function will not complete
417 until the transport provider has processed all previously sent data
418 units.
419
421 See attributes(5) for descriptions of the following attributes:
422
423
424
425
426 ┌─────────────────────────────┬─────────────────────────────┐
427 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
428 ├─────────────────────────────┼─────────────────────────────┤
429 │MT Level │Safe │
430 └─────────────────────────────┴─────────────────────────────┘
431
433 close(2), poll(2), select(3C), t_accept(3NSL), t_alloc(3NSL),
434 t_bind(3NSL), t_close(3NSL), t_connect(3NSL), t_getinfo(3NSL), t_lis‐
435 ten(3NSL), t_open(3NSL), t_rcv(3NSL), t_rcvconnect(3NSL), t_rcvu‐
436 data(3NSL), t_snddis(3NSL), attributes(5)
437
438
439
440SunOS 5.11 7 May 1998 t_optmgmt(3NSL)