t_rcvvudata(3nsl)

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

NAME

6       t_rcvvudata  -  receive a data unit into one or more noncontiguous buf‐
7       fers
8

SYNOPSIS

10       #include <xti.h>
11
12
13
14       int t_rcvvudata(int fd, struct t_unitdata *unitdata, struct t_iovec *iov,
15            unsigned int iovcount, int *flags);
16
17

DESCRIPTION

19       This function is used in connectionless mode to  receive  a  data  unit
20       from  another  transport  user.   The argument  fd identifies the local
21       transport endpoint through which data will be received,  unitdata holds
22       information  associated with the received data unit,  iovcount contains
23       the  number  of  non-contiguous  udata  buffers  which  is  limited  to
24       T_IOV_MAX, which is an implementation-defined value of at least 16, and
25       flags is set on return to indicate that the complete data unit was  not
26       received.   If  the  limit on  iovcount is exceeded, the function fails
27       with TBADDATA.  The argument  unitdata points to a   t_unitdata  struc‐
28       ture containing the following members:
29
30         struct netbuf addr;
31         struct netbuf opt;
32         struct netbuf udata;
33
34
35
36       The   maxlen  field  of   addr and  opt must be set before calling this
37       function to indicate the maximum size  of  the  buffer  for  each.  The
38       udata  field  of   t_unitdata  is  not  used. The  iov_len and iov_base
39       fields of "iov0" through  iov [iovcount-1] must be set  before  calling
40       t_rcvvudata()  to  define the buffer where the userdata will be placed.
41       If the maxlen field of  addr or  opt is set to zero then no information
42       is returned in the  buf field for this parameter.
43
44
45       On  return  from this call,  addr specifies the protocol address of the
46       sending user,  opt identifies options that were  associated  with  this
47       data  unit, and  iov[0].iov_base through iov [iovcount-1].iov_base con‐
48       tains the user data that was received. The return  value  of   t_rcvvu‐
49       data() is the number of bytes of user data given to the user.
50
51
52       Note  that the limit on the total number of bytes available in all buf‐
53       fers passed:
54
55         iov(0).iov_len + . . + iov(iovcount-1).iov_len)
56
57
58
59       may be constrained by implementation limits.  If  no  other  constraint
60       applies,  it  will be limited by INT_MAX. In practice, the availability
61       of memory to an application is likely to impose a lower  limit  on  the
62       amount  of data that can be sent or received using scatter/gather func‐
63       tions.
64
65
66       By default,  t_rcvvudata() operates in synchronous mode and waits for a
67       data  unit  to  arrive  if  none  is  currently available.  However, if
68       O_NONBLOCK is set by means of t_open(3NSL) or  fcntl(2),  t_rcvvudata()
69       executes in asynchronous mode and fails if no data units are available.
70
71
72       If the buffers defined in the  iov[] array are not large enough to hold
73       the current data unit, the buffers will be filled and  T_MORE  will  be
74       set  in  flags on return to indicate that another  t_rcvvudata() should
75       be called to retrieve the rest of the data unit.  Subsequent  calls  to
76       t_rcvvudata()  will  return  zero  for  the  length  of the address and
77       options, until the full data unit has been received.
78

RETURN VALUES

80       On successful completion,  t_rcvvudata() returns the  number  of  bytes
81       received.  Otherwise,  it  returns  -1 on failure and t_errno is set to
82       indicate the error.
83

VALID STATES

85       T_IDLE.
86

ERRORS

88       On failure, t_errno is set to one of the following:
89
90       TBADDATA       iovcount is greater than  T_IOV_MAX.
91
92
93       TBADF          The specified file descriptor does not refer to a trans‐
94                      port endpoint.
95
96
97       TBUFOVFLW      The  number of bytes allocated for the incoming protocol
98                      address or options (maxlen) is greater than  0  but  not
99                      sufficient  to  store  the  information.   The unit data
100                      information to be returned  in  unitdata  will  be  dis‐
101                      carded.
102
103
104       TLOOK          An  asynchronous  event  has  occurred on this transport
105                      endpoint and requires immediate attention.
106
107
108       TNODATA        O_NONBLOCK was set, but  no  data  units  are  currently
109                      available from the transport provider.
110
111
112       TNOTSUPPORT    This  function is not supported by the underlying trans‐
113                      port provider.
114
115
116       TOUTSTATE      The communications endpoint referenced by fd is  not  in
117                      one  of  the  states in which a call to this function is
118                      valid.
119
120
121       TPROTO         This error indicates that a  communication  problem  has
122                      been detected between XTI and the transport provider for
123                      which there is no other suitable XTI error (t_errno).
124
125
126       TSYSERR        A system error has occurred  during  execution  of  this
127                      function.
128
129

TLI COMPATIBILITY

131       In  the  TLI  interface  definition, no counterpart of this routine was
132       defined.
133

ATTRIBUTES

135       See attributes(5)  for descriptions of the following attributes:
136
137
138
139
140       ┌─────────────────────────────┬─────────────────────────────┐
141       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
142       ├─────────────────────────────┼─────────────────────────────┤
143       │MT Level                     │Safe                         │
144       └─────────────────────────────┴─────────────────────────────┘
145