Manual Pages for UNIX Operating System command usage for man t_snd

Networking Services Library Functions                 t_snd(3NSL)



NAME
     t_snd - send data or expedited data over a connection

SYNOPSIS
     #include 



     int t_snd(int fd, void *buf, unsigned int nbytes, int flags);


DESCRIPTION
     This routine is part of the  XTI  interfaces  which  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.h header file  must
     be  used.   Refer  to  the   TLI COMPATIBILITY section for a
     description of differences between the two interfaces.


     This function is used to send  either  normal  or  expedited
     data.  The  argument  fd identifies the local transport end-
     point over which data should be sent, buf points to the user
     data,  nbytes  specifies the number of bytes of user data to
     be sent, and flags specifies any  optional  flags  described
     below:

     T_EXPEDITED     If set in flags, the data will  be  sent  as
                     expedited  data  and  will be subject to the
                     interpretations of the transport provider.


     T_MORE          If set in flags, this indicates to the tran-
                     sport  provider  that  the transport service
                     data unit  (TSDU)  (or  expedited  transport
                     service  data  unit  -  ETSDU) is being sent
                     through  multiple   t_snd()   calls.    Each
                     t_snd()  with the  T_MORE flag set indicates
                     that another t_snd() will follow  with  more
                     data for the current TSDU (or ETSDU).

                     The end of the TSDU (or ETSDU) is identified
                     by  a t_snd() call with the  T_MORE flag not
                     set. Use of  T_MORE enables a user to  break
                     up  large  logical data units without losing
                     the boundaries of those units at  the  other
                     end  of  the  connection.  The  flag implies
                     nothing about how the data is  packaged  for
                     transfer  below  the transport interface. If
                     the transport provider does not support  the
                     concept  of  a TSDU as indicated in the info



SunOS 5.11           Last change: 7 May 1998                    1






Networking Services Library Functions                 t_snd(3NSL)



                     argument  on  return  from  t_open(3NSL)  or
                     t_getinfo(3NSL),  the   T_MORE  flag  is not
                     meaningful and will be ignored if set.

                     The sending of a zero-length fragment  of  a
                     TSDU  or  ETSDU is only permitted where this
                     is used to indicate the end  of  a  TSDU  or
                     ETSDU;  that is, when the T_MORE flag is not
                     set. Some transport  providers  also  forbid
                     zero-length TSDUs and ETSDUs.


     T_PUSH          If set in flags, requests that the  provider
                     transmit  all  data  that it has accumulated
                     but not sent.  The request is a local action
                     on  the  provider  and  does  not affect any
                     similarly named protocol flag (for  example,
                     the  TCP  PUSH flag). This effect of setting
                     this flag is protocol-dependent, and it  may
                     be  ignored  entirely by transport providers
                     which  do  not  support  the  use  of   this
                     feature.



     Note that the communications provider  is  free  to  collect
     data  in  a  send  buffer  until it accumulates a sufficient
     amount for transmission.


     By default, t_snd() operates in  synchronous  mode  and  may
     wait  if  flow  control  restrictions  prevent the data from
     being accepted by the local transport provider at  the  time
     the  call  is made.  However, if  O_NONBLOCK is set by means
     of  t_open(3NSL) or fcntl(2), t_snd() will execute in  asyn-
     chronous  mode,  and will fail immediately if there are flow
     control restrictions. The process can arrange to be informed
     when  the  flow control restrictions are cleared by means of
     either t_look(3NSL) or the EM interface.


     On successful completion,  t_snd()  returns  the  number  of
     bytes  (octets)  accepted  by  the  communications provider.
     Normally this will equal the number of octets  specified  in
     nbytes.   However,  if  O_NONBLOCK is set or the function is
     interrupted by a signal, it is possible that  only  part  of
     the  data  has  actually been accepted by the communications
     provider.  In this case,  t_snd() returns a  value  that  is
     less than the value of nbytes.  If t_snd() is interrupted by
     a signal before it could transfer data to the communications
     provider,  it  returns   -1 with  t_errno set to TSYSERR and
     errno set to EINTR.



SunOS 5.11           Last change: 7 May 1998                    2






Networking Services Library Functions                 t_snd(3NSL)



     If nbytes is zero and sending of zero bytes is not supported
     by  the  underlying communications service,  t_snd() returns
     -1 with  t_errno set to TBADDATA.


     The size of each TSDU or ETSDU must not exceed the limits of
     the transport provider as specified by the current values in
     the TSDU or ETSDU fields in the info  argument  returned  by
     t_getinfo(3NSL).


     The error TLOOK is returned for asynchronous events.  It  is
     required  only  for  an incoming disconnect event but may be
     returned for other events.

RETURN VALUES
     On successful completion,  t_snd()  returns  the  number  of
     bytes  accepted by the transport provider. Otherwise,  -1 is
     returned on failure and  t_errno  is  set  to  indicate  the
     error.


     Note that if the number of bytes accepted by the  communica-
     tions  provider  is less than the number of bytes requested,
     this may either indicate that  O_NONBLOCK  is  set  and  the
     communications  provider  is blocked due to flow control, or
     that  O_NONBLOCK is clear and the function  was  interrupted
     by a signal.

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

     TBADDATA       Illegal amount of data:

                        o    A single send was attempted specify-
                             ing  a TSDU (ETSDU) or fragment TSDU
                             (ETSDU) greater than that  specified
                             by the current values of the TSDU or
                             ETSDU fields in the info argument.

                        o    A send of a zero byte  TSDU  (ETSDU)
                             or  zero  byte  fragment  of  a TSDU
                             (ETSDU) is not supported by the pro-
                             vider.

                        o    Multiple   sends   were    attempted
                             resulting  in  a TSDU (ETSDU) larger
                             than that specified by  the  current
                             value of the TSDU or ETSDU fields in
                             the info argument - the  ability  of
                             an XTI implementation to detect such
                             an  error  case  is  implementation-



SunOS 5.11           Last change: 7 May 1998                    3






Networking Services Library Functions                 t_snd(3NSL)



                             dependent. See WARNINGS, below.


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


     TBADFLAG       An invalid flag was specified.


     TFLOW          O_NONBLOCK was  set,  but  the  flow  control
                    mechanism  prevented  the  transport provider
                    from accepting any data at this time.


     TLOOK          An asynchronous event has  occurred  on  this
                    transport endpoint.


     TNOTSUPPORT    This function is not supported by the  under-
                    lying transport provider.


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


     TPROTO         This error  indicates  that  a  communication
                    problem has been detected between XTI and the
                    transport 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 

  Error Description Values




SunOS 5.11           Last change: 7 May 1998                    4






Networking Services Library Functions                 t_snd(3NSL)



     The t_errno values that can be set by the XTI interface  and
     cannot be set by the TLI interface are:
       TPROTO
       TLOOK
       TBADFLAG
       TOUTSTATE


     The t_errno values that this routine can return  under  dif-
     ferent circumstances than its XTI counterpart are:
       TBADDATA


     In the TBADDATA error cases  described  above,  TBADDATA  is
     returned,  only  for  illegal  zero  byte TSDU ( ETSDU) send
     attempts.

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



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


SEE ALSO
     fcntl(2),   t_getinfo(3NSL),   t_look(3NSL),   t_open(3NSL),
     t_rcv(3NSL), attributes(5)

WARNINGS
     It is important to  remember  that  the  transport  provider
     treats  all  users of a transport endpoint as a single user.
     Therefore if  several  processes  issue  concurrent  t_snd()
     calls then the different data may be intermixed.


     Multiple sends which exceed the maximum TSDU or  ETSDU  size
     may   not   be   discovered   by   XTI.   In  this  case  an
     implementation-dependent error will result, generated by the
     transport  provider, perhaps on a subsequent XTI call.  This
     error may take the form of a connection abort, a TSYSERR,  a
     TBADDATA or a TPROTO error.


     If multiple sends which exceed the  maximum  TSDU  or  ETSDU
     size are detected by XTI, t_snd() fails with TBADDATA.




SunOS 5.11           Last change: 7 May 1998                    5