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_connect( Socket_t xClientSocket,
                             struct freertos_sockaddr *pxAddress,
                             socklen_t xAddressLength );

Connect a TCP socket to a remote socket.

The socket must first have been successfully created by a call to FreeRTOS_socket(), and optionally bound to a port using a call to FreeRTOS_bind().

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.

FreeRTOS_connect() 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 connect operation does not succeed immediately then the calling RTOS task will be held in the Blocked state (so that other tasks can execute) until either the connect request is successful, or the timeout expires.


xClientSocket   The handle of the socket being bound. The socket must have already been created (see FreeRTOS_socket()).

pxAddress   A pointer to a freertos_sockaddr structure that contains the destination IP address and port number (the remote socket the local socket is attempting to connect to).

xAddressLength   Not currently used, but should be set to sizeof( struct freertos_sockaddr ) to ensure future compatibility.


If the connect operation succeeded then 0 is returned.

If xClientSocket is not a valid TCP socket then -pdFREERTOS_ERRNO_EBADF is returned.

If xClientSocket was already connected before FreeRTOS_connect() was called then -pdFREERTOS_ERRNO_EISCONN is returned.

If xClientSocket is not in a state that allows a connect operation then either -pdFREERTOS_ERRNO_EINPROGRESS or -pdFREERTOS_ERRNO_EAGAIN is returned.

If the socket has a read block time of zero and the connect operation cannot succeed immediately then -pdFREERTOS_ERRNO_EWOULDBLOCK is returned.

If the connect attempt times out then -pdFREERTOS_ERRNO_ETIMEDOUT is returned.

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

Example usage:

See the Sending TCP Data section of the FreeRTOS-Plus-TCP networking tutorial pages.

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