IOTH(3)

IOTH(3) 💖

okay bestie, so this is the libioth manual page — it lives in the Library Functions Manual section 3, and it's literally the whole Internet of Threads API. it's a lot. grab a snack. 🍓

---

✨ NAME ✨

ioth_newstack, ioth_newstackl, ioth_newstackv, ioth_delstack, ioth_msocket, ioth_set_defstack, ioth_get_defstack, ioth_socket, ioth_close, ioth_bind, ioth_connect, ioth_listen, ioth_accept, ioth_getsockname, ioth_getpeername, ioth_setsockopt, ioth_getsockopt, ioth_shutdown, ioth_ioctl, ioth_fcntl, ioth_read, ioth_readv, ioth_recv, ioth_recvfrom, ioth_recvmsg, ioth_write, ioth_writev, ioth_send, ioth_sendto ioth_sendmsg, ioth_if_nametoindex, ioth_linksetupdown, ioth_ipaddr_add, ioth_ipaddr_del, ioth_iproute_add, ioth_iproute_del, ioth_iplink_add, ioth_iplink_del, ioth_linksetaddr, ioth_linkgetaddr — Internet of Threads (IoTh) library

like. that's the whole roster. it's giving main character energy on every single one of these. 👑

---

🌸 SYNOPSIS 🌸

#include <ioth.h>

struct ioth *ioth_newstack(const char *stack, const char *vnl);

struct ioth *ioth_newstackl(const char *stack, const char *vnl, ... );

struct ioth *ioth_newstackv(const char *stack, const char *vnlv[]);

int ioth_delstack(struct ioth *iothstack);

int ioth_msocket(struct ioth *iothstack, int domain, int type, int
protocol);

void ioth_set_defstack(struct ioth *iothstack);

struct ioth *ioth_get_defstack(void);

int ioth_socket(int domain, int type, int protocol);

• Berkeley Sockets API

int ioth_close(int fd);

int ioth_bind(int sockfd, const struct sockaddr *addr, socklen_t
addrlen);

int ioth_connect(int sockfd, const struct sockaddr *addr, socklen_t
addrlen);

int ioth_listen(int sockfd, int backlog);

int ioth_accept(int sockfd, struct sockaddr *restrict addr, socklen_t
*restrict addrlen);

int ioth_getsockname(int sockfd, struct sockaddr *restrict addr,
socklen_t *restrict addrlen);

int ioth_getpeername(int sockfd, struct sockaddr *restrict addr,
socklen_t *restrict addrlen);

int ioth_getsockopt(int sockfd, int level, int optname, void *restrict
optval, socklen_t *restrict optlen);

int ioth_setsockopt(int sockfd, int level, int optname, const void
*optval, socklen_t optlen);

int ioth_shutdown(int sockfd, int how);

int ioth_ioctl(int fd, unsigned long request, ...);

int ioth_fcntl(int fd, int cmd, ... /* arg */ );

ssize_t ioth_read(int fd, void *buf, size_t count);

ssize_t ioth_readv(int fd, const struct iovec *iov, int iovcnt);

ssize_t ioth_recv(int sockfd, void *buf, size_t len, int flags);

ssize_t ioth_recvfrom(int sockfd, void *restrict buf, size_t len, int
flags, struct sockaddr *restrict src_addr, socklen_t *restrict addrlen);

ssize_t ioth_recvmsg(int sockfd, struct msghdr *msg, int flags);

ssize_t ioth_write(int fd, const void *buf, size_t count);

ssize_t ioth_writev(int fd, const struct iovec *iov, int iovcnt);

ssize_t ioth_send(int sockfd, const void *buf, size_t len, int flags);

ssize_t ioth_sendto(int sockfd, const void *buf, size_t len, int flags,
const struct sockaddr *dest_addr, socklen_t addrlen);

ssize_t ioth_sendmsg(int sockfd, const struct msghdr *msg, int flags);

• nlinline+ API

int ioth_if_nametoindex(const char *ifname);

int ioth_linksetupdown(unsigned int ifindex, int updown);

int ioth_ipaddr_add(int family, void *addr, int prefixlen, unsigned int
ifindex);

int ioth_ipaddr_del(int family, void *addr, int prefixlen, unsigned int
ifindex);

int ioth_iproute_add(int family, void *dst_addr, int dst_prefixlen, void
*gw_addr, unsigned int ifindex);

int ioth_iproute_del(int family, void *dst_addr, int dst_prefixlen, void
*gw_addr, unsigned int ifindex);

int ioth_iplink_add(const char *ifname, unsigned int ifindex, const char
*type, const char *data);

int ioth_iplink_del(const char *ifname, unsigned int ifindex`);

int ioth_linksetaddr(unsigned int ifindex, void *macaddr`);

int ioth_linkgetaddr(unsigned int ifindex, void *macaddr`);

(yes, those trailing backticks in the last three are in the original. i'm not touching them. they're part of the lore. 💀)

---

🦋 DESCRIPTION 🦋

so. libioth is the API for the Internet of Threads. the whole serve is that TCP-IP networking stacks can be loaded as dynamic libraries at run time. like, at runtime. no recompile, no nothing. obsessed.

the vibe check, bullet by bullet:

• the API is minimal: Berkeley Sockets + msocket + newstack/delstack. ✨
• the stack implementation can be chosen as a plugin at run time.
• netlink based stack/interface/ip configuration via nlinline.
• ioth sockets are real file descriptors, and they're poll/select/ppoll/pselect/epoll friendly.
• plug-ins can be loaded in private address namespaces: libioth supports several stacks of the same type (same plugin) even if the stack implementation library was designed to provide just one stack.

libioth provides the following functions:

• ioth_newstack — ioth_newstack creates a new stack without any interface if vnl is NULL; otherwise the new stack has a virtual interface connected to the vde network identified by the VNL (Virtual Network Locator, see vde_open(3)).
• ioth_newstackl, ioth_newstackv — ioth_newstackl and ioth_newstackv (l = list, v = vector) support the creation of a new stack with several interfaces. you can hand over the VNLs either as a sequence of arguments (like in execl(3)) or as a NULL terminated array of VNLs (like the arguments in execv(3)).
• ioth_delstack — this function terminates/deletes a stack. bye bestie 🫶
• ioth_msocket — this is the multi-stack supporting extension of socket(2). it behaves exactly as socket except for the added heading argument that lets you choose the stack among those currently available (previously created by an ioth_newstack*).
• ioth_set_defstack, ioth_get_defstack — these define and retrieve the default stack, respectively. the default stack is implicitly used by ioth_msocket when its first argument iothstack is NULL. the default stack is initially defined as the native stack provided by the kernel. use ioth_set_defstack(mystack) to define mystack as the current default stack. ioth_set_defstack(NULL) to revert the default stack back to the native stack.
• ioth_socket — ioth_socket opens a socket using the default stack: ioth_socket(d, t, p) is an alias for ioth_msocket(NULL, d, t, p).
• ioth_close, ioth_bind, ioth_connect, ioth_listen, ioth_accept, ioth_getsockname, ioth_getpeername, ioth_setsockopt, ioth_getsockopt, ioth_shutdown, ioth_ioctl, ioth_fcntl, ioth_read, ioth_readv, ioth_recv, ioth_recvfrom, ioth_recvmsg, ioth_write, ioth_writev, ioth_send, ioth_sendto, ioth_sendmsg — these functions have the **same signature and functionalities of their counterpart in (2) and (3), just without the ioth_ prefix. same energy, new name. 💅
• **ioth_if_nametoindex, ioth_linksetupdown, ioth_ipaddr_add, ioth_ipaddr_del, ioth_iproute_add, ioth_iproute_del, ioth_iplink_add, ioth_iplink_del, ioth_linksetaddr, ioth_linkgetaddr — these functions have the same signature and functionnalities described in nlinline(3).

---

💜 RETURN VALUE 💜

• ioth_newstack, ioth_newstackl, ioth_newstackv return a struct stack pointer, or NULL in case of error. this address is used as a descriptor of the newly created stack and is later passed as a parameter to ioth_msocket, ioth_set_defstack or ioth_delstack. 🎀
• ioth_msocket and ioth_socket return the file descriptor of the new socket, or -1 in case of errore.
• ioth_delstack returns -1 in case of error, 0 otherwise. if there are file descriptors already in use, this function fails and errno is EBUSY. ⚠️ (so close your fds first, bestie, or it's not gonna happen.)
• ioth_get_defstack returns the stack descriptor of the default stack.
• the return values of all the other functions are defined in the man pages of the corresponding functions provided by the GNU C library or nlinline(3).

---

🔥 SEE ALSO 🔥

• vde_plug(1)
• vdeplug_open(3)
• nlinline(3)

---

👑 AUTHOR 👑

VirtualSquare. project leader: Renzo Davoli.

---

VirtualSquare — January 2024 — IOTH(3)

and that's the page, bestie 💖 ngl this whole thing is iconic — a whole socket API that lets you hot-swap networking stacks like outfits. go forth and ioth_msocket responsibly. no cap. 🦋✨