Welcome to TinyCSocket’s documentation!

Indices and tables

Reference documentation

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”.

  • 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
file tinycsocket_posix.c
#include “tinycsocket.h”#include <errno.h>#include <netdb.h>#include <sys/socket.h>#include <unistd.h>

Functions

int errno2retcode(int error_code)
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

Variables

const tcs_socket TCS_NULLSOCKET = -1

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

const int TCS_AF_INET = AF_INET

IPv4 interface

const int TCS_SOCK_STREAM = SOCK_STREAM

Use for streaming types like TCP

const int TCS_SOCK_DGRAM = SOCK_DGRAM

Use for datagrams types like UDP

const int TCS_IPPROTO_TCP = IPPROTO_TCP

Use TCP protocol (use with TCS_SOCK_STREAM for normal cases)

const int TCS_IPPROTO_UDP = IPPROTO_UDP

Use UDP protocol (use with TCS_SOCK_DGRAM for normal cases)

const int TCS_AI_PASSIVE = AI_PASSIVE

Use this flag for pure listening sockets

const int TCS_MSG_WAITALL = MSG_WAITALL
const int TCS_MSG_PEEK = MSG_PEEK
const int TCS_MSG_OOB = MSG_OOB
const int TCS_BACKLOG_SOMAXCONN = SOMAXCONN

Max number of queued sockets when listening

const int TCS_SD_RECIEVE = SHUT_RD

To shutdown incoming packets for socket

const int TCS_SD_SEND = SHUT_WR

To shutdown outgoing packets for socket

const int TCS_SD_BOTH = SHUT_RDWR

To shutdown both incoming and outgoing packets for socket

const int TCS_SOL_SOCKET = SOL_SOCKET

Socket option level

const int TCS_SO_REUSEADDR = SO_REUSEADDR

This is a tricky one!

const int TCS_SO_RCVBUF = SO_RCVBUF

Byte size of receiving buffer

const int TCS_SO_SNDBUF = SO_SNDBUF

Byte size of receiving buffer

file tinycsocket_simple.c
#include <stdbool.h>#include <stdio.h>#include “tinycsocket.h”

Functions

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”.

  • 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)
file tinycsocket_win32.c
#include “tinycsocket.h”
dir /home/docs/checkouts/readthedocs.org/user_builds/tinycsocket/checkouts/v0.2/src