Tinycsocket

Crossplatform header-only low-level socket C library.

Repository: https://github.com/dosshell/tinycsocket

Online documentation: https://tinycsocket.readthedocs.io/

Download: latest

// Put the following define in exactly one of your c/cpp files before including.
#define TINYCSOCKET_IMPLEMENTATION
#include "tinycsocket.h"

int main(int argc, const char* argv[])
{
    tcs_lib_init();

    TcsSocket client_socket = TCS_SOCKET_INVALID;
    tcs_socket(&client_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
    tcs_connect_str(client_socket, "example.com", 80);

    uint8_t send_buffer[] =
        "GET / HTTP/1.1\r\n"
        "Host: example.com\r\n"
        "Connection: close\r\n"
        "\r\n";
    tcs_send(client_socket, send_buffer, sizeof(send_buffer) - 1, TCS_MSG_SENDALL, NULL);

    uint8_t recv_buffer[8192] = {0};
    size_t bytes_received = 0;
    tcs_receive(client_socket, recv_buffer, sizeof(recv_buffer), TCS_MSG_WAITALL, &bytes_received);

    tcs_shutdown(client_socket, TCS_SHUTDOWN_BOTH);
    tcs_close(&client_socket);

    tcs_lib_cleanup();
}

Tinycsocket is a thin cross-platform header-only low-level socket library written in C99 (with C++ compatibility).

It focuses on a minimal footprint to get crossplatform sockets, fast compilations and to be intuitive to use.

When working with sockets, you notice that almost all of the popular desktop and server operating systems implement “BSD sockets”. But the implementations differs and they have their own extensions. If you make #ifdef for all differences (which many are non obvious), make a general error handling and implement the different poll systems… you get tinycsocket! Oh, and also add some common low-level functions outside BSD sockets, such as list all available network interfaces on your machine.

The API is a superset of the BSD sockets API with some differences. All functions return an error-code. The advantage is that the error handling is simple to understand and to handle for all platforms. The disadvantage is that the functions can not be easily integrated in expressions. Note that the TcsSocket type is your native OS socket type. You can call any OS specific code that expects native sockets or vice versa.

This library does NOT provide any event system or any high level abstractions.

See the example folder for information of how to use tinycsocket.

Currently supported platforms: - Windows NT 5.0 SP1 (Windows 2000 SP1) or newer. - POSIX.1-2001 compliant systems (Linux, FreeBSD, OpenBSD, MacOS, Solaris etc.) - Android (API level 24+ for full IPv6 interface support)

Installation instructions

The library supports both header-only and the cmake build system. When using cmake build system you do not need to define the implementation definition.

Use the header only

Download the latest header from the include directory in this repository.

Download latest

You need to define TINYCSOCKET_IMPLEMENTATION in exactly one translation unit (c/cpp file) before including the header file. You can put this in a separate translation unit to not pollute your namespace with OS socket symbols.

In exactly one translation unit:

#define TINYCSOCKET_IMPLEMENTATION
#include "tinycsocket.h"

In the others:

#include "tinycsocket.h"

I want to use CMake

If you are using cmake version 3.11 or newer, you can easily add tinycsocket to your build system. This is how I use it most of the times.

Here is an example of a CMakeLists.txt file that let you link to tinycsocket:

include(FetchContent)
FetchContent_Declare(
    tinycsocket
    GIT_REPOSITORY https://github.com/dosshell/tinycsocket.git
    GIT_TAG v0.4  # Use the latest version tag, or master if you want to break your build system in the future
)
FetchContent_MakeAvailable(tinycsocket)

# You can now link to tinycsocket from your target
add_executable(my-cmake-project main.cpp)
target_link_libraries(my-cmake-project PRIVATE tinycsocket)

And that’s it. You can now include tinycsocket.h in your target and start using it.

I just want the lib files and link by my self

You can also build this project to get a lib directory and an include directory. Generate a build-system out of tinycsocket with cmake and build the install target. Don’t forget that if you are targeting Windows you also need to link to wsock32.lib, ws2_32.lib and iphlpapi.lib.

The following commands will create these include- and lib folders in a folder named install:

git clone https://github.com/dosshell/tinycsocket.git
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX:Path=../install ../tinycsocket
cmake --build . --target INSTALL --config Release

You can now remove the build directory and the tinycsocket directory if you like.

Tested platforms in CI

These platforms are tested for every pull request. All configurations are tested as both static library and header-only.

OS	Compiler	Arch	Notes
Windows Server 2025	MSVC v19.44	x86
Windows Server 2025	MSVC v19.44	x64
Windows Server 2025	i686-w64-mingw32-gcc-posix v13	x86	WINVER 0x500
Windows Server 2025	i686-w64-mingw32-gcc-posix v13	x86	WINVER 0x502
Windows Server 2025	i686-w64-mingw32-gcc v15.2	x86	WINVER 0x603
Windows Server 2025	x86_64-w64-mingw32-gcc-posix v13	x64	WINVER 0x502
Windows Server 2025	x86_64-w64-mingw32-gcc v15.2	x64	WINVER 0x603
Wine (Alpine 3.23)	MSVC v19.44	x86
Wine (Alpine 3.23)	MSVC v19.44	x64
Wine (Alpine 3.23)	i686-w64-mingw32-gcc-posix v13	x86	WINVER 0x500
Wine (Alpine 3.23)	i686-w64-mingw32-gcc-posix v13	x86	WINVER 0x502
Wine (Alpine 3.23)	i686-w64-mingw32-gcc v15.2	x86	WINVER 0x603
Wine (Alpine 3.23)	x86_64-w64-mingw32-gcc-posix v13	x64	WINVER 0x502
Wine (Alpine 3.23)	x86_64-w64-mingw32-gcc v15.2	x64	WINVER 0x603
Linux Alpine 3.23 (musl)	gcc v15.2	x86_64
Linux Alpine 3.23 (musl)	gcc v15.2	x86
Linux Ubuntu 24.04 (glibc)	gcc v13.3	x86_64
Linux Ubuntu 24.04 (glibc)	gcc v13.3	x86
Linux Ubuntu 24.04 (glibc)	s390x-linux-gnu-gcc	s390x	Big-endian
MacOS (latest)	Apple Clang	arm64
FreeBSD 15.0	Clang 19.1	x86_64
OpenBSD (latest)	Clang	x86_64
Android API 24 (Bionic)	NDK Clang	x86_64	Emulator
Android API 21 (Bionic)	NDK Clang	x86_64	Emulator, ioctl fallback
OmniOS (illumos)	gcc	x86_64
OmniOS (illumos)	gcc	x86_64	ioctl fallback
Cygwin (Windows Server 2025)	gcc	x86_64

Function Reference Index

List of all available functions in TinyCSocket:

symbol	description
tcs_strerror	Convert a tinycsocket result code to a static human-readable string.
tcs_lib_init	Initialize tinycsocket library.
tcs_lib_cleanup	De-initialize tinycsocket library.
tcs_socket	Create a new socket (BSD-style)
tcs_socket_tcp	Create a TCP socket, optionally bind to a local address and/or connect to a remote address.
tcs_socket_tcp_str	Create a TCP socket from string addresses, optionally bind and/or connect.
tcs_socket_udp	Create a UDP socket, optionally bind to a local address and/or connect to a remote address.
tcs_socket_udp_str	Create a UDP socket from string addresses, optionally bind and/or connect.
tcs_socket_packet	Create a packet socket bound to a network interface.
tcs_socket_packet_str	Create a packet socket bound to a named network interface.
tcs_close	Closes the socket, stop communication and free all resources for the socket.
tcs_bind	Binds a socket to a local address.
tcs_connect	Connect a socket to a remote address structure.
tcs_connect_str	Connect a socket to a remote hostname and port.
tcs_listen	Let a socket start listening for incoming connections.
tcs_accept	Accept a socket from a listening socket.
tcs_shutdown	Turn off communication with a 3-way handshaking for the socket.
tcs_send	Sends data on a socket, blocking.
tcs_send_to	Sends data to an address, useful with UDP sockets.
tcs_sendv	Sends several data buffers on a socket as one message.
tcs_send_netstring	Send data encoded as a netstring.
tcs_receive	Receive data from a socket to your buffer.
tcs_receive_from	Receive data from an address, useful with UDP sockets.
tcs_receive_line	Read up to and including a delimiter.
tcs_receive_netstring	Receive a netstring-encoded message.
tcs_poll_create	Create a context used for waiting on several sockets.
tcs_poll_destroy	Frees all resources bound to the poll context.
tcs_poll_add	Add a socket to the poll context.
tcs_poll_modify	Modify the poll flags for a socket already in the poll context.
tcs_poll_remove	Remove a socket from the poll context.
tcs_poll_wait	Wait for events on sockets in the poll context.
tcs_opt_set	Set parameters on a socket. It is recommended to use tcs_opt_*_set() instead.
tcs_opt_get	Get parameters on a socket. It is recommended to use tcs_opt_*_get() instead.
tcs_opt_type_get	Query the socket type (e.g.
tcs_opt_broadcast_set	Enable the socket to be allowed to send to broadcast addresses.
tcs_opt_broadcast_get	Query whether broadcast is enabled on a socket.
tcs_opt_keep_alive_set	Enable or disable TCP keep-alive on a socket.
tcs_opt_keep_alive_get	Query whether keep-alive is enabled on a socket.
tcs_opt_reuse_address_set	Allow or disallow address reuse on a socket.
tcs_opt_reuse_address_get	Query whether address reuse is enabled on a socket.
tcs_opt_reuse_port_set	Allow or disallow multiple sockets to bind to the same address and port.
tcs_opt_reuse_port_get	Query whether port reuse is enabled on a socket.
tcs_opt_send_buffer_size_set	Set the send buffer size of a socket.
tcs_opt_send_buffer_size_get	Query the send buffer size of a socket.
tcs_opt_receive_buffer_size_set	Set the receive buffer size of a socket.
tcs_opt_receive_buffer_size_get	Query the receive buffer size of a socket.
tcs_opt_receive_timeout_set	Set the receive timeout of a socket.
tcs_opt_receive_timeout_get	Query the receive timeout of a socket.
tcs_opt_linger_set	Configure the linger behavior of a socket on close.
tcs_opt_linger_get	Query the linger behavior of a socket.
tcs_opt_ip_no_delay_set	Enable or disable Nagle’s algorithm (TCP_NODELAY).
tcs_opt_ip_no_delay_get	Query whether Nagle’s algorithm is disabled on a socket.
tcs_opt_out_of_band_inline_set	Enable or disable inline reception of out-of-band data.
tcs_opt_out_of_band_inline_get	Query whether out-of-band data is received inline.
tcs_opt_priority_set	Set the socket priority.
tcs_opt_priority_get	Query the socket priority.
tcs_opt_membership_add_to	Join a multicast group on a specific local interface.
tcs_opt_membership_drop_from	Leave a multicast group on a specific local interface.
tcs_opt_membership_add	Join a multicast group using the default local interface.
tcs_opt_membership_add_str	Join a multicast group by address string.
tcs_opt_membership_drop	Leave a multicast group using the default local interface.
tcs_opt_membership_drop_str	Leave a multicast group by address string.
tcs_opt_multicast_interface_set	Set the outgoing interface for multicast packets.
tcs_opt_multicast_loop_set	Enable or disable multicast loopback.
tcs_opt_multicast_loop_get	Get the current multicast loopback setting.
tcs_opt_nonblocking_set	Set a socket to non-blocking or blocking mode.
tcs_opt_nonblocking_get	Query the non-blocking state of a socket.
tcs_interface_list	List available network interfaces.
tcs_address_resolve	Resolve a hostname to one or more addresses.
tcs_address_list	List addresses associated with network interfaces.
tcs_address_socket_local	Get the local address of a bound or connected socket.
tcs_address_socket_remote	Get the remote address of a connected socket.
tcs_address_socket_family	Get the address family of a socket.
tcs_address_parse	Parse a network address from a string.
tcs_address_to_str	Convert an address to a string.
tcs_address_is_equal	Check if two addresses are equal. Returns false for NULL, mismatched, unknown, or unsupported address families.
tcs_address_is_any	Check if the address is a wildcard (any) address. Returns false for NULL, unknown, or unsupported address families.
tcs_address_is_link_local	Check if the address is a link-local address. Returns false for NULL, unknown, or unsupported address families.
tcs_address_is_loopback	Check if the address is a loopback address. Returns false for NULL, unknown, or unsupported address families.
tcs_address_is_multicast	Check if the address is a multicast address. Returns false for NULL, unknown, or unsupported address families.
tcs_address_is_broadcast	Check if the address is a broadcast address. Returns false for NULL, unknown, or unsupported address families.
tcs_address_is_supported	Check if the address family is known and supported by this platform. Returns false for NULL or unknown families.

Constant Reference Index

List of all available constants in TinyCSocket:

symbol	description
char* TCS_VERSION_TXT
char* TCS_LICENSE_TXT
TcsFamily TCS_FAMILY_ANY	Layer 4 agnostic (AF_UNSPEC)
TcsFamily TCS_FAMILY_IPV4	INET IPv4 interface (AF_INET)
TcsFamily TCS_FAMILY_IPV6	INET IPv6 interface (AF_INET6)
TcsFamily TCS_FAMILY_PACKET	Layer 2 interface (AF_PACKET on Linux; unsupported elsewhere)
struct TcsAddress TCS_ADDRESS_NONE
TcsAddressIpv4 TCS_ADDRESS_IPV4_ANY
TcsAddressIpv4 TCS_ADDRESS_IPV4_LOOPBACK
TcsAddressIpv4 TCS_ADDRESS_IPV4_BROADCAST
TcsAddressIpv4 TCS_ADDRESS_IPV4_NONE
struct TcsAddressIpv6 TCS_ADDRESS_IPV6_ANY
struct TcsAddressIpv6 TCS_ADDRESS_IPV6_LOOPBACK
TcsSocket TCS_SOCKET_INVALID	Define new sockets to this value, always.
uint32_t TCS_FLAG_NONE
TcsSocketType TCS_SOCKET_STREAM	Use for streaming types like TCP
TcsSocketType TCS_SOCKET_DGRAM	Use for datagrams types like UDP
TcsSocketType TCS_SOCKET_RAW	Use for raw sockets, eg. layer 2 packet sockets
TcsProtocol TCS_PROTOCOL_IP_TCP	TCP, IANA-assigned (RFC 9293). Use with TCS_SOCKET_STREAM.
TcsProtocol TCS_PROTOCOL_IP_UDP	UDP, IANA-assigned (RFC 768). Use with TCS_SOCKET_DGRAM.
TcsProtocol TCS_PROTOCOL_ETH_ALL	Receive all protocols. Use with TCS_FAMILY_PACKET.
uint32_t TCS_MSG_PEEK
uint32_t TCS_MSG_OOB
uint32_t TCS_MSG_WAITALL
uint32_t TCS_MSG_SENDALL
int TCS_BACKLOG_MAX	Max number of queued sockets when listening
int32_t TCS_SOL_SOCKET	Socket option level for socket options
int32_t TCS_SOL_IP	IP option level for socket options
int32_t TCS_SOL_TCP	TCP option level for socket options
int32_t TCS_SOL_PACKET	Packet option level for socket options. Linux-only; -1 elsewhere.
int32_t TCS_SO_TYPE
int32_t TCS_SO_BROADCAST
int32_t TCS_SO_KEEPALIVE
int32_t TCS_SO_LINGER
int32_t TCS_SO_REUSEADDR
int32_t TCS_SO_REUSEPORT
int32_t TCS_SO_RCVBUF	Byte size of receiving buffer
int32_t TCS_SO_RCVTIMEO
int32_t TCS_SO_SNDBUF	Byte size of sending buffer
int32_t TCS_SO_OOBINLINE
int32_t TCS_SO_PRIORITY
int32_t TCS_IP_MEMBERSHIP_ADD
int32_t TCS_IP_MEMBERSHIP_DROP
int32_t TCS_IP_MULTICAST_LOOP
int32_t TCS_TCP_NODELAY
int32_t TCS_PACKET_MEMBERSHIP_ADD
int32_t TCS_PACKET_MEMBERSHIP_DROP
int32_t TCS_WAIT_INF
struct TcsPollEvent TCS_POLL_EVENT_EMPTY

Reference Details

This section contains details of all functions. Note that this is also available in source code as doxygen comments.

tcs_strerror

Convert a tinycsocket result code to a static human-readable string.

const char* tcs_strerror(TcsResult result)

The returned pointer is never NULL and must not be freed.

Parameters:

type	name	description
TcsResult	result

tcs_lib_init

Initialize tinycsocket library.

TcsResult tcs_lib_init(void)

This function needs to be called before using any other function in the library.

On Windows, it will initialize Winsock, otherwise it does nothing and will always return TCS_SUCCESS .

You can call this multiple times, it will keep a counter of how many times you have called it (RAII friendly). You should call tcs_lib_cleanup() after you are done with the library (before program exit), atleast the number of times you have called tcs_lib_init() .

#include "tinycsocket.h"

int main()
{
  TcsResult tcs_init_res = tcs_lib_init();
  if (tcs_init_res != TCS_SUCCESS)
      return -1; // Failed to initialize tinycsocket
  // Do stuff with the library here
  tcs_lib_cleanup();
}

Parameters:

type	name	description
void	None

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_SYSTEM – if a system error occurred. Maybe the Windows version is not supported, or broken.

• TCS_ERROR_MEMORY – if the library failed to allocate memory.

See Also:

• tcs_lib_cleanup()

tcs_lib_cleanup

De-initialize tinycsocket library.

TcsResult tcs_lib_cleanup(void)

You need to call this the same amount of times as you have called tcs_lib_init() .

Parameters:

type	name	description
void	None

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_LIBRARY_NOT_INITIALIZED – if you have not called tcs_lib_init() before calling this function.

tcs_socket

Create a new socket (BSD-style)

TcsResult tcs_socket(TcsSocket *out_socket, TcsFamily family, TcsSocketType type, TcsProtocol protocol)

This is a thin wrapper around the native socket function. You may want to use one of the helper functions to create and setup a socket directly:

• tcs_socket_tcp_str()

• tcs_socket_udp_str()

• tcs_socket_packet_str()

Call tcs_close() to stop communication and free all resources for the socket.

#include "tinycsocket.h"

int main()
{
  TcsResult tcs_init_res = tcs_lib_init();
  if (tcs_init_res != TCS_SUCCESS)
      return -1; // Failed to initialize tinycsocket

  TcsSocket my_socket = TCS_SOCKET_INVALID; // Always initialize TcsSocket to TCS_SOCKET_INVALID.
  TcsResult tcs_socket_res = tcs_socket(&my_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
  if (tcs_socket_res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -2; // Failed to create socket
  }

  // Do stuff with my_socket here. See examples in the documentation.

  tcs_close(&my_socket); // Safe to call even if my_socket is TCS_SOCKET_INVALID
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
TcsFamily	family	See TcsFamily for supported values.
TcsSocketType	type	specifies the type of the socket, supported values are: TCS_SOCKET_STREAM, TCS_SOCKET_DGRAM and TCS_SOCKET_RAW.
TcsProtocol	protocol	specifies the protocol, for example TCS_PROTOCOL_IP_TCP or TCS_PROTOCOL_IP_UDP.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_SUCCESS – if successful.

• TCS_ERROR_INVALID_ARGUMENT – if you have provided an invalid argument. Such as a socket that is not TCS_SOCKET_INVALID.

• TCS_ERROR_NOT_SUPPORTED – if you have provided an address family, type, or protocol that is not supported on this platform.

• TCS_ERROR_PERMISSION_DENIED – if you do not have permission to create the socket. E.g. raw sockets often require elevated permissions.

See Also:

• tcs_socket_tcp_str()

• tcs_socket_udp_str()

• tcs_socket_packet_str()

• tcs_close()

• tcs_lib_init()

• tcs_lib_cleanup()

tcs_socket_tcp

Create a TCP socket, optionally bind to a local address and/or connect to a remote address.

TcsResult tcs_socket_tcp(TcsSocket *out_socket, const struct TcsAddress *local_address, const struct TcsAddress *remote_address, int timeout_ms)

Creates an IPv4 or IPv6 TCP socket based on the address family of the provided address(es). If local_address is not NULL, SO_REUSEADDR is set and the socket is bound to it. If remote_address is not NULL, the socket connects to it. At least one of local_address or remote_address must be non-NULL. If both are provided, they must have the same address family. On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  struct TcsAddress local = TCS_ADDRESS_NONE;
  local.family = TCS_FAMILY_IPV4;
  local.data.ipv4.address = TCS_ADDRESS_IPV4_ANY;
  local.data.ipv4.port = 8080;

  TcsSocket server = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_tcp(&server, &local, NULL, 0);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now bound, call tcs_listen() and tcs_accept() to accept connections

  tcs_close(&server);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const struct TcsAddress *	local_address	address to bind to, or NULL to skip binding.
const struct TcsAddress *	remote_address	address to connect to, or NULL to skip connecting.
int	timeout_ms	maximum time in milliseconds to wait for connection, or TCS_WAIT_INF for OS default timeout. Ignored if remote_address is NULL.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, if both addresses are NULL, or if both are provided with different address families.

• TCS_ERROR_CONNECTION_REFUSED – if the remote server refused the connection.

• TCS_ERROR_TIMED_OUT – if the connection attempt timed out.

See Also:

• tcs_connect()

• tcs_listen()

• tcs_close()

tcs_socket_tcp_str

Create a TCP socket from string addresses, optionally bind and/or connect.

TcsResult tcs_socket_tcp_str(TcsSocket *out_socket, const char *local_address, const char *remote_address, int timeout_ms)

Resolves the address strings with tcs_address_resolve() and delegates to tcs_socket_tcp() . Addresses must include a port, e.g. “127.0.0.1:8080” or “[::1]:8080”. At least one of local_address or remote_address must be non-NULL. On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  TcsSocket socket = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_tcp_str(&socket, NULL, "127.0.0.1:8080", 5000);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now connected and ready for communication

  tcs_close(&socket);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const char *	local_address	address string to bind to, or NULL to skip binding.
const char *	remote_address	address string to connect to, or NULL to skip connecting.
int	timeout_ms	maximum time in milliseconds to wait for connection, or TCS_WAIT_INF for OS default timeout. Ignored if remote_address is NULL.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, or if both addresses are NULL.

• TCS_ERROR_CONNECTION_REFUSED – if the remote server refused the connection.

• TCS_ERROR_TIMED_OUT – if the connection attempt timed out.

See Also:

• tcs_socket_tcp()

• tcs_close()

tcs_socket_udp

Create a UDP socket, optionally bind to a local address and/or connect to a remote address.

TcsResult tcs_socket_udp(TcsSocket *out_socket, const struct TcsAddress *local_address, const struct TcsAddress *remote_address)

Creates an IPv4 or IPv6 UDP socket based on the address family of the provided address(es). If local_address is not NULL, SO_REUSEADDR is set and the socket is bound to it. If remote_address is not NULL and is a unicast address, the socket is connected to it, allowing use of tcs_send() instead of tcs_send_to() . If remote_address is a multicast address, the socket joins the multicast group. When only remote_address is given (no local_address ), the socket is also connected, allowing use of tcs_send() . When both are given, the socket is not connected to avoid filtering out multicast traffic — use tcs_send_to() instead. At least one of local_address or remote_address must be non-NULL. If both are provided, they must have the same address family. On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  struct TcsAddress local = TCS_ADDRESS_NONE;
  local.family = TCS_FAMILY_IPV4;
  local.data.ipv4.address = TCS_ADDRESS_IPV4_ANY;
  local.data.ipv4.port = 8080;

  TcsSocket socket = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_udp(&socket, &local, NULL);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now bound and ready to receive with tcs_receive_from()

  tcs_close(&socket);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const struct TcsAddress *	local_address	address to bind to, or NULL to skip binding.
const struct TcsAddress *	remote_address	address to connect to, or NULL to skip connecting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, if both addresses are NULL, or if both are provided with different address families.

See Also:

• tcs_socket_udp_str()

• tcs_close()

tcs_socket_udp_str

Create a UDP socket from string addresses, optionally bind and/or connect.

TcsResult tcs_socket_udp_str(TcsSocket *out_socket, const char *local_address, const char *remote_address)

Parses the address strings with tcs_address_resolve() and delegates to tcs_socket_udp() . Addresses must include a port, e.g. “127.0.0.1:8080” or “[::1]:8080”. At least one of local_address or remote_address must be non-NULL. On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  TcsSocket socket = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_udp_str(&socket, "0.0.0.0:8080", NULL);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now bound and ready to receive with tcs_receive_from()

  tcs_close(&socket);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const char *	local_address	address string to bind to, or NULL to skip binding.
const char *	remote_address	address string to connect to, or NULL to skip connecting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, or if both addresses are NULL.

See Also:

• tcs_socket_udp()

• tcs_close()

tcs_socket_packet

Create a packet socket bound to a network interface.

TcsResult tcs_socket_packet(TcsSocket *out_socket, const struct TcsAddress *bind_address, TcsSocketType type)

Creates an AF_PACKET socket for sending and receiving raw L2 frames. The socket is bound to the interface and protocol specified in bind_address . On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  struct TcsAddress bind = TCS_ADDRESS_NONE;
  bind.family = TCS_FAMILY_PACKET;
  bind.data.packet.interface_id = 1; // e.g. lo
  bind.data.packet.protocol = 0x22F0; // e.g. AVTP

  TcsSocket socket = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_packet(&socket, &bind, TCS_SOCKET_DGRAM);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now bound and ready for tcs_send_to() / tcs_receive_from()

  tcs_close(&socket);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const struct TcsAddress *	bind_address	address with family TCS_FAMILY_PACKET specifying interface_id and protocol.
TcsSocketType	type	socket type, either TCS_SOCKET_RAW for full L2 frames or TCS_SOCKET_DGRAM for frames without the L2 header.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, or if bind_address is NULL or not TCS_FAMILY_PACKET.

See Also:

• tcs_socket_packet_str()

• tcs_close()

tcs_socket_packet_str

Create a packet socket bound to a named network interface.

TcsResult tcs_socket_packet_str(TcsSocket *out_socket, const char *interface_name, uint16_t protocol, TcsSocketType type)

Looks up the interface by name using tcs_interface_list() and delegates to tcs_socket_packet() . On failure, *out_socket is always set back to TCS_SOCKET_INVALID .

#include "tinycsocket.h"
int main()
{
  tcs_lib_init();

  TcsSocket socket = TCS_SOCKET_INVALID;
  TcsResult res = tcs_socket_packet_str(&socket, "eth0", 0x22F0, TCS_SOCKET_DGRAM);
  if (res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -1;
  }

  // Socket is now bound and ready for tcs_send_to() / tcs_receive_from()

  tcs_close(&socket);
  tcs_lib_cleanup();
}

Parameters:

type	name	description
TcsSocket *	out_socket	pointer to socket context to be created, which must have been initialized to TCS_SOCKET_INVALID before use.
const char *	interface_name	name of the network interface to bind to.
uint16_t	protocol	EtherType protocol in host byte order, e.g. 0x22F0 for AVTP.
TcsSocketType	type	socket type, either TCS_SOCKET_RAW for full L2 frames or TCS_SOCKET_DGRAM for frames without the L2 header.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if out_socket is NULL, if *out_socket is not TCS_SOCKET_INVALID, or if interface_name is NULL or not found.

See Also:

• tcs_socket_packet()

• tcs_close()

tcs_close

Closes the socket, stop communication and free all resources for the socket.

TcsResult tcs_close(TcsSocket *socket)

This will free all resources associated with the socket and set the socket value to TCS_SOCKET_INVALID .

Parameters:

type	name	description
TcsSocket *	socket	is a pointer to your socket context you have previously created with tcs_socket() or one of the helper functions. Will be set to TCS_SOCKET_INVALID on success.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if socket is NULL or already TCS_SOCKET_INVALID.

See Also:

• tcs_socket()

• tcs_socket_tcp()

• tcs_socket_udp()

• tcs_socket_packet()

• tcs_lib_init()

• tcs_lib_cleanup()

tcs_bind

Binds a socket to a local address.

TcsResult tcs_bind(TcsSocket socket, const struct TcsAddress *local_address)

This function associates a socket with a specific local address and port, allowing it to receive incoming connections or datagrams on that address. For TCP server sockets, you must call this before tcs_listen() . For UDP sockets, binding determines which address and port the socket will receive datagrams on.

#include "tinycsocket.h"
int main()
{
  TcsResult tcs_init_res = tcs_lib_init();
  if (tcs_init_res != TCS_SUCCESS)
    return -1;

  TcsSocket server_socket = TCS_SOCKET_INVALID;
  TcsResult socket_res = tcs_socket(&server_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
  if (socket_res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -2;
  }

  struct TcsAddress local_address = TCS_ADDRESS_NONE;
  local_address.family = TCS_FAMILY_IPV4;
  local_address.data.ipv4.address = TCS_ADDRESS_IPV4_ANY; // Bind to all interfaces
  local_address.data.ipv4.port = 8080;

  TcsResult bind_res = tcs_bind(server_socket, &local_address);
  if (bind_res != TCS_SUCCESS)
  {
    tcs_close(&server_socket);
    tcs_lib_cleanup();
    return -3; // Failed to bind to address
  }

  // For TCP: now call tcs_listen()
  // For UDP: socket is ready to receive datagrams

  tcs_close(&server_socket);
  tcs_lib_cleanup();
  return 0;
}

Parameters:

type	name	description
TcsSocket	socket	The socket to bind. Must be a valid socket created with tcs_socket().
const struct TcsAddress *	local_address	The local address structure to bind to. Use TCS_ADDRESS_IPV4_ANY for the address field to bind to all interfaces.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if socket is invalid or local_address is NULL.

• TCS_ERROR_NOT_SUPPORTED – if local_address has an address family not supported on this platform.

• TCS_ERROR_PERMISSION_DENIED – if binding to the specified address/port requires elevated privileges.

• TCS_ERROR_SYSTEM – if the address is already in use or another system error occurred.

See Also:

• tcs_listen()

• tcs_socket_tcp()

• tcs_socket_udp()

• tcs_address_socket_local()

tcs_connect

Connect a socket to a remote address structure.

TcsResult tcs_connect(TcsSocket socket, const struct TcsAddress *address)

This function establishes a connection to the specified remote address structure. For TCP sockets, this initiates a three-way handshake. For UDP sockets, this associates the socket with the remote address for subsequent send operations. The function blocks until the connection is established, fails, or the OS-default connect timeout expires (typically tens of seconds to a few minutes, platform-dependent). Use TcsPoll or tcs_opt_nonblocking_set() for non-blocking behavior.

#include "tinycsocket.h"
int main()
{
  TcsResult tcs_init_res = tcs_lib_init();
  if (tcs_init_res != TCS_SUCCESS)
    return -1;

  TcsSocket client_socket = TCS_SOCKET_INVALID;
  TcsResult socket_res = tcs_socket(&client_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
  if (socket_res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -2;
  }

  struct TcsAddress remote_address = TCS_ADDRESS_NONE;
  remote_address.family = TCS_FAMILY_IPV4;
  remote_address.data.ipv4.address = 0x7F000001; // 127.0.0.1 loopback
  remote_address.data.ipv4.port = 8080;

  TcsResult connect_res = tcs_connect(client_socket, &remote_address);
  if (connect_res != TCS_SUCCESS)
  {
    tcs_close(&client_socket);
    tcs_lib_cleanup();
    return -3; // Failed to connect
  }

  // Socket is now connected and ready for communication
  uint8_t buffer[] = "Hello, server!";
  size_t sent_size = 0;
  tcs_send(client_socket, buffer, sizeof(buffer)-1, TCS_MSG_SENDALL, &sent_size);

  tcs_close(&client_socket);
  tcs_lib_cleanup();
  return 0;
}

Parameters:

type	name	description
TcsSocket	socket	The socket to connect. Must be a valid socket created with tcs_socket().
const struct TcsAddress *	address	The remote address structure to connect to.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if socket is invalid or address is NULL.

• TCS_ERROR_NOT_SUPPORTED – if address has an address family not supported on this platform.

• TCS_ERROR_CONNECTION_REFUSED – if the remote server refused the connection.

• TCS_ERROR_TIMED_OUT – if the connection attempt timed out (can take 3+ minutes for unreachable hosts).

• TCS_ERROR_SYSTEM – if another system error occurred.

See Also:

• tcs_connect_str()

• tcs_socket_tcp()

• tcs_bind()

• tcs_listen()

tcs_connect_str

Connect a socket to a remote hostname and port.

TcsResult tcs_connect_str(TcsSocket socket, const char *remote_address, uint16_t port)

This function establishes a connection to the specified remote address and port. For TCP sockets, this initiates a three-way handshake. For UDP sockets, this associates the socket with the remote address for subsequent send operations. Timeout for this function is set by OS defaults. Use TcsPoll or tcs_opt_nonblocking_set() for non-blocking behavior.

#include "tinycsocket.h"
int main()
{
  TcsResult tcs_init_res = tcs_lib_init();
  if (tcs_init_res != TCS_SUCCESS)
    return -1;

  TcsSocket client_socket = TCS_SOCKET_INVALID;
  TcsResult socket_res = tcs_socket(&client_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
  if (socket_res != TCS_SUCCESS)
  {
    tcs_lib_cleanup();
    return -2;
  }

  TcsResult connect_res = tcs_connect_str(client_socket, "192.168.1.100", 8080);
  if (connect_res != TCS_SUCCESS)
  {
    tcs_close(&client_socket);
    tcs_lib_cleanup();
    return -3; // Failed to connect
  }

  // Socket is now connected and ready for communication
  uint8_t buffer[] = "Hello, server!";
  size_t sent_size = 0;
  tcs_send(client_socket, buffer, sizeof(buffer)-1, TCS_MSG_SENDALL, &sent_size);

  tcs_close(&client_socket);
  tcs_lib_cleanup();
  return 0;
}

Parameters:

type	name	description
TcsSocket	socket	The socket to connect. Must be a valid socket created with tcs_socket().
const char *	remote_address	The remote hostname or IP address to connect to.
uint16_t	port	The remote port number to connect to.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if socket is invalid or remote_address is NULL.

• TCS_ERROR_CONNECTION_REFUSED – if the remote server refused the connection.

• TCS_ERROR_ADDRESS_LOOKUP_FAILED – if the hostname could not be resolved.

• TCS_ERROR_TIMED_OUT – if the connection attempt timed out.

• TCS_ERROR_SYSTEM – if another system error occurred.

See Also:

• tcs_connect()

• tcs_socket_tcp_str()

• tcs_bind()

• tcs_listen()

tcs_listen

Let a socket start listening for incoming connections.

TcsResult tcs_listen(TcsSocket socket, int backlog)

Call tcs_bind() first to bind to a local address to listening at.

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
int	backlog	is the maximum number of queued incoming sockets. Use TCS_BACKLOG_MAX to set it to max.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_accept()

tcs_accept

Accept a socket from a listening socket.

TcsResult tcs_accept(TcsSocket listener, TcsSocket *out_socket, struct TcsAddress *out_address)

The accepted socket inherits the listening socket’s local address and port; only the remote (peer) endpoint differs. The listening socket itself is not affected by this call.

Example usage:

TcsSocket listen_socket = TCS_SOCKET_INVALID;
tcs_socket(&listen_socket, TCS_FAMILY_IPV4, TCS_SOCKET_STREAM, TCS_PROTOCOL_IP_TCP);
struct TcsAddress local_address = TCS_ADDRESS_NONE;
local_address.family = TCS_FAMILY_IPV4;
local_address.data.ipv4.port = 1212;
tcs_bind(listen_socket, &local_address);
tcs_listen(listen_socket, TCS_BACKLOG_MAX);
while (true)
{
  TcsSocket client_socket = TCS_SOCKET_INVALID;
  tcs_accept(listen_socket, &client_socket, NULL);
  // Do stuff with client_socket here
  tcs_close(&client_socket);
}

Parameters:

type	name	description
TcsSocket	listener	is your listening socket you used when you called tcs_listen().
TcsSocket *	out_socket	is your accepted socket. Must have the in value of TCS_SOCKET_INVALID.
struct TcsAddress *	out_address	is an optional pointer to a buffer where the remote address of the accepted socket can be stored.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_shutdown

Turn off communication with a 3-way handshaking for the socket.

TcsResult tcs_shutdown(TcsSocket socket, TcsShutdownDirection direction)

Use this function to cancel blocking calls (recv, accept etc) from another thread, or use sigaction. The socket will finish all queued sends first.

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
TcsShutdownDirection	direction	defines in which direction you want to turn off the communication.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_send

Sends data on a socket, blocking.

TcsResult tcs_send(TcsSocket socket, const uint8_t *buffer, size_t buffer_size, uint32_t flags, size_t *out_sent_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
const uint8_t *	buffer	is a pointer to your data you want to send.
size_t	buffer_size	is number of bytes of the data you want to send.
uint32_t	flags	is a bitmask of send flags. Use TCS_FLAG_NONE for no flags, or TCS_MSG_SENDALL to keep sending until all bytes are transmitted (or the call fails).
size_t *	out_sent_size	is how many bytes that was successfully sent.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_receive()

tcs_send_to

Sends data to an address, useful with UDP sockets.

TcsResult tcs_send_to(TcsSocket socket, const uint8_t *buffer, size_t buffer_size, uint32_t flags, const struct TcsAddress *destination_address, size_t *out_sent_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
const uint8_t *	buffer	is a pointer to your data you want to send.
size_t	buffer_size	is number of bytes of the data you want to send.
uint32_t	flags	is a bitmask of send flags. Use TCS_FLAG_NONE for no flags, or TCS_MSG_SENDALL to keep sending until all bytes are transmitted (or the call fails).
const struct TcsAddress *	destination_address	is the address to send to.
size_t *	out_sent_size	is how many bytes that was successfully sent.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if destination_address has an address family not supported on this platform.

See Also:

• tcs_receive_from()

tcs_sendv

Sends several data buffers on a socket as one message.

TcsResult tcs_sendv(TcsSocket socket, const struct TcsIoVec *iov, size_t iov_length, uint32_t flags, size_t *out_sent_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
const struct TcsIoVec *	iov	is a pointer to your array of scatter/gather buffers you want to send.
size_t	iov_length	is the number of buffers in your array.
uint32_t	flags	is a bitmask of send flags. Use TCS_FLAG_NONE for no flags, or TCS_MSG_SENDALL to keep sending until all bytes are transmitted (or the call fails).
size_t *	out_sent_size	is how many bytes in total that was successfully sent.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_send_netstring

Send data encoded as a netstring.

TcsResult tcs_send_netstring(TcsSocket socket, const uint8_t *buffer, size_t buffer_size)

Netstrings provide a simple framing format for sending discrete messages over a stream-oriented transport such as TCP ( TCS_SOCKET_STREAM ). The format is:

  <length>:<data>,
For example, the string "hello" is encoded as 5 :hello,

This is useful when you need packet-like semantics over TCP, where message boundaries are otherwise not preserved.

Parameters:

type	name	description
TcsSocket	socket	socket to send on.
const uint8_t *	buffer	data to send.
size_t	buffer_size	number of bytes to send.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_receive_netstring()

tcs_receive

Receive data from a socket to your buffer.

TcsResult tcs_receive(TcsSocket socket, uint8_t *buffer, size_t buffer_size, uint32_t flags, size_t *out_received_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
uint8_t *	buffer	is a pointer to your buffer where you want to store the incoming data to.
size_t	buffer_size	is the byte size of your buffer, for preventing overflows.
uint32_t	flags	is a bitmask of receive flags. Use TCS_FLAG_NONE for no flags, or any combination of TCS_MSG_PEEK, TCS_MSG_OOB, and TCS_MSG_WAITALL.
size_t *	out_received_size	is how many bytes that was successfully written to your buffer.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_send()

tcs_receive_from

Receive data from an address, useful with UDP sockets.

TcsResult tcs_receive_from(TcsSocket socket, uint8_t *buffer, size_t buffer_size, uint32_t flags, struct TcsAddress *out_source_address, size_t *out_received_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
uint8_t *	buffer	is a pointer to your buffer where you want to store the incoming data to.
size_t	buffer_size	is the byte size of your buffer, for preventing overflows.
uint32_t	flags	is a bitmask of receive flags. Use TCS_FLAG_NONE for no flags, or any combination of TCS_MSG_PEEK, TCS_MSG_OOB, and TCS_MSG_WAITALL.
struct TcsAddress *	out_source_address	is the address the data was received from.
size_t *	out_received_size	is how many bytes that was successfully written to your buffer.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_send_to()

tcs_receive_line

Read up to and including a delimiter.

TcsResult tcs_receive_line(TcsSocket socket, uint8_t *buffer, size_t buffer_size, uint8_t delimiter, size_t *out_received_size)

This function ensures that the socket buffer will keep its data after the delimiter. For performance it is recommended to read everything and split it yourself. The call will block until the delimiter is received or the supplied buffer is filled. The timeout time will not be per call but between each packet received. Longer call time than timeout is possible.

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
uint8_t *	buffer	is a pointer to your buffer where you want to store the incoming data to.
size_t	buffer_size	is the byte size of your buffer, for preventing overflows.
uint8_t	delimiter	is your byte value where you want to stop reading. (including delimiter)
size_t *	out_received_size	is how many bytes that was successfully written to your buffer.

Returns:

TCS_AGAIN if no delimiter was found and the supplied buffer was filled. TCS_SUCCESS if the delimiter was found. Otherwise the error code.

See Also:

• tcs_receive_netstring()

tcs_receive_netstring

Receive a netstring-encoded message.

TcsResult tcs_receive_netstring(TcsSocket socket, uint8_t *buffer, size_t buffer_size, size_t *out_received_size)

Reads and decodes a netstring (see tcs_send_netstring() for format details) from a stream socket. This allows receiving discrete messages over TCP where message boundaries are otherwise not preserved.

Parameters:

type	name	description
TcsSocket	socket	socket to receive from.
uint8_t *	buffer	buffer to store the decoded data (without the netstring framing).
size_t	buffer_size	size of the buffer in bytes.
size_t *	out_received_size	optional pointer to receive the number of payload bytes received.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_ILL_FORMED_MESSAGE – if the netstring is malformed or the length overflows.

• TCS_ERROR_MEMORY – if the buffer is too small for the payload.

See Also:

• tcs_send_netstring()

tcs_poll_create

Create a context used for waiting on several sockets.

TcsResult tcs_poll_create(struct TcsPoll **out_poll)

TcsPoll can be used to monitor several sockets for events (reading, writing or error). Use tcs_poll_wait() to get a list of sockets ready to interact with. Errors are always reported regardless of flags.

tcs_lib_init();
TcsSocket socket1 = TCS_SOCKET_INVALID;
TcsSocket socket2 = TCS_SOCKET_INVALID;
tcs_socket(&socket1, TCS_FAMILY_IPV4, TCS_SOCKET_DGRAM, TCS_PROTOCOL_IP_UDP);
tcs_socket(&socket2, TCS_FAMILY_IPV4, TCS_SOCKET_DGRAM, TCS_PROTOCOL_IP_UDP);

struct TcsAddress addr1 = TCS_ADDRESS_NONE;
addr1.family = TCS_FAMILY_IPV4;
addr1.data.ipv4.port = 1000;
tcs_bind(socket1, &addr1);

struct TcsAddress addr2 = TCS_ADDRESS_NONE;
addr2.family = TCS_FAMILY_IPV4;
addr2.data.ipv4.port = 1001;
tcs_bind(socket2, &addr2);

struct TcsPoll* poll = NULL;
tcs_poll_create(&poll);
tcs_poll_add(poll, socket1, NULL, TCS_POLL_READ); // Only wait for incoming data
tcs_poll_add(poll, socket2, NULL, TCS_POLL_READ);

size_t populated = 0;
struct TcsPollEvent ev[2] = {TCS_POLL_EVENT_EMPTY, TCS_POLL_EVENT_EMPTY};
tcs_poll_wait(poll, ev, 2, &populated, 1000); // Will wait 1000 ms for data on port 1000 or 1001
for (size_t i = 0; i < populated; ++i)
{
    if (ev[i].can_read)
    {
        uint8_t recv_buffer[8192] = {0};
        size_t received_size = 0;
        tcs_receive(ev[i].socket, recv_buffer, 8191, TCS_FLAG_NONE, &received_size);
    }
}
tcs_poll_destroy(&poll);
tcs_close(&socket1);
tcs_close(&socket2);
tcs_lib_cleanup();

Parameters:

type	name	description
struct TcsPoll **	out_poll	is your out poll context pointer. Initiate a TcsPoll pointer to NULL and use the address of this pointer.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_poll_destroy()

tcs_poll_destroy

Frees all resources bound to the poll context.

TcsResult tcs_poll_destroy(struct TcsPoll **poll)

Will set poll to NULL when successful.

Parameters:

type	name	description
struct TcsPoll **	poll	is your poll context pointer created with tcs_poll_create(). Will be set to NULL.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_poll_create()

tcs_poll_add

Add a socket to the poll context.

TcsResult tcs_poll_add(struct TcsPoll *poll, TcsSocket socket, void *user_data, uint32_t flags)

Parameters:

type	name	description
struct TcsPoll *	poll	is your poll context pointer created with tcs_poll_create().
TcsSocket	socket	will be added to the poll context. Note that you can still use it outside of the poll context.
void *	user_data	is a pointer of your choice that is associated with the socket. Use NULL if not used.
uint32_t	flags	is a bitmask of TcsPollFlags (e.g. TCS_POLL_READ | TCS_POLL_WRITE). Errors are always reported.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_poll_remove()

tcs_poll_modify

Modify the poll flags for a socket already in the poll context.

TcsResult tcs_poll_modify(struct TcsPoll *poll, TcsSocket socket, uint32_t flags)

Parameters:

type	name	description
struct TcsPoll *	poll	is your poll context pointer created with tcs_poll_create().
TcsSocket	socket	is the socket to modify.
uint32_t	flags	is the new bitmask of TcsPollFlags. Errors are always reported.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if the socket is not in the poll context.

See Also:

• tcs_poll_add()

tcs_poll_remove

Remove a socket from the poll context.

TcsResult tcs_poll_remove(struct TcsPoll *poll, TcsSocket socket)

Parameters:

type	name	description
struct TcsPoll *	poll	is a context pointer created with tcs_poll_create()
TcsSocket	socket	will be removed from the poll context.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_poll_add()

tcs_poll_wait

Wait for events on sockets in the poll context.

TcsResult tcs_poll_wait(struct TcsPoll *poll, struct TcsPollEvent *out_events, size_t events_length, size_t *out_events_length, int timeout_ms)

Parameters:

type	name	description
struct TcsPoll *	poll	is your poll context pointer created with tcs_poll_create().
struct TcsPollEvent *	out_events	is an array to fill with events. Assign each element to TCS_POLL_EVENT_EMPTY before the call.
size_t	events_length	number of in elements in your out_events array. Does not make sense to have more events than number of sockets in the poll context. If too short, all events may not be returned.
size_t *	out_events_length	will contain the number of events the out_events array has been populated with by the call.
int	timeout_ms	is the maximum wait time for any event. If any event happens before this time, the call will return immediately.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

• tcs_poll_remove()

tcs_opt_set

Set parameters on a socket. It is recommended to use tcs_opt_*_set() instead.

TcsResult tcs_opt_set(TcsSocket socket, int32_t level, int32_t option_name, const void *option_value, size_t option_size)

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
int32_t	level	is the definition level.
int32_t	option_name	is the option name.
const void *	option_value	is a pointer to the option value.
size_t	option_size	is the byte size of the data pointed by option_value.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_get

Get parameters on a socket. It is recommended to use tcs_opt_*_get() instead.

TcsResult tcs_opt_get(TcsSocket socket, int32_t level, int32_t option_name, void *out_option_value, size_t *option_size)

uint8_t c;
size_t a = sizeof(c);
tcs_opt_get(socket, TCS_SOL_IP, TCS_IP_MULTICAST_LOOP, &c, &a);

Parameters:

type	name	description
TcsSocket	socket	is your in-out socket context.
int32_t	level	is the definition level.
int32_t	option_name	is the option name.
void *	out_option_value	is a pointer to receive the option value.
size_t *	option_size	is a pointer the byte size of the data pointed by out_option_value.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_type_get

Query the socket type (e.g.

TcsResult tcs_opt_type_get(TcsSocket socket, TcsSocketType *out_type)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
TcsSocketType *	out_type	pointer to receive the socket type.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_broadcast_set

Enable the socket to be allowed to send to broadcast addresses.

TcsResult tcs_opt_broadcast_set(TcsSocket socket, bool do_allow_broadcast)

By default, sockets are not permitted to send to broadcast addresses (e.g. 255.255.255.255 or subnet broadcast addresses) as a safety measure to prevent accidental broadcast storms. Enable this option on UDP sockets that need to send broadcast traffic.

Only valid for protocols that support broadcast, for example UDP. Default is false.

Parameters:

type	name	description
TcsSocket	socket	socket to enable/disable permission to send broadcast on.
bool	do_allow_broadcast	set to true to allow, false to forbid.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_broadcast_get

Query whether broadcast is enabled on a socket.

TcsResult tcs_opt_broadcast_get(TcsSocket socket, bool *out_is_broadcast_allowed)

See tcs_opt_broadcast_set() for details on the broadcast option.

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_broadcast_allowed	pointer to receive the current broadcast setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_keep_alive_set

Enable or disable TCP keep-alive on a socket.

TcsResult tcs_opt_keep_alive_set(TcsSocket socket, bool do_keep_alive)

Keep-alive operates at the transport layer (TCP). When enabled, the OS periodically sends probe packets on an idle connection to detect if the remote peer is still reachable. Without keep-alive, a connection where neither side sends data can remain open indefinitely even if the remote host has crashed or the network path is broken.

Keep-alive probes also prevent NAT routers and stateful firewalls from dropping idle connection mappings due to inactivity timeouts.

This is particularly useful for long-lived connections that may be idle for extended periods, such as database connections or control channels.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_keep_alive	set to true to enable, false to disable.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_keep_alive_get

Query whether keep-alive is enabled on a socket.

TcsResult tcs_opt_keep_alive_get(TcsSocket socket, bool *out_is_keep_alive_enabled)

See tcs_opt_keep_alive_set() for details on what keep-alive does.

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_keep_alive_enabled	pointer to receive the current keep-alive setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_reuse_address_set

Allow or disallow address reuse on a socket.

TcsResult tcs_opt_reuse_address_set(TcsSocket socket, bool do_allow_reuse_address)

TCP: Allows binding to a port that is in the TIME_WAIT state. When a TCP connection is closed, the port remains reserved for up to 2 minutes (2x Maximum Segment Lifetime) to ensure delayed packets from the old connection are not misinterpreted by a new one. This option bypasses that restriction, which is useful for server sockets that need to restart quickly. On POSIX, it also allows overlapping wildcard and specific address binds on the same port (e.g. both 0.0.0.0:8080 and 192.168.1.1:8080). The most specific address wins.

UDP: Allows multiple sockets to bind to the same address and port. The behavior for unicast datagrams is OS-specific, but on most implementations only the most recently bound socket receives them. This is primarily useful for multicast, where several sockets need to receive the same group traffic.

For load-balancing multiple sockets on the same port, see tcs_opt_reuse_port_set() .

Note

On Windows, this library sets SO_EXCLUSIVEADDRUSE alongside SO_REUSEADDR for TCP sockets to prevent port hijacking, matching the security guarantees of POSIX. For UDP sockets, only SO_REUSEADDR is set, preserving multicast and same-port binding behavior. I.e. it mimics POSIX behaviour.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_allow_reuse_address	set to true to allow, false to disallow.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_reuse_address_get

Query whether address reuse is enabled on a socket.

TcsResult tcs_opt_reuse_address_get(TcsSocket socket, bool *out_is_reuse_address_allowed)

See tcs_opt_reuse_address_set() for details on the address reuse option.

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_reuse_address_allowed	pointer to receive the current setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_reuse_port_set

Allow or disallow multiple sockets to bind to the same address and port.

TcsResult tcs_opt_reuse_port_set(TcsSocket socket, bool do_allow_reuse_port)

When enabled, the kernel distributes incoming traffic across all sockets bound to the same address and port. All participating sockets must set this option, and on POSIX systems they must belong to the same effective UID.

This is useful for multi-threaded or multi-process servers that want to load-balance incoming connections or datagrams across workers without application-level dispatching.

Note

Only supported on POSIX (Linux 3.9+). Returns TCS_ERROR_NOT_SUPPORTED on Windows, which has no equivalent with the same semantics.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_allow_reuse_port	set to true to allow, false to disallow.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_reuse_port_get

Query whether port reuse is enabled on a socket.

TcsResult tcs_opt_reuse_port_get(TcsSocket socket, bool *out_is_reuse_port_allowed)

See tcs_opt_reuse_port_set() for details.

Note

Returns TCS_ERROR_NOT_SUPPORTED on Windows.

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_reuse_port_allowed	pointer to receive the current setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_send_buffer_size_set

Set the send buffer size of a socket.

TcsResult tcs_opt_send_buffer_size_set(TcsSocket socket, size_t send_buffer_size)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
size_t	send_buffer_size	desired send buffer size in bytes.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_send_buffer_size_get

Query the send buffer size of a socket.

TcsResult tcs_opt_send_buffer_size_get(TcsSocket socket, size_t *out_send_buffer_size)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
size_t *	out_send_buffer_size	pointer to receive the send buffer size in bytes.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_receive_buffer_size_set

Set the receive buffer size of a socket.

TcsResult tcs_opt_receive_buffer_size_set(TcsSocket socket, size_t receive_buffer_size)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
size_t	receive_buffer_size	desired receive buffer size in bytes.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_receive_buffer_size_get

Query the receive buffer size of a socket.

TcsResult tcs_opt_receive_buffer_size_get(TcsSocket socket, size_t *out_receive_buffer_size)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
size_t *	out_receive_buffer_size	pointer to receive the receive buffer size in bytes.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_receive_timeout_set

Set the receive timeout of a socket.

TcsResult tcs_opt_receive_timeout_set(TcsSocket socket, int timeout_ms)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
int	timeout_ms	timeout in milliseconds. Must be non-negative.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_receive_timeout_get

Query the receive timeout of a socket.

TcsResult tcs_opt_receive_timeout_get(TcsSocket socket, int *out_timeout_ms)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
int *	out_timeout_ms	pointer to receive the timeout in milliseconds.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_linger_set

Configure the linger behavior of a socket on close.

TcsResult tcs_opt_linger_set(TcsSocket socket, bool do_linger, int timeout_seconds)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_linger	set to true to enable lingering, false to disable.
int	timeout_seconds	linger timeout in seconds (only used when do_linger is true).

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_linger_get

Query the linger behavior of a socket.

TcsResult tcs_opt_linger_get(TcsSocket socket, bool *out_do_linger, int *out_timeout_seconds)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_do_linger	pointer to receive whether lingering is enabled.
int *	out_timeout_seconds	pointer to receive the linger timeout in seconds.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_ip_no_delay_set

Enable or disable Nagle’s algorithm (TCP_NODELAY).

TcsResult tcs_opt_ip_no_delay_set(TcsSocket socket, bool use_no_delay)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	use_no_delay	set to true to disable Nagle’s algorithm (lower latency), false to enable it.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_ip_no_delay_get

Query whether Nagle’s algorithm is disabled on a socket.

TcsResult tcs_opt_ip_no_delay_get(TcsSocket socket, bool *out_is_no_delay_used)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_no_delay_used	pointer to receive the current setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_out_of_band_inline_set

Enable or disable inline reception of out-of-band data.

TcsResult tcs_opt_out_of_band_inline_set(TcsSocket socket, bool enable_oob)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	enable_oob	set to true to receive OOB data inline, false to disable.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_out_of_band_inline_get

Query whether out-of-band data is received inline.

TcsResult tcs_opt_out_of_band_inline_get(TcsSocket socket, bool *out_is_oob_enabled)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_oob_enabled	pointer to receive the current setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_priority_set

Set the socket priority.

TcsResult tcs_opt_priority_set(TcsSocket socket, int priority)

Note

Not supported on Windows. Will return TCS_ERROR_NOT_SUPPORTED on that platform.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
int	priority	priority value.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_priority_get

Query the socket priority.

TcsResult tcs_opt_priority_get(TcsSocket socket, int *out_priority)

Note

Not supported on Windows. Will return TCS_ERROR_NOT_SUPPORTED on that platform.

Parameters:

type	name	description
TcsSocket	socket	socket to query.
int *	out_priority	pointer to receive the priority value.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_membership_add_to

Join a multicast group on a specific local interface.

TcsResult tcs_opt_membership_add_to(TcsSocket socket, const struct TcsAddress *local_address, const struct TcsAddress *multicast_address)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const struct TcsAddress *	local_address	local interface address to use.
const struct TcsAddress *	multicast_address	multicast group address to join.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if either address has an address family not supported on this platform.

tcs_opt_membership_drop_from

Leave a multicast group on a specific local interface.

TcsResult tcs_opt_membership_drop_from(TcsSocket socket, const struct TcsAddress *local_address, const struct TcsAddress *multicast_address)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const struct TcsAddress *	local_address	local interface address used when joining.
const struct TcsAddress *	multicast_address	multicast group address to leave.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if either address has an address family not supported on this platform.

tcs_opt_membership_add

Join a multicast group using the default local interface.

TcsResult tcs_opt_membership_add(TcsSocket socket, const struct TcsAddress *multicast_address)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const struct TcsAddress *	multicast_address	multicast group address to join.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if multicast_address has an address family not supported on this platform.

tcs_opt_membership_add_str

Join a multicast group by address string.

TcsResult tcs_opt_membership_add_str(TcsSocket socket, const char *multicast_address)

Resolves the multicast address string and joins the group using the default local interface.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const char *	multicast_address	multicast group address string (e.g. “239.1.2.3” or “ff02::1”).

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if multicast_address is NULL.

• TCS_ERROR_ADDRESS_LOOKUP_FAILED – if the address string could not be resolved.

See Also:

• tcs_opt_membership_add()

• tcs_opt_membership_drop_str()

tcs_opt_membership_drop

Leave a multicast group using the default local interface.

TcsResult tcs_opt_membership_drop(TcsSocket socket, const struct TcsAddress *multicast_address)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const struct TcsAddress *	multicast_address	multicast group address to leave.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if multicast_address has an address family not supported on this platform.

tcs_opt_membership_drop_str

Leave a multicast group by address string.

TcsResult tcs_opt_membership_drop_str(TcsSocket socket, const char *multicast_address)

Parses the multicast address string and leaves the group using the default local interface.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const char *	multicast_address	multicast group address string (e.g. “239.1.2.3” or “ff02::1”).

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_INVALID_ARGUMENT – if multicast_address is NULL.

• TCS_ERROR_ADDRESS_LOOKUP_FAILED – if the address string could not be resolved.

See Also:

• tcs_opt_membership_drop()

• tcs_opt_membership_add_str()

tcs_opt_multicast_interface_set

Set the outgoing interface for multicast packets.

TcsResult tcs_opt_multicast_interface_set(TcsSocket socket, const struct TcsAddress *local_address)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
const struct TcsAddress *	local_address	local interface address to use for outgoing multicast.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if local_address has an address family not supported on this platform.

tcs_opt_multicast_loop_set

Enable or disable multicast loopback.

TcsResult tcs_opt_multicast_loop_set(TcsSocket socket, bool do_loopback)

When enabled, multicast packets sent on this socket are looped back and delivered to local receivers on the same host.

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_loopback	set to true to enable loopback, false to disable.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_multicast_loop_get

Get the current multicast loopback setting.

TcsResult tcs_opt_multicast_loop_get(TcsSocket socket, bool *out_is_loopback)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
bool *	out_is_loopback	pointer to receive the current setting.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_nonblocking_set

Set a socket to non-blocking or blocking mode.

TcsResult tcs_opt_nonblocking_set(TcsSocket socket, bool do_nonblocking)

Parameters:

type	name	description
TcsSocket	socket	socket to configure.
bool	do_nonblocking	set to true for non-blocking, false for blocking.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_opt_nonblocking_get

Query the non-blocking state of a socket.

TcsResult tcs_opt_nonblocking_get(TcsSocket socket, bool *out_is_nonblocking)

Note

Not supported on Windows. Will return TCS_ERROR_NOT_SUPPORTED on that platform.

Parameters:

type	name	description
TcsSocket	socket
bool *	out_is_nonblocking

tcs_interface_list

List available network interfaces.

TcsResult tcs_interface_list(struct TcsInterface out_interfaces[], size_t interfaces_length, size_t *out_length)

Parameters:

type	name	description
struct TcsInterface	out_interfaces	array to receive interface information, or NULL to only count.
size_t	interfaces_length	number of elements in the out_interfaces array.
size_t *	out_length	pointer to receive the total number of interfaces available, which may exceed interfaces_length.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_resolve

Resolve a hostname to one or more addresses.

TcsResult tcs_address_resolve(const char *hostname, TcsFamily address_family, struct TcsAddress out_addresses[], size_t addresses_length, size_t *out_length)

Parameters:

type	name	description
const char *	hostname	hostname or IP string to resolve.
TcsFamily	address_family	address family filter, or TCS_FAMILY_ANY for all.
struct TcsAddress	out_addresses	array to receive resolved addresses, or NULL to only count.
size_t	addresses_length	number of elements in the out_addresses array.
size_t *	out_length	pointer to receive the number of addresses found.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

Return values:

• TCS_ERROR_NOT_SUPPORTED – if address_family is not supported on this platform (e.g. TCS_FAMILY_PACKET on non-Linux).

tcs_address_list

List addresses associated with network interfaces.

TcsResult tcs_address_list(TcsInterfaceId interface_id_filter, TcsFamily address_family_filter, struct TcsInterfaceAddress out_interface_addresses[], size_t interface_addresses_length, size_t *out_length)

Note

If address_family_filter is not supported on this platform (e.g. TCS_FAMILY_PACKET on non-Linux), no entries match and *out_length is 0.

Parameters:

type	name	description
TcsInterfaceId	interface_id_filter	interface ID to filter by, or 0 for all interfaces.
TcsFamily	address_family_filter	address family filter, or TCS_FAMILY_ANY for all.
struct TcsInterfaceAddress	out_interface_addresses	array to receive results, or NULL to only count.
size_t	interface_addresses_length	number of elements in the out_interface_addresses array.
size_t *	out_length	pointer to receive the total number of results available, which may exceed interface_addresses_length.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_socket_local

Get the local address of a bound or connected socket.

TcsResult tcs_address_socket_local(TcsSocket socket, struct TcsAddress *out_local_address)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
struct TcsAddress *	out_local_address	pointer to receive the local address.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_socket_remote

Get the remote address of a connected socket.

TcsResult tcs_address_socket_remote(TcsSocket socket, struct TcsAddress *out_remote_address)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
struct TcsAddress *	out_remote_address	pointer to receive the remote address.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_socket_family

Get the address family of a socket.

TcsResult tcs_address_socket_family(TcsSocket socket, TcsFamily *out_family)

Parameters:

type	name	description
TcsSocket	socket	socket to query.
TcsFamily *	out_family	pointer to receive the address family.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_parse

Parse a network address from a string.

TcsResult tcs_address_parse(const char str[], struct TcsAddress *out_address)

Supports IPv4, IPv6 (RFC 4291 all three forms), MAC, and bracket/port notation (RFC 3986). IPv6 zone IDs are limited to numeric values per the minimum requirement of RFC 4007. String-based zone IDs (e.g. “%%eth0”) are not supported.

Examples: * 192.168.0.1:1212 * ::1 * [::1]:443 * fe80::1%3 * ::ffff:192.168.1.1 * 91:E0:F0:00:FE:00 *

Note that this function will not perform DNS resolution. Use tcs_address_resolve() for that.

Parameters:

type	name	description
const char	str	The string to parse.
struct TcsAddress *	out_address	The parsed address.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_address_to_str

Convert an address to a string.

TcsResult tcs_address_to_str(const struct TcsAddress *address, char out_str[], size_t str_length, size_t *out_length)

This will make a verbose string representation of the address. Pass out_str=NULL and str_length=0 with out_length set to query the required size.

Parameters:

type	name	description
const struct TcsAddress *	address	the address to convert.
char	out_str	buffer to receive the null-terminated string representation.
size_t	str_length	capacity of out_str in bytes. A buffer of 70 bytes is always sufficient for any supported address family.
size_t *	out_length	receives the length of the written string excluding the null terminator. May be NULL.

Returns:

TCS_SUCCESS if successful, TCS_ERROR_MEMORY if out_str is too small, otherwise the error code.

tcs_address_is_equal

Check if two addresses are equal. Returns false for NULL, mismatched, unknown, or unsupported address families.

bool tcs_address_is_equal(const struct TcsAddress *l, const struct TcsAddress *r)

Parameters:

type	name	description
const struct TcsAddress *	l
const struct TcsAddress *	r

tcs_address_is_any

Check if the address is a wildcard (any) address. Returns false for NULL, unknown, or unsupported address families.

bool tcs_address_is_any(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr

tcs_address_is_link_local

Check if the address is a link-local address. Returns false for NULL, unknown, or unsupported address families.

bool tcs_address_is_link_local(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr

tcs_address_is_loopback

Check if the address is a loopback address. Returns false for NULL, unknown, or unsupported address families.

bool tcs_address_is_loopback(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr

tcs_address_is_multicast

Check if the address is a multicast address. Returns false for NULL, unknown, or unsupported address families.

bool tcs_address_is_multicast(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr

tcs_address_is_broadcast

Check if the address is a broadcast address. Returns false for NULL, unknown, or unsupported address families.

bool tcs_address_is_broadcast(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr

tcs_address_is_supported

Check if the address family is known and supported by this platform. Returns false for NULL or unknown families.

bool tcs_address_is_supported(const struct TcsAddress *addr)

Parameters:

type	name	description
const struct TcsAddress *	addr