*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> t_optmgmt (3)              
Title
Content
Arch
Section
 

p(7P)

Contents


 t_optmgmt(3)                                                   t_optmgmt(3)




 NAME    [Toc]    [Back]
      t_optmgmt() - manage options for a transport endpoint

 SYNOPSIS    [Toc]    [Back]
      #include <xti.h>            /* for X/OPEN Transport Interface - XTI */
      /* or */
      #include <tiuser.h>         /* for Transport Layer Interface - TLI  */

      int t_optmgmt (fd, req, ret);
      int fd;
      struct t_optmgmt *req;
      struct t_optmgmt *ret;

 DESCRIPTION    [Toc]    [Back]
      The t_optmgmt() function enables a transport user to retrieve, verify
      or negotiate protocol options with the transport provider.  The
      argument fd identifies a bound transport endpoint.

      The req and ret arguments point to a t_optmgmt structure containing
      the following members:

           struct netbuf opt;
           t_scalar_t flags;

      The opt field identifies protocol options. The flags field is used to
      specify the action to take with those options.

      The options are represented by a netbuf structure in a manner similar
      to the address in t_bind().  The argument req is used to request a
      specific action of the provider and to send options to the provider.
      The argument len specifies the number of bytes in the options.  buf
      points to the options buffer.  maxlen has no meaning for the req
      argument.  For XTI over the OSI transport provider, the options buffer
      should be of struct isoco_options for connection-oriented service, or
      struct isocl_options for connectionless service.  For TLI, see the
      documentation of the transport provider being used.

      The transport provider may return options and flag values to the user
      through ret.  For ret, maxlen specifies the maximum size of the
      options buffer, and buf points to the buffer where the options are to
      be placed.  For XTI over the OSI transport provider, the options
      buffer should be of struct isoco_options for connection-oriented
      service, or struct isocl_options for connectionless service.  For TLI,
      see the documentation of the transport provider being used.  On
      return, len specifies the number of bytes of options returned.  The
      value in maxlen has no meaning for the req argument, but must be set
      in the ret argument to specify the maximum number of bytes the options
      buffer can hold.  The actual content of the options is imposed by the
      transport provider.





 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




      Each option in the options buffer is of the form struct t_opthdr
      possibly followed by an option value.

      The level field of struct t_opthdr identifies the XTI level or a
      protocol of the transport provider.  The name field identifies the
      option within the level.  len contains its total length; i.e. the
      length of the option header t_opthdr plus the length of the option
      value.  If t_optmgmt() is called with the action T_NEGOTIATE set, the
      status field of the returned options contains information about the
      success or failure of a negotiation.

      Each option in the input or output option buffer must start at a
      t_uscalar_t boundary.  The macro OPT_NEXTHDR(pbuf, buflen, option) can
      be used for that purpose.  The parameter pbuf denotes a pointer to an
      option buffer opt.buf, and buflen is its length.  The parameter option
      points to a current option in the option buffer.  OPT_NEXTHDR returns
      a pointer to the position of the next option or returns a null pointer
      if the option buffer is exhausted.  The macro is helpful for writing
      and reading.  See <xti.h> in the CAE Specification X/Open Transport
      Interface (XTI) manual from X/Open Company Limited for the exact
      definition.

      If the transport user specifies several options on input, all options
      must address the same level.

      If any option in the options buffer does not indicate the same level
      as the first option, or the level specified is unsupported, then the
      t_optmgmt() request will fail with [TBADOPT].  If the error is
      detected, some options have possibly been successfully negotiated.
      The transport user can check the current status by calling t_optmgmt()
      with the T_CURRENT flag set.

      The flags field of req must specify one of the following actions:

      T_NEGOTIATE         This action enables the transport user to
                          negotiate option values.

                          The user specifies the options of interest and
                          their values in the buffer specified by req-
                          >opt.buf and req->opt.len.  The negotiated option
                          values are returned in the buffer pointed to by
                          ret->opt.buf.  The status field of each returned
                          option is set to indicate the result of the
                          negotiation.  The status is one of the following:

                          T_SUCCESS             if the proposed value was
                                                negotiated.

                          T_PARTSUCCESS         if a degraded value was
                                                negotiated.




 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




                          T_FAILURE             if the negotiation failed
                                                according to the negotiation
                                                rules.

                          T_NOTSUPPORT          if the transport provider
                                                does not support this option
                                                or illegally requests
                                                negotiation of a privileged
                                                option.

                          T_READONLY            if modification of a readonly
 option was requested.

                          If the status is T_SUCCESS, T_FAILURE,
                          T_NOTSUPPORT or T_READONLY, the returned option
                          value is the same as the one requested on input.

                          The overall result of the negotiation is returned
                          in ret->flags.

                          This field contains the worst single result,
                          whereby the rating is done according to the order
                          of T_NOTSUPPORT, T_READONLY, T_FAILURE,
                          T_PARTSUCCESS, T_SUCCESS.  The value T_NOTSUPPORT
                          is the worst result and T_SUCCESS is the best.

                          For each level, the option T_ALLOPT can be
                          requested on input.  No value is given  with this
                          option; only the t_opthdr part is specified.  This
                          input requests to negotiate all supported options
                          of this level to their default values.  The result
                          is returned option by option in ret->opt.buf.
                          (Note that depending on the state of the transport
                          endpoint, not all requests to negotiate the
                          default may be successful.)

      T_CHECK             This action enables the user to verify whether the
                          options specified in req are supported by the
                          transport provider.

                          If an option is specified with no option value (it
                          consists only of a t_opthdr structure), the option
                          is returned with its status field set to T_SUCCESS
                          if it is supported, T_NOTSUPPORT if it is not or
                          needs additional user privileges, and T_READONLY
                          if it is read-only (in the current state).  No
                          option value is returned.

                          If an option is specified with an option value,
                          the status field of the returned option has the
                          same value, as if the user had tried to negotiate



 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




                          this value with T_NEGOTIATE.  If the status is
                          T_SUCCESS, T_FAILURE, T_NOTSUPPORT, or T_READONLY,
                          the returned option value is the same as the one
                          requested on input.

                          The overall result of the option checks is
                          returned in ret->flags.  This field contains the
                          worst single result of the option checks, whereby
                          the rating is the same as for T_NEGOTIATE.

                          Note that no negotiation takes place.  All
                          currently effective option values remain
                          unchanged.

      T_DEFAULT           This action enables the transport user to retrieve
                          the default option values.  The user specifies the
                          option of interest in req->opt.buf.  The option
                          values are irrelevant and will be ignored; it is
                          sufficient to specify the t_opthdr part of an
                          option only.  The default values are then returned
                          in ret->opt.buf.

                          The status field returned is one of the following:

                          T_NOTSUPPORT          if the protocol level does
                                                not support this option or
                                                if the transport user
                                                illegally requested a
                                                privileged option.

                          T_READONLY            if the option is read-only.

                          T_SUCCESS             in all other cases.

                          The overall result of the request is returned in
                          ret->flags.  This field contains the worst single
                          result, whereby the rating is the same as for
                          T_NEGOTIATE.

                          For each level, the option T_ALLOPT can be
                          requested on input.  All supported options of this
                          level with their default values are then returned.
                          In this case, ret->opt.maxlen must be given at
                          least the value info->options (see t_getinfo(3),
                          t_open(3)) before the call.

      T_CURRENT           This action enables the transport user to retrieve
                          the currently effective option values.  The user
                          specifies the options of interest in req->opt.buf.
                          The option values are irrelevant and will be
                          ignored; it is sufficient to specify the t_opthdr



 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




                          part of an option only.  The default values are
                          then returned in ret->opt.buf.

                          The status field returned is one of the following:

                          T_NOTSUPPORT          if the protocol level does
                                                not support this option or
                                                if the transport user
                                                illegally requested a
                                                privileged option.

                          T_READONLY            if the option is read-only.

                          T_SUCCESS             in all other cases.

                          The overall result of the request is returned in
                          ret->flags.  This field contains the worst single
                          result, whereby the rating is the same as for
                          T_NEGOTIATE.

                          For each level, the option T_ALLOPT can be
                          requested on input.  All supported options of this
                          level with their currently effective values are
                          then returned.

                          The option T_ALLOPT can only be used with
                          t_optmgmt() and the actions T_NEGOTIATE,
                          T_DEFAULT, and T_CURRENT.  It can be used with any
                          supported level and addresses all supported
                          options of this level.  The option has no value;
                          it consists of a t_opthdr only.  Since in a
                          t_optmgmt() call only options of one level may be
                          addressed, this option should not be requested
                          together with other options.  The function returns
                          as soon as this option has been processed.

                          Options are independently processed in the order
                          they appear in the input option buffer.  If an
                          option is multiply input, it depends on the
                          implementation whether it is multiply output or
                          whether it is returned only once.

                          Transport providers may not be able to provide an
                          interface capable of supporting T_NEGOTIATE and/or
                          T_CHECK functionalities.  When this is the case,
                          the error [T_NOTSUPPORT] is returned.

      The function t_optmgmt() may block under various circumstances and
      depending on the implementation.  The function will block, for
      instance, if the protocol addressed by the call resides on a separate
      controller.  It may also block due to flow control constraints, i.e.



 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




      if data set previously across this transport endpoint has not yet been
      fully processed.  If the function is interrupted by a signal, the
      option negotiations that have been done so far may remain valid.  The
      behavior of the function is not changed if O_NONBLOCK is set.

    XTI-Level Options    [Toc]    [Back]
      XTI level options are not specific for a particular transport
      provider.  An XTI implementation supports none, all or any subset of
      the options defined below.  An implementation may restrict the use of
      any of these options by offering them only in  the privileged or
      read-only mode, or if fd relates to specific transport providers.

      The subsequent options are not association-related.  They may be
      negotiated in all XTI states except T_UNINIT.

      The protocol level is XTI_GENERIC.  For this level, the following
      options are defined.  A request for XTI_DEBUG is an absolute
      requirement.  A request to activate XTI_LINGER is an absolute
      requirement; the timeout value to this option is not.  XTI_RCVBUF,
      XTI_RECVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are not absolute
      requirements.

      XTI_DEBUG           This option enables debugging.  The values of this
                          option are implementation- defined.  Debugging is
                          disabled if the option is specified with "no
                          value", i.e. with an option header only.

                          The system supplies utilities to process the
                          traces.  Note that an implementation may also
                          provide other means for debugging.

      XTI_LINGER          This option is used to linger the execution of a
                          t_close() or close() if send data is still queued
                          in the send buffer.  The option value specifies
                          the linger period.  If a close() or t_close() is
                          issued and the send buffer is not empty, the
                          system attempts to send the pending data within
                          the linger period before closing the endpoint.
                          Data still pending after the linger period has
                          elapsed is discarded.

                          Depending on the implementation, t_close() or
                          close() either block for at maximum the linger
                          period, or immediately return, whereupon the
                          system holds the connection in existence for at
                          most the linger period.

                          The option constists of a structure t_linger
                          declared as:
                          struct t_linger{
                             t_uscalar_t l_onoff;  /* switch option on/off     */



 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




                             t_uscalar_t l_linger; /* linger period in seconds */
                          }

                          Legal values for the l_onoff are:

                          T_NO    switch option off

                          T_YES   activate option

                          The value of l_onoff is an absolute requirement.

                          The field l_linger determines the linger period in
                          seconds.  The transport user can request the
                          default value by setting the field to T_UNSPEC.
                          The default timeout value depends on the
                          underlying transport provider (it is often
                          T_INFINITE).  Legal values for this field are
                          T_UNSPEC, T_INFINITE, and all non-negative
                          numbers.

                          The l_linger value is not an absolute requirement.
                          The implementation may place upper and lower
                          limits to this value.  Requests that fall short of
                          the lower limit are negotiated to the lower limit.

                          Note that this option does not linger the
                          execution of t_snddis().

      XTI_RCVBUF          This option is used to adjust the internal buffer
                          size allocated for the receive buffer.  The buffer
                          size may be increased for high-volume connections,
                          or decreased to limit the possible backlog of
                          incoming data.  Default and maximum buffer sizes
                          are protocol-dependent; see individual protocol
                          manual entries, such as tc
.
                          Maximum buffer size is controlled by the ndd
                          variables tcp_recv_hiwater_max and
                          udp_recv_hiwater_max depending upon the underlying
                          protocol in use.

                          This request is not an absolute requirement.  The
                          implementation may place upper and lower limits on
                          the option value.  Requests that fall short of the
                          lower limit are negotiated to the lower limit.

                          Legal values are all positive numbers.

      XTI_RCVLOWAT        This option is used to set a low-water mark in the
                          receive buffer.  The option values gives the
                          minimal number of bytes that must have accumulated
                          in the receive buffer before they become visible



 Hewlett-Packard Company            - 7 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




                          to the transport user.  If and when the amount of
                          accumulated receive data exceeds the low-water
                          mark, a T_DATA event is created, an event
                          mechanism (e.g.  poll() or select()) indicates the
                          data, and the data can be read by t_rcv() or
                          t_rcvudata().

                          This request is not an absolute requirement.  The
                          implementation may place upper and lower limits on
                          the option value.  Requests that fall short of the
                          lower limit are negotiated to the lower limit.

                          Legal values are all positive numbers.

      XTI_SNDBUF          This option is used to adjust the internal buffer
                          size allocated for the send buffer. The default
                          maximum size of this buffer is controlled by the
                          ndd variable tcp_xmit_hiwater_max.

                          This request is not an absolute requirement.  The
                          implementation may place upper and lower limits on
                          the option value.  Requests that fall short of the
                          lower limit are negotiated to the lower limit.

                          Legal values are all positive numbers.

      XTI_SNDLOWAT        This option is used to set a low-water mark in the
                          send buffer.  The option value gives the minimal
                          number of bytes that must have accumulated in the
                          send buffer before they are sent.

                          This request is not an absolute requirement.  The
                          implementation may place upper and lower limits on
                          the option value.  Requests that fall short of the
                          lower limit are negotiated to the lower limit.

                          Legal values are all positive numbers.

    Thread-Safeness    [Toc]    [Back]
      The t_optmgmt() function is safe to be called by multithreaded
      applications, and it is thread-safe for both POSIX Threads and DCE
      User Threads.  It has a cancellation point.  It is neither asynccancel
 safe nor async-signal safe.  Finally, it is not fork-safe.

    Valid States    [Toc]    [Back]
      All - apart from T_UNINIT.

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, a value of 0 is returned.  Otherwise, a
      value of -1 is returned, and t_errno is set to indicate the error.




 Hewlett-Packard Company            - 8 -   HP-UX 11i Version 2: August 2003






 t_optmgmt(3)                                                   t_optmgmt(3)




      TLI supports any transport provider which is compliant with TPI
      (Transport Provider Interface).  Users can access TLI versions of the
      t_* routines by linking with /usr/lib/libnsl_s.a.  For more
      information on TLI, see the TLI section of STREAMS/UX for HP 9000
      Reference Manual.

 ERRORS    [Toc]    [Back]
      On failure, t_errno is set to the following:

      [TBADF]             The specified identifier does not refer to a
                          transport endpoint.

      [TOUTSTATE]         The function was issued in the wrong sequence.

      [TACCES]            The user does not have the permission to negotiate
                          the specified options.

      [TBADOPT]           The specified protocol options were in an
                          incorrect format or contained illegal information.

      [TBADFLAG]          An invalid flag was specified.

      [TBUFOVFLW]         The number of bytes allowed for an incoming
                          argument (maxlen) is greater than 0 and not
                          sufficient to store the value of that argument.
                          The information to be returned in ret will be
                          discarded.

      [TSYSERR]           A system error has occurred during execution of
                          this function.

      [TPROTO]            (XTI only) This error indicates that a
                          communication problem has been detected between
                          XTI and the transport provider for which there is
                          no existing XTI t_errno.

      [TNOTSUPPORT]       (XTI only) This action is not supported by the
                          underlying transport provider.

 SEE ALSO    [Toc]    [Back]
      t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3),
      t_open(3), t_rcvconnect(3).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      t_optmgmt(): SVID2, XPG3, XPG4


 Hewlett-Packard Company            - 9 -   HP-UX 11i Version 2: August 2003
[ Back ]
      
      
 Similar pages
Name OS Title
t_optmgmt Tru64 Manage protocol options for a transport endpoint
t_close HP-UX close a transport endpoint
t_unbind IRIX disable a transport endpoint
t_close Tru64 Close a transport endpoint.
t_open HP-UX establish a transport endpoint
t_open IRIX establish a transport endpoint
t_unbind HP-UX disable a transport endpoint
t_open Tru64 Establishes a transport endpoint
t_close IRIX close a transport endpoint
t_unbind Tru64 Disable a transport endpoint.
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service