VSOCK(4) Device Drivers Manual VSOCK(4)

vsock — VM Sockets

#include <sys/socket.h>
#include <sys/vsock.h>

int
socket(AF_VSOCK, SOCK_STREAM, 0);

The vsock protocol allows for socket communication between a virtual machine and its host. Socket connections may be established using standard socket interfaces. Currently, only stream connections from a guest are supported using this protocol.

When a vsock socket is set non-blocking, and the connection cannot be established immediately, connect(2) returns with the error EINPROGRESS, and the connection is established asynchronously.

When the asynchronous connection completes successfully, select(2) or poll(2) or kqueue(2) will indicate the file descriptor is ready for writing. If the connection encounters an error, the file descriptor is marked ready for both reading and writing, and the pending error can be retrieved via the socket option SO_ERROR.

Note that even if the socket is non-blocking, it is possible for the connection to be established immediately. In that case connect(2) does not return with EINPROGRESS.

Sockets bound to the vsock protocol family utilize the following addressing structure which can be found in the header ⟨sys/vsock.h⟩.

struct sockaddr_vm {
	uint8_t 	svm_len;
	sa_family_t	svm_family;
	uint16_t	svm_reserved1;
	uint32_t	svm_port;
	uint32_t	svm_cid;
};

Addresses consist of a cid and a port. The field svm_len contains the total length of the structure, while the field svm_family contains the value AF_VSOCK. The field svm_reserved1 is reserved and should be set to zero.

Sockets may be created with the local address VMADDR_CID_ANY to effect “wildcard” matching on incoming messages. The cid addresses VMADDR_CID_HYPERVISOR or VMADDR_CID_HOST may be used to connect(2) or bind(2) to the hypervisor or host respectively. VMADDR_PORT_ANY may be used to obtain the next available free port when calling bind(2).

Wildcard matches any address.
The address of the hypervisor.
The address of the host.

Wildcard matches any port.

A vsock socket operation may fail with a general socket error or one of the following vsock specific errors:

[]
returned by bind(2) when attempting to bind to a privileged port;
[]
returned by bind(2) when attempting to bind to a cid and port that is already in use;
[]
returned by bind(2) when attempting to bind to an invalid cid or port;
[]
returned by connect(2) when attempting to connect to an invalid cid;
[]
returned by connect(2) when attempting to connect using a non-blocking socket;
[]
when passing an invalid parameter;
[]
when a vsock transport does not exist;
[]
when performing an operation on a non-connected socket;
[]
returned by connect(2) when a connection attempt has timed out;
[]
returned by send(2) or recv(2) when sending or receiving using a non-blocking socket.

The ioctl(2) command codes below are defined in ⟨sys/vsock.h⟩. All commands require these includes:

        #include <sys/ioctl.h>
        #include <sys/vsock.h>

The third argument to ioctl(2) should be a pointer to the type indicated in parenthesis.

(uint32_t) Returns the local cid of this socket's transport.

bind(2), connect(2), ioctl(2), kqueue(2), poll(2), select(2), socket(2)

July 9, 2020 macOS