1 .\" 2 .\" The contents of this file are subject to the terms of the 3 .\" Common Development and Distribution License (the "License"). 4 .\" You may not use this file except in compliance with the License. 5 .\" 6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7 .\" or http://www.opensolaris.org/os/licensing. 8 .\" See the License for the specific language governing permissions 9 .\" and limitations under the License. 10 .\" 11 .\" When distributing Covered Code, include this CDDL HEADER in each 12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13 .\" If applicable, add the following below this CDDL HEADER, with the 14 .\" fields enclosed by brackets "[]" replaced with your own identifying 15 .\" information: Portions Copyright [yyyy] [name of copyright owner] 16 .\" 17 .\" 18 .\" Copyright 1989 AT&T 19 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved. 20 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All Rights Reserved. 21 .\" Copyright 2018 Nexenta Systems, Inc. 22 .\" 23 .Dd August 2, 2018 24 .Dt SOCKET 3C 25 .Os 26 .Sh NAME 27 .Nm socket 28 .Nd create an endpoint for communication 29 .Sh LIBRARY 30 .Lb libc 31 .Sh SYNOPSIS 32 .In sys/types.h 33 .In sys/socket.h 34 .Ft int 35 .Fo socket 36 .Fa "int domain" 37 .Fa "int type" 38 .Fa "int protocol" 39 .Fc 40 .Sh DESCRIPTION 41 The 42 .Fn socket 43 function creates an endpoint for communication and returns a 44 descriptor. 45 .Pp 46 The 47 .Fa domain 48 argument specifies the protocol family within which communication takes place. 49 The protocol family is generally the same as the address family for the 50 addresses supplied in later operations on the socket. 51 These families are defined in 52 .In sys/socket.h . 53 .Pp 54 The currently supported protocol families are: 55 .Bl -tag -width "PF_INET6" 56 .It Dv PF_UNIX 57 UNIX system internal protocols 58 .It Dv PF_INET 59 Internet Protocol Version 4 (IPv4) 60 .It Dv PF_INET6 61 Internet Protocol Version 6 (IPv6) 62 .It Dv PF_NCA 63 Network Cache and Accelerator (NCA) protocols 64 .El 65 .Pp 66 The socket has the indicated 67 .Fa type , 68 which specifies the communication semantics. 69 Currently defined types are: 70 .Bl -tag -width Ds 71 .It Dv SOCK_STREAM 72 .It Dv SOCK_DGRAM 73 .It Dv SOCK_RAW 74 .It Dv SOCK_SEQPACKET 75 .It Dv SOCK_RDM 76 .El 77 .Pp 78 The 79 .Fa type 80 may be augmented by a bitwise-inclusive-OR of flags from the following list, 81 defined in 82 .In sys/socket.h : 83 .Bl -tag -width Ds 84 .It Dv SOCK_CLOEXEC 85 Creates the socket with the 86 .Dv FD_CLOEXEC 87 flag set, causing the underlying file descriptor to be closed prior to any 88 future calls to 89 .Xr exec 2 . 90 This is similar in purpose to the 91 .Dv O_CLOEXEC 92 flag to 93 .Xr open 2 . 94 .It Dv SOCK_NDELAY 95 Creates the socket with the 96 .Dv O_NDELAY 97 flag set, causing the socket to provide nonblocking semantics as described for 98 .Dv O_NDELAY 99 in 100 .Xr open 2 . 101 .Dv SOCK_NONBLOCK 102 should normally be used in preference to 103 .Dv SOCK_NDELAY , 104 and takes precedence if both are set. 105 See 106 .Xr open 2 107 for further details. 108 .It Dv SOCK_NONBLOCK 109 Creates the socket with the 110 .Dv O_NONBLOCK 111 flag set, causing the socket to provide nonblocking semantics as described for 112 .Dv O_NONBLOCK 113 in 114 .Xr open 2 . 115 .El 116 .Pp 117 There must be an entry in the 118 .Xr netconfig 4 119 file for at least each protocol family and type required. 120 If a non-zero protocol has been specified but no exact match for the protocol 121 family, type, and protocol is found, then the first entry containing the 122 specified family and type with a 123 .Fa protocol 124 value of zero will be used. 125 .Pp 126 A 127 .Dv SOCK_STREAM 128 type provides sequenced, reliable, two-way connection-based byte streams. 129 An out-of-band data transmission mechanism may be supported. 130 A 131 .Dv SOCK_DGRAM 132 socket supports datagrams (connectionless, unreliable messages of a fixed 133 (typically small) maximum length). 134 A 135 .Dv SOCK_SEQPACKET 136 socket may provide a sequenced, reliable, two-way connection-based data 137 transmission path for datagrams of fixed maximum length; a consumer may be 138 required to read an entire packet with each read system call. 139 This facility is protocol specific, and presently not implemented for any 140 protocol family. 141 .Dv SOCK_RAW 142 sockets provide access to internal network interfaces. 143 The types 144 .Dv SOCK_RAW , 145 which is available only to a user with the 146 .Em net_rawaccess 147 privilege, and 148 .Dv SOCK_RDM , 149 for which no implementation currently exists, are not described here. 150 .Pp 151 The 152 .Fa protocol 153 parameter is a protocol-family-specific value which specifies a particular 154 protocol to be used with the socket. 155 Normally this value is zero, as commonly only a single protocol exists to 156 support a particular socket type within a given protocol family. 157 However, multiple protocols may exist, in which case a particular protocol may 158 be specified in this manner. 159 .Pp 160 Sockets of type 161 .Dv SOCK_STREAM 162 are full-duplex byte streams, similar to pipes. 163 A stream socket must be in a "connected" state before any data may be sent or 164 received on it. 165 A connection to another socket is created with a 166 .Xr connect 3C 167 call. 168 Once connected, data may be transferred using 169 .Xr read 2 170 and 171 .Xr write 2 172 calls or some variant of the 173 .Xr send 3C 174 and 175 .Xr recv 3C 176 calls. 177 When a session has been completed, a 178 .Xr close 2 179 may be performed. 180 Out-of-band data may also be transmitted as described on the 181 .Xr send 3C 182 manual page and received as described on the 183 .Xr recv 3C 184 manual page. 185 .Pp 186 The communications protocols used to implement a 187 .Dv SOCK_STREAM 188 insure that data is not lost or duplicated. 189 If a piece of data for which the peer protocol has buffer space cannot be 190 successfully transmitted within a reasonable length of time, then the connection 191 is considered broken and calls will indicate an error with -1 returns and with 192 .Er ETIMEDOUT 193 as the specific code in the global variable 194 .Va errno . 195 The protocols optionally keep sockets "warm" by forcing transmissions roughly 196 every minute in the absence of other activity. 197 An error is then indicated if no response can be elicited on an otherwise idle 198 connection for a extended period (for instance 5 minutes). 199 A 200 .Dv SIGPIPE 201 signal is raised if a thread sends on a broken stream; this causes naive 202 processes, which do not handle the signal, to exit. 203 .Pp 204 .Dv SOCK_SEQPACKET 205 sockets employ the same system calls as 206 .Dv SOCK_STREAM 207 sockets. 208 The only difference is that 209 .Xr read 2 210 calls will return only the amount of data requested, and any remaining in the 211 arriving packet will be discarded. 212 .Pp 213 .Dv SOCK_DGRAM 214 and 215 .Dv SOCK_RAW 216 sockets allow datagrams to be sent to correspondents named in 217 .Xr sendto 3C 218 calls. 219 Datagrams are generally received with 220 .Xr recvfrom 3C , 221 which returns the next datagram with its return address. 222 .Pp 223 An 224 .Xr fcntl 2 225 call can be used to specify a process group to receive a 226 .Dv SIGURG 227 signal when the out-of-band data arrives. 228 It can also enable non-blocking I/O. 229 .Pp 230 The operation of sockets is controlled by socket level options. 231 These options are defined in the file 232 .In sys/socket.h . 233 .Xr setsockopt 3C 234 and 235 .Xr getsockopt 3C 236 are used to set and get options, respectively. 237 .Sh RETURN VALUES 238 Upon successful completion, a descriptor referencing the socket is returned. 239 Otherwise, -1 is returned and 240 .Va errno 241 is set to indicate the error. 242 .Sh ERRORS 243 The 244 .Fn socket 245 function will fail if: 246 .Bl -tag -width Er 247 .It Bq Er EACCES 248 Permission to create a socket of the specified type or protocol is denied. 249 .It Bq Er EAGAIN 250 There were insufficient resources available to complete the operation. 251 .It Bq Er EAFNOSUPPORT 252 The specified address family is not supported by the protocol family. 253 .It Bq Er EMFILE 254 The per-process descriptor table is full. 255 .It Bq Er ENOMEM 256 Insufficient user memory is available. 257 .It Bq Er ENOSR 258 There were insufficient STREAMS resources available to complete the operation. 259 .It Bq Er EPFNOSUPPORT 260 The specified protocol family is not supported. 261 .It Bq Er EPROTONOSUPPORT 262 The protocol type is not supported by the address family. 263 .It Bq Er EPROTOTYPE 264 The socket type is not supported by the protocol. 265 .It Bq Er EINVAL 266 One or more of the specified flags is not supported. 267 .El 268 .Sh MT-LEVEL 269 .Sy Safe 270 .Sh SEE ALSO 271 .Xr nca 1 , 272 .Xr close 2 , 273 .Xr exec 2 , 274 .Xr fcntl 2 , 275 .Xr ioctl 2 , 276 .Xr open 2 , 277 .Xr read 2 , 278 .Xr write 2 , 279 .Xr accept 3C , 280 .Xr bind 3C , 281 .Xr connect 3C , 282 .Xr getsockname 3C , 283 .Xr getsockopt 3C , 284 .Xr listen 3C , 285 .Xr recv 3C , 286 .Xr send 3C , 287 .Xr setsockopt 3C , 288 .Xr shutdown 3C , 289 .Xr socketpair 3C , 290 .Xr in.h 3HEAD , 291 .Xr socket.h 3HEAD , 292 .Xr attributes 5 293 .Sh NOTES 294 Historically, 295 .Dv AF_ Ns * 296 was commonly used in places where 297 .Dv PF_ Ns * 298 was meant. 299 New code should be careful to use 300 .Dv PF_ Ns * 301 as necessary.