API

Types

struct device

The struct device is an opaque structure containing internal parameter, like the device name, device flags, device file descriptor, etc. You should not access them.

The structure size may vary from an operating system to an other, you should not rely on it.

t_tuntap_log

typedef void (*t_tuntap_log)(int level, const char *msg);

This type is a pointer to a log function. It allows to override the default behaviour, which is printing every messages on the error output prefixed with its error level.

Error levels are described later, they are macros in the form TUNTAP_LOG_*.

t_tun

The t_tun type map the file descriptor type of a given operating system.

Typically it's an int on UNIXes and a HANDLE on Windows.

Macros

There is two type of macros, the libtuntap ones, and the "portable" ones. The laters are here to help portable parts of the code to rely on meaningful names, not hard-coded magic values.

libtuntap macros

TUNTAP_ID_MAX

TUNTAP_ID_MAX is the maximal device unit giveable as the third parameter of tuntap_start().

TUNTAP_ID_ANY

TUNTAP_ID_ANY is the wild-card device unit giveable as the third parameter of tuntap_start().

TUNTAP_MODE_ETHERNET

TUNTAP_MODE_ETHERNET is the tap-mode giveable as the second parameter of tuntap_start().

TUNTAP_MODE_TUNNEL

TUNTAP_MODE_TUNNEL is the tun-mode giveable as the second parameter of tuntap_start().

TUNTAP_MODE_PERSIST

TUNTAP_MODE_PERSIST is the persistence flag giveable OR'ed with the second parameter of tuntap_start().

This flag is optional and should be used with either TUNTAP_MODE_TUNNEL or TUNTAP_MODE_ETHERNET.

TUNTAP_LOG_ERR

TUNTAP_LOG_ERR describes an error message.

TUNTAP_LOG_WARN

TUNTAP_LOG_WARN describes a warning message.

TUNTAP_LOG_INFO

TUNTAP_LOG_INFO describes an informational message.

TUNTAP_LOG_NOTICE

TUNTAP_LOG_NOTICE describes a message which is not really an error nor a warning. It is mostly used to warn about unimplemented or unavailable part of the libtuntap.

TUNTAP_LOG_DEBUG

TUNTAP_LOG_DEBUG describes a debug messages. You should see one only if your are using the git HEAD.

TUNTAP_LOG_NONE

TUNTAP_LOG_NONE describes other things. It is only used by tuntap_log_hexdump() and tuntap_log_chksum().

Portable macros

ETHER_ADDR_LEN

ETHER_ADDR_LEN is a value dictated by [[http://www.ieee802.org/3/|IEEE 802.3]] standard. On Linux systems its value is mapped on ETH_ALEN one.

IF_NAMESIZE

IF_NAMESIZE gives the maximal length of an interface name. On BSD systems its value is mapped on IFNAMSIZ one.

IF_DESCRSIZE

IF_DESCSIZE gives the maximal length of an interface description.

TUNFD_INVALID_VALUE

TUNFD_INVALID_VALUE is the invalid value of the t_tun type. On UNIXes systems its value is -1. On Windows systems its value is INVALID_HANDLE_VALUE.

Functions

tuntap_init

struct device *tuntap_init(void);

This function will allocate and initialise a struct device.

tuntap_version

int tuntap_version(void);

This function returns the version number of libtuntap. You can extract the major and the minor like this:

int version = tuntap_version();
int major = version >> 8;
int minor = version & major;

Note that this version number is not the same as the shared library version.

tuntap_destroy

void tuntap_destroy(struct device *dev);

This function will free allocated memory, close file descriptors and destroy the interface.

=== tuntap_release

void tuntap_release(struct device *dev);

This function will free allocated memory and close file descriptors. leaving the interface.

=== tuntap_start

int tuntap_start(struct device dev*, int mode, int unit);

This function will configure the device with the mode mode and the optional device unit unit.

The mode parameter should be either TUNTAP_MODE_ETHERNET or TUNTAP_MODE_TUNNEL eventually ORed with TUNTAP_MODE_PERSIST.

The unit parameter should always be less than TUNTAP_ID_MAX and greater than 0. If you don't need a particular value, you should use TUNTAP_ID_ANY, which is a sort of wild-card device unit. With this parameter, the kernel will pick the next available device. The term "device unit" is also known as PPA, for Physical Point of Attachment, in Solaris documentation.

Examples:

tuntap_start(dev, TUNTAP_MODE_ETHERNET, TUNTAP_ID_ANY)

tuntap_start(dev, TUNTAP_MODE_TUNNEL, 2)

tuntap_start(dev, TUNTAP_MODE_TUNNEL | TUNTAP_MODE_PERSIST, TUNTAP_ID_ANY)

tuntap_get_ifname

char     *tuntap_get_ifname(struct device *dev);

This function fetch and return the name of the interface described by dev.

tuntap_set_ifname

int tuntap_set_ifname(struct device *dev, const char *ifname);

This function replaces the name of the interface described by dev with the given name ifname.

It returns -1 on error.

Compatibility: Linux.

tuntap_get_hwaddr

char         *tuntap_get_hwaddr(struct device *dev);

This function fetch and returns the link-layer address (MAC) of the interface described by dev.

The returned string come from a statically allocated buffer, ans thus should be saved if needed for later use.

tuntap_set_hwaddr

int tuntap_set_hwaddr(struct device *dev, const char *mac_addr);

This function replaces the link-layer address of the interface described by dev with the given address mac_addr.

It returns -1 on error.

tuntap_set_descr

int tuntap_set_descr(struct device *dev, const char *desc);

This function replaces the description of the interface described by dev with the given string desc.

Compatibility: OpenBSD, FreeBSD.

tuntap_up

int tuntap_up(struct device *dev);

This function set interface to the UP state, just like ifconfig eth0 up would do.

tuntap_down

int tuntap_down(struct device *dev);

This function set interface to the DOWN state, just like ifconfig eth0 down would do.

tuntap_get_mtu

int tuntap_get_mtu(struct device *dev);

This function fetch and returns the Maximum Transfer Unit (MTU) of the interface described by dev.

tuntap_set_mtu

int tuntap_set_mtu(struct device *dev, int mtu);

This function replaces the MTU of the interface described by dev with the given value mtu.

tuntap_set_ip

int tuntap_set_ip(struct device *dev, const char *, int ip_addr);

This function replaces the IP address of the interface described by dev with the given address ip_addr.

tuntap_read

int tuntap_read(struct device *dev, void *buf, size_t buf_len);

This function will read one packet from the interface descibed by dev and will store it in the buffer buf of size buf_len. This value can be retrieved with a call to tuntap_get_readable().

tuntap_write

int tuntap_write(struct device *dev, void *buf, size_t buf_len);

This function will write the packet stored in the buffer buf of size buf_len to the interface descibed by dev.

tuntap_get_readable

int tuntap_get_readable(struct device *dev);

This function will return the size of the next packet waiting in the buffer queue of the interface described by dev. On Linux this function is the same as tuntap_get_mtu(), because the ioctl call FIONREAD is not supported on caracter devices.

tuntap_set_nonblocking

int tuntap_set_nonblocking(struct device *dev, int set);

This function will set the socket of the interface described by dev to a non-blocking state.

tuntap_set_debug

int tuntap_set_debug(struct device *dev, int set);

This function will enable or disable the debug mode of the interface described by dev, depending of the value of set.

If set is 0, it will disable debug, and if it is 1 it will enable it.

The debug mode will add more output regarding the interface on the console.

This functionality depend on your operating system. It is enable by default on FreeBSD and NetBSD, but you might have to recompile your tun and tap drivers on Linux and OpenBSD to enable it.

tuntap_log_set_cb

void tuntap_log_set_cb(t_tuntap_log cb);

This function allow to set an external printing function, in order to erase the default behaviour.

tuntap_log_hexdump

void tuntap_log_hexdump(void *, size_t);

This function is actualy not documented.

tuntap_log_chksum

void tuntap_log_chksum(void *, int);

This function is actualy not documented.

TUNTAP_GET_FD

int TUNTAP_GET_FD(struct device *dev)

This macro will return the socket of the interface described by dev.