Overview

Platform-neutral BSD-modeled network socket implementation.

#include "etcpal/socket.h"

WARNING: This module must be explicitly initialized before use. Initialize the module by calling etcpal_init() with the relevant feature mask:

etcpal_init(ETCPAL_FEATURE_SOCKETS);

ETCPAL_FEATURE_SOCKETS

#define ETCPAL_FEATURE_SOCKETS

Use the etcpal/socket module.

Definition: common.h:137

etcpal_init

etcpal_error_t etcpal_init(etcpal_features_t features)

Initialize the EtcPal library.

Definition: common.c:112

This module attempts to abstract the network socket interface from various platforms into one platform-neutral interface. The functions and flags are modeled after the BSD sockets interface. This API is too large and complex to provide a concise how-to here; users of this module are assumed to already be familiar with some version of the BSD interface. If not, UNIX Network Programming: The Sockets Networking API by Stevens, Fenner, and Rudoff is highly recommended reading.

Data Structures
struct	EtcPalLinger
	Option value for ETCPAL_SO_LINGER. More...

struct	EtcPalMreq
	Option value for ETCPAL_IP_ADD_MEMBERSHIP and ETCPAL_IP_DROP_MEMBERSHIP. More...

struct	EtcPalGroupReq
	Option value for ETCPAL_MCAST_JOIN_GROUP and ETCPAL_MCAST_LEAVE_GROUP. More...

struct	EtcPalMsgHdr
	Message data received from etcpal_recvmsg. More...

struct	EtcPalCMsgHdr
	Ancillary data received from etcpal_recvmsg. More...

struct	EtcPalPktInfo
	Information about a datagram packet received with etcpal_recvmsg. More...

struct	EtcPalPollEvent
	A description of an event that occurred on a socket, for usage with etcpal_poll_wait(). More...

struct	EtcPalAddrinfo
	A structure containing name and address information about an internet host. More...

Macros
#define	ETCPAL_CMSG_IS_VALID(cmsg) ((cmsg)->valid)
	This takes a pointer to a control (ancillary) message and determines if it's valid or not.

#define	ETCPAL_POLL_VALID_INPUT_EVENT_MASK 0x0fu
	Mask of valid events for use with etcpal_poll_add_socket().

#define	ETCPAL_SOCKET_INVALID [PLATFORM_DEFINED]
	An identifier for an invalid socket handle.

#define	ETCPAL_SOCKET_MAX_POLL_SIZE [PLATFORM_DEFINED]
	The maximum number of sockets that can be simultaneously monitored by etcpal_poll_wait(). More...

Typedefs
typedef uint32_t	etcpal_poll_events_t
	Event flags for the etcpal_poll_*() API functions.

typedef struct EtcPalLinger	EtcPalLinger
	Option value for ETCPAL_SO_LINGER.

typedef struct EtcPalMreq	EtcPalMreq
	Option value for ETCPAL_IP_ADD_MEMBERSHIP and ETCPAL_IP_DROP_MEMBERSHIP.

typedef struct EtcPalGroupReq	EtcPalGroupReq
	Option value for ETCPAL_MCAST_JOIN_GROUP and ETCPAL_MCAST_LEAVE_GROUP.

typedef struct EtcPalMsgHdr	EtcPalMsgHdr
	Message data received from etcpal_recvmsg.

typedef struct EtcPalCMsgHdr	EtcPalCMsgHdr
	Ancillary data received from etcpal_recvmsg.

typedef struct EtcPalPktInfo	EtcPalPktInfo
	Information about a datagram packet received with etcpal_recvmsg.

typedef struct EtcPalPollEvent	EtcPalPollEvent
	A description of an event that occurred on a socket, for usage with etcpal_poll_wait().

typedef struct EtcPalAddrinfo	EtcPalAddrinfo
	A structure containing name and address information about an internet host. More...

typedef PLATFORM_DEFINED	etcpal_socket_t
	A socket handle. More...

Functions
etcpal_error_t	etcpal_accept (etcpal_socket_t id, EtcPalSockAddr address, etcpal_socket_t conn_sock)
	Accept a connection on a socket. More...

etcpal_error_t	etcpal_bind (etcpal_socket_t id, const EtcPalSockAddr *address)
	Bind a name to a socket. More...

etcpal_error_t	etcpal_close (etcpal_socket_t id)
	Close a socket. More...

etcpal_error_t	etcpal_connect (etcpal_socket_t id, const EtcPalSockAddr *address)
	Initiate a connection on a socket. More...

etcpal_error_t	etcpal_getpeername (etcpal_socket_t id, EtcPalSockAddr *address)
	Get the name of the connected peer socket. More...

etcpal_error_t	etcpal_getsockname (etcpal_socket_t id, EtcPalSockAddr *address)
	Get socket name. More...

etcpal_error_t	etcpal_getsockopt (etcpal_socket_t id, int level, int option_name, void option_value, size_t option_len)
	Get an option value for a socket. More...

etcpal_error_t	etcpal_listen (etcpal_socket_t id, int backlog)
	Listen for connections on a socket. More...

int	etcpal_recv (etcpal_socket_t id, void *buffer, size_t length, int flags)
	Receive data on a connected socket. More...

int	etcpal_recvfrom (etcpal_socket_t id, void buffer, size_t length, int flags, EtcPalSockAddr address)
	Receive data on a socket. More...

int	etcpal_recvmsg (etcpal_socket_t id, EtcPalMsgHdr *msg, int flags)
	Receive both datagram and ancillary data on a socket. More...

bool	etcpal_cmsg_firsthdr (EtcPalMsgHdr msgh, EtcPalCMsgHdr firsthdr)
	Get the first control (ancillary) message associated with the passed in message. More...

bool	etcpal_cmsg_nxthdr (EtcPalMsgHdr msgh, const EtcPalCMsgHdr cmsg, EtcPalCMsgHdr *nxthdr)
	Get the next valid control (ancillary) message after the passed in control message. More...

bool	etcpal_cmsg_to_pktinfo (const EtcPalCMsgHdr cmsg, EtcPalPktInfo pktinfo)
	Convert a control (ancillary) message to EtcPalPktInfo. More...

int	etcpal_send (etcpal_socket_t id, const void *message, size_t length, int flags)
	Send data on a connected socket. More...

int	etcpal_sendto (etcpal_socket_t id, const void message, size_t length, int flags, const EtcPalSockAddr dest_addr)
	Send data on a socket. More...

etcpal_error_t	etcpal_setsockopt (etcpal_socket_t id, int level, int option_name, const void *option_value, size_t option_len)
	Set an option value on a socket. More...

etcpal_error_t	etcpal_shutdown (etcpal_socket_t id, int how)
	Shut down part of a full-duplex connection. More...

etcpal_error_t	etcpal_socket (unsigned int family, unsigned int type, etcpal_socket_t *id)
	Create a socket. More...

etcpal_error_t	etcpal_setblocking (etcpal_socket_t id, bool blocking)
	Change the blocking behavior of a socket. More...

etcpal_error_t	etcpal_getblocking (etcpal_socket_t id, bool *blocking)
	Get the current blocking behavior of a socket. More...

etcpal_error_t	etcpal_getaddrinfo (const char hostname, const char service, const EtcPalAddrinfo hints, EtcPalAddrinfo result)
	Get address information for a named internet host and/or service. More...

bool	etcpal_nextaddr (EtcPalAddrinfo *ai)
	Get the next address from the list returned by etcpal_getaddrinfo(). More...

void	etcpal_freeaddrinfo (EtcPalAddrinfo *ai)
	Free an addrinfo list returned by etcpal_getaddrinfo(). More...

etcpal_poll API
The etcpal_poll functions enable monitoring several sockets at once.
typedef PLATFORM_DEFINED	EtcPalPollContext
	A structure that holds context information for poll operations on multiple sockets. More...

etcpal_error_t	etcpal_poll_context_init (EtcPalPollContext *context)
	Create a new context for waiting on events on multiple sockets. More...

void	etcpal_poll_context_deinit (EtcPalPollContext *context)
	Invalidate a previously-initialized EtcPalPollContext structure. More...

etcpal_error_t	etcpal_poll_add_socket (EtcPalPollContext context, etcpal_socket_t socket, etcpal_poll_events_t events, void user_data)
	Add a new socket to an EtcPalPollContext. More...

etcpal_error_t	etcpal_poll_modify_socket (EtcPalPollContext context, etcpal_socket_t socket, etcpal_poll_events_t new_events, void new_user_data)
	Change the set of events or user data associated with a monitored socket. More...

void	etcpal_poll_remove_socket (EtcPalPollContext *context, etcpal_socket_t socket)
	Remove a monitored socket from an EtcPalPollContext. More...

etcpal_error_t	etcpal_poll_wait (EtcPalPollContext context, EtcPalPollEvent event, int timeout_ms)
	Wait for an event on a set of sockets defined by an EtcPalPollContext. More...

Flags for etcpal_recvfrom() and etcpal_recvmsg()
#define	ETCPAL_MSG_PEEK 0x1
	Input flag to cause the packet to remain in the input queue when received.

Level values for etcpal_setsockopt() and etcpal_getsockopt()
Refer to the group of option names for each level.
#define	ETCPAL_SOL_SOCKET 0
	etcpal_socket API level.

#define	ETCPAL_IPPROTO_IP 1
	IPv4 protocol level.

#define	ETCPAL_IPPROTO_ICMPV6 2
	ICMPv6 protocol level.

#define	ETCPAL_IPPROTO_IPV6 3
	IPv6 protocol level.

#define	ETCPAL_IPPROTO_TCP 4
	TCP protocol level.

#define	ETCPAL_IPPROTO_UDP 5
	UDP protocol level.

Options for level ETCPAL_SOL_SOCKET
Used in the option parameter to etcpal_setsockopt() and etcpal_getsockopt(). Refer to the similarly-named option on your favorite man page for more details.
#define	ETCPAL_SO_BROADCAST 0
	Get/Set, value is boolean int.

#define	ETCPAL_SO_ERROR 1
	Get only, value is int representing platform error value.

#define	ETCPAL_SO_KEEPALIVE 2
	Get/Set, value is boolean int.

#define	ETCPAL_SO_LINGER 3
	Get/Set, value is EtcPalLinger.

#define	ETCPAL_SO_RCVBUF 4
	Get/Set, value is int representing byte size.

#define	ETCPAL_SO_SNDBUF 5
	Get/Set, value is int representing byte size.

#define	ETCPAL_SO_RCVTIMEO 6
	Get/Set, value is int representing ms.

#define	ETCPAL_SO_SNDTIMEO 7
	Get/Set, value is int representing ms.

#define	ETCPAL_SO_REUSEADDR 8
	Get/Set, value is boolean int.

#define	ETCPAL_SO_REUSEPORT 9
	Get/Set, value is boolean int.

#define	ETCPAL_SO_TYPE 10
	Get only, value is int.

Options for level ETCPAL_IPPROTO_IP or ETCPAL_IPPROTO_IPV6
Used in the option parameter to etcpal_setsockopt() and etcpal_getsockopt(). Refer to the similarly-named option on your favorite man page for more details.
#define	ETCPAL_IP_TTL 11
	Get/Set, value is int. More...

#define	ETCPAL_IP_MULTICAST_IF 12
	Get/Set, value is unsigned int representing interface index (see Network Interface Indexes).

#define	ETCPAL_IP_MULTICAST_TTL 13
	Get/Set, value is int. More...

#define	ETCPAL_IP_MULTICAST_LOOP 14
	Get/Set, value is boolean int.

#define	ETCPAL_IP_ADD_MEMBERSHIP 15
	[Legacy IPv4-only option, use of ETCPAL_MCAST_JOIN_GROUP is preferred] Set only, value is EtcPalMreq.

#define	ETCPAL_IP_DROP_MEMBERSHIP 16
	[Legacy IPv4-only option, use of ETCPAL_MCAST_LEAVE_GROUP is preferred] Set only, value is EtcPalMreq.

#define	ETCPAL_MCAST_JOIN_GROUP 17
	Set only, value is EtcPalGroupReq.

#define	ETCPAL_MCAST_LEAVE_GROUP 18
	Set only, value is EtcPalGroupReq.

#define	ETCPAL_IPV6_V6ONLY 19
	Get/Set, value is boolean int.

#define	ETCPAL_IP_PKTINFO 20
	Get/Set, value is boolean int. More...

#define	ETCPAL_IPV6_PKTINFO 21
	Get/Set, value is boolean int (note that this equates to IPV6_RECVPKTINFO on Mac and Linux). More...

'how' values for etcpal_shutdown()
#define	ETCPAL_SHUT_RD 0

#define	ETCPAL_SHUT_WR 1

#define	ETCPAL_SHUT_RDWR 2

'family' values for etcpal_socket() and EtcPalAddrinfo
#define	ETCPAL_AF_UNSPEC 0u

#define	ETCPAL_AF_INET 1u

#define	ETCPAL_AF_INET6 2u

'type' values for etcpal_socket() and etcpal_getsockopt()
#define	ETCPAL_SOCK_STREAM 0u

#define	ETCPAL_SOCK_DGRAM 1u

Output 'flags' values for etcpal_recvmsg()
#define	ETCPAL_MSG_TRUNC 0x2
	Packet data was truncated due to insufficient space in the buffer.

#define	ETCPAL_MSG_CTRUNC 0x4
	Ancillary data was truncated due to insufficient space in the buffer.

Defines for CMSG buffer sizes required for various CMSG types
#define	ETCPAL_CONTROL_SIZE_IP_PKTINFO ETCPAL_PLATFORM_IN_PKTINFO_SPACE
	The minimum size a CMSG buffer needs to store one IPv4 PKTINFO message.

#define	ETCPAL_CONTROL_SIZE_IPV6_PKTINFO ETCPAL_PLATFORM_IN6_PKTINFO_SPACE
	The minimum size a CMSG buffer needs to store one IPv6 PKTINFO message. More...

#define	ETCPAL_MAX_CONTROL_SIZE_PKTINFO
	The minimum size a CMSG buffer needs to store one PKTINFO message (IPv4 or IPv6). More...

Flag values to use with etcpal_poll_events_t.
#define	ETCPAL_POLL_IN 0x1u
	Notify when data is available for reading on the socket.

#define	ETCPAL_POLL_OUT 0x2u
	Notify when the socket has space available to write data.

#define	ETCPAL_POLL_CONNECT 0x4u
	Notify when a non-blocking connect operation has completed.

#define	ETCPAL_POLL_OOB 0x8u
	Notify when there is out-of-band data on a TCP socket.

#define	ETCPAL_POLL_ERR 0x10u
	An error has occurred on the socket (output only).

'flags' values for EtcPalAddrinfo
Refer to the similarly-named flags in your favorite getaddrinfo() man page for more details.
#define	ETCPAL_AI_PASSIVE 0x01

#define	ETCPAL_AI_CANONNAME 0x02

#define	ETCPAL_AI_NUMERICHOST 0x04

Macro Definition Documentation

◆ ETCPAL_CONTROL_SIZE_IPV6_PKTINFO

#define ETCPAL_CONTROL_SIZE_IPV6_PKTINFO ETCPAL_PLATFORM_IN6_PKTINFO_SPACE

The minimum size a CMSG buffer needs to store one IPv6 PKTINFO message.

In order for this to be used on Linux, the application must define _GNU_SOURCE. In order for this to be used on Mac, the application must define _GNU_SOURCE and __APPLE_USE_RFC_3542.

◆ ETCPAL_IP_MULTICAST_TTL

#define ETCPAL_IP_MULTICAST_TTL 13

Get/Set, value is int.

Value indicates TTL for IPv4 or hop limit for IPv6.

◆ ETCPAL_IP_PKTINFO

#define ETCPAL_IP_PKTINFO 20

Get/Set, value is boolean int.

On lwIP, this option will not be supported unless the LWIP_NETBUF_RECVINFO compiler definition is set to 1.

◆ ETCPAL_IP_TTL

#define ETCPAL_IP_TTL 11

Get/Set, value is int.

Value indicates TTL for IPv4 or hop limit for IPv6.

◆ ETCPAL_IPV6_PKTINFO

#define ETCPAL_IPV6_PKTINFO 21

Get/Set, value is boolean int (note that this equates to IPV6_RECVPKTINFO on Mac and Linux).

This option is not currently supported on lwIP.

◆ ETCPAL_MAX_CONTROL_SIZE_PKTINFO

#define ETCPAL_MAX_CONTROL_SIZE_PKTINFO

Value:

(ETCPAL_CONTROL_SIZE_IP_PKTINFO > ETCPAL_CONTROL_SIZE_IPV6_PKTINFO ? ETCPAL_CONTROL_SIZE_IP_PKTINFO \

: ETCPAL_CONTROL_SIZE_IPV6_PKTINFO)

ETCPAL_CONTROL_SIZE_IPV6_PKTINFO

#define ETCPAL_CONTROL_SIZE_IPV6_PKTINFO

The minimum size a CMSG buffer needs to store one IPv6 PKTINFO message.

Definition: socket.h:265

ETCPAL_CONTROL_SIZE_IP_PKTINFO

#define ETCPAL_CONTROL_SIZE_IP_PKTINFO

The minimum size a CMSG buffer needs to store one IPv4 PKTINFO message.

Definition: socket.h:258

The minimum size a CMSG buffer needs to store one PKTINFO message (IPv4 or IPv6).

In order for this to be used on Linux, the application must define _GNU_SOURCE. In order for this to be used on Mac, the application must define _GNU_SOURCE and __APPLE_USE_RFC_3542.

◆ ETCPAL_SOCKET_MAX_POLL_SIZE

#define ETCPAL_SOCKET_MAX_POLL_SIZE [PLATFORM_DEFINED]

The maximum number of sockets that can be simultaneously monitored by etcpal_poll_wait().

Some systems have no compile-time limit on this value - it could be a runtime system-defined limit (e.g. ulimit) or even limited only by the amount of available memory. In that case this constant will have the value -1.

Typedef Documentation

◆ etcpal_socket_t

typedef PLATFORM_DEFINED etcpal_socket_t

A socket handle.

Typedefed to the system's socket identifier.

◆ EtcPalAddrinfo

typedef struct EtcPalAddrinfo EtcPalAddrinfo

A structure containing name and address information about an internet host.

Returned by etcpal_getaddrinfo().

◆ EtcPalPollContext

typedef PLATFORM_DEFINED EtcPalPollContext

A structure that holds context information for poll operations on multiple sockets.

See the documentation for etcpal_poll_context_init() and etcpal_poll_wait() for more information.

Function Documentation

◆ etcpal_accept()

etcpal_error_t etcpal_accept	(	etcpal_socket_t	id,
		EtcPalSockAddr *	address,
		etcpal_socket_t *	conn_sock
	)

Accept a connection on a socket.

Refer to your favorite accept() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPalSockAddr type. Connected socket is returned in an output parameter rather than the return value.

Parameters

[in]	id	Listening socket on which to accept a new connection.
[out]	address	Remote address from which the connection was accepted.
[out]	conn_sock	Filled in on success with handle to connected socket.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (failure).

◆ etcpal_bind()

etcpal_error_t etcpal_bind	(	etcpal_socket_t	id,
		const EtcPalSockAddr *	address
	)

Bind a name to a socket.

Refer to your favorite bind() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPalSockAddr type.

Parameters

[in]	id	Socket to which to bind an address (traditionally called a 'name').
[in]	address	Address to assign to the socket.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_close()

etcpal_error_t etcpal_close ( etcpal_socket_t id )

Close a socket.

Refer to your favorite close() man page for more information.

On UNIX-like systems, note that this may also successfully close descriptors that don't refer to sockets; however, for portability it should only be used on identifiers that were returned from an etcpal_* function.

Parameters

[in] id Socket to close.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_cmsg_firsthdr()

bool etcpal_cmsg_firsthdr	(	EtcPalMsgHdr *	msgh,
		EtcPalCMsgHdr *	firsthdr
	)

Get the first control (ancillary) message associated with the passed in message.

This function is used in place of the OS standard CMSG_FIRSTHDR macro. Refer to your favorite recvmsg() man page for more information.

On lwIP, in order to receive ancillary data (e.g. PKTINFO), make sure to enable the LWIP_NETBUF_RECVINFO compiler definition to enable setting the relevant socket options (e.g. ETCPAL_IP_PKTINFO).

Parameters

[in,out]	msgh	Message containing the desired control message.
[out]	firsthdr	The first control message.

Returns: True if the first CMSG header was found and outputted, or false otherwise.

◆ etcpal_cmsg_nxthdr()

bool etcpal_cmsg_nxthdr	(	EtcPalMsgHdr *	msgh,
		const EtcPalCMsgHdr *	cmsg,
		EtcPalCMsgHdr *	nxthdr
	)

Get the next valid control (ancillary) message after the passed in control message.

This function is used in place of the OS standard CMSG_NXTHDR macro. Refer to your favorite recvmsg() man page for more information.

On lwIP, in order to receive ancillary data (e.g. PKTINFO), make sure to enable the LWIP_NETBUF_RECVINFO compiler definition to enable setting the relevant socket options (e.g. ETCPAL_IP_PKTINFO).

Parameters

[in,out]	msgh	Message containing the desired control message.
[in]	cmsg	The control message preceding the desired control message.
[out]	nxthdr	The next control message.

Returns: True if the next CMSG header was found and outputted, or false otherwise.

◆ etcpal_cmsg_to_pktinfo()

bool etcpal_cmsg_to_pktinfo	(	const EtcPalCMsgHdr *	cmsg,
		EtcPalPktInfo *	pktinfo
	)

Convert a control (ancillary) message to EtcPalPktInfo.

The application must check the cmsg level and type.

This function is used in place of the OS standard CMSG_DATA macro. Refer to your favorite recvmsg() man page for more information.

On lwIP, in order to receive ancillary data (e.g. PKTINFO), make sure to enable the LWIP_NETBUF_RECVINFO compiler definition to enable setting the relevant socket options (e.g. ETCPAL_IP_PKTINFO).

Parameters

[in]	cmsg	The control message. The level should be ETCPAL_IPPROTO_IP or ETCPAL_IPPROTO_IPV6. If it's ETCPAL_IPPROTO_IP, the type should be ETCPAL_IP_PKTINFO. Otherwise if it's ETCPAL_IPPROTO_IPV6, the type should be ETCPAL_IPV6_PKTINFO.
[out]	pktinfo	A EtcPalPktInfo struct filled in from the given control message.

Returns: True if the EtcPalPktInfo struct was successfully filled in, or false otherwise.

◆ etcpal_connect()

etcpal_error_t etcpal_connect	(	etcpal_socket_t	id,
		const EtcPalSockAddr *	address
	)

Initiate a connection on a socket.

Refer to your favorite connect() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters

[in]	id	Socket to connect.
[in]	address	Address to which to connect.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_freeaddrinfo()

void etcpal_freeaddrinfo ( EtcPalAddrinfo * ai )

Free an addrinfo list returned by etcpal_getaddrinfo().

Most platforms allocate memory when getaddrinfo() is called. This must always be called after any call to etcpal_getaddrinfo() to free that memory. It can be called with any of the EtcPalAddrinfo instances in the list, and the whole list will be freed. See the example usage in the description of etcpal_getaddrinfo().

Parameters

[in] ai Pointer to EtcPalAddrinfo struct for which to free the platform memory.

◆ etcpal_getaddrinfo()

etcpal_error_t etcpal_getaddrinfo	(	const char *	hostname,
		const char *	service,
		const EtcPalAddrinfo *	hints,
		EtcPalAddrinfo *	result
	)

Get address information for a named internet host and/or service.

Refer to your favorite getaddrinfo() man page for more information. One difference between this and the POSIX function is the way that multiple addresses are iterated. EtcPal uses the etcpal_nextaddr() function instead of a next pointer to iterate over multiple addresses. For example:

EtcPalAddrinfo info;
if (0 == etcpal_getaddrinfo("www.google.com", "http", NULL, &info))
{
  do
  {
    char inet_str[ETCPAL_IP_STRING_BYTES];
    if (kEtcPalErrOk == etcpal_ip_to_string(&info.ai_addr.ip, inet_str))
    {
      printf("Address: %s\n", inet_str);
    }
    else
    {
      printf("Address conversion error!\n");
    }
  } while (etcpal_nextaddr(&info));
 
  etcpal_freeaddrinfo(&info);
}

On an internet-connected machine with DNS resolution capability, the above code should print something like:

Address: 172.217.4.196
Address: 172.217.4.196
Address: 2607:f8b0:4009:806::2004
Address: 2607:f8b0:4009:806::2004

Parameters

[in]	hostname	Either a string-represented numerical network address or a network hostname to resolve.
[in]	service	Either a string-represented numerical port number or a service name.
[in]	hints	Structure containing hints restricting the address types that can be returned.
[out]	result	On success, filled in with the first address result.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (an error occurred).

◆ etcpal_getblocking()

etcpal_error_t etcpal_getblocking	(	etcpal_socket_t	id,
		bool *	blocking
	)

Get the current blocking behavior of a socket.

This is similar to checking the state of the O_NONBLOCK flag through the fcntl() function on a BSD socket.

Parameters

[in]	id	Socket for which to read the blocking behavior.
[out]	blocking	Filled in with whether the socket is currently blocking or not.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getpeername()

etcpal_error_t etcpal_getpeername	(	etcpal_socket_t	id,
		EtcPalSockAddr *	address
	)

Get the name of the connected peer socket.

Refer to your favorite getpeername() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters

[in]	id	Connected socket for which to get the peer address.
[in]	address	Filled in with peer address on success.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getsockname()

etcpal_error_t etcpal_getsockname	(	etcpal_socket_t	id,
		EtcPalSockAddr *	address
	)

Get socket name.

Refer to your favorite getsockname() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters

[in]	id	Connected socket for which to get the bound address.
[in]	address	Filled in with bound address on success.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getsockopt()

etcpal_error_t etcpal_getsockopt	(	etcpal_socket_t	id,
		int	level,
		int	option_name,
		void *	option_value,
		size_t *	option_len
	)

Get an option value for a socket.

Refer to your favorite getsockopt() man page for more information.

Differences from POSIX: Some overlapping option values are consolidated and some legacy option values are not included. Some value types are different; see the documentation of each possible option value.

Parameters

[in]	id	Socket for which to get the option value.
[in]	level	Protocol level of the option for which to get the value.
[in]	option_name	Name of the option for which to get the value.
[out]	option_value	Filled in with option value on success.
[in,out]	option_len	Contains size of buffer pointed to by option_value, filled in with actual size of value returned.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_listen()

etcpal_error_t etcpal_listen	(	etcpal_socket_t	id,
		int	backlog
	)

Listen for connections on a socket.

Refer to your favorite listen() man page for more information.

Parameters

[in]	id	ETCPAL_SOCK_STREAM socket on which to listen.
[in]	backlog	Maximum length of pending connection queue.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_nextaddr()

bool etcpal_nextaddr ( EtcPalAddrinfo * ai )

Get the next address from the list returned by etcpal_getaddrinfo().

Most platforms allocate and return a linked list of address info structs in their getaddrinfo() implementation. To avoid further memory allocation in the abstraction layer, this non-POSIX-like way to iterate through the EtcPalAddrinfo structs is provided. To get all of the addresses returned from a etcpal_getaddrinfo() call, keep calling this on the result struct until it returns false.

Parameters

[in,out] ai Pointer to last EtcPalAddrinfo struct, filled in with values of the next address.

Returns: true (next address was filled in) or false (no more addresses or error).

◆ etcpal_poll_add_socket()

etcpal_error_t etcpal_poll_add_socket	(	EtcPalPollContext *	context,
		etcpal_socket_t	socket,
		etcpal_poll_events_t	events,
		void *	user_data
	)

Add a new socket to an EtcPalPollContext.

This socket will be monitored on future calls to etcpal_poll_wait() for the events specified in the 'events' parameter. See the definitions of the ETCPAL_POLL_* flag values for more information. The flag values can be 'or'ed together to monitor for multiple events. Only flag values that are not marked 'output only' are valid for use with this function. Errors on sockets will always be reported with the ETCPAL_POLL_ERR flag.

On some systems, the underlying polling method has a limit to how many sockets can be monitored in a single call. If there is a limit, it is defined as the positive value ETCPAL_SOCKET_MAX_POLL_SIZE. Otherwise, that constant is set to -1.

Parameters

[in,out]	context	Pointer to EtcPalPollContext to which to add new socket.
[in]	socket	Socket to start monitoring.
[in]	events	Events to monitor for on this socket.
[in]	user_data	Opaque data pointer that is passed back with events on this socket.

Returns: kEtcPalErrOk: Socket added successfully.; kEtcPalErrExists: The socket has already been added to this context.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNoMem: ETCPAL_SOCKET_MAX_POLL_SIZE is exceeded in this context.; kEtcPalErrSys: System call failed.

◆ etcpal_poll_context_deinit()

void etcpal_poll_context_deinit ( EtcPalPollContext * context )

Invalidate a previously-initialized EtcPalPollContext structure.

This must be called at shutdown or when the EtcPalPollContext is no longer needed to free any resources being used to track polling context.

Parameters

[in] context Pointer to EtcPalPollContext to deinitialize.

◆ etcpal_poll_context_init()

etcpal_error_t etcpal_poll_context_init ( EtcPalPollContext * context )

Create a new context for waiting on events on multiple sockets.

EtcPalPollContext structures contain information about an application's interest in events on a set of sockets. The etcpal_poll_wait() function can then be used to block the calling thread until one such event takes place.

This function must be called on an EtcPalPollContext structure before using it with any other etcpal_poll_* function.

Parameters

[in,out] context Pointer to EtcPalPollContext to initialize.

Returns: kEtcPalErrOk: Init successful.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrSys: System call failed.

◆ etcpal_poll_modify_socket()

etcpal_error_t etcpal_poll_modify_socket	(	EtcPalPollContext *	context,
		etcpal_socket_t	socket,
		etcpal_poll_events_t	new_events,
		void *	new_user_data
	)

Change the set of events or user data associated with a monitored socket.

The new events and/or user data will be used on the next call to etcpal_poll_wait().

Parameters

[in,out]	context	Pointer to EtcPalPollContext on which to modify socket parameters.
[in]	socket	Socket to modify.
[in]	new_events	New set of events to monitor for on this socket. Passing the same events as before is also valid if only the user data is being changed.
[in]	new_user_data	New opaque data pointer that is passed back with events on this socket. Passing the same pointer as before is also valid if only the events are being changed.

Returns: kEtcPalErrOk: Socket modified successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotFound: Socket was not previously added to this context.; kEtcPalErrSys: System call failed.

◆ etcpal_poll_remove_socket()

void etcpal_poll_remove_socket	(	EtcPalPollContext *	context,
		etcpal_socket_t	socket
	)

Remove a monitored socket from an EtcPalPollContext.

This socket will no longer be monitored on future calls to etcpal_poll_wait().

Parameters

[in,out]	context	Pointer to EtcPalPollContext from which to remove socket.
[in]	socket	Socket to remove.

◆ etcpal_poll_wait()

etcpal_error_t etcpal_poll_wait	(	EtcPalPollContext *	context,
		EtcPalPollEvent *	event,
		int	timeout_ms
	)

Wait for an event on a set of sockets defined by an EtcPalPollContext.

Waits for events defined by previous calls to etcpal_poll_add_socket() on this context structure. Reports one event at a time in the output 'event' parameter. Waits up to timeout_ms milliseconds; use ETCPAL_WAIT_FOREVER to wait indefinitely. If there are no sockets currently added to the context structure, returns the special error code kEtcPalErrNoSockets immediately.

This function should not be assumed to be thread-safe with respect to the other etcpal_poll API functions; for this reason, etcpal_poll_add_socket(), etcpal_poll_modify_socket(), and etcpal_poll_remove_socket() should not be called while this function is blocking.

Uses OS-specific APIs for monitoring multiple sockets under the hood. Details:

Platform:	API used:	Notes:
Linux	epoll()
lwIP	select()	ETCPAL_SOCKET_MAX_POLL_SIZE is controlled by FD_SETSIZE which is in turn controlled by MEMP_NUM_NETCONN in lwipopts.h.
macOS	kqueue()
MQX (RTCS)	select()	ETCPAL_SOCKET_MAX_POLL_SIZE is controlled by the RTCS config constant RTCSCFG_FD_SETSIZE.
Microsoft Windows	select()	ETCPAL_SOCKET_MAX_POLL_SIZE defaults to 64, but can be increased by setting FD_SETSIZE=[new_value] as a compile-time definition.

Parameters

[in]	context	Pointer to EtcPalPollContext for which to wait for events.
[out]	event	On success, contains information about the event that occurred.
[in]	timeout_ms	How long to wait for an event, in milliseconds. Use ETCPAL_WAIT_FOREVER to wait indefinitely.

Returns: kEtcPalErrOk: An event occurred, and information is available in the event argument.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNoSockets: The context has no sockets added to it.; kEtcPalErrTimedOut: Timed out waiting for an event to occur.; kEtcPalErrSys: System or socket call failed.; Other etcpal_error_t values are possible from underlying socket calls.

◆ etcpal_recv()

int etcpal_recv	(	etcpal_socket_t	id,
		void *	buffer,
		size_t	length,
		int	flags
	)

Receive data on a connected socket.

Refer to your favorite recv() man page for more information.

Parameters

[in]	id	Socket on which to receive.
[out]	buffer	Buffer in which to place received data.
[in]	length	Size in bytes of buffer.
[in]	flags	Receive flags.

Returns: Number of bytes received (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_recvfrom()

int etcpal_recvfrom	(	etcpal_socket_t	id,
		void *	buffer,
		size_t	length,
		int	flags,
		EtcPalSockAddr *	address
	)

Receive data on a socket.

Refer to your favorite recvfrom() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters

[in]	id	Socket on which to receive.
[out]	buffer	Buffer in which to place received data.
[in]	length	Size in bytes of buffer.
[in]	flags	Receive flags.
[out]	address	If provided, filled in on success with peer address from which the data was received.

Returns: Number of bytes received (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_recvmsg()

int etcpal_recvmsg	(	etcpal_socket_t	id,
		EtcPalMsgHdr *	msg,
		int	flags
	)

Receive both datagram and ancillary data on a socket.

Refer to your favorite recvmsg() man page for more information, but also note that the etcpal_cmsg_[...] functions must be used instead of the OS standard CMSG_[...] macros.

On lwIP, in order to receive ancillary data (e.g. PKTINFO), make sure to enable the LWIP_NETBUF_RECVINFO compiler definition to enable setting the relevant socket options (e.g. ETCPAL_IP_PKTINFO).

Parameters

[in]	id	Socket on which to receive.
[in,out]	msg	Message data filled in when a message is received.
[in]	flags	Receive flags.

Returns: Number of bytes received (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_send()

int etcpal_send	(	etcpal_socket_t	id,
		const void *	message,
		size_t	length,
		int	flags
	)

Send data on a connected socket.

Refer to your favorite send() man page for more information.

Differences from POSIX: Returns int rather than nonstandard ssize_t.

Parameters

[in]	id	Socket on which to send.
[in]	message	Message to send.
[in]	length	Size in bytes of message.
[in]	flags	Send flags.

Returns: Number of bytes sent (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_sendto()

int etcpal_sendto	(	etcpal_socket_t	id,
		const void *	message,
		size_t	length,
		int	flags,
		const EtcPalSockAddr *	dest_addr
	)

Send data on a socket.

Refer to your favorite sendto() man page for more information.

Differences from POSIX: Returns int rather than nonstandard ssize_t. addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters

[in]	id	Socket on which to send.
[in]	message	Message to send.
[in]	length	Size in bytes of message.
[in]	flags	Send flags.
[in]	dest_addr	Address to which to send the message.

Returns: Number of bytes sent (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_setblocking()

etcpal_error_t etcpal_setblocking	(	etcpal_socket_t	id,
		bool	blocking
	)

Change the blocking behavior of a socket.

This is similar to manipulating the O_NONBLOCK flag through the fcntl() function on a BSD socket.

Parameters

[in]	id	Socket for which to change the blocking behavior.
[in]	blocking	true (socket should block) or false (socket should not block).

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_setsockopt()

etcpal_error_t etcpal_setsockopt	(	etcpal_socket_t	id,
		int	level,
		int	option_name,
		const void *	option_value,
		size_t	option_len
	)

Set an option value on a socket.

Refer to your favorite setsockopt() man page for more information.

Differences from POSIX: Some overlapping option values are consolidated and some legacy option values are not included. Some value types are different; see the documentation of each possible option value.

Parameters

[in]	id	Socket for which to set the option value.
[in]	level	Protocol level of the option for which to set the value.
[in]	option_name	Name of the option for which to set the value.
[out]	option_value	Value to set for the option.
[in,out]	option_len	Size of value pointed to by option_value.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_shutdown()

etcpal_error_t etcpal_shutdown	(	etcpal_socket_t	id,
		int	how
	)

Shut down part of a full-duplex connection.

Refer to your favorite shutdown() man page for more information.

Parameters

[in]	id	Socket to be shut down.
[in]	how	How to shut down the socket, one of the ETCPAL_SHUT_* values.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_socket()

etcpal_error_t etcpal_socket	(	unsigned int	family,
		unsigned int	type,
		etcpal_socket_t *	id
	)

Create a socket.

Refer to your favorite socket() man page for more information.

Differences from POSIX: Returns an error code and fills in an output parameter for the socket handle instead of returning the socket handle. Rarely-used 'protocol' parameter is omitted.

Parameters

[in]	family	Protocol family that the socket should use.
[in]	type	Socket communication type.
[out]	id	Filled in with socket handle on success. Filled in with ETCPAL_SOCKET_INVALID on failure.

Returns: kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

Overview

Data Structures

Macros

Typedefs

Functions

etcpal_poll API

Flags for etcpal_recvfrom() and etcpal_recvmsg()

Level values for etcpal_setsockopt() and etcpal_getsockopt()

Options for level ETCPAL_SOL_SOCKET

Options for level ETCPAL_IPPROTO_IP or ETCPAL_IPPROTO_IPV6

'how' values for etcpal_shutdown()

'family' values for etcpal_socket() and EtcPalAddrinfo

'type' values for etcpal_socket() and etcpal_getsockopt()

Output 'flags' values for etcpal_recvmsg()

Defines for CMSG buffer sizes required for various CMSG types

Flag values to use with etcpal_poll_events_t.

'flags' values for EtcPalAddrinfo

Macro Definition Documentation

◆ ETCPAL_CONTROL_SIZE_IPV6_PKTINFO

◆ ETCPAL_IP_MULTICAST_TTL

◆ ETCPAL_IP_PKTINFO

◆ ETCPAL_IP_TTL

◆ ETCPAL_IPV6_PKTINFO

◆ ETCPAL_MAX_CONTROL_SIZE_PKTINFO

◆ ETCPAL_SOCKET_MAX_POLL_SIZE

Typedef Documentation

◆ etcpal_socket_t

◆ EtcPalAddrinfo

◆ EtcPalPollContext

Function Documentation

◆ etcpal_accept()

◆ etcpal_bind()

◆ etcpal_close()

◆ etcpal_cmsg_firsthdr()

◆ etcpal_cmsg_nxthdr()

◆ etcpal_cmsg_to_pktinfo()

◆ etcpal_connect()

◆ etcpal_freeaddrinfo()

◆ etcpal_getaddrinfo()

◆ etcpal_getblocking()

◆ etcpal_getpeername()

◆ etcpal_getsockname()

◆ etcpal_getsockopt()

◆ etcpal_listen()

◆ etcpal_nextaddr()

◆ etcpal_poll_add_socket()

◆ etcpal_poll_context_deinit()

◆ etcpal_poll_context_init()

◆ etcpal_poll_modify_socket()

◆ etcpal_poll_remove_socket()

◆ etcpal_poll_wait()

◆ etcpal_recv()

◆ etcpal_recvfrom()

◆ etcpal_recvmsg()

◆ etcpal_send()

◆ etcpal_sendto()

◆ etcpal_setblocking()

◆ etcpal_setsockopt()

◆ etcpal_shutdown()

◆ etcpal_socket()