1.\" 2.\" Copyright (c) 2020 Apple Inc. All rights reserved. 3.\" 4.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. The rights granted to you under the License 10.\" may not be used to create, or enable the creation or redistribution of, 11.\" unlawful or unlicensed copies of an Apple operating system, or to 12.\" circumvent, violate, or enable the circumvention or violation of, any 13.\" terms of an Apple operating system software license agreement. 14.\" 15.\" Please obtain a copy of the License at 16.\" http://www.opensource.apple.com/apsl/ and read it before using this file. 17.\" 18.\" The Original Code and all software distributed under the License are 19.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23.\" Please see the License for the specific language governing rights and 24.\" limitations under the License. 25.\" 26.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27.\" 28.\" @(#)vsock.4 7/9/2020 29.\" 30.Dd July 9, 2020 31.Dt VSOCK 4 32.Os macOS 33.Sh NAME 34.Nm vsock 35.Nd VM Sockets 36.Sh SYNOPSIS 37.In sys/socket.h 38.In sys/vsock.h 39.Ft int 40.Fn socket AF_VSOCK SOCK_STREAM 0 41.Sh DESCRIPTION 42The 43.Tn vsock 44protocol 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. 45.Pp 46.Ss "Non-blocking connect" 47When a 48.Tn vsock 49socket is set non-blocking, and the connection cannot be established immediately, 50.Xr connect 2 51returns with the error 52.Dv EINPROGRESS , 53and the connection is established asynchronously. 54.Pp 55When the asynchronous connection completes successfully, 56.Xr select 2 57or 58.Xr poll 2 59or 60.Xr kqueue 2 61will indicate the file descriptor is ready for writing. 62If the connection encounters an error, the file descriptor 63is marked ready for both reading and writing, and the pending error 64can be retrieved via the socket option 65.Dv SO_ERROR . 66.Pp 67Note that even if the socket is non-blocking, it is possible for the connection 68to be established immediately. In that case 69.Xr connect 2 70does not return with 71.Dv EINPROGRESS . 72.Sh ADDRESSING 73Sockets bound to the vsock protocol family utilize 74the following addressing structure which can be found in the header 75.Aq Pa sys/vsock.h . 76.Bd -literal -offset indent 77struct sockaddr_vm { 78 uint8_t svm_len; 79 sa_family_t svm_family; 80 uint16_t svm_reserved1; 81 uint32_t svm_port; 82 uint32_t svm_cid; 83}; 84.Ed 85.Pp 86Addresses consist of a cid and a port. 87The field 88.Ar svm_len 89contains the total length of the structure, while the field 90.Ar svm_family 91contains the value 92.Fa AF_VSOCK . 93The field 94.Fa svm_reserved1 95is reserved and should be set to zero. 96.Pp 97Sockets may be created with the local address 98.Dv VMADDR_CID_ANY 99to effect 100.Dq wildcard 101matching on incoming messages. 102The cid addresses 103.Dv VMADDR_CID_HYPERVISOR 104or 105.Dv VMADDR_CID_HOST 106may be used to 107.Xr connect 2 108or 109.Xr bind 2 110to the hypervisor or host respectively. 111.Dv VMADDR_PORT_ANY 112may be used to obtain the next available free port when calling 113.Xr bind 2 . 114.Ss CID Constants 115.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR" 116.It Dv VMADDR_CID_ANY 117Wildcard matches any address. 118.It Dv VMADDR_CID_HYPERVISOR 119The address of the hypervisor. 120.It Dv VMADDR_CID_HOST 121The address of the host. 122.El 123.Ss Port Constants 124.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR" 125.It Dv VMADDR_PORT_ANY 126Wildcard matches any port. 127.El 128.Sh ERRORS 129A 130.Tn vsock 131socket operation may fail with a general socket error or one of the following 132.Tn vsock 133specific errors: 134.Bl -tag -width ".It Bq Er EADDRNOTAVAIL" 135.It Bq Er EACCES 136returned by 137.Xr bind 2 138when attempting to bind to a privileged port; 139.It Bq Er EADDRINUSE 140returned by 141.Xr bind 2 142when attempting to bind to a cid and port that is already in use; 143.It Bq Er EADDRNOTAVAIL 144returned by 145.Xr bind 2 146when attempting to bind to an invalid cid or port; 147.It Bq Er EFAULT 148returned by 149.Xr connect 2 150when attempting to connect to an invalid cid; 151.It Bq Er EINPROGRESS 152returned by 153.Xr connect 2 154when attempting to connect using a non-blocking socket; 155.It Bq Er EINVAL 156when passing an invalid parameter; 157.It Bq Er ENODEV 158when a vsock transport does not exist; 159.It Bq Er ENOTCONN 160when performing an operation on a non-connected socket; 161.It Bq Er ETIMEDOUT 162returned by 163.Xr connect 2 164when a connection attempt has timed out; 165.It Bq Er EWOULDBLOCK 166returned by 167.Xr send 2 168or 169.Xr recv 2 170when sending or receiving using a non-blocking socket. 171.El 172.Sh IOCTLS 173The 174.Xr ioctl 2 175command codes below are defined in 176.Aq Pa sys/vsock.h . 177All commands require 178these includes: 179.Bd -literal 180 #include <sys/ioctl.h> 181 #include <sys/vsock.h> 182.Ed 183.Pp 184The third argument to 185.Xr ioctl 2 186should be a pointer to the type indicated in parenthesis. 187.Bl -tag -width IOCTL_VM_SOCKETS_GET_LOCAL_CID 188.It Dv IOCTL_VM_SOCKETS_GET_LOCAL_CID 189.Pq Li uint32_t 190Returns the local cid of this socket's transport. 191.El 192.Sh SEE ALSO 193.Xr bind 2 , 194.Xr connect 2 , 195.Xr ioctl 2 , 196.Xr kqueue 2 , 197.Xr poll 2 , 198.Xr select 2 , 199.Xr socket 2 200