---
name: "libvdestack"
section: "3"
platform: "linux"
package: "libvdestack0"
version: "0.1.3-1+b3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/libvdestack"
---

# libvdestack(3)

vde network namespace as a user library

## NAME

vde\_addstack, vde\_delstack, vde\_stackcmd, vde\_msocket - vde network namespace as a user library

## SYNOPSIS

\#include \*vdestack.h\*

struct vdestack \*vde\_addstack(char \**vdenet*, char \**ifname*);

void vde\_delstack(struct vdestack \**stack*);

int vde\_stackcmd(struct vdestack \**stack*, char \**stackcmd*);

int vde\_msocket(struct vdestack \**stack*,int *domain*, int *type*, int *protocol*);

void vde\_default\_stack(struct vdestack \**stack*);

## DESCRIPTION

Libvdestack implements the idea of Internet of Threads through network namespaces. By libvdestack a program can use one (or even several) private networking protocol stack(s), thus a program can be assigned its own IP address(es), routing etc.

- vde\_addstack

  create a private network namespace: *vdenet* is the URL-like specification of a vde network as described in :[vde\_plug(1)](/vde_plug/1.md). *ifname* is the name of the interface in the network namespace. When *ifname* is NULL, the default interface :name is vde0.

- vde\_delstack

  destroy a vdestack when it is no longer needed.

- vde\_stackcmd

  run a command or a comma separated sequence of commands in the private network namespace. The purpose of this function is to configure the networking parameters and options (e.g. IP address, routing). For security reasons, commands must be specified using full pathnames. Do not use this function to start long lasting or non terminating programs, the caller waits for the termination of the command sequence.

- vde\_msocket

  it has the same semantics of [socket(2)](/socket/2.md) except that the socket is defined in the scope of the network namespace whose descriptor is the first argument. The remaining arguments are those defined in [socket(2)](/socket/2.md).

- vde\_default\_stack

  define the default stack: any successive [socket(2)](/socket/2.md) call will use the stack passed as parameter to vde\_default\_stack. Use NULL to undefine the default stack.

## RETURN VALUE

vde\_addstack returns a struct vdestack pointer which is used as a descriptor and thus passed as an argument to the other functions of this library. NULL is returned in case of error.

vde\_stackcmd returns the exit status of the command. If the stackcmd argument is a comma separated sequence of commands, the execution terminates upon the first command whose exit status is not zero, and the exit status of that command is returned. Therefore when vde\_stackcmd returns zero the entire sequence was successfully executed.

On success, vde\_msocket returns a valid file descriptor. -1 is returned elseways and errno is set appropriately as described in [socket(2)](/socket/2.md).

## NOTES

Libvdestack fails if user namespaces have not been configured in the running kernel and enabled for users. In Debian the sysctl knob kernel.unprivileged\_userns\_clone must be set to 1.

## EXAMPLE

The following excerpt of C code shows the use of libvdestack:

-

  ```
  ...
  int fd;
  int exit_status;
  struct vdestack *stack = vde_addstack("vde://", NULL);
  if (stack == NULL)
      ... error management
  exit_status = vde_stackcmd(stack,
            "/bin/ip link set vde0 up;"
            "/bin/ip addr add 10.0.0.1/24 dev vde0;"
            "/bin/ip route add default via 10.0.0.254");
  if (exit_status != 0)
     ... error management
  fd = vde_msocket(stack, AF_INET, SOCK_STREAM, 0);
     ... fd can be used in any context in which a file descriptor returned by socket(2) can.
  e.g. bind, accept, connect, read/write, send/recv ...
  vde_delstack(stack);
  ```

## SEE ALSO

[socket(2)](/socket/2.md), [vde\_plug(1)](/vde_plug/1.md)

## BUGS

Bug reports should be addressed to *info@virtualsquare.org*

## AUTHOR

VirtualSquare. Project leader: Renzo Davoli.