Download FreeRTOS

Quality RTOS & Embedded Software

Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.


[FreeRTOS-Plus-TCP API Reference]

BaseType_t FreeRTOS_recv( Socket_t xSocket,
                          void *pvBuffer,
                          size_t xBufferLength,
                          BaseType_t xFlags );

Receive data from a TCP socket (see FreeRTOS_recvfrom() for the UDP equivalent).

The socket must have already been created using a call to FreeRTOS_socket(), bound to a port number, and connected to a remote socket.

The socket can be explicitly bound to a port number by calling FreeRTOS_bind().

The socket can actively connect to a remote socket using FreeRTOS_connect(). If FreeRTOS_connect() is called on a socket that is not bound to a port number, and the value of ipconfigALLOW_SOCKET_SEND_WITHOUT_BIND is set to 1 in FreeRTOSIPConfig.h, then the TCP/IP stack will automatically bind the socket to a port number from the private address range.

Alternatively the socket can wait for incoming connections using FreeRTOS_accept().

FreeRTOS_recv() has an optional timeout. The timeout defaults to ipconfigSOCK_DEFAULT_RECEIVE_BLOCK_TIME, and is modified using the FREERTOS_SO_RCVTIMEO parameter in a call to FreeRTOS_setsockopt(). If the receive operation cannot return received bytes immediately then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either bytes are received, or the timeout expires.

FreeRTOS-Plus-TCP does not [currently] use all the function parameters. The parameters that are not used are retained in the function's prototype to ensure consistency with the expected standard Berkeley sockets API, and to ensure compatibility with future versions of FreeRTOS-Plus-TCP.


xSocket   The handle of the socket from which data is being read.

pvBuffer   The buffer into which received data will be placed.

xBufferLength   The size of the buffer (in bytes) pointed to by the pvBuffer parameter - and therefore also the maximum number of bytes that will be read.

ulFlags   Not currently used. Future FreeRTOS-Plus-TCP versions may implement receive options using the ulFlags parameter.


If the receive was successful then the number of bytes received (placed in the buffer pointed to by pvBuffer) is returned.

If a time out occurred before data could be received then 0 is returned.

If there was not enough memory for the socket to be able to create either an Rx or Tx stream then -pdFREERTOS_ERRNO_ENOMEM is returned.

If the socket was closed or got closed then -pdFREERTOS_ERRNO_ENOTCONN is returned.

If the socket received a signal, causing the read operation to be aborted, then -pdFREERTOS_ERRNO_EINTR is returned.

If the socket is not valid, is not a TCP socket, or is not bound then -pdFREERTOS_ERRNO_EINVAL is returned;

Note that, because FreeRTOS does not implement errno, the behaviour in the presence of an error is necessarily different to that of recv() functions that are fully compliant with the expected Berkeley sockets behaviour.

Example usage:

See the "Creating, Configuring and Binding TCP Client and Server Sockets" section of the FreeRTOS-Plus-TCP networking tutorial pages for examples of how to prepare a TCP socket for receiving data.

See the "Receiving TCP Data" section of the FreeRTOS-Plus-TCP networking tutorial pages for examples of receiving data from a TCP socket.

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.