1t_optmgmt(3NSL)      Networking Services Library Functions     t_optmgmt(3NSL)
2
3
4

NAME

6       t_optmgmt - manage options for a transport endpoint
7

SYNOPSIS

9       #include <xti.h>
10
11
12
13       int t_optmgmt(int fd, const struct t_optmgmt *req, struct t_optmgmt *ret);
14
15

DESCRIPTION

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

RETURN VALUES

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

VALID STATES

315       ALL - apart from T_UNINIT.
316

ERRORS

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

TLI COMPATIBILITY

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

ATTRIBUTES

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

SEE ALSO

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)
Impressum