.th TcpReceive III 4/21/86
.sh "NAME"
TcpReceive - receive data from a TCP connection
.sh "C SYNOPSIS"
.nf
 int         Loc_Name;
 char        *Buf_Addr;
 int         Max_Size;
 int         *Buf_Size;
 int         *Buf_Flag;
 int         Async_ID;
 int         (*Async_SR)();
 int         Time_Out;
 int         stat;
 . . .
 stat = TcpReceive (Loc_Name,
                    Buf_Addr,
                    Max_Size,
                    Buf_Size,
                    Buf_Flag,
                    Async_ID,
                    Async_SR,
                    Time_Out);
.fi
.sh "DESCRIPTION"
The TcpReceive primitive is used to receive data from a TCP connection.
.s3
The Loc_Name parameter is the local connection name associated with a
specific TCP connection.  This identifier was returned from a
previously successful TcpOpen primitive call to establish the
connection.
.s3
The Buf_Addr parameter is an address of the buffer to store the data
received on the connection.  The Max_Size is the maximum size of this
data buffer.  When data arrives from the remote TCP for this
connection, the TCP Daemon will buffer this data within the Network
Sharable Segment associated with this connection.  When the application
process issues the TcpReceive request and there is a sufficient amount
of data buffered to satisfy this request, the data is transferred into
the specified user's buffer pointed to by Buf_Addr and the actual
number of bytes transferred is stored in the location addressed by
Buf_Size.  In addition, any flags associated with this data are also
set in the location addressed by Buf_Flag.
.s3
The Time_Out parameter specifies the amount of time (ticks) which this
TcpReceive request may be pending.  
.s3
The asynchronous service handling parameters, Async_ID and Async_SR,
are currently not implemented by the TCP Daemon.  These parameters must
be set to null (0) until this feature has been incorporated within the
daemon.
.s3
When data is transferred to the buffer, the application process must
only use the Buf_Size value to determine the actual number of bytes
transferred.  Under most circumstances, the number of bytes transferred
will not coincide with the number of bytes contained within an actual
network message.  This is due to the data flow policies governing TCP
connections.  In fact, the incoming data from the remote TCP will be
segmentized into variable size data chunks with each chunk arriving as
part of a separate network message.  However, the daemon will guarantee
that all data transferred to the application will always be in the
order received from the remote TCP.
.sh "EXCEPTIONS"
TcpReceive
returns the following error codes:
.lp 10 0
.nf
XtcpOK    (0)      Successful
XtcpNoX   (3)      Non-existent TCP Daemon
XtcpNoNSS (6)      Non-existent TCP Connection
XtcpLock  (10)     Can not lock Network Sharable Segment
XtcpRbusy (9)      Exceeded pending TcpReceive's per user limit
XtcpAsync (7)      Asynchronous request ack'ed by daemon
.fi
.i0
.sh "FILES"
.nf
/ksb/include/tcp.h     TCP Interface Definitions for C
/ksb/lib/TCP.a   TCP Interface Library for C
.fi
.sh "SEE ALSO"
TcpOpen (III)

