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_AF_IP4, TCS_SOCK_STREAM, TCS_PROTOCOL_IP_TCP);
    tcs_connect_str(client_socket, "example.com", 80);

    uint8_t send_buffer[] = "GET / HTTP/1.1\nHost: example.com\n\n";
    tcs_send(client_socket, send_buffer, sizeof(send_buffer), TCS_MSG_SENDALL, NULL);

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

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

    tcs_lib_free();
}

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