199 lines
5.3 KiB
Groff
199 lines
5.3 KiB
Groff
.\"
|
|
.\" Copyright (c) 2020 Apple Inc. All rights reserved.
|
|
.\"
|
|
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
|
|
.\"
|
|
.\" This file contains Original Code and/or Modifications of Original Code
|
|
.\" as defined in and that are subject to the Apple Public Source License
|
|
.\" Version 2.0 (the 'License'). You may not use this file except in
|
|
.\" compliance with the License. The rights granted to you under the License
|
|
.\" may not be used to create, or enable the creation or redistribution of,
|
|
.\" unlawful or unlicensed copies of an Apple operating system, or to
|
|
.\" circumvent, violate, or enable the circumvention or violation of, any
|
|
.\" terms of an Apple operating system software license agreement.
|
|
.\"
|
|
.\" Please obtain a copy of the License at
|
|
.\" http://www.opensource.apple.com/apsl/ and read it before using this file.
|
|
.\"
|
|
.\" The Original Code and all software distributed under the License are
|
|
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
|
|
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
|
|
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
|
|
.\" Please see the License for the specific language governing rights and
|
|
.\" limitations under the License.
|
|
.\"
|
|
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
|
|
.\"
|
|
.\" @(#)vsock.4 7/9/2020
|
|
.\"
|
|
.Dd July 9, 2020
|
|
.Dt VSOCK 4
|
|
.Os macOS
|
|
.Sh NAME
|
|
.Nm vsock
|
|
.Nd VM Sockets
|
|
.Sh SYNOPSIS
|
|
.In sys/socket.h
|
|
.In sys/vsock.h
|
|
.Ft int
|
|
.Fn socket AF_VSOCK SOCK_STREAM 0
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Tn 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.
|
|
.Pp
|
|
.Ss "Non-blocking connect"
|
|
When a
|
|
.Tn vsock
|
|
socket is set non-blocking, and the connection cannot be established immediately,
|
|
.Xr connect 2
|
|
returns with the error
|
|
.Dv EINPROGRESS ,
|
|
and the connection is established asynchronously.
|
|
.Pp
|
|
When the asynchronous connection completes successfully,
|
|
.Xr select 2
|
|
or
|
|
.Xr poll 2
|
|
or
|
|
.Xr 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
|
|
.Dv SO_ERROR .
|
|
.Pp
|
|
Note that even if the socket is non-blocking, it is possible for the connection
|
|
to be established immediately. In that case
|
|
.Xr connect 2
|
|
does not return with
|
|
.Dv EINPROGRESS .
|
|
.Sh ADDRESSING
|
|
Sockets bound to the vsock protocol family utilize
|
|
the following addressing structure which can be found in the header
|
|
.Aq Pa sys/vsock.h .
|
|
.Bd -literal -offset indent
|
|
struct sockaddr_vm {
|
|
uint8_t svm_len;
|
|
sa_family_t svm_family;
|
|
uint16_t svm_reserved1;
|
|
uint32_t svm_port;
|
|
uint32_t svm_cid;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Addresses consist of a cid and a port.
|
|
The field
|
|
.Ar svm_len
|
|
contains the total length of the structure, while the field
|
|
.Ar svm_family
|
|
contains the value
|
|
.Fa AF_VSOCK .
|
|
The field
|
|
.Fa svm_reserved1
|
|
is reserved and should be set to zero.
|
|
.Pp
|
|
Sockets may be created with the local address
|
|
.Dv VMADDR_CID_ANY
|
|
to effect
|
|
.Dq wildcard
|
|
matching on incoming messages.
|
|
The cid addresses
|
|
.Dv VMADDR_CID_HYPERVISOR
|
|
or
|
|
.Dv VMADDR_CID_HOST
|
|
may be used to
|
|
.Xr connect 2
|
|
or
|
|
.Xr bind 2
|
|
to the hypervisor or host respectively.
|
|
.Dv VMADDR_PORT_ANY
|
|
may be used to obtain the next available free port when calling
|
|
.Xr bind 2 .
|
|
.Ss CID Constants
|
|
.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR"
|
|
.It Dv VMADDR_CID_ANY
|
|
Wildcard matches any address.
|
|
.It Dv VMADDR_CID_HYPERVISOR
|
|
The address of the hypervisor.
|
|
.It Dv VMADDR_CID_HOST
|
|
The address of the host.
|
|
.El
|
|
.Ss Port Constants
|
|
.Bl -tag -width ".Dv VMADDR_CID_HYPERVISOR"
|
|
.It Dv VMADDR_PORT_ANY
|
|
Wildcard matches any port.
|
|
.El
|
|
.Sh ERRORS
|
|
A
|
|
.Tn vsock
|
|
socket operation may fail with a general socket error or one of the following
|
|
.Tn vsock
|
|
specific errors:
|
|
.Bl -tag -width ".It Bq Er EADDRNOTAVAIL"
|
|
.It Bq Er EACCES
|
|
returned by
|
|
.Xr bind 2
|
|
when attempting to bind to a privileged port;
|
|
.It Bq Er EADDRINUSE
|
|
returned by
|
|
.Xr bind 2
|
|
when attempting to bind to a cid and port that is already in use;
|
|
.It Bq Er EADDRNOTAVAIL
|
|
returned by
|
|
.Xr bind 2
|
|
when attempting to bind to an invalid cid or port;
|
|
.It Bq Er EFAULT
|
|
returned by
|
|
.Xr connect 2
|
|
when attempting to connect to an invalid cid;
|
|
.It Bq Er EINPROGRESS
|
|
returned by
|
|
.Xr connect 2
|
|
when attempting to connect using a non-blocking socket;
|
|
.It Bq Er EINVAL
|
|
when passing an invalid parameter;
|
|
.It Bq Er ENODEV
|
|
when a vsock transport does not exist;
|
|
.It Bq Er ENOTCONN
|
|
when performing an operation on a non-connected socket;
|
|
.It Bq Er ETIMEDOUT
|
|
returned by
|
|
.Xr connect 2
|
|
when a connection attempt has timed out;
|
|
.It Bq Er EWOULDBLOCK
|
|
returned by
|
|
.Xr send 2
|
|
or
|
|
.Xr recv 2
|
|
when sending or receiving using a non-blocking socket.
|
|
.El
|
|
.Sh IOCTLS
|
|
The
|
|
.Xr ioctl 2
|
|
command codes below are defined in
|
|
.Aq Pa sys/vsock.h .
|
|
All commands require
|
|
these includes:
|
|
.Bd -literal
|
|
#include <sys/ioctl.h>
|
|
#include <sys/vsock.h>
|
|
.Ed
|
|
.Pp
|
|
The third argument to
|
|
.Xr ioctl 2
|
|
should be a pointer to the type indicated in parenthesis.
|
|
.Bl -tag -width IOCTL_VM_SOCKETS_GET_LOCAL_CID
|
|
.It Dv IOCTL_VM_SOCKETS_GET_LOCAL_CID
|
|
.Pq Li uint32_t
|
|
Returns the local cid of this socket's transport.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr bind 2 ,
|
|
.Xr connect 2 ,
|
|
.Xr ioctl 2 ,
|
|
.Xr kqueue 2 ,
|
|
.Xr poll 2 ,
|
|
.Xr select 2 ,
|
|
.Xr socket 2
|