Merging upstream version 6.8.

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

1 files changed, 493 insertions, 0 deletions

diff --git a/man/man2/socket.2 b/man/man2/socket.2
new file mode 100644
index 0000000..cf41c2f
--- /dev/null
+++ b/man/man2/socket.2
@@ -0,0 +1,493 @@
+'\" t
+.\" Copyright (c) 1983, 1991 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"     $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $
+.\"
+.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1998, 1999 by Andi Kleen <ak@muc.de>
+.\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH socket 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+socket \- create an endpoint for communication
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.P
+.BI "int socket(int " domain ", int " type ", int " protocol );
+.fi
+.SH DESCRIPTION
+.BR socket ()
+creates an endpoint for communication and returns a file descriptor
+that refers to that endpoint.
+The file descriptor returned by a successful call will be
+the lowest-numbered file descriptor not currently open for the process.
+.P
+The
+.I domain
+argument specifies a communication domain; this selects the protocol
+family which will be used for communication.
+These families are defined in
+.IR <sys/socket.h> .
+The formats currently understood by the Linux kernel include:
+.TS
+tab(:);
+l1 lw40 l.
+Name:Purpose:Man page
+T{
+.B AF_UNIX
+T}:T{
+Local communication
+T}:T{
+.BR unix (7)
+T}
+T{
+.B AF_LOCAL
+T}:T{
+Synonym for
+.B AF_UNIX
+T}:T{
+T}
+T{
+.B AF_INET
+T}:IPv4 Internet protocols:T{
+.BR ip (7)
+T}
+T{
+.B AF_AX25
+T}:T{
+Amateur radio AX.25 protocol
+T}:T{
+.\" Part of ax25-tools
+.BR ax25 (4)
+T}
+T{
+.B AF_IPX
+T}:IPX \- Novell protocols:
+T{
+.B AF_APPLETALK
+T}:AppleTalk:T{
+.BR ddp (7)
+T}
+T{
+.B AF_X25
+T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{
+.BR x25 (7)
+T}
+T{
+.B AF_INET6
+T}:IPv6 Internet protocols:T{
+.BR ipv6 (7)
+T}
+T{
+.B AF_DECnet
+T}:T{
+DECet protocol sockets
+T}
+T{
+.B AF_KEY
+T}:T{
+Key management protocol, originally developed for usage with IPsec
+T}
+T{
+.B AF_NETLINK
+T}:T{
+Kernel user interface device
+T}:T{
+.BR netlink (7)
+T}
+T{
+.B AF_PACKET
+T}:T{
+Low-level packet interface
+T}:T{
+.BR packet (7)
+T}
+T{
+.B AF_RDS
+T}:T{
+.\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4
+Reliable Datagram Sockets (RDS) protocol
+T}:T{
+.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7
+.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7
+.BR rds (7)
+.br
+.BR rds\-rdma (7)
+T}
+T{
+.B AF_PPPOX
+T}:T{
+Generic PPP transport layer, for setting up L2 tunnels
+(L2TP and PPPoE)
+T}
+T{
+.B AF_LLC
+T}:T{
+.\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa
+Logical link control (IEEE 802.2 LLC) protocol
+T}
+T{
+.B AF_IB
+T}:T{
+.\" commits: 8d36eb01da5d371f..ce117ffac2e93334
+InfiniBand native addressing
+T}
+T{
+.B AF_MPLS
+T}:T{
+.\" commits: 0189197f441602acdca3f97750d392a895b778fd
+Multiprotocol Label Switching
+T}
+T{
+.B AF_CAN
+T}:T{
+.\" commits: 8dbde28d9711475a..5423dd67bd0108a1
+Controller Area Network automotive bus protocol
+T}
+T{
+.B AF_TIPC
+T}:T{
+.\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4
+TIPC, "cluster domain sockets" protocol
+T}
+T{
+.B AF_BLUETOOTH
+T}:T{
+.\" commits: 8d36eb01da5d371f..ce117ffac2e93334
+Bluetooth low-level socket protocol
+T}
+T{
+.B AF_ALG
+T}:T{
+.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
+Interface to kernel crypto API
+T}
+T{
+.B AF_VSOCK
+T}:T{
+.\" commit: d021c344051af91f42c5ba9fdedc176740cbd238
+VSOCK (originally "VMWare VSockets") protocol
+for hypervisor-guest communication
+T}:T{
+.BR vsock (7)
+T}
+T{
+.B AF_KCM
+T}:T{
+.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
+KCM (kernel connection multiplexer) interface
+T}
+T{
+.B AF_XDP
+T}:T{
+.\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7
+XDP (express data path) interface
+T}
+.TE
+.P
+Further details of the above address families,
+as well as information on several other address families, can be found in
+.BR address_families (7).
+.P
+The socket has the indicated
+.IR type ,
+which specifies the communication semantics.
+Currently defined types
+are:
+.TP 16
+.B SOCK_STREAM
+Provides sequenced, reliable, two-way, connection-based byte streams.
+An out-of-band data transmission mechanism may be supported.
+.TP
+.B SOCK_DGRAM
+Supports datagrams (connectionless, unreliable messages of a fixed
+maximum length).
+.TP
+.B SOCK_SEQPACKET
+Provides a sequenced, reliable, two-way connection-based data
+transmission path for datagrams of fixed maximum length; a consumer is
+required to read an entire packet with each input system call.
+.TP
+.B SOCK_RAW
+Provides raw network protocol access.
+.TP
+.B SOCK_RDM
+Provides a reliable datagram layer that does not guarantee ordering.
+.TP
+.B SOCK_PACKET
+Obsolete and should not be used in new programs;
+see
+.BR packet (7).
+.P
+Some socket types may not be implemented by all protocol families.
+.P
+Since Linux 2.6.27, the
+.I type
+argument serves a second purpose:
+in addition to specifying a socket type,
+it may include the bitwise OR of any of the following values,
+to modify the behavior of
+.BR socket ():
+.TP 16
+.B SOCK_NONBLOCK
+Set the
+.B O_NONBLOCK
+file status flag on the open file description (see
+.BR open (2))
+referred to by the new file descriptor.
+Using this flag saves extra calls to
+.BR fcntl (2)
+to achieve the same result.
+.TP
+.B SOCK_CLOEXEC
+Set the close-on-exec
+.RB ( FD_CLOEXEC )
+flag on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.P
+The
+.I protocol
+specifies a particular protocol to be used with the socket.
+Normally only a single protocol exists to support a particular
+socket type within a given protocol family, in which case
+.I protocol
+can be specified as 0.
+However, it is possible that many protocols may exist, in
+which case a particular protocol must be specified in this manner.
+The protocol number to use is specific to the \*(lqcommunication domain\*(rq
+in which communication is to take place; see
+.BR protocols (5).
+See
+.BR getprotoent (3)
+on how to map protocol name strings to protocol numbers.
+.P
+Sockets of type
+.B SOCK_STREAM
+are full-duplex byte streams.
+They do not preserve
+record boundaries.
+A stream socket must be in
+a
+.I connected
+state before any data may be sent or received on it.
+A connection to
+another socket is created with a
+.BR connect (2)
+call.
+Once connected, data may be transferred using
+.BR read (2)
+and
+.BR write (2)
+calls or some variant of the
+.BR send (2)
+and
+.BR recv (2)
+calls.
+When a session has been completed a
+.BR close (2)
+may be performed.
+Out-of-band data may also be transmitted as described in
+.BR send (2)
+and received as described in
+.BR recv (2).
+.P
+The communications protocols which implement a
+.B SOCK_STREAM
+ensure that data is not lost or duplicated.
+If a piece of data for which
+the peer protocol has buffer space cannot be successfully transmitted
+within a reasonable length of time, then the connection is considered
+to be dead.
+When
+.B SO_KEEPALIVE
+is enabled on the socket the protocol checks in a protocol-specific
+manner if the other end is still alive.
+A
+.B SIGPIPE
+signal is raised if a process sends or receives
+on a broken stream; this causes naive processes,
+which do not handle the signal, to exit.
+.B SOCK_SEQPACKET
+sockets employ the same system calls as
+.B SOCK_STREAM
+sockets.
+The only difference is that
+.BR read (2)
+calls will return only the amount of data requested,
+and any data remaining in the arriving packet will be discarded.
+Also all message boundaries in incoming datagrams are preserved.
+.P
+.B SOCK_DGRAM
+and
+.B SOCK_RAW
+sockets allow sending of datagrams to correspondents named in
+.BR sendto (2)
+calls.
+Datagrams are generally received with
+.BR recvfrom (2),
+which returns the next datagram along with the address of its sender.
+.P
+.B SOCK_PACKET
+is an obsolete socket type to receive raw packets directly from the
+device driver.
+Use
+.BR packet (7)
+instead.
+.P
+An
+.BR fcntl (2)
+.B F_SETOWN
+operation can be used to specify a process or process group to receive a
+.B SIGURG
+signal when the out-of-band data arrives or
+.B SIGPIPE
+signal when a
+.B SOCK_STREAM
+connection breaks unexpectedly.
+This operation may also be used to set the process or process group
+that receives the I/O and asynchronous notification of I/O events via
+.BR SIGIO .
+Using
+.B F_SETOWN
+is equivalent to an
+.BR ioctl (2)
+call with the
+.B FIOSETOWN
+or
+.B SIOCSPGRP
+argument.
+.P
+When the network signals an error condition to the protocol module (e.g.,
+using an ICMP message for IP) the pending error flag is set for the socket.
+The next operation on this socket will return the error code of the pending
+error.
+For some protocols it is possible to enable a per-socket error queue
+to retrieve detailed information about the error; see
+.B IP_RECVERR
+in
+.BR ip (7).
+.P
+The operation of sockets is controlled by socket level
+.IR options .
+These options are defined in
+.IR <sys/socket.h> .
+The functions
+.BR setsockopt (2)
+and
+.BR getsockopt (2)
+are used to set and get options.
+.SH RETURN VALUE
+On success, a file descriptor for the new socket is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+Permission to create a socket of the specified type and/or protocol
+is denied.
+.TP
+.B EAFNOSUPPORT
+The implementation does not support the specified address family.
+.TP
+.B EINVAL
+Unknown protocol, or protocol family not available.
+.TP
+.B EINVAL
+.\" Since Linux 2.6.27
+Invalid flags in
+.IR type .
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been reached.
+.TP
+.BR ENOBUFS " or " ENOMEM
+Insufficient memory is available.
+The socket cannot be
+created until sufficient resources are freed.
+.TP
+.B EPROTONOSUPPORT
+The protocol type or the specified protocol is not
+supported within this domain.
+.P
+Other errors may be generated by the underlying protocol modules.
+.SH STANDARDS
+POSIX.1-2008.
+.P
+.B SOCK_NONBLOCK
+and
+.B SOCK_CLOEXEC
+are Linux-specific.
+.SH HISTORY
+POSIX.1-2001, 4.4BSD.
+.P
+.BR socket ()
+appeared in 4.2BSD.
+It is generally portable to/from
+non-BSD systems supporting clones of the BSD socket layer (including
+System\ V variants).
+.P
+The manifest constants used under 4.x BSD for protocol families
+are
+.BR PF_UNIX ,
+.BR PF_INET ,
+and so on, while
+.BR AF_UNIX ,
+.BR AF_INET ,
+and so on are used for address
+families.
+However, already the BSD man page promises: "The protocol
+family generally is the same as the address family", and subsequent
+standards use AF_* everywhere.
+.SH EXAMPLES
+An example of the use of
+.BR socket ()
+is shown in
+.BR getaddrinfo (3).
+.SH SEE ALSO
+.BR accept (2),
+.BR bind (2),
+.BR close (2),
+.BR connect (2),
+.BR fcntl (2),
+.BR getpeername (2),
+.BR getsockname (2),
+.BR getsockopt (2),
+.BR ioctl (2),
+.BR listen (2),
+.BR read (2),
+.BR recv (2),
+.BR select (2),
+.BR send (2),
+.BR shutdown (2),
+.BR socketpair (2),
+.BR write (2),
+.BR getprotoent (3),
+.BR address_families (7),
+.BR ip (7),
+.BR socket (7),
+.BR tcp (7),
+.BR udp (7),
+.BR unix (7)
+.P
+\[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq]
+and
+\[lq]BSD Interprocess Communication Tutorial\[rq],
+reprinted in
+.I UNIX Programmer's Supplementary Documents Volume 1.