1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd January 17, 2026 29.Dt SOCKET 2 30.Os 31.Sh NAME 32.Nm socket 33.Nd create an endpoint for communication 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/socket.h 38.Ft int 39.Fn socket "int domain" "int type" "int protocol" 40.Sh DESCRIPTION 41The 42.Fn socket 43system call 44creates an endpoint for communication and returns a descriptor. 45.Pp 46The 47.Fa domain 48argument specifies a communications domain within which 49communication will take place; this selects the protocol family 50which should be used. 51These families are defined in the include file 52.In sys/socket.h . 53The currently understood formats are: 54.Pp 55.Bl -tag -width "PF_BLUETOOTH" 56.It Dv PF_LOCAL 57Host-internal protocols (alias for 58.Dv PF_UNIX ) . 59.It Dv PF_UNIX 60Host-internal protocols. 61See 62.Xr unix 4 . 63.It Dv PF_INET 64Internet version 4 protocols. 65See 66.Xr icmp 4 , 67.Xr igmp 4 , 68.Xr ip 4 , 69.Xr sctp 4 , 70.Xr tcp 4 , 71.Xr udp 4 , 72.Xr udplite 4 . 73.It Dv PF_INET6 74Internet version 6 protocols. 75See 76.Xr icmp6 4 , 77.Xr ip6 4 , 78.Xr mld 4 . 79.It Dv PF_DIVERT 80Firewall packet diversion/re-injection. 81See 82.Xr divert 4 . 83.It Dv PF_ROUTE 84Legacy protocol to control routing tables and receive network 85configuration events from the kernel. 86New applications should prefer 87.Xr rtnetlink 4 88over 89.Xr route 4 . 90.It Dv PF_KEY 91Internal key-management function. 92See 93.Xr ipsec 4 . 94.It Dv PF_NETGRAPH 95Netgraph sockets. 96See 97.Xr netgraph 3 98and 99.Xr ng_socket 4 . 100.It Dv PF_NETLINK 101Netlink protocols. 102See 103.Xr genetlink 4 , 104.Xr netlink 4 , 105.Xr rtnetlink 4 . 106.It Dv PF_BLUETOOTH 107Bluetooth protocols. 108See 109.Xr ng_btsocket 4 . 110.It Dv PF_INET_SDP 111OFED socket direct protocol (IPv4). 112.It Dv PF_HYPERV 113HyperV sockets. 114.El 115.Pp 116Each protocol family is connected to an address family, which has the 117same name except that the prefix is 118.Dq Dv AF_ 119in place of 120.Dq Dv PF_ . 121Other protocol families may be also defined, beginning with 122.Dq Dv PF_ , 123with corresponding address families. 124.Pp 125The socket has the indicated 126.Fa type , 127which specifies the semantics of communication. 128Currently 129defined types are: 130.Pp 131.Bl -tag -width "SOCK_SEQPACKET" 132.It Dv SOCK_STREAM 133Stream socket. 134.It Dv SOCK_DGRAM 135Datagram socket. 136.It Dv SOCK_RAW 137Raw-protocol interface. 138.It Dv SOCK_SEQPACKET 139Sequenced packet stream. 140.El 141.Pp 142Additionally, the following flags are allowed in the 143.Fa type 144argument: 145.Pp 146.Bl -tag -width "SOCK_NONBLOCK" 147.It Dv SOCK_CLOEXEC 148Set close-on-exec on the new socket. 149See 150.Xr fcntl 2 151.Dv FD_CLOEXEC 152flag for 153.Dv F_GETFD 154command. 155.It Dv SOCK_CLOFORK 156Set close-on-fork on the new socket. 157See 158.Xr fcntl 2 159.Dv FD_CLOFORK 160flag for 161.Dv F_GETFD 162command. 163.It Dv SOCK_NONBLOCK 164Set non-blocking mode on the new socket. 165See 166.Xr fcntl 2 167.Dv O_NONBLOCK 168flag for 169.Dv F_SETFL 170command. 171.El 172.Pp 173The 174.Fa protocol 175argument 176specifies a particular protocol to be used with the socket. 177Normally only a single protocol exists to support a particular 178socket type within a given protocol family. 179However, it is possible 180that many protocols may exist, in which case a particular protocol 181must be specified in this manner. 182The protocol number to use is 183particular to the 184.Dq "communication domain" 185in which communication 186is to take place; see 187.Xr protocols 5 . 188The 189.Fa protocol 190argument may be set to zero (0) to request the default 191implementation of a socket type for the protocol, if any. 192.Sh STREAM SOCKET TYPE 193The 194.Dv SOCK_STREAM 195socket type provides reliable, sequenced, full-duplex octet streams between 196the socket and a peer to which the socket is connected. 197A socket of type 198.Dv SOCK_STREAM 199needs to be in a 200.Em connected 201state before any data can be sent or received. 202A connection to another socket is created with a 203.Xr connect 2 204system call. 205(Some protocol families, such as the Internet family, 206support the notion of an 207.Dq implied connect , 208which permits data to be sent piggybacked onto a connect operation by 209using the 210.Xr sendto 2 211system call.) 212Once connected, data may be sent using 213.Xr send 2 , 214.Xr sendto 2 , 215.Xr sendmsg 2 216and 217.Xr write 2 218system calls. 219Data may be received using 220.Xr recv 2 , 221.Xr recvfrom 2 , 222.Xr recvmsg 2 , 223and 224.Xr read 2 225system calls. 226Record boundaries are not maintained; data sent on a stream socket using output 227operations of one size can be received using input operations of smaller or 228larger sizes without loss of data. 229Data may be buffered; successful return from an output function does not imply 230that the data has been delivered to the peer or even transmitted from the local 231system. 232For certain protocols out-of-band data may also be transmitted as described in 233.Xr send 2 234and received as described in 235.Xr recv 2 . 236.Pp 237If data cannot be successfully transmitted within a given time then the 238connection is considered broken, and subsequent operations shall fail with 239a protocol specific error code. 240A 241.Dv SIGPIPE 242signal is raised if a thread attempts to send data on a broken stream (one that 243is no longer connected). 244The signal can be suppressed by the 245.Dv MSG_NOSIGNAL 246flag with distinct 247.Xr send 2 , 248.Xr sendto 2 , 249and 250.Xr sendmsg 2 251system calls or by the 252.Dv SO_NOSIGPIPE 253socket option set on the socket with 254.Xr setsockopt 2 . 255.Pp 256The 257.Dv SOCK_STREAM 258socket is supported by the following protocol families: 259.Dv PF_INET , 260.Dv PF_INET6 , 261.Dv PF_UNIX , 262.Dv PF_BLUETOOTH , 263.Dv PF_HYPERV , 264and 265.Dv PF_INET_SDP . 266Out-of-band data transmission mechanism is supported for stream sockets of 267.Dv PF_INET 268and 269.Dv PF_INET6 270protocol families. 271.Sh DATAGRAM SOCKET TYPE 272The 273.Dv SOCK_DGRAM 274socket type supports connectionless data transfer which is not necessarily 275acknowledged or reliable. 276Datagrams can be sent to the address specified (possibly multicast or 277broadcast) in each output operation, and incoming datagrams can be received 278from multiple sources. 279The source address of each datagram is available when receiving the datagram 280with 281.Xr recvfrom 2 282or 283.Xr recvmsg 2 . 284An application can also pre-specify a peer address with 285.Xr sendto 2 286or 287.Xr sendmsg 2 , 288in which case calls to output functions that do not specify a peer address 289shall send to the pre-specified peer. 290If a peer has been specified, only datagrams from that peer shall be received. 291A datagram shall be sent in a single output operation, and needs to be received 292in a single input operation. 293The maximum size of a datagram is protocol-specific. 294Output datagrams may be buffered within the system; thus, a successful return 295from an output function does not guarantee that a datagram is actually sent or 296received. 297.Pp 298The 299.Dv SOCK_DGRAM 300socket is supported by the following protocol families: 301.Dv PF_INET , 302.Dv PF_INET6 , 303.Dv PF_UNIX , 304.Dv PF_NETGRAPH , 305and 306.Dv PF_NETLINK . 307.Sh SEQUENCED PACKET SOCKET TYPE 308The 309.Dv SOCK_SEQPACKET 310socket type is similar to the 311.Dv SOCK_STREAM 312type, and is also connection-oriented. 313The only difference between these types is that record boundaries are 314maintained using the 315.Dv SOCK_SEQPACKET 316type. 317A record can be sent using one or more output operations and received using one 318or more input operations, but a single operation never transfers parts of more 319than one record. 320Record boundaries are set by the sender with the 321.Dv MSG_EOR 322flag of 323.Xr send 2 324or 325.Xr sendmsg 2 326functions. 327There is no possibility to set a record boundary with 328.Xr write 2 . 329Record boundaries are visible to the receiver via the 330.Dv MSG_EOR 331flag in the received message flags returned by the 332.Xr recvmsg 2 333function. 334It is protocol-specific whether a maximum record size is imposed. 335.Pp 336The 337.Dv SOCK_SEQPACKET 338socket is supported by the following protocol families: 339.Dv PF_INET , 340.Dv PF_INET6 , 341and 342.Dv PF_UNIX . 343.Pp 344.Sh RAW SOCKET TYPE 345The 346.Dv SOCK_RAW 347socket type provides access to internal network protocols and interfaces. 348It is a datagram socket in its nature, thus has the same semantics of 349read and write operations. 350The 351.Dv SOCK_RAW 352type is available only to the super-user and is described in 353.Xr ip 4 354and 355.Xr ip6 4 . 356.Sh NON-BLOCKING MODE 357A socket can be created in 358.Em non-blocking mode 359with the help of 360.Dv SOCK_NONBLOCK 361flag. 362Alternatively, the non-blocking mode on a socket can be turned on and off with 363the help of the 364.Dv O_NONBLOCK 365flag of the 366.Xr fcntl 2 367system call. 368.Pp 369When a non-blocking socket has not enough data in its receive buffer to fulfill 370the application supplied buffer, then data receiving system calls like 371.Xr recv 2 , 372.Xr recvfrom 2 , 373.Xr recvmsg 2 374and 375.Xr read 2 376will not block waiting for the data but immediately return. 377Return value will indicate amount of bytes read into the supplied buffer. 378The 379.Va errno 380will be set to 381.Dv EAGAIN 382.Po 383has same value as 384.Dv EWOULDBLOCK 385.Pc . 386.Pp 387If application tries to send more data on a non-blocking socket than the socket 388send buffer can accomodate with 389.Xr send 2 , 390.Xr sendto 2 , 391.Xr sendmsg 2 392or 393.Xr write 2 394system calls partial data will be sent. 395Return value will indicate amount of bytes sent. 396The 397.Va errno 398will be set to 399.Dv EAGAIN . 400Note that sockets of 401.Dv SOCK_DGRAM 402type are unreliable, thus for these sockets sending operations will never fail 403with 404.Dv EAGAIN 405in non-blocking mode neither will block in blocking mode. 406.Sh OTHER OPERATIONS ON SOCKETS 407Since socket descriptors are file descriptors, many generic file operations 408performed by 409.Xr fcntl 2 , 410apply. 411Socket descriptors can be used with all event engines, such as 412.Xr kevent 2 , 413.Xr select 2 414and 415.Xr poll 2 . 416.Pp 417An 418.Xr fcntl 2 419system call can be used to specify a process group to receive 420a 421.Dv SIGURG 422signal when the out-of-band data arrives. 423It may also enable non-blocking I/O 424and asynchronous notification of I/O events 425via 426.Dv SIGIO . 427.Pp 428The operation of sockets is controlled by socket level 429.Em options . 430These options are defined in the file 431.In sys/socket.h . 432The 433.Xr setsockopt 2 434and 435.Xr getsockopt 2 436system calls are used to set and get options, respectively. 437.Pp 438Connection associated with a socket can be terminated by 439.Xr close 2 440system call. 441One direction of communication can be disabled with 442.Xr shutdown 2 . 443.Sh RETURN VALUES 444A -1 is returned if an error occurs, otherwise the return 445value is a descriptor referencing the socket. 446.Sh ERRORS 447The 448.Fn socket 449system call fails if: 450.Bl -tag -width Er 451.It Bq Er EACCES 452Permission to create a socket of the specified type and/or protocol 453is denied. 454.It Bq Er EAFNOSUPPORT 455The address family (domain) is not supported or the 456specified domain is not supported by this protocol family. 457.It Bq Er EMFILE 458The per-process descriptor table is full. 459.It Bq Er ENFILE 460The system file table is full. 461.It Bq Er ENOBUFS 462Insufficient buffer space is available. 463The socket cannot be created until sufficient resources are freed. 464.It Bq Er EPERM 465User has insufficient privileges to carry out the requested operation. 466.It Bq Er EPROTONOSUPPORT 467The protocol type or the specified protocol is not supported 468within this domain. 469.It Bq Er EPROTOTYPE 470The socket type is not supported by the protocol. 471.El 472.Sh SEE ALSO 473.Xr accept 2 , 474.Xr bind 2 , 475.Xr close 2 , 476.Xr connect 2 , 477.Xr fcntl 2 , 478.Xr getpeername 2 , 479.Xr getsockname 2 , 480.Xr getsockopt 2 , 481.Xr ioctl 2 , 482.Xr kevent 2 , 483.Xr listen 2 , 484.Xr poll 2 , 485.Xr read 2 , 486.Xr recv 2 , 487.Xr select 2 , 488.Xr send 2 , 489.Xr sendmsg 2 , 490.Xr sendto 2 , 491.Xr signal 3 , 492.Xr shutdown 2 , 493.Xr socketpair 2 , 494.Xr write 2 , 495.Xr CMSG_DATA 3 , 496.Xr getprotoent 3 , 497.Xr netgraph 3 , 498.Xr divert 4 , 499.Xr genetlink 4 , 500.Xr icmp 4 , 501.Xr icmp6 4 , 502.Xr igmp 4 , 503.Xr ip 4 , 504.Xr ip6 4 , 505.Xr ipsec 4 , 506.Xr netlink 4 , 507.Xr ng_socket 4 , 508.Xr route 4 , 509.Xr rtnetlink 4 , 510.Xr sctp 4 , 511.Xr tcp 4 , 512.Xr udp 4 , 513.Xr protocols 5 514.Rs 515.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 516.%B PS1 517.%N 7 518.Re 519.Rs 520.%T "BSD Interprocess Communication Tutorial" 521.%B PS1 522.%N 8 523.Re 524.Sh STANDARDS 525The 526.Fn socket 527function conforms to 528.St -p1003.1-2008 . 529The 530.Tn POSIX 531standard specifies only the 532.Dv AF_INET , 533.Dv AF_INET6 , 534and 535.Dv AF_UNIX 536constants for address families, and requires the use of 537.Dv AF_* 538constants for the 539.Fa domain 540argument of 541.Fn socket . 542The 543.Dv SOCK_CLOEXEC 544and 545.Dv SOCK_CLOFORK 546flags are expected to conform to 547.St -p1003.1-2024 . 548.Tn POSIX 549standard. 550The 551.Dv SOCK_RDM 552.Fa type , 553the 554.Dv PF_* 555constants, and other address families are 556.Fx 557extensions. 558.Sh HISTORY 559The 560.Fn socket 561system call appeared in 562.Bx 4.2 . 563.Pp 564The 565.Dv SOCK_CLOFORK 566flag appeared in 567.Fx 15.0 . 568