bsd/man/man4/vsock.4

   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
  42 The
  43 .Tn vsock
  44 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.
  45 .Pp
  46 .Ss "Non-blocking connect"
  47 When a
  48 .Tn vsock
  49 socket is set non-blocking, and the connection cannot be established immediately,
  50 .Xr connect 2
  51 returns with the error
  52 .Dv EINPROGRESS ,
  53 and the connection is established asynchronously.
  54 .Pp
  55 When the asynchronous connection completes successfully,
  56 .Xr select 2
  57 or
  58 .Xr poll 2
  59 or
  60 .Xr kqueue 2
  61 will indicate the file descriptor is ready for writing.
  62 If the connection encounters an error, the file descriptor
  63 is marked ready for both reading and writing, and the pending error
  64 can be retrieved via the socket option
  65 .Dv SO_ERROR .
  66 .Pp
  67 Note that even if the socket is non-blocking, it is possible for the connection
  68 to be established immediately. In that case
  69 .Xr connect 2
  70 does not return with
  71 .Dv EINPROGRESS .
  72 .Sh ADDRESSING
  73 Sockets bound to the vsock protocol family utilize
  74 the following addressing structure which can be found in the header
  75 .Aq Pa sys/vsock.h .
  76 .Bd -literal -offset indent
  77 struct 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
  86 Addresses consist of a cid and a port.
  87 The field
  88 .Ar svm_len
  89 contains the total length of the structure, while the field
  90 .Ar svm_family
  91 contains the value
  92 .Fa AF_VSOCK .
  93 The field
  94 .Fa svm_reserved1
  95 is reserved and should be set to zero.
  96 .Pp
  97 Sockets may be created with the local address
  98 .Dv VMADDR_CID_ANY
  99 to effect
 100 .Dq wildcard
 101 matching on incoming messages.
 102 The address in a
 103 .Xr connect 2
 104 call may be given as
 105 .Dv VMADDR_CID_ANY
 106 to mean
 107 .Dq this host .
 108 The cid addresses
 109 .Dv VMADDR_CID_HYPERVISOR
 110 or
 111 .Dv VMADDR_CID_HOST
 112 may be used to
 113 .Xr connect 2
 114 or
 115 .Xr bind 2
 116 to the hypervisor or host respectively.
 117 .Dv VMADDR_PORT_ANY
 118 may 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
 123 Wildcard matches any address.
 124 .It Dv VMADDR_CID_HYPERVISOR
 125 The address of the hypervisor.
 126 .It Dv VMADDR_CID_HOST
 127 The address of the host.
 128 .El
 129 .Ss Port Constants
 130 .Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR"
 131 .It Dv VMADDR_PORT_ANY
 132 Wildcard matches any port.
 133 .El
 134 .Sh ERRORS
 135 A
 136 .Tn vsock
 137 socket operation may fail with a general socket error or one of the following
 138 .Tn vsock
 139 specific errors:
 140 .Bl -tag -width ".It Bq Er EADDRNOTAVAIL"
 141 .It Bq Er EACCES
 142 returned by
 143 .Xr bind 2
 144 when attempting to bind to a privileged port;
 145 .It Bq Er EADDRINUSE
 146 returned by
 147 .Xr bind 2
 148 when attempting to bind to a cid and port that is already in use;
 149 .It Bq Er EADDRNOTAVAIL
 150 returned by
 151 .Xr bind 2
 152 when attempting to bind to an invalid cid or port;
 153 .It Bq Er EFAULT
 154 returned by
 155 .Xr connect 2
 156 when attempting to connect to an invalid cid;
 157 .It Bq Er EINPROGRESS
 158 returned by
 159 .Xr connect 2
 160 when attempting to connect using a non-blocking socket;
 161 .It Bq Er EINVAL
 162 when passing an invalid parameter;
 163 .It Bq Er ENODEV
 164 when a vsock transport does not exist;
 165 .It Bq Er ENOTCONN
 166 when performing an operation on a non-connected socket;
 167 .It Bq Er ETIMEDOUT
 168 returned by
 169 .Xr connect 2
 170 when a connection attempt has timed out;
 171 .It Bq Er EWOULDBLOCK
 172 returned by
 173 .Xr send 2
 174 or
 175 .Xr recv 2
 176 when sending or receiving using a non-blocking socket.
 177 .El
 178 .Sh IOCTLS
 179 The
 180 .Xr ioctl 2
 181 command codes below are defined in
 182 .Aq Pa sys/vsock.h .
 183 All commands require
 184 these includes:
 185 .Bd -literal
 186         #include <sys/ioctl.h>
 187         #include <sys/vsock.h>
 188 .Ed
 189 .Pp
 190 The third argument to
 191 .Xr ioctl 2
 192 should 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
 196 Returns 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