1 SOCKET(3C) Standard C Library Functions SOCKET(3C) 2 3 NAME 4 socket - create an endpoint for communication 5 6 LIBRARY 7 Standard C Library (libc, -lc) 8 9 SYNOPSIS 10 #include <sys/types.h> 11 #include <sys/socket.h> 12 13 int 14 socket(int domain, int type, int protocol); 15 16 DESCRIPTION 17 The socket() function creates an endpoint for communication and returns a 18 descriptor. 19 20 The domain argument specifies the protocol family within which 21 communication takes place. The protocol family is generally the same as 22 the address family for the addresses supplied in later operations on the 23 socket. These families are defined in <sys/socket.h>. 24 25 The currently supported protocol families are: 26 27 PF_UNIX UNIX system internal protocols 28 29 PF_INET Internet Protocol Version 4 (IPv4) 30 31 PF_INET6 Internet Protocol Version 6 (IPv6) 32 33 PF_NCA Network Cache and Accelerator (NCA) protocols 34 35 The socket has the indicated type, which specifies the communication 36 semantics. Currently defined types are: 37 38 SOCK_STREAM 39 40 SOCK_DGRAM 41 42 SOCK_RAW 43 44 SOCK_SEQPACKET 45 46 SOCK_RDM 47 48 The type may be augmented by a bitwise-inclusive-OR of flags from the 49 following list, defined in <sys/socket.h>: 50 51 SOCK_CLOEXEC 52 Creates the socket with the FD_CLOEXEC flag set, causing the 53 underlying file descriptor to be closed prior to any future calls 54 to exec(2). This is similar in purpose to the O_CLOEXEC flag to 55 open(2). 56 57 SOCK_NDELAY 58 Creates the socket with the O_NDELAY flag set, causing the socket 59 to provide nonblocking semantics as described for O_NDELAY in 60 open(2). SOCK_NONBLOCK should normally be used in preference to 61 SOCK_NDELAY, and takes precedence if both are set. See open(2) 62 for further details. 63 64 SOCK_NONBLOCK 65 Creates the socket with the O_NONBLOCK flag set, causing the 66 socket to provide nonblocking semantics as described for 67 O_NONBLOCK in open(2). 68 69 There must be an entry in the netconfig(4) file for at least each 70 protocol family and type required. If a non-zero protocol has been 71 specified but no exact match for the protocol family, type, and protocol 72 is found, then the first entry containing the specified family and type 73 with a protocol value of zero will be used. 74 75 A SOCK_STREAM type provides sequenced, reliable, two-way connection-based 76 byte streams. An out-of-band data transmission mechanism may be 77 supported. A SOCK_DGRAM socket supports datagrams (connectionless, 78 unreliable messages of a fixed (typically small) maximum length). A 79 SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way 80 connection-based data transmission path for datagrams of fixed maximum 81 length; a consumer may be required to read an entire packet with each 82 read system call. This facility is protocol specific, and presently not 83 implemented for any protocol family. SOCK_RAW sockets provide access to 84 internal network interfaces. The types SOCK_RAW, which is available only 85 to a user with the net_rawaccess privilege, and SOCK_RDM, for which no 86 implementation currently exists, are not described here. 87 88 The protocol parameter is a protocol-family-specific value which 89 specifies a particular protocol to be used with the socket. Normally 90 this value is zero, as commonly only a single protocol exists to support 91 a particular socket type within a given protocol family. However, 92 multiple protocols may exist, in which case a particular protocol may be 93 specified in this manner. 94 95 Sockets of type SOCK_STREAM are full-duplex byte streams, similar to 96 pipes. A stream socket must be in a "connected" state before any data 97 may be sent or received on it. A connection to another socket is created 98 with a connect(3C) call. Once connected, data may be transferred using 99 read(2) and write(2) calls or some variant of the send(3C) and recv(3C) 100 calls. When a session has been completed, a close(2) may be performed. 101 Out-of-band data may also be transmitted as described on the send(3C) 102 manual page and received as described on the recv(3C) manual page. 103 104 The communications protocols used to implement a SOCK_STREAM insure that 105 data is not lost or duplicated. If a piece of data for which the peer 106 protocol has buffer space cannot be successfully transmitted within a 107 reasonable length of time, then the connection is considered broken and 108 calls will indicate an error with -1 returns and with ETIMEDOUT as the 109 specific code in the global variable errno. The protocols optionally 110 keep sockets "warm" by forcing transmissions roughly every minute in the 111 absence of other activity. An error is then indicated if no response can 112 be elicited on an otherwise idle connection for a extended period (for 113 instance 5 minutes). A SIGPIPE signal is raised if a thread sends on a 114 broken stream; this causes naive processes, which do not handle the 115 signal, to exit. 116 117 SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM 118 sockets. The only difference is that read(2) calls will return only the 119 amount of data requested, and any remaining in the arriving packet will 120 be discarded. 121 122 SOCK_DGRAM and SOCK_RAW sockets allow datagrams to be sent to 123 correspondents named in sendto(3C) calls. Datagrams are generally 124 received with recvfrom(3C), which returns the next datagram with its 125 return address. 126 127 An fcntl(2) call can be used to specify a process group to receive a 128 SIGURG signal when the out-of-band data arrives. It can also enable non- 129 blocking I/O. 130 131 The operation of sockets is controlled by socket level options. These 132 options are defined in the file <sys/socket.h>. setsockopt(3C) and 133 getsockopt(3C) are used to set and get options, respectively. 134 135 RETURN VALUES 136 Upon successful completion, a descriptor referencing the socket is 137 returned. Otherwise, -1 is returned and errno is set to indicate the 138 error. 139 140 ERRORS 141 The socket() function will fail if: 142 143 [EACCES] Permission to create a socket of the specified type or 144 protocol is denied. 145 146 [EAGAIN] There were insufficient resources available to 147 complete the operation. 148 149 [EAFNOSUPPORT] The specified address family is not supported by the 150 protocol family. 151 152 [EMFILE] The per-process descriptor table is full. 153 154 [ENOMEM] Insufficient user memory is available. 155 156 [ENOSR] There were insufficient STREAMS resources available to 157 complete the operation. 158 159 [EPFNOSUPPORT] The specified protocol family is not supported. 160 161 [EPROTONOSUPPORT] The protocol type is not supported by the address 162 family. 163 164 [EPROTOTYPE] The socket type is not supported by the protocol. 165 166 [EINVAL] One or more of the specified flags is not supported. 167 168 MT-LEVEL 169 Safe 170 171 SEE ALSO 172 nca(1), close(2), exec(2), fcntl(2), ioctl(2), open(2), read(2), 173 write(2), accept(3C), bind(3C), connect(3C), getsockname(3C), 174 getsockopt(3C), listen(3C), recv(3C), send(3C), setsockopt(3C), 175 shutdown(3C), socketpair(3C), in.h(3HEAD), socket.h(3HEAD), attributes(5) 176 177 NOTES 178 Historically, AF_* was commonly used in places where PF_* was meant. New 179 code should be careful to use PF_* as necessary. 180 181 illumos August 2, 2018 illumos