socket(2)                                                     socket(2)

  socket()

  NAME

    socket() - create an endpoint for communication

  SYNOPSIS

    #include 
    #include 

    int socket (int protofamily, int type, int protocol)

  DESCRIPTION

    The socket(2) function creates an endpoint for communication and returns a
    descriptor.

    The protofamily parameter specifies a communications protofamily within
    which communication will take place; this selects the protocol family
    which should be used. These families are defined in the include file . Currently, the sockets understand only two formats:

    AF_INET
        ARPA Internet protocols

    AF_UNIX
        UNIX internal protocols

    The socket has the indicated type, which specifies the semantics of
    communication. Currently defined types are:

    SOCK_STREAM
    SOCK_DGRAM
    SOCK_RAW
    SOCK_SEQPACKET

    *     A SOCK_STREAM type provides sequenced, reliable, two-way connection
          based byte streams. An out-of-band data transmission mechanism can
          be supported. The AF_UNIX format supports SOCK_STREAM only.
    *     A SOCK_DGRAM socket supports datagrams (connectionless, unreliable
          messages of a fixed (typically small) maximum length).
    *     A SOCK_SEQPACKET socket can provide a sequenced, reliable, two-way
          connection-based data transmission path for datagrams of fixed
          maximum length; a consumer might be required to read an entire
          packet with each read system call. This facility is protocol
          specific, and presently implemented only for PF_NS.
    *     SOCK_RAW sockets provide access to internal network protocols and
          interfaces. They are not described here.

    The 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. However, it is possible that many
    protocols exist, in which case a particular protocol must be specified in
    this manner. Since only AF_INET protocols are supported in this
    implementation and because sockets of type SOCK_STREAM and SOCK_DGRAM only
    support one protocol each, use the value 0 for the protocol.

    Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
    pipes. A stream socket must be in a connected state before any data can be
    sent or received on it. A connection to another socket is created with a
    connect(2) call. Once connected, data can be transferred using read(2) and
    write(2) calls or some variant of the send(2) and recv(2) calls. When a
    session has been completed a close(2) can be performed. Out-of-band data
    can also be transmitted as described in send(2) and received as described
    in recv(2).

    The communications protocols used to implement a SOCK_STREAM insure 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 broken and
    calls will indicate an error with -1 returns and with [ETIMEDOUT] as the
    specific code in the global variable errno The protocols optionally keep
    sockets warm by forcing transmissions roughly every minute in the absence
    of other activity. An error is then indicated if no response can be
    elicited on an otherwise idle connection for a extended period (such as
    five minutes). A SIGPIPE signal is raised if a process sends 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 difference is that read(2) calls will return only the
    amount of data requested, and any remaining in the arriving packet will be
    discarded.

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

    An fcntl(2) call can be used to specify a process group to receive a
    SIGURG signal when the out-of-band data arrives. It might also enable non-
    blocking I/O and asynchronous notification of I/O events through SIGIO.

    The operation of sockets is controlled by socket level options These
    options are defined in the file . The setsockopt(2) and
    getsockopt(2) functions are used to set and get options, respectively.

  RETURN VALUES

    The function returns a descriptor referencing the socket; if the function
    fails, it returns -1 and sets errno to indicate the error.

  ERRORS

    The socket(2) call fails if:

    [EPROTONOSUPPORT]
        The protocol type or the specified protocol is not supported within
        this protofamily.

    [EMFILE]
        The per-process descriptor table is full.

    [ENFILE]
        The system file table is full.

    [EACCESS]
        Permission to create a socket of the specified type and/or protocol is
        denied.

    [ENOBUFS]
        Insufficient buffer space is available. The socket cannot be created
        until sufficient resources are freed.

  SEE ALSO

    accept(2)

    bind(2)

    connect(2)

    getsockname(2)

    getsockopt(2)

    listen(2)

    read(2)

    recv(2)

    select(2)

    send(2)

    write(2)

  USAGE NOTES

    The socket function is thread safe.

    The socket function is async-signal safe.