.\" Copyright (C) 2022 VirtualSquare. Project Leader: Renzo Davoli
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License,
.\" as published by the Free Software Foundation, either version 2
.\" of the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA.
.\"
.\" Automatically generated by Pandoc 3.1.11
.\"
.TH "IOTH" "3" "January 2024" "VirtualSquare" "Library Functions Manual"
.SH 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
.SH SYNOPSIS
\f[CB]#include <ioth.h>\f[R]
.PP
\f[CB]struct ioth *ioth_newstack(const char *\f[R]\f[I]stack\f[R]\f[CB], const char *\f[R]\f[I]vnl\f[R]\f[CB]);\f[R]
.PP
\f[CB]struct ioth *ioth_newstackl(const char *\f[R]\f[I]stack\f[R]\f[CB], const char *\f[R]\f[I]vnl\f[R]\f[CB], ... );\f[R]
.PP
\f[CB]struct ioth *ioth_newstackv(const char *\f[R]\f[I]stack\f[R]\f[CB], const char *\f[R]\f[I]vnlv\f[R]\f[CB][]);\f[R]
.PP
\f[CB]int ioth_delstack(struct ioth *\f[R]\f[I]iothstack\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_msocket(struct ioth *\f[R]\f[I]iothstack\f[R]\f[CB], int\f[R]
\f[I]domain\f[R]\f[CB], int\f[R] \f[I]type\f[R]\f[CB], int\f[R]
\f[I]protocol\f[R]\f[CB]);\f[R]
.PP
\f[CB]void ioth_set_defstack(struct ioth *\f[R]\f[I]iothstack\f[R]\f[CB]);\f[R]
.PP
\f[CB]struct ioth *ioth_get_defstack(void);\f[R]
.PP
\f[CB]int ioth_socket(int\f[R] \f[I]domain\f[R]\f[CB], int\f[R]
\f[I]type\f[R]\f[CB], int\f[R] \f[I]protocol\f[R]\f[CB]);\f[R]
.IP \[bu] 2
Berkeley Sockets API
.PP
\f[CB]int ioth_close(int\f[R] \f[I]fd\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_bind(int\f[R]
\f[I]sockfd\f[R]\f[CB], const struct sockaddr *\f[R]\f[I]addr\f[R]\f[CB], socklen_t\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_connect(int\f[R]
\f[I]sockfd\f[R]\f[CB], const struct sockaddr *\f[R]\f[I]addr\f[R]\f[CB], socklen_t\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_listen(int\f[R] \f[I]sockfd\f[R]\f[CB], int\f[R]
\f[I]backlog\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_accept(int\f[R]
\f[I]sockfd\f[R]\f[CB], struct sockaddr *restrict\f[R]
\f[I]addr\f[R]\f[CB], socklen_t *restrict\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_getsockname(int\f[R]
\f[I]sockfd\f[R]\f[CB], struct sockaddr *restrict\f[R]
\f[I]addr\f[R]\f[CB], socklen_t *restrict\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_getpeername(int\f[R]
\f[I]sockfd\f[R]\f[CB], struct sockaddr *restrict\f[R]
\f[I]addr\f[R]\f[CB], socklen_t *restrict\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_getsockopt(int\f[R] \f[I]sockfd\f[R]\f[CB], int\f[R]
\f[I]level\f[R]\f[CB], int\f[R]
\f[I]optname\f[R]\f[CB], void *restrict\f[R]
\f[I]optval\f[R]\f[CB], socklen_t *restrict\f[R]
\f[I]optlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_setsockopt(int\f[R] \f[I]sockfd\f[R]\f[CB], int\f[R]
\f[I]level\f[R]\f[CB], int\f[R]
\f[I]optname\f[R]\f[CB], const void *\f[R]\f[I]optval\f[R]\f[CB], socklen_t\f[R]
\f[I]optlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_shutdown(int\f[R] \f[I]sockfd\f[R]\f[CB], int\f[R]
\f[I]how\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_ioctl(int\f[R] \f[I]fd\f[R]\f[CB], unsigned long\f[R]
\f[I]request\f[R]\f[CB], ...);\f[R]
.PP
\f[CB]int ioth_fcntl(int\f[R] \f[I]fd\f[R]\f[CB], int\f[R]
\f[I]cmd\f[R]\f[CB], ... /* arg */ );\f[R]
.PP
\f[CB]ssize_t ioth_read(int\f[R]
\f[I]fd\f[R]\f[CB], void *\f[R]\f[I]buf\f[R]\f[CB], size_t\f[R]
\f[I]count\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_readv(int\f[R]
\f[I]fd\f[R]\f[CB], const struct iovec *\f[R]\f[I]iov\f[R]\f[CB], int\f[R]
\f[I]iovcnt\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_recv(int\f[R]
\f[I]sockfd\f[R]\f[CB], void *\f[R]\f[I]buf\f[R]\f[CB], size_t\f[R]
\f[I]len\f[R]\f[CB], int\f[R] \f[I]flags\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_recvfrom(int\f[R]
\f[I]sockfd\f[R]\f[CB], void *restrict\f[R]
\f[I]buf\f[R]\f[CB], size_t\f[R] \f[I]len\f[R]\f[CB], int\f[R]
\f[I]flags\f[R]\f[CB], struct sockaddr *restrict\f[R]
\f[I]src_addr\f[R]\f[CB], socklen_t *restrict\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_recvmsg(int\f[R]
\f[I]sockfd\f[R]\f[CB], struct msghdr *\f[R]\f[I]msg\f[R]\f[CB], int\f[R]
\f[I]flags\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_write(int\f[R]
\f[I]fd\f[R]\f[CB], const void *\f[R]\f[I]buf\f[R]\f[CB], size_t\f[R]
\f[I]count\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_writev(int\f[R]
\f[I]fd\f[R]\f[CB], const struct iovec *\f[R]\f[I]iov\f[R]\f[CB], int\f[R]
\f[I]iovcnt\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_send(int\f[R]
\f[I]sockfd\f[R]\f[CB], const void *\f[R]\f[I]buf\f[R]\f[CB], size_t\f[R]
\f[I]len\f[R]\f[CB], int\f[R] \f[I]flags\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_sendto(int\f[R]
\f[I]sockfd\f[R]\f[CB], const void *\f[R]\f[I]buf\f[R]\f[CB], size_t\f[R]
\f[I]len\f[R]\f[CB], int\f[R]
\f[I]flags\f[R]\f[CB], const struct sockaddr *\f[R]\f[I]dest_addr\f[R]\f[CB], socklen_t\f[R]
\f[I]addrlen\f[R]\f[CB]);\f[R]
.PP
\f[CB]ssize_t ioth_sendmsg(int\f[R]
\f[I]sockfd\f[R]\f[CB], const struct msghdr *\f[R]\f[I]msg\f[R]\f[CB], int\f[R]
\f[I]flags\f[R]\f[CB]);\f[R]
.IP \[bu] 2
nlinline+ API
.PP
\f[CB]int ioth_if_nametoindex(const char *\f[R]\f[I]ifname\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_linksetupdown(unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB], int\f[R] \f[I]updown\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_ipaddr_add(int\f[R]
\f[I]family\f[R]\f[CB], void *\f[R]\f[I]addr\f[R]\f[CB], int\f[R]
\f[I]prefixlen\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_ipaddr_del(int\f[R]
\f[I]family\f[R]\f[CB], void *\f[R]\f[I]addr\f[R]\f[CB], int\f[R]
\f[I]prefixlen\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_iproute_add(int\f[R]
\f[I]family\f[R]\f[CB], void *\f[R]\f[I]dst_addr\f[R]\f[CB], int\f[R]
\f[I]dst_prefixlen\f[R]\f[CB], void *\f[R]\f[I]gw_addr\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_iproute_del(int\f[R]
\f[I]family\f[R]\f[CB], void *\f[R]\f[I]dst_addr\f[R]\f[CB], int\f[R]
\f[I]dst_prefixlen\f[R]\f[CB], void *\f[R]\f[I]gw_addr\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_iplink_add(const char *\f[R]\f[I]ifname\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB], const char *\f[R]\f[I]type\f[R]\f[CB], const char *\f[R]\f[I]data\f[R]\f[CB]);\f[R]
.PP
\f[CB]int ioth_iplink_del(const char *\f[R]\f[I]ifname\f[R]\f[CB], unsigned int\f[R]
\f[I]ifindex\f[R]\[ga]);
.PP
\f[CB]int ioth_linksetaddr(unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB], void *\f[R]\f[I]macaddr\f[R]\[ga]);
.PP
\f[CB]int ioth_linkgetaddr(unsigned int\f[R]
\f[I]ifindex\f[R]\f[CB], void *\f[R]\f[I]macaddr\f[R]\[ga]);
.SH DESCRIPTION
\f[CB]libioth\f[R] is the API for the Internet of Threads.
TCP\-IP networking stacks can be loaded as dynamic libraries at run
time.
.IP \[bu] 2
the API is minimal: Berkeley Sockets + msocket + newstack/delstack.
.IP \[bu] 2
the stack implementation can be chosen as a plugin at run time.
.IP \[bu] 2
netlink based stack/interface/ip configuration via nlinline.
.IP \[bu] 2
ioth sockets are real file descriptors, poll/select/ppoll/pselect/epoll
friendly
.IP \[bu] 2
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.
.PP
\f[CB]libioth\f[R] provides the following functions:
.TP
\f[CB]ioth_newstack\f[R]
\f[CB]ioth_newstack\f[R] creates a new stack without any interface if
\f[CB]vnl\f[R] 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) ).
.TP
\f[CB]ioth_newstackl\f[R], \f[CB]ioth_newstackv\f[R]
ioth_newstackl\f[CB]and\f[R]ioth_newstackv\[ga] (l = list, v = vector)
support the creation of a new stack with several interfaces.
It is possible to provide the VNLs as a sequence of arguments (as in
execl(3)) or as a NULL terminated array of VNLs (as the arguments in
execv(3)).
.TP
\f[CB]ioth_delstack\f[R]
This function terminates/deletes a stack.
.TP
\f[CB]ioth_msocket\f[R]
This is the multi\-stack supporting extension of socket(2).
It behaves exactly as socket except for the added heading argument that
allows the choice of the stack among those currently available
(previously created by a \f[CB]ioth_newstack*\f[R]).
.TP
\f[CB]ioth_set_defstack\f[R], \f[CB]ioth_get_defstack\f[R]
These functions 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 to the native stack.
.TP
\f[CB]ioth_socket\f[R]
\f[CB]ioth_socket\f[R] opens a socket using the default stack:
\f[CB]ioth_socket(d, t, p)\f[R] is an alias for
\f[CB]ioth_msocket(NULL, d, t, p)\f[R]
.TP
\f[CB]ioth_close\f[R], \f[CB]ioth_bind\f[R], \f[CB]ioth_connect\f[R], \f[CB]ioth_listen\f[R], \f[CB]ioth_accept\f[R], \f[CB]ioth_getsockname\f[R], \f[CB]ioth_getpeername\f[R], \f[CB]ioth_setsockopt\f[R], \f[CB]ioth_getsockopt\f[R], \f[CB]ioth_shutdown\f[R], \f[CB]ioth_ioctl\f[R], \f[CB]ioth_fcntl\f[R], \f[CB]ioth_read\f[R], \f[CB]ioth_readv\f[R], \f[CB]ioth_recv\f[R], \f[CB]ioth_recvfrom\f[R], \f[CB]ioth_recvmsg\f[R], \f[CB]ioth_write\f[R], \f[CB]ioth_writev\f[R], \f[CB]ioth_send\f[R], \f[CB]ioth_sendto\f[R], \f[CB]ioth_sendmsg\f[R]
these functions have the same signature and functionalities of their
counterpart in (2) and (3) without the \f[CB]ioth_\f[R] prefix.
.TP
\f[CB]ioth_if_nametoindex\f[R], \f[CB]ioth_linksetupdown\f[R], \f[CB]ioth_ipaddr_add\f[R], \f[CB]ioth_ipaddr_del\f[R], \f[CB]ioth_iproute_add\f[R], \f[CB]ioth_iproute_del\f[R], \f[CB]ioth_iplink_add\f[R], \f[CB]ioth_iplink_del\f[R], \f[CB]ioth_linksetaddr\f[R], \f[CB]ioth_linkgetaddr\f[R]
these functions have the same signature and functionnalities described
in \f[CB]nlinline\f[R](3).
.SH RETURN VALUE
\f[CB]ioth_newstack\f[R], \f[CB]ioth_newstackl\f[R],
\f[CB]ioth_newstackv\f[R] return a \f[CB]struct stack\f[R] pointer, NULL
in case of error.
This address is used as a descriptor of the newly created stack and is
later passed as parameter to \f[CB]ioth_msocket\f[R],
\f[CB]ioth_set_defstack\f[R] or \f[CB]ioth_delstack\f[R].
.PP
\f[CB]ioth_msocket\f[R] and \f[CB]ioth_socket\f[R] return the file
descriptor of the new socket, \-1 in case of errore.
.PP
\f[CB]ioth_delstack\f[R] returns \-1 in case of error, 0 otherwise.
If there are file descriptors already in use, this function fails and
errno is EBUSY.
.PP
\f[CB]ioth_get_defstack\f[R] returns the stack descriptor of the default
stack.
.PP
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)
.SH SEE ALSO
vde_plug(1), vdeplug_open(3), nlinline(3)
.SH AUTHOR
VirtualSquare.
Project leader: Renzo Davoli