Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 232 insertions, 0 deletions

diff --git a/man/man7/vsock.7 b/man/man7/vsock.7
new file mode 100644
index 0000000..015e9db
--- /dev/null
+++ b/man/man7/vsock.7
@@ -0,0 +1,232 @@
+.\" Copyright (C) 2018, Stefan Hajnoczi <stefanha@redhat.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH vsock 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+vsock \- Linux VSOCK address family
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.B #include <linux/vm_sockets.h>
+.P
+.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
+.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
+.fi
+.SH DESCRIPTION
+The VSOCK address family facilitates communication between virtual machines and
+the host they are running on.
+This address family is used by guest agents and
+hypervisor services that need a communications channel that is independent of
+virtual machine network configuration.
+.P
+Valid socket types are
+.B SOCK_STREAM
+and
+.BR SOCK_DGRAM .
+.B SOCK_STREAM
+provides connection-oriented byte streams with guaranteed, in-order delivery.
+.B SOCK_DGRAM
+provides a connectionless datagram packet service with best-effort delivery and
+best-effort ordering.
+Availability of these socket types is dependent on the
+underlying hypervisor.
+.P
+A new socket is created with
+.P
+.in +4n
+.EX
+socket(AF_VSOCK, socket_type, 0);
+.EE
+.in
+.P
+When a process wants to establish a connection, it calls
+.BR connect (2)
+with a given destination socket address.
+The socket is automatically bound to a free port if unbound.
+.P
+A process can listen for incoming connections by first binding to a socket
+address using
+.BR bind (2)
+and then calling
+.BR listen (2).
+.P
+Data is transmitted using the
+.BR send (2)
+or
+.BR write (2)
+families of system calls and data is received using the
+.BR recv (2)
+or
+.BR read (2)
+families of system calls.
+.SS Address format
+A socket address is defined as a combination of a 32-bit Context Identifier
+(CID) and a 32-bit port number.
+The CID identifies the source or destination,
+which is either a virtual machine or the host.
+The port number differentiates between multiple services running on
+a single machine.
+.P
+.in +4n
+.EX
+struct sockaddr_vm {
+    sa_family_t    svm_family;    /* Address family: AF_VSOCK */
+    unsigned short svm_reserved1;
+    unsigned int   svm_port;      /* Port # in host byte order */
+    unsigned int   svm_cid;       /* Address in host byte order */
+    unsigned char  svm_zero[sizeof(struct sockaddr) \-
+                            sizeof(sa_family_t) \-
+                            sizeof(unsigned short) \-
+                            sizeof(unsigned int) \-
+                            sizeof(unsigned int)];
+};
+.EE
+.in
+.P
+.I svm_family
+is always set to
+.BR AF_VSOCK .
+.I svm_reserved1
+is always set to 0.
+.I svm_port
+contains the port number in host byte order.
+The port numbers below 1024 are called
+.IR "privileged ports" .
+Only a process with the
+.B CAP_NET_BIND_SERVICE
+capability may
+.BR bind (2)
+to these port numbers.
+.I svm_zero
+must be zero-filled.
+.P
+There are several special addresses:
+.B VMADDR_CID_ANY
+(\-1U)
+means any address for binding;
+.B VMADDR_CID_HYPERVISOR
+(0) is reserved for services built into the hypervisor;
+.B VMADDR_CID_LOCAL
+(1) is the well-known address for local communication (loopback);
+.B VMADDR_CID_HOST
+(2)
+is the well-known address of the host.
+.P
+The special constant
+.B VMADDR_PORT_ANY
+(\-1U)
+means any port number for binding.
+.SS Live migration
+Sockets are affected by live migration of virtual machines.
+Connected
+.B SOCK_STREAM
+sockets become disconnected when the virtual machine migrates to a new host.
+Applications must reconnect when this happens.
+.P
+The local CID may change across live migration if the old CID is
+not available on the new host.
+Bound sockets are automatically updated to the new CID.
+.SS Ioctls
+The following ioctls are available on the
+.I /dev/vsock
+device.
+.TP
+.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
+Get the CID of the local machine.
+The argument is a pointer to an
+.IR "unsigned int" .
+.IP
+.in +4n
+.EX
+ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);
+.EE
+.in
+.IP
+Consider using
+.B VMADDR_CID_ANY
+when binding instead of getting the local CID with
+.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID .
+.SS Local communication
+.B VMADDR_CID_LOCAL
+(1) directs packets to the same host that generated them.
+This is useful
+for testing applications on a single host and for debugging.
+.P
+The local CID obtained with
+.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
+can be used for the same purpose, but it is preferable to use
+.BR VMADDR_CID_LOCAL .
+.SH ERRORS
+.TP
+.B EACCES
+Unable to bind to a privileged port without the
+.B CAP_NET_BIND_SERVICE
+capability.
+.TP
+.B EADDRINUSE
+Unable to bind to a port that is already in use.
+.TP
+.B EADDRNOTAVAIL
+Unable to find a free port for binding or unable to bind to a nonlocal CID.
+.TP
+.B EINVAL
+Invalid parameters.
+This includes:
+attempting to bind a socket that is already bound, providing an invalid struct
+.IR sockaddr_vm ,
+and other input validation errors.
+.TP
+.B ENOPROTOOPT
+Invalid socket option in
+.BR setsockopt (2)
+or
+.BR getsockopt (2).
+.TP
+.B ENOTCONN
+Unable to perform operation on an unconnected socket.
+.TP
+.B EOPNOTSUPP
+Operation not supported.
+This includes:
+the
+.B MSG_OOB
+flag that is not implemented for the
+.BR send (2)
+family of syscalls and
+.B MSG_PEEK
+for the
+.BR recv (2)
+family of syscalls.
+.TP
+.B EPROTONOSUPPORT
+Invalid socket protocol number.
+The protocol should always be 0.
+.TP
+.B ESOCKTNOSUPPORT
+Unsupported socket type in
+.BR socket (2).
+Only
+.B SOCK_STREAM
+and
+.B SOCK_DGRAM
+are valid.
+.SH VERSIONS
+Support for VMware (VMCI) has been available since Linux 3.9.
+KVM (virtio) is supported since Linux 4.8.
+Hyper-V is supported since Linux 4.14.
+.P
+.B VMADDR_CID_LOCAL
+is supported since Linux 5.6.
+.\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe
+Local communication in the guest and on the host is available since Linux 5.6.
+Previous versions supported only local communication within a guest
+(not on the host), and with only some transports (VMCI and virtio).
+.SH SEE ALSO
+.BR bind (2),
+.BR connect (2),
+.BR listen (2),
+.BR recv (2),
+.BR send (2),
+.BR socket (2),
+.BR capabilities (7)