TinyCSocket

Tinycsocket is a thin cross-platform socket library written in C99. It focuses on a minimal footprint, cross-platform and to also provide simple lowlevel utils (for example tcs_simple_connect(…) which resolves and connects to a hostname). The API is similar to BSD sockets 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 plattforms. The disadvantage is that the functions can not be easily integrated in expressions.

Currently support plattforms:

  • Windows 2000 SP1 and newer (XP, Server 2003, Vista, Server 2008, 7, 8, 8.1 and 10)

  • POSIX.1-2001 systems

Installation Instructions

Depending on if you use cmake or not there are two installation instructions.

I want to use CMake and submodules

If you are using a cmake project, it is recommended to include tinycsocket to your build system. Add this repo as a submodule and add tinycsocket/src to your CMakeLists.txt.

git submodule add https://gitlab.com/dosshell/tinycsocket.git
add_subdirectory(tinycsocket/src)
target_link_libraries(your_target PRIVATE tinycsocket)

You can read more about how to use submodules here: https://git-scm.com/book/en/v2/Git-Tools-Submodules

Reference documentation

Currently available functions:

symbol

description

tcs_lib_init

Call this to initialize the library, eg. call this before any other function.

tcs_lib_free

Call this when you are done with tinycsocket lib to free resources.

tcs_create

Creates a new socket.

tcs_bind

Binds the socket to a local address.

tcs_connect

Connects to a remote address.

tcs_listen

Start listen for incoming sockets.

tcs_accept

Accepts a socket from a listen socket.

tcs_send

Sends data on a socket, blocking.

tcs_sendto

Sends data to an address, useful with UDP sockets.

tcs_recv

Receive data from a socket to your buffer.

tcs_recvfrom

Sends data to an address, useful with UDP sockets.

tcs_setsockopt

Set parameters on a socket.

tcs_shutdown

Turn off communication for the socket.

tcs_close

closes the socket, call this when you are done with the socket.

tcs_getaddrinfo

Get addresses you can connect to given a computer name and a port.

tcs_freeaddrinfo

Frees your linked address list you acquired from tcs_getaddrinfo.

tcs_simple_connect

Connects a socket to a node and a port.

tcs_simple_bind

Creates a socket and binds it to a node and a port.

tcs_simple_create_and_listen

Creates a socket and starts to listen to an address with TCP.

tcs_simple_recv_all

Receives and fill the buffer width a fixed length of data (normal recv can fill the buffer less than the buffer length)

tcs_simple_send_all

Sends the full buffer (normal send is allowed to send only a part of the buffer)

tcs_simple_recv_netstring

tcs_simple_send_netstring

All References:

struct tcs_addrinfo
#include <tinycsocket.h>

Public Members

int ai_flags
int ai_family
int ai_socktype
int ai_protocol
int ai_addrlen
struct tcs_sockaddr *ai_addr
char *ai_canonname
struct tcs_addrinfo *ai_next
struct tcs_sockaddr
#include <tinycsocket.h>

Public Members

sa_family_t ss_family
char __ss_pad1[_SS_PAD1SIZE__]
int64_t __ss_align
char __ss_pad2[_SS_PAD2SIZE__]
file tinycsocket.h
#include <stddef.h>#include <stdint.h>

Defines

TINYCSOCKET_USE_POSIX_IMPL
_SS_MAXSIZE__
_SS_ALIGNSIZE__
_SS_PAD1SIZE__
_SS_PAD2SIZE__

Typedefs

typedef int tcs_socket
typedef unsigned short int sa_family_t

Functions

int tcs_lib_init(void)

Call this to initialize the library, eg. call this before any other function.

Return

TCS_SUCCESS if successful, otherwise the error code.

int tcs_lib_free(void)

Call this when you are done with tinycsocket lib to free resources.

Return

TCS_SUCCESS if successful, otherwise the error code.

int tcs_create(tcs_socket *socket_ctx, int domain, int type, int protocol)

Creates a new socket.

tcs_socket my_socket = TCS_NULLSOCKET;
tcs_create(&my_socket, TCS_AF_INET, TCS_SOCK_STREAM, TCS_IPPROTO_TCP);

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_close()

See

tcs_lib_init()

Parameters

int tcs_bind(tcs_socket socket_ctx, const struct tcs_sockaddr *address, int address_length)

Binds the socket to a local address.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_getaddrinfo()

Parameters
  • socket_ctx: is you in-out socket context.

  • address: is you address to bind to.

  • address_length: is you byte size of your address argument.

int tcs_connect(tcs_socket socket_ctx, const struct tcs_sockaddr *address, int address_length)

Connects to a remote address.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_shutdown()

Parameters
  • socket_ctx: is your in-out socket context.

  • address: is the remote address to connect to.

  • address_length: is the byte size of the address argument.

int tcs_listen(tcs_socket socket_ctx, int backlog)

Start listen for incoming sockets.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_accept()

Parameters
  • socket_ctx: is your in-out socket context.

  • backlog: is the maximum number of queued incoming sockets. Use TCS_BACKLOG_SOMAXCONN to set it to max.

int tcs_accept(tcs_socket socket_ctx, tcs_socket *child_socket_ctx, struct tcs_sockaddr *address, int *address_length)

Accepts a socket from a listen socket.

Return

TCS_SUCCESS if successful, otherwise the error code.

Parameters
  • socket_ctx: is your listening socket you used when you called tcs_listen().

  • child_socket_ctx: is you accepted socket. Must have the in value of TCS_NULLSOCKET.

  • address: is an optional pointer to a buffer where the underlaying address can be stored.

  • address_length: is an optional in-out pointer to a #int containing the byte size of the address argument.

int tcs_send(tcs_socket socket_ctx, const uint8_t *buffer, size_t buffer_length, uint32_t flags, size_t *bytes_sent)

Sends data on a socket, blocking.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_recv()

Parameters
  • socket_ctx: is your in-out socket context.

  • buffer: is a pointer to your data you want to send.

  • buffer_length: is number of bytes of the data you want to send.

  • flags: is currently not in use.

  • bytes_sent: is how many bytes that was successfully sent.

int tcs_sendto(tcs_socket socket_ctx, const uint8_t *buffer, size_t buffer_length, uint32_t flags, const struct tcs_sockaddr *destination_address, size_t destination_address_length, size_t *bytes_sent)

Sends data to an address, useful with UDP sockets.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_recvfrom()

See

tcs_getaddrinfo()

Parameters
  • socket_ctx: is your in-out socket context.

  • buffer: is a pointer to your data you want to send.

  • buffer_length: is number of bytes of the data you want to send.

  • flags: is currently not in use.

  • destination_address: is the address to send to.

  • destination_address_length: is the byte size of the destination_adress argument.

  • bytes_sent: is how many bytes that was successfully sent.

int tcs_recv(tcs_socket socket_ctx, uint8_t *buffer, size_t buffer_length, uint32_t flags, size_t *bytes_recieved)

Receive data from a socket to your buffer.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_send()

Parameters
  • socket_ctx: is your in-out socket context.

  • buffer: is a pointer to your buffer where you want to store the incoming data to.

  • buffer_length: is the byte size of your buffer, for preventing overflows.

  • flags: is currently not in use.

  • bytes_recieved: is how many bytes that was successfully written to your buffer.

int tcs_recvfrom(tcs_socket socket_ctx, uint8_t *buffer, size_t buffer_length, uint32_t flags, struct tcs_sockaddr *source_address, size_t *source_address_length, size_t *bytes_recieved)

Sends data to an address, useful with UDP sockets.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_sendto()

See

tcs_getaddrinfo()

Parameters
  • socket_ctx: is your in-out socket context.

  • buffer: is a pointer to your buffer where you want to store the incoming data to.

  • buffer_length: is the byte size of your buffer, for preventing overflows.

  • flags: is currently not in use.

  • source_address: is the address to receive from.

  • source_address_length: is the byte size of the source_address argument.

  • bytes_recieved: is how many bytes that was successfully written to your buffer.

int tcs_setsockopt(tcs_socket socket_ctx, int32_t level, int32_t option_name, const void *option_value, int option_length)

Set parameters on a socket.

Return

TCS_SUCCESS if successful, otherwise the error code.

Parameters
  • socket_ctx: is your in-out socket context.

  • level: is the definition level.

  • option_name: is the option name.

  • option_value: is a pointer to the option value.

  • option_length: is the byte size of the data pointed by option_value.

int tcs_shutdown(tcs_socket socket_ctx, int how)

Turn off communication for the socket.

Return

TCS_SUCCESS if successful, otherwise the error code.

Parameters
  • socket_ctx: is your in-out socket context.

  • how: defines in which direction you want to turn off the communication.

int tcs_close(tcs_socket *socket_ctx)

closes the socket, call this when you are done with the socket.

Return

TCS_SUCCESS if successful, otherwise the error code.

Parameters
  • socket_ctx: is your in-out socket context.

int tcs_getaddrinfo(const char *node, const char *service, const struct tcs_addrinfo *hints, struct tcs_addrinfo **res)

Get addresses you can connect to given a computer name and a port.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_freeaddrinfo()

Parameters
  • node: is your computer identifier: hostname, IPv4 or IPv6 address.

  • service: is your port number. Also some support for common aliases like “http” exist.

  • hints: is a struct with hints, for example if you only are interested in IPv6.

  • res: is your output pointer to a linked list of addresses. You need to free this list when you are done with it.

int tcs_freeaddrinfo(struct tcs_addrinfo **addressinfo)

Frees your linked address list you acquired from tcs_getaddrinfo.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_getaddrinfo()

Parameters
  • addressinfo: is your linked list you acquired from tcs_getaddrinfo

int tcs_simple_connect(tcs_socket socket_ctx, const char *hostname, const char *port)

Connects a socket to a node and a port.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_simple_listen()

See

tcs_simple_bind()

Parameters
  • socket_ctx: is your out socket context. Must have been previously created.

  • hostname: is the name of the host to connect to, for example localhost.

  • port: is a string representation of the port you want to connect to. Normally an integer, like “5000” but also some support for common aliases like “http” exist.

  • domain: only supports TCS_AF_INET for now

  • protocol: specifies the protocol, for example TCS_IPPROTO_TCP or TCS_IPPROTO_UDP.

int tcs_simple_bind(tcs_socket *socket_ctx, const char *hostname, const char *port, int domain, int protocol)

Creates a socket and binds it to a node and a port.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_simple_connect()

Parameters
  • socket_ctx: is your out socket context. Must be of TCS_NULLSOCKET value.

  • hostname: is the name of the host to bind to, for example “192.168.0.1” or “localhost”.

  • port: is a string representation of the port you want to bind to. Normally an integer, like “5000” but also some support for common aliases like “http” exist.

  • domain: only supports TCS_AF_INET for now

  • protocol: specifies the protocol, for example TCS_IPPROTO_TCP or TCS_IPPROTO_UDP.

int tcs_simple_create_and_listen(tcs_socket *socket_ctx, const char *hostname, const char *port, int domain)

Creates a socket and starts to listen to an address with TCP.

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_simple_connect()

Parameters
  • socket_ctx: is your out socket context. Must be of TCS_NULLSOCKET value.

  • hostname: is the name of the address to listen on, for example “192.168.0.1” or “localhost”. Use NULL for all interfaces.

  • port: is a string representation of the port you want to listen to. Normally an integer, like “5000” but also some support for common aliases like “http” exist.

  • domain: only supports TCS_AF_INET for now

int tcs_simple_recv_all(tcs_socket socket_ctx, uint8_t *buffer, size_t length)

Receives and fill the buffer width a fixed length of data (normal recv can fill the buffer less than the buffer length)

Return

TCS_SUCCESS if successful, otherwise the error code.

See

tcs_send_all()

Parameters
  • socket_ctx: is your in-out socket context.

  • buffer: is a pointer to your buffer where you want to store the incoming data to.

  • buffer_length: is the byte size of your buffer, it will fill the complete buffer.

int tcs_simple_send_all(tcs_socket socket_ctx, uint8_t *buffer, size_t length, uint32_t flags)

Sends the full buffer (normal send is allowed to send only a part of the buffer)

int tcs_simple_recv_netstring(tcs_socket socket_ctx, uint8_t *buffer, size_t buffer_length, size_t *bytes_recieved)
int tcs_simple_send_netstring(tcs_socket socket_ctx, uint8_t *buffer, size_t buffer_length)

Variables

const tcs_socket TCS_NULLSOCKET

An empty socket, you should always define your new sockets to this value

const int TCS_AF_INET

IPv4 interface

const int TCS_SOCK_STREAM

Use for streaming types like TCP

const int TCS_SOCK_DGRAM

Use for datagrams types like UDP

const int TCS_IPPROTO_TCP

Use TCP protocol (use with TCS_SOCK_STREAM for normal cases)

const int TCS_IPPROTO_UDP

Use UDP protocol (use with TCS_SOCK_DGRAM for normal cases)

const int TCS_AI_PASSIVE

Use this flag for pure listening sockets

const int TCS_MSG_WAITALL
const int TCS_MSG_PEEK
const int TCS_MSG_OOB
const int TCS_BACKLOG_SOMAXCONN

Max number of queued sockets when listening

const int TCS_SD_RECIEVE

To shutdown incoming packets for socket

const int TCS_SD_SEND

To shutdown outgoing packets for socket

const int TCS_SD_BOTH

To shutdown both incoming and outgoing packets for socket

const int TCS_SOL_SOCKET

Socket option level

const int TCS_SO_REUSEADDR

This is a tricky one!

const int TCS_SO_RCVBUF

Byte size of receiving buffer

const int TCS_SO_SNDBUF

Byte size of receiving buffer

const int TCS_SUCCESS = 0
const int TCS_ERROR_UNKNOWN = -1
const int TCS_ERROR_MEMORY = -2
const int TCS_ERROR_INVALID_ARGUMENT = -3
const int TCS_ERROR_KERNEL = -4
const int TCS_ERROR_ADDRESS_LOOKUP_FAILED = -5
const int TCS_ERROR_CONNECTION_REFUSED = -6
const int TCS_ERROR_NOT_INITED = -7
const int TCS_ERROR_TIMED_OUT = -8
const int TCS_ERROR_NOT_IMPLEMENTED = -9
const int TCS_ERROR_NOT_CONNECTED = -10
const int TCS_ERROR_ILL_FORMED_MESSAGE = -11
const int TCS_ERROR_SOCKET_CLOSED = -13
dir /home/docs/checkouts/readthedocs.org/user_builds/tinycsocket/checkouts/latest/src

Indices and tables