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 address in a 103.Xr connect 2 104call may be given as 105.Dv VMADDR_CID_ANY 106to mean 107.Dq this host . 108The cid addresses 109.Dv VMADDR_CID_HYPERVISOR 110or 111.Dv VMADDR_CID_HOST 112may be used to 113.Xr connect 2 114or 115.Xr bind 2 116to the hypervisor or host respectively. 117.Dv VMADDR_PORT_ANY 118may be used to obtain the next available free port when calling 119.Xr bind 2 . 120.Ss CID Constants 121.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR" 122.It Dv VMADDR_CID_ANY 123Wildcard matches any address. 124.It Dv VMADDR_CID_HYPERVISOR 125The address of the hypervisor. 126.It Dv VMADDR_CID_HOST 127The address of the host. 128.El 129.Ss Port Constants 130.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR" 131.It Dv VMADDR_PORT_ANY 132Wildcard matches any port. 133.El 134.Sh ERRORS 135A 136.Tn vsock 137socket operation may fail with a general socket error or one of the following 138.Tn vsock 139specific errors: 140.Bl -tag -width ".It Bq Er EADDRNOTAVAIL" 141.It Bq Er EACCES 142returned by 143.Xr bind 2 144when attempting to bind to a privileged port; 145.It Bq Er EADDRINUSE 146returned by 147.Xr bind 2 148when attempting to bind to a cid and port that is already in use; 149.It Bq Er EADDRNOTAVAIL 150returned by 151.Xr bind 2 152when attempting to bind to an invalid cid or port; 153.It Bq Er EFAULT 154returned by 155.Xr connect 2 156when attempting to connect to an invalid cid; 157.It Bq Er EINPROGRESS 158returned by 159.Xr connect 2 160when attempting to connect using a non-blocking socket; 161.It Bq Er EINVAL 162when passing an invalid parameter; 163.It Bq Er ENODEV 164when a vsock transport does not exist; 165.It Bq Er ENOTCONN 166when performing an operation on a non-connected socket; 167.It Bq Er ETIMEDOUT 168returned by 169.Xr connect 2 170when a connection attempt has timed out; 171.It Bq Er EWOULDBLOCK 172returned by 173.Xr send 2 174or 175.Xr recv 2 176when sending or receiving using a non-blocking socket. 177.El 178.Sh IOCTLS 179The 180.Xr ioctl 2 181command codes below are defined in 182.Aq Pa sys/vsock.h . 183All commands require 184these includes: 185.Bd -literal 186 #include <sys/ioctl.h> 187 #include <sys/vsock.h> 188.Ed 189.Pp 190The third argument to 191.Xr ioctl 2 192should be a pointer to the type indicated in parenthesis. 193.Bl -tag -width IOCTL_VM_SOCKETS_GET_LOCAL_CID 194.It Dv IOCTL_VM_SOCKETS_GET_LOCAL_CID 195.Pq Li uint32_t 196Returns the local cid of this socket's transport. 197.El 198.Sh SEE ALSO 199.Xr bind 2 , 200.Xr connect 2 , 201.Xr ioctl 2 , 202.Xr kqueue 2 , 203.Xr poll 2 , 204.Xr select 2 , 205.Xr socket 2 206