1.\" $OpenBSD: socket.2,v 1.44 2022/03/31 17:27:16 naddy Exp $ 2.\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)socket.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: March 31 2022 $ 34.Dt SOCKET 2 35.Os 36.Sh NAME 37.Nm socket 38.Nd create an endpoint for communication 39.Sh SYNOPSIS 40.In sys/socket.h 41.Ft int 42.Fn socket "int domain" "int type" "int protocol" 43.Sh DESCRIPTION 44.Fn socket 45creates an endpoint for communication and returns a descriptor. 46.Pp 47The 48.Fa domain 49parameter specifies a communications domain within which 50communication will take place; this selects the protocol family 51which should be used. 52These families are defined in the include file 53.In sys/socket.h . 54The currently understood formats are: 55.Pp 56.Bl -tag -width "AF_INET6XXX" -offset indent -compact 57.It AF_UNIX 58UNIX internal protocols 59.It AF_INET 60Internet Protocol version 4 (IPv4) protocol family 61.It AF_INET6 62Internet Protocol version 6 (IPv6) protocol family 63.El 64.Pp 65The socket has the indicated 66.Fa type , 67which specifies the semantics of communication. 68Currently defined types are: 69.Pp 70.Bl -tag -width "SOCK_SEQPACKETXXX" -offset indent -compact 71.It SOCK_STREAM 72.It SOCK_DGRAM 73.It SOCK_RAW 74.It SOCK_SEQPACKET 75.El 76.Pp 77A 78.Dv SOCK_STREAM 79type provides sequenced, reliable, 80two-way connection based byte streams. 81An out-of-band data transmission mechanism may be supported. 82A 83.Dv SOCK_DGRAM 84socket supports 85datagrams (connectionless, unreliable messages of 86a fixed (typically small) maximum length). 87A 88.Dv SOCK_SEQPACKET 89socket may provide a sequenced, reliable, 90two-way connection-based data transmission path for datagrams 91of fixed maximum length; a consumer may be required to read 92an entire packet with each read system call. 93This facility is protocol specific, and presently implemented only for 94.Dv AF_UNIX . 95.Dv SOCK_RAW 96sockets provide access to internal network protocols and interfaces, 97and are available only to the superuser. 98.Pp 99Any combination of the following flags may additionally be used in the 100.Fa type 101argument: 102.Pp 103.Bl -tag -width "SOCK_NONBLOCKX" -offset indent -compact 104.It SOCK_CLOEXEC 105Set close-on-exec flag on the new descriptor. 106.It SOCK_NONBLOCK 107Set non-blocking I/O mode on the new socket. 108.It SOCK_DNS 109For domains 110.Dv AF_INET 111or 112.Dv AF_INET6 , 113only allow 114.Xr connect 2 , 115.Xr sendto 2 , 116or 117.Xr sendmsg 2 118to the DNS port (typically 53). 119.El 120.Pp 121The 122.Fa protocol 123specifies a particular protocol to be used with the socket. 124Normally only a single protocol exists to support a particular 125socket type within a given protocol family. 126However, it is possible that many protocols may exist, 127in which case a particular protocol must be specified in this manner. 128The protocol number to use is particular to the 129.Dq communication domain 130in which communication is to take place; see 131.Xr protocols 5 . 132A value of 0 for 133.Fa protocol 134will let the system select an appropriate protocol for the requested 135socket type. 136.Pp 137Sockets of type 138.Dv SOCK_STREAM 139are full-duplex byte streams. 140A stream socket must be in a 141.Em connected 142state before any data may be sent or received on it. 143A connection to another socket is created with a 144.Xr connect 2 145call. 146Once connected, data may be transferred using 147.Xr read 2 148and 149.Xr write 2 150calls or some variant of the 151.Xr send 2 152and 153.Xr recv 2 154calls. 155When a session has been completed, a 156.Xr close 2 157may be performed. 158Out-of-band data may also be transmitted as described in 159.Xr send 2 160and received as described in 161.Xr recv 2 . 162.Pp 163The communications protocols used to implement a 164.Dv SOCK_STREAM 165ensure that data is not lost or duplicated. 166If a piece of data for which the peer protocol has buffer space cannot 167be successfully transmitted within a reasonable length of time, then the 168connection is considered broken and calls will indicate an error with \-1 169returns and with 170.Er ETIMEDOUT 171as the specific code in the global variable 172.Va errno . 173The protocols optionally keep sockets 174.Dq warm 175by forcing transmissions roughly every minute in the absence of other activity. 176An error is then indicated if no response can be elicited on an otherwise 177idle connection for an extended period (e.g., 5 minutes). 178A 179.Dv SIGPIPE 180signal is raised if a process sends on a broken stream; this causes 181naive processes, which do not handle the signal, to exit. 182.Pp 183.Dv SOCK_SEQPACKET 184sockets employ the same system calls 185as 186.Dv SOCK_STREAM 187sockets. 188The only difference is that 189.Xr read 2 190calls will return only the amount of data requested, 191and any remaining in the arriving packet will be discarded. 192.Pp 193.Dv SOCK_DGRAM 194and 195.Dv SOCK_RAW 196sockets allow sending of datagrams to correspondents named in 197.Xr send 2 198calls. 199Datagrams are generally received with 200.Xr recvfrom 2 , 201which returns the next datagram with its return address. 202.Pp 203An 204.Xr fcntl 2 205call can be used to specify a process group to receive 206a 207.Dv SIGURG 208signal when the out-of-band data arrives. 209It may also enable non-blocking I/O and asynchronous notification 210of I/O events via 211.Dv SIGIO . 212.Pp 213The operation of sockets is controlled by socket level 214.Em options . 215These options are defined in the file 216.In sys/socket.h . 217.Xr setsockopt 2 218and 219.Xr getsockopt 2 220are used to set and get options, respectively. 221.Sh RETURN VALUES 222If successful, 223.Fn socket 224returns a non-negative integer, the socket file descriptor. 225Otherwise, a value of \-1 is returned and 226.Va errno 227is set to indicate the error. 228.Sh ERRORS 229The 230.Fn socket 231call fails if: 232.Bl -tag -width Er 233.It Bq Er EAFNOSUPPORT 234The specified address family is not supported on this machine. 235.It Bq Er EPROTONOSUPPORT 236The protocol type or the specified protocol is not supported 237within this domain. 238.It Bq Er EPROTOTYPE 239The combination of the specified protocol and type is not supported. 240.It Bq Er EMFILE 241The per-process descriptor table is full. 242.It Bq Er ENFILE 243The system file table is full. 244.It Bq Er ENOBUFS 245Insufficient resources were available in the system 246to perform the operation. 247.It Bq Er EACCES 248Permission to create a socket of the specified type and/or protocol 249is denied. 250.El 251.Sh SEE ALSO 252.Xr accept 2 , 253.Xr bind 2 , 254.Xr connect 2 , 255.Xr getsockname 2 , 256.Xr getsockopt 2 , 257.Xr ioctl 2 , 258.Xr listen 2 , 259.Xr poll 2 , 260.Xr read 2 , 261.Xr recv 2 , 262.Xr select 2 , 263.Xr send 2 , 264.Xr setsockopt 2 , 265.Xr shutdown 2 , 266.Xr socketpair 2 , 267.Xr write 2 , 268.Xr getprotoent 3 , 269.Xr inet 4 , 270.Xr inet6 4 , 271.Xr netintro 4 , 272.Xr unix 4 273.Rs 274.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 275.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 276.Re 277.Rs 278.%T "BSD Interprocess Communication Tutorial" 279.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 280.Re 281.Sh STANDARDS 282The 283.Fn socket 284function conforms to 285.St -p1003.1-2008 . 286The 287.Dv SOCK_CLOEXEC 288and 289.Dv SOCK_NONBLOCK 290flags are expected to conform to a future revision of that standard. 291.Pp 292The 293.Dv SOCK_DNS 294flag is an 295.Ox 296extension. 297.Sh HISTORY 298The 299.Fn socket 300system call first appeared in 301.Bx 4.1c . 302Support for the 303.Dv SOCK_CLOEXEC 304and 305.Dv SOCK_NONBLOCK 306flags appeared in 307.Ox 5.7 . 308Support for the 309.Dv SOCK_DNS 310flag appeared in 311.Ox 5.9 . 312