Manual Pages for UNIX Operating System command usage for man t_bind

Networking Services Library Functions                t_bind(3NSL)



NAME
     t_bind - bind an address to a transport endpoint

SYNOPSIS
     #include 




     int t_bind(int fd, const struct t_bind *req, struct t_bind *ret);


DESCRIPTION
     This routine is part of the XTI interfaces that evolved from
     the  TLI  interfaces. XTI represents the future evolution of
     these interfaces. However, TLI interfaces are supported  for
     compatibility.  When  using  a TLI routine that has the same
     name as an XTI routine, the   tiuser.hheader  file  must  be
     used.   Refer  to  the   TLI  COMPATIBILITY  section  for  a
     description of differences between the two interfaces.


     This function associates a protocol address with  the  tran-
     sport  endpoint specified by fd and activates that transport
     endpoint. In connection mode,  the  transport  provider  may
     begin enqueuing incoming connect indications, or servicing a
     connection   request   on   the   transport   endpoint.   In
     connectionless-mode,  the transport user may send or receive
     data units through the transport endpoint.


     The req and ret arguments point to a t_bind  structure  con-
     taining the following members:

       struct netbuf  addr;
       unsigned  qlen;



     The addr field of the t_bind structure specifies a  protocol
     address,  and the qlen field is used to indicate the maximum
     number of outstanding connection indications.


     The parameter req  is  used  to  request  that  an  address,
     represented  by  the netbuf structure, be bound to the given
     transport endpoint. The parameter len specifies  the  number
     of  bytes  in  the  address,  and  buf points to the address
     buffer. The parameter maxlen has  no  meaning  for  the  req
     argument.  On  return,  ret  contains  an  encoding  for the
     address that the transport provider actually  bound  to  the
     transport  endpoint;  if  an  address was specified in  req,



SunOS 5.11           Last change: 7 May 1998                    1






Networking Services Library Functions                t_bind(3NSL)



     this will be an encoding of the same address.  In  ret,  the
     user  specifies  maxlen,  which  is  the maximum size of the
     address buffer, and buf which points to the buffer where the
     address is to be placed. On return, len specifies the number
     of bytes in the bound address, and buf points to  the  bound
     address.  If  maxlen equals zero, no address is returned. If
     maxlen is greater than zero and less than the length of  the
     address,  t_bind() fails with t_errno set to TBUFOVFLW.


     If the requested address is  not  available,  t_bind()  will
     return  -1 with t_errno set as appropriate. If no address is
     specified in req (the len field of addr in req  is  zero  or
     req  is   NULL),  the  transport  provider  will  assign  an
     appropriate address  to  be  bound,  and  will  return  that
     address  in the addr field of ret. If the transport provider
     could not allocate  an  address,  t_bind()  will  fail  with
     t_errno set to TNOADDR.


     The parameter req may be a null pointer if the user does not
     wish  to  specify an address to be bound. Here, the value of
     qlen is assumed to be zero, and the transport provider  will
     assign  an address to the transport endpoint. Similarly, ret
     may be a null pointer if the user does not care what address
     was bound by the provider and is not interested in the nego-
     tiated value of qlen. It is valid to set req and ret to  the
     null  pointer  for the same call, in which case the provider
     chooses the address to bind to the  transport  endpoint  and
     does not return that information to the user.


     The  qlen  field  has  meaning  only  when  initializing   a
     connection-mode  service.  It  specifies  the number of out-
     standing connection indications that the transport  provider
     should  support  for  the  given transport endpoint. An out-
     standing connection indication is one that has  been  passed
     to  the  transport  user by the transport provider but which
     has not been accepted or rejected. A value of  qlen  greater
     than  zero is only meaningful when issued by a passive tran-
     sport user that expects other users to call it. The value of
     qlen will be negotiated by the transport provider and may be
     changed if the transport provider cannot support the  speci-
     fied  number of outstanding connection indications. However,
     this value of qlen will never be negotiated from a requested
     value  greater  than  zero to zero. This is a requirement on
     transport providers; see WARNINGS below. On return, the qlen
     field in ret will contain the negotiated value.


     If fd refers to a  connection-mode  service,  this  function
     allows  more  than one transport endpoint to be bound to the



SunOS 5.11           Last change: 7 May 1998                    2






Networking Services Library Functions                t_bind(3NSL)



     same protocol address.  but it is not possible to bind  more
     than  one  protocol  address to the same transport endpoint.
     However, the transport provider must also support this capa-
     bility.  If a user binds more than one transport endpoint to
     the same protocol address, only one endpoint can be used  to
     listen  for connection indications associated with that pro-
     tocol address. In other words, only one t_bind() for a given
     protocol  address  may  specify a value of qlen greater than
     zero. In this way, the transport provider can identify which
     transport endpoint should be notified of an incoming connec-
     tion indication. If a  user  attempts  to  bind  a  protocol
     address  to a second transport endpoint with a value of qlen
     greater than zero, t_bind() will return  -1 and set  t_errno
     to  TADDRBUSY. When a user accepts a connection on the tran-
     sport endpoint that is being used as the listening endpoint,
     the  bound protocol address will be found to be busy for the
     duration  of  the  connection,  until  a  t_unbind(3NSL)  or
     t_close(3NSL)  call has been issued. No other transport end-
     points may be bound for  listening  on  that  same  protocol
     address  while that initial listening endpoint is active (in
     the data transfer phase or in the  T_IDLE state). This  will
     prevent  more  than one transport endpoint bound to the same
     protocol address from accepting connection indications.


     If  fd refers to connectionless mode service, this  function
     allows for more than one transport endpoint to be associated
     with a protocol address, where the underlying transport pro-
     vider  supports  this  capability (often in conjunction with
     value of a protocol-specific option). If a user attempts  to
     bind  a second transport endpoint to an already bound proto-
     col address when such capability  is  not  supported  for  a
     transport provider, t_bind() will return  -1 and set t_errno
     to TADDRBUSY.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.   Oth-
     erwise,  a  value  of   -1 is returned and t_errno is set to
     indicate an error.

VALID STATES
     T_UNBND

ERRORS
     On failure, t_errno is set to one of the following:

     TACCES       The user does not have permission  to  use  the
                  specified address.


     TADDRBUSY    The requested address is in use.




SunOS 5.11           Last change: 7 May 1998                    3






Networking Services Library Functions                t_bind(3NSL)



     TBADADDR     The  specified  protocol  address  was  in   an
                  incorrect  format or contained illegal informa-
                  tion.


     TBADF        The specified file descriptor does not refer to
                  a transport endpoint.


     TBUFOVFLW    The number of bytes  allowed  for  an  incoming
                  argument  (maxlen)  is  greater  than 0 but not
                  sufficient to store the value of that argument.
                  The provider's state will change to  T_IDLE and
                  the information to be returned in ret  will  be
                  discarded.


     TOUTSTATE    The communications endpoint referenced  by   fd
                  is  not in one of the states in which a call to
                  this function is valid.


     TNOADDR      The transport provider could  not  allocate  an
                  address.


     TPROTO       This error indicates that a communication prob-
                  lem has been detected between XTI and the tran-
                  sport provider for  which  there  is  no  other
                  suitable XTI error (t_errno).


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


TLI COMPATIBILITY
     The XTI and TLI interface definitions have common names  but
     use different header files. This, and other semantic differ-
     ences between the two interfaces are described in  the  sub-
     sections below.

  Interface Header
     The XTI interfaces use the header file,  xti.h.  TLI  inter-
     faces  should  not  use  this  header.   They should use the
     header:


     #include 

  Address Bound




SunOS 5.11           Last change: 7 May 1998                    4






Networking Services Library Functions                t_bind(3NSL)



     The user can compare the addresses in req and ret to  deter-
     mine whether the transport provider bound the transport end-
     point to a different address than that requested.

  Error Description Values
     The t_errno values TPROTO and TADDRBUSY can be  set  by  the
     XTI interface but cannot be set by the TLI interface.


     A t_errno value that this routine can return under different
     circumstances  than its XTI counterpart is TBUFOVFLW. It can
     be returned even when the maxlen field of the  corresponding
     buffer has been set to zero.

ATTRIBUTES
     See attributes(5)  for descriptions of the following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     t_accept(3NSL),        t_alloc(3NSL),         t_close(3NSL),
     t_connect(3NSL), t_unbind(3NSL), attributes(5)

WARNINGS
     The requirement that the value of qlen never  be  negotiated
     from  a  requested  value  greater than zero to zero implies
     that transport providers, rather than the XTI implementation
     itself, accept this restriction.


     An implementation need not allow an  application  explicitly
     to  bind  more  than one communications endpoint to a single
     protocol address, while permitting more than one  connection
     to be accepted to the same protocol address. That means that
     although an attempt to bind  a  communications  endpoint  to
     some  address with  qlen=0 might be rejected with TADDRBUSY,
     the user may nevertheless use this (unbound) endpoint  as  a
     responding  endpoint in a call to  t_accept(3NSL). To become
     independent of such  implementation  differences,  the  user
     should    supply    unbound    responding    endpoints    to
     t_accept(3NSL).






SunOS 5.11           Last change: 7 May 1998                    5






Networking Services Library Functions                t_bind(3NSL)



     The local address bound to an endpoint may change as  result
     of  a  t_accept(3NSL) or  t_connect(3NSL) call. Such changes
     are  not  necessarily  reversed  when  the   connection   is
     released.



















































SunOS 5.11           Last change: 7 May 1998                    6