@CHIP-RTOS C Library - TCP/IP API

recv

Receive a message from another socket.

int recv ( int sd, char far *bufptr, int bufLen,
           int flags, unsigned long timeout,
           int *error );

Parameters

sd

Socket descriptor.

bufptr

Output parameter:   Pointer to input buffer where received characters will be stored.

bufLen

Maximum characters to store in buffer at bufptr .

flags

Wait option:

• MSG_BLOCKING - Sleep until data comes in.
  
• MSG_TIMEOUT - The caller wakes up after timeout or if any data is received.
  
• MSG_DONTWAIT - Return immediately after collecting what ever data is ready.
  

timeout

Maximum milliseconds to wait if flags is set to MSG_TIMEOUT

error

Output parameter:  Failure code, 0 on success.

Return Value

-1: Failure, see error value reported
otherwise: Count of received bytes stored in buffer at bufptr

Comments

This API function applies only to TCP sockets.   It receives a message from another socket.   This API function may be used only if the socket is in a connected state.

If flags parameter is set to MSG_DONTWAIT, this API call returns immediately.  If no data is available -1 is returned and output parameter error is set to 235.

If flags parameter is set to MSG_BLOCKING, the recv call waits for either a message to arrive or a socket error condition to occur (such as connection lost or socket closed).   By default the blocking mode is set for all sockets at the opensocket call.   If however the socket was subsequently set to non-blocking mode with the Set_Blocking_Mode API, the MSG_BLOCKING flag will then not work here.

SC1x3/SC2x Comments

This legacy version of recv() specified here is not compatible to the BSD 4.4 Socket API.   The recv() function can be used in BSD 4.4 compatible mode if the compilation switch

     #define BSD44_SOCKET_API_STYLE

is defined in the user application prior to including the Beck C-Library header files.   Using this switch the C-Library TCPIP_Socket.H include file redefines recv() to recv_bsd().  The parameters to recv_bsd() are identical to the parameters of the BSD4.4 socket recv() function.

The recv_bsd() method uses dynamical linking, so therefore executes faster than this legacy API's sofware interrupt method. The compilation switch

     #define TCPIP_DYN_LINK_SOCK

may be defined in the user application prior to including the Beck C-Library header files to implement this legacy recv() method using the faster recv_bsd() dynamic linked API.

The first compilation switch takes precedence.   This second compilation option, TCPIP_DYN_LINK_SOCK will be not affect this API when the first option (BSD44_SOCKET_API_STYLE ) is defined.

See Also

send        recvfrom        opensocket
Set_Blocking_Mode        select        select_ms
recv_bsd                

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00