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.

Integrate with CMake

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

Manually Linking

You can also build this project to get a lib directory and an include directoy. 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 and ws2_32.lib. The following commands will create these include- and lib folders in a folder named install:

git clone https://gitlab.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.

Reference Documentation

This is the part you probably are looking for.

List of All Functions

List of all available functions in TinyCSocket:

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 Receive data from an address, useful with UDP sockets.
tcs_setsockopt Set parameters on a socket.
tcs_shutdown Turn off communication for the socket. Will finish all sends first.
tcs_close Closes the socket, call this when you are done with the socket.
tcs_get_addresses Get addresses you can connect to given a computer name and a port.
tcs_get_interfaces Get local addresses of your computer.
tcs_simple_create_and_connect Connects a socket to a node and a port.
tcs_simple_create_and_bind Creates a DATAGRAM 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 Receive data until the buffer is filled (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  

List of All Constants

List of all available constants in TinyCSocket:

symbol description
const TcsSocket TCS_NULLSOCKET An empty socket, you should always define your new sockets to this value
const uint16_t TCS_AF_UNSPEC Layer 3 agnostic
const uint16_t TCS_AF_INET IPv4 interface
const uint16_t TCS_AF_INET6 IPv6 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 uint32_t TCS_AI_PASSIVE Use this flag for pure listening sockets
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_RECEIVE 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

Reference Details

This section contains details of all functions.

tcs_lib_init

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

TcsReturnCode tcs_lib_init(void)

Parameters:

type name description
void None None

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_lib_free

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

TcsReturnCode tcs_lib_free(void)

Parameters:

type name description
void None None

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_create

Creates a new socket.

TcsReturnCode tcs_create(TcsSocket *socket_ctx, int family, int type, int protocol)

Parameters:

type name description
TcsSocket * socket_ctx is your in-out pointer to the socket context, you must initialize the socket to TCS_NULLSOCKET before use.
int family only supports TCS_AF_INET for now.
int type specifies the type of the socket, for example TCS_SOCK_STREAM or TCS_SOCK_DGRAM.
int protocol specifies the protocol, for example TCS_IPPROTO_TCP or TCS_IPPROTO_UDP.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_close()
  • tcs_lib_init()

tcs_bind

Binds the socket to a local address.

TcsReturnCode tcs_bind(TcsSocket socket_ctx, const struct TcsAddress *address)

Parameters:

type name description
TcsSocket socket_ctx is your in-out socket context.
const struct TcsAddress * address is you address to bind to.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_getaddrinfo()

tcs_connect

Connects to a remote address.

TcsReturnCode tcs_connect(TcsSocket socket_ctx, const struct TcsAddress *address)

Parameters:

type name description
TcsSocket socket_ctx is your in-out socket context.
const struct TcsAddress * address is the remote address to connect to.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_shutdown()

tcs_listen

Start listen for incoming sockets.

TcsReturnCode tcs_listen(TcsSocket socket_ctx, int backlog)

Parameters:

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

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_accept()

tcs_accept

Accepts a socket from a listen socket.

TcsReturnCode tcs_accept(TcsSocket socket_ctx, TcsSocket *child_socket_ctx, struct TcsAddress *address)

Parameters:

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

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_send

Sends data on a socket, blocking.

TcsReturnCode tcs_send(TcsSocket socket_ctx, const uint8_t *buffer, size_t buffer_size, uint32_t flags, size_t *bytes_sent)

Parameters:

type name description
TcsSocket socket_ctx 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 currently not in use.
size_t * bytes_sent is how many bytes that was successfully sent.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_recv()

tcs_sendto

Sends data to an address, useful with UDP sockets.

TcsReturnCode tcs_sendto(TcsSocket socket_ctx, const uint8_t *buffer, size_t buffer_size, uint32_t flags, const struct TcsAddress *destination_address, size_t *bytes_sent)

Parameters:

type name description
TcsSocket socket_ctx 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 currently not in use.
const struct TcsAddress * destination_address is the address to send to.
size_t * bytes_sent is how many bytes that was successfully sent.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_recvfrom()
  • tcs_getaddrinfo()

tcs_recv

Receive data from a socket to your buffer.

TcsReturnCode tcs_recv(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size, uint32_t flags, size_t *bytes_received)

Parameters:

type name description
TcsSocket socket_ctx 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 currently not in use.
size_t * bytes_received 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_recvfrom

Receive data from an address, useful with UDP sockets.

TcsReturnCode tcs_recvfrom(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size, uint32_t flags, struct TcsAddress *source_address, size_t *bytes_received)

Parameters:

type name description
TcsSocket socket_ctx 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 currently not in use.
struct TcsAddress * source_address is the address to receive from.
size_t * bytes_received is how many bytes that was successfully written to your buffer.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_sendto()
  • tcs_getaddrinfo()

tcs_setsockopt

Set parameters on a socket.

TcsReturnCode tcs_setsockopt(TcsSocket socket_ctx, int32_t level, int32_t option_name, const void *option_value, size_t option_size)

Parameters:

type name description
TcsSocket socket_ctx 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_shutdown

Turn off communication for the socket. Will finish all sends first.

TcsReturnCode tcs_shutdown(TcsSocket socket_ctx, int how)

Parameters:

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

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_close

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

TcsReturnCode tcs_close(TcsSocket *socket_ctx)

Parameters:

type name description
TcsSocket * socket_ctx is your in-out socket context.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_get_addresses

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

TcsReturnCode tcs_get_addresses(const char *node, const char *service, uint16_t address_family, struct TcsAddress found_addresses[], size_t found_addresses_length, size_t *no_of_found_addresses)

Parameters:

type name description
const char * node is your computer identifier: hostname, IPv4 or IPv6 address.
const char * service is your port number. Also some support for common aliases like “http” exist.
uint16_t address_family filters which address family you want, for example if you only are interested in IPv6. Use TCS_AF_UNSPEC to not filter.
struct TcsAddress found_addresses is a pointer to your array which will be populated with found addresses.
size_t found_addresses_length is number of elements your array can store.
size_t * no_of_found_addresses will output the number of addresses that was populated in .

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_get_interfaces

Get local addresses of your computer.

TcsReturnCode tcs_get_interfaces(struct TcsInterface found_interfaces[], size_t found_interfaces_length, size_t *no_of_found_interfaces)

Parameters:

type name description
struct TcsInterface found_interfaces is a pointer to your array which will be populated with found interfaces.
size_t found_interfaces_length is number of elements your array can store.
size_t * no_of_found_interfaces will output the number of addresses that was populated in .

Returns:

TCS_SUCCESS if successful, otherwise the error code.

tcs_simple_create_and_connect

Connects a socket to a node and a port.

TcsReturnCode tcs_simple_create_and_connect(TcsSocket *socket_ctx, const char *hostname, const char *port, uint16_t family)

Parameters:

type name description
TcsSocket * socket_ctx is your out socket context. Must have been previously created.
const char * hostname is the name of the host to connect to, for example localhost.
const char * 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.
uint16_t family only supports TCS_AF_INET for now

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_simple_listen()
  • tcs_simple_bind()

tcs_simple_create_and_bind

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

TcsReturnCode tcs_simple_create_and_bind(TcsSocket *socket_ctx, const char *hostname, const char *port, uint16_t family)

Parameters:

type name description
TcsSocket * socket_ctx is your out socket context. Must be of TCS_NULLSOCKET value.
const char * hostname is the name of the host to bind to, for example “192.168.0.1” or “localhost”.
const char * 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.
uint16_t family only supports TCS_AF_INET for now

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_simple_connect()

tcs_simple_create_and_listen

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

TcsReturnCode tcs_simple_create_and_listen(TcsSocket *socket_ctx, const char *hostname, const char *port, uint16_t family)

Parameters:

type name description
TcsSocket * socket_ctx is your out socket context. Must be of TCS_NULLSOCKET value.
const char * hostname is the name of the address to listen on, for example “192.168.0.1” or “localhost”. Use NULL for all interfaces.
const char * 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.
uint16_t family only supports TCS_AF_INET for now.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_simple_connect()

tcs_simple_recv_all

Receive data until the buffer is filled (normal recv can fill the buffer less than the buffer length).

TcsReturnCode tcs_simple_recv_all(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size)

Parameters:

type name description
TcsSocket socket_ctx 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, it will fill the complete buffer.

Returns:

TCS_SUCCESS if successful, otherwise the error code.

See Also:

  • tcs_send_all()

tcs_simple_send_all

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

TcsReturnCode tcs_simple_send_all(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size, uint32_t flags)

Parameters:

type name description
TcsSocket socket_ctx is your in-out socket context.
uint8_t * buffer is a pointer to your data you want to send.
size_t buffer_size is the total size of your buffer in bytes.
uint32_t flags your flags.

Returns:

<documentation is not available>

tcs_simple_recv_netstring

TcsReturnCode tcs_simple_recv_netstring(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size, size_t *bytes_received)

Parameters:

type name description
TcsSocket socket_ctx None
uint8_t * buffer None
size_t buffer_size None
size_t * bytes_received None

Returns:

<documentation is not available>

tcs_simple_send_netstring

TcsReturnCode tcs_simple_send_netstring(TcsSocket socket_ctx, uint8_t *buffer, size_t buffer_size)

Parameters:

type name description
TcsSocket socket_ctx None
uint8_t * buffer None
size_t buffer_size None

Returns:

<documentation is not available>