---
name: "vsock"
section: "4"
platform: "macos"
package: "xnu"
version: "12377.121.6"
release: "macOS 26.5"
platforms: ["macos"]
url: "https://new.carta.tech/vsock/4"
---

# vsock(4)

VM Sockets

## NAME

**vsock** – VM Sockets

## SYNOPSIS

**#include \<sys/socket.h\>**

**#include \<sys/vsock.h\>**

*int*\

**socket**(*AF\_VSOCK*, *SOCK\_STREAM*, *0*);

## DESCRIPTION

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.

### Non-blocking connect

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

When the asynchronous connection completes successfully, [select(2)](/select/2.md) or [poll(2)](/poll/2.md) or [kqueue(2)](/kqueue/2.md) 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)](/connect/2.md) does not return with EINPROGRESS.

## ADDRESSING

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)](/connect/2.md) or [bind(2)](/bind/2.md) to the hypervisor or host respectively. VMADDR\_PORT\_ANY may be used to obtain the next available free port when calling [bind(2)](/bind/2.md).

### CID Constants

- VMADDR\_CID\_ANY

  Wildcard matches any address.

- VMADDR\_CID\_HYPERVISOR

  The address of the hypervisor.

- VMADDR\_CID\_HOST

  The address of the host.

### Port Constants

- VMADDR\_PORT\_ANY

  Wildcard matches any port.

## ERRORS

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

- \[EACCES\]

  returned by [bind(2)](/bind/2.md) when attempting to bind to a privileged port;

- \[EADDRINUSE\]

  returned by [bind(2)](/bind/2.md) when attempting to bind to a cid and port that is already in use;

- \[EADDRNOTAVAIL\]

  returned by [bind(2)](/bind/2.md) when attempting to bind to an invalid cid or port;

- \[EFAULT\]

  returned by [connect(2)](/connect/2.md) when attempting to connect to an invalid cid;

- \[EINPROGRESS\]

  returned by [connect(2)](/connect/2.md) when attempting to connect using a non-blocking socket;

- \[EINVAL\]

  when passing an invalid parameter;

- \[ENODEV\]

  when a vsock transport does not exist;

- \[ENOTCONN\]

  when performing an operation on a non-connected socket;

- \[ETIMEDOUT\]

  returned by [connect(2)](/connect/2.md) when a connection attempt has timed out;

- \[EWOULDBLOCK\]

  returned by [send(2)](/send/2.md) or [recv(2)](/recv/2.md) when sending or receiving using a non-blocking socket.

## IOCTLS

The [ioctl(2)](/ioctl/2.md) 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)](/ioctl/2.md) should be a pointer to the type indicated in parenthesis.

- IOCTL\_VM\_SOCKETS\_GET\_LOCAL\_CID

  (uint32\_t) Returns the local cid of this socket's transport.

## SEE ALSO

[bind(2)](/bind/2.md), [connect(2)](/connect/2.md), [ioctl(2)](/ioctl/2.md), [kqueue(2)](/kqueue/2.md), [poll(2)](/poll/2.md), [select(2)](/select/2.md), [socket(2)](/socket/2.md)