SOCKET(2)                 (2020-06-09)                  SOCKET(2)

     NAME
          socket - create an endpoint for communication

     SYNOPSIS
          #include <sys/types.h>          /* See NOTES */
          #include <sys/socket.h>

          int socket(int domain, int type, int protocol

     DESCRIPTION
          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.

          The domain argument specifies a communication domain; this
          selects the protocol family which will be used for communi-
          cation.  These families are defined in <sys/socket.h>. The
          formats currently understood by the Linux kernel include:
          tab(:); l1 lw40 l.  Name:Purpose:Man page T{ AF_UNIX T}:T{
          Local communication T}:T{ unix(7) T} T{ AF_LOCAL T}:T{ Syn-
          onym for AF_UNIX T}:T{ T} T{ AF_INET T}:IPv4 Internet
          protocols:T{ ip(7) T} T{ AF_AX25 T}:T{ Amateur radio AX.25
          protocol T}:T{ ax25(4) T} T{ AF_IPX T}:IPX - Novell proto-
          cols: T{ AF_APPLETALK T}:AppleTalk:T{ ddp(7) T} T{ AF_X25
          T}:ITU-T X.25 / ISO-8208 protocol:T{ x25(7) T} T{ AF_INET6
          T}:IPv6 Internet protocols:T{ ipv6(7) T} T{ AF_DECnet T}:T{
          DECet protocol sockets T} T{ AF_KEY T}:T{ Key management
          protocol, originally developed for usage with IPsec T} T{
          AF_NETLINK T}:T{ Kernel user interface device T}:T{
          netlink(7) T} T{ AF_PACKET T}:T{ Low-level packet interface
          T}:T{ packet(7) T} T{ AF_RDS T}:T{ Reliable Datagram Sockets
          (RDS) protocol T}:T{ rds(7)
          rds-rdma(7) T} T{ AF_PPPOX T}:T{ Generic PPP transport
          layer, for setting up L2 tunnels (L2TP and PPPoE) T} T{
          AF_LLC T}:T{ Logical link control (IEEE 802.2 LLC) protocol
          T} T{ AF_IB T}:T{ InfiniBand native addressing T} T{ AF_MPLS
          T}:T{ Multiprotocol Label Switching T} T{ AF_CAN T}:T{ Con-
          troller Area Network automotive bus protocol T} T{ AF_TIPC
          T}:T{ TIPC, "cluster domain sockets" protocol T} T{
          AF_BLUETOOTH T}:T{ Bluetooth low-level socket protocol T} T{
          AF_ALG T}:T{ Interface to kernel crypto API T} T{ AF_VSOCK
          T}:T{ VSOCK (originally "VMWare VSockets") protocol for
          hypervisor-guest communication T}:T{ vsock(7) T} T{ AF_KCM
          T}:T{ KCM (kernel connection multiplexer) interface T} T{
          AF_XDP T}:T{ XDP (express data path) interface T}

          Further details of the above address families, as well as
          information on several other address families, can be found

     Page 1                        Linux             (printed 5/24/22)

     SOCKET(2)                 (2020-06-09)                  SOCKET(2)

          in address_families(7).

          The socket has the indicated type, which specifies the com-
          munication semantics.  Currently defined types are:

          SOCK_STREAM     Provides sequenced, reliable, two-way,
                          connection-based byte streams.  An out-of-
                          band data transmission mechanism may be sup-
                          ported.

          SOCK_DGRAM      Supports datagrams (connectionless, unreli-
                          able messages of a fixed maximum length).

          SOCK_SEQPACKET  Provides a sequenced, reliable, two-way
                          connection-based data transmission path for
                          datagrams of fixed maximum length; a con-
                          sumer is required to read an entire packet
                          with each input system call.

          SOCK_RAW        Provides raw network protocol access.

          SOCK_RDM        Provides a reliable datagram layer that does
                          not guarantee ordering.

          SOCK_PACKET     Obsolete and should not be used in new pro-
                          grams; see packet(7).

          Some socket types may not be implemented by all protocol
          families.

          Since Linux 2.6.27, the type argument serves a second pur-
          pose: in addition to specifying a socket type, it may
          include the bitwise OR of any of the following values, to
          modify the behavior of socket():

          SOCK_NONBLOCK   Set the O_NONBLOCK file status flag on the
                          open file description (see open(2)) referred
                          to by the new file descriptor.  Using this
                          flag saves extra calls to fcntl(2) to
                          achieve the same result.

          SOCK_CLOEXEC    Set the close-on-exec (FD_CLOEXEC) flag on
                          the new file descriptor.  See the descrip-
                          tion of the O_CLOEXEC flag in open(2) for
                          reasons why this may be useful.

          The protocol specifies a particular protocol to be used with
          the socket.  Normally only a single protocol exists to sup-
          port a particular socket type within a given protocol fam-
          ily, in which case 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

     Page 2                        Linux             (printed 5/24/22)

     SOCKET(2)                 (2020-06-09)                  SOCKET(2)

          protocol number to use is specific to the communication
          domain in which communication is to take place; see
          protocols(5).  See getprotoent(3) on how to map protocol
          name strings to protocol numbers.

          Sockets of type SOCK_STREAM are full-duplex byte streams.
          They do not preserve record boundaries.  A stream socket
          must be in a connected state before any data may be sent or
          received on it.  A connection to another socket is created
          with a connect(2) call.  Once connected, data may be trans-
          ferred using read(2) and write(2) calls or some variant of
          the send(2) and recv(2) calls.  When a session has been com-
          pleted a close(2) may be performed.  Out-of-band data may
          also be transmitted as described in send(2) and received as
          described in recv(2).

          The communications protocols which implement a 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
          SO_KEEPALIVE is enabled on the socket the protocol checks in
          a protocol-specific manner if the other end is still alive.
          A 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.  SOCK_SEQPACKET sockets employ
          the same system calls as SOCK_STREAM sockets.  The only dif-
          ference is that 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.

          SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams
          to correspondents named in sendto(2) calls.  Datagrams are
          generally received with recvfrom(2), which returns the next
          datagram along with the address of its sender.

          SOCK_PACKET is an obsolete socket type to receive raw pack-
          ets directly from the device driver.  Use packet(7) instead.

          An fcntl(2) F_SETOWN operation can be used to specify a pro-
          cess or process group to receive a SIGURG signal when the
          out-of-band data arrives or SIGPIPE signal when a
          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 SIGIO.  Using F_SETOWN is equivalent to an ioctl(2) call
          with the FIOSETOWN or SIOCSPGRP argument.

          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

     Page 3                        Linux             (printed 5/24/22)

     SOCKET(2)                 (2020-06-09)                  SOCKET(2)

          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 IP_RECVERR in ip(7).

          The operation of sockets is controlled by socket level
          options. These options are defined in <sys/socket.h>. The
          functions setsockopt(2) and getsockopt(2) are used to set
          and get options.

     RETURN VALUE
          On success, a file descriptor for the new socket is
          returned.  On error, -1 is returned, and errno is set appro-
          priately.

     ERRORS
          EACCES
               Permission to create a socket of the specified type
               and/or protocol is denied.

          EAFNOSUPPORT
               The implementation does not support the specified
               address family.

          EINVAL
               Unknown protocol, or protocol family not available.

          EINVAL
               Invalid flags in type.

          EMFILE
               The per-process limit on the number of open file
               descriptors has been reached.

          ENFILE
               The system-wide limit on the total number of open files
               has been reached.

          ENOBUFS or ENOMEM
               Insufficient memory is available.  The socket cannot be
               created until sufficient resources are freed.

          EPROTONOSUPPORT
               The protocol type or the specified protocol is not sup-
               ported within this domain.

          Other errors may be generated by the underlying protocol
          modules.

     CONFORMING TO
          POSIX.1-2001, POSIX.1-2008, 4.4BSD.

     Page 4                        Linux             (printed 5/24/22)

     SOCKET(2)                 (2020-06-09)                  SOCKET(2)

          The SOCK_NONBLOCK and SOCK_CLOEXEC flags are Linux-specific.

          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).

     NOTES
          POSIX.1 does not require the inclusion of <sys/types.h>, and
          this header file is not required on Linux.  However, some
          historical (BSD) implementations required this header file,
          and portable applications are probably wise to include it.

          The manifest constants used under 4.x BSD for protocol fami-
          lies are PF_UNIX, PF_INET, and so on, while AF_UNIX,
          AF_INET, and so on are used for address families.  However,
          already the BSD man page promises: "The protocol family gen-
          erally is the same as the address family", and subsequent
          standards use AF_* everywhere.

     EXAMPLES
          An example of the use of socket() is shown in
          getaddrinfo(3).

     SEE ALSO
          accept(2), bind(2), close(2), connect(2), fcntl(2),
          getpeername(2), getsockname(2), getsockopt(2), ioctl(2),
          listen(2), read(2), recv(2), select(2), send(2),
          shutdown(2), socketpair(2), write(2), getprotoent(3),
          address_families(7), ip(7), socket(7), tcp(7), udp(7),
          unix(7)

          lqAn Introductory 4.3BSD Interprocess Communication Tutorialrq
          and lqBSD Interprocess Communication Tutorialrq, reprinted in
          UNIX Programmer's Supplementary Documents Volume 1.

     COLOPHON
          This page is part of release 5.10 of the Linux man-pages
          project.  A description of the project, information about
          reporting bugs, and the latest version of this page, can be
          found at https://www.kernel.org/doc/man-pages/.

     Page 5                        Linux             (printed 5/24/22)