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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd November 24, 1997 36.Dt SOCKET 2 37.Os 38.Sh NAME 39.Nm socket 40.Nd create an endpoint for communication 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In sys/types.h 45.In sys/socket.h 46.Ft int 47.Fn socket "int domain" "int type" "int protocol" 48.Sh DESCRIPTION 49The 50.Fn socket 51system call 52creates an endpoint for communication and returns a descriptor. 53.Pp 54The 55.Fa domain 56argument specifies a communications domain within which 57communication will take place; this selects the protocol family 58which should be used. 59These families are defined in the include file 60.In sys/socket.h . 61The currently understood formats are: 62.Pp 63.Bd -literal -offset indent -compact 64PF_LOCAL Host-internal protocols, formerly called PF_UNIX, 65PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL, 66PF_INET Internet version 4 protocols, 67PF_PUP PUP protocols, like BSP, 68PF_APPLETALK AppleTalk protocols, 69PF_ROUTE Internal Routing protocol, 70PF_LINK Link layer interface, 71PF_IPX Novell Internet Packet eXchange protocol, 72PF_RTIP Help Identify RTIP packets, 73PF_PIP Help Identify PIP packets, 74PF_ISDN Integrated Services Digital Network, 75PF_KEY Internal key-management function, 76PF_INET6 Internet version 6 protocols, 77PF_NATM Native ATM access, 78PF_ATM ATM, 79PF_NETGRAPH Netgraph sockets 80.Ed 81.Pp 82The socket has the indicated 83.Fa type , 84which specifies the semantics of communication. 85Currently 86defined types are: 87.Pp 88.Bd -literal -offset indent -compact 89SOCK_STREAM Stream socket, 90SOCK_DGRAM Datagram socket, 91SOCK_RAW Raw-protocol interface, 92SOCK_RDM Reliably-delivered packet, 93SOCK_SEQPACKET Sequenced packet stream 94.Ed 95.Pp 96A 97.Dv SOCK_STREAM 98type provides sequenced, reliable, 99two-way connection based byte streams. 100An out-of-band data transmission mechanism may be supported. 101A 102.Dv SOCK_DGRAM 103socket supports 104datagrams (connectionless, unreliable messages of 105a fixed (typically small) maximum length). 106A 107.Dv SOCK_SEQPACKET 108socket may provide a sequenced, reliable, 109two-way connection-based data transmission path for datagrams 110of fixed maximum length; a consumer may be required to read 111an entire packet with each read system call. 112This facility is protocol specific, and presently unimplemented. 113.Dv SOCK_RAW 114sockets provide access to internal network protocols and interfaces. 115The types 116.Dv SOCK_RAW , 117which is available only to the super-user, and 118.Dv SOCK_RDM , 119which is planned, 120but not yet implemented, are not described here. 121.Pp 122The 123.Fa protocol 124argument 125specifies a particular protocol to be used with the socket. 126Normally only a single protocol exists to support a particular 127socket type within a given protocol family. 128However, it is possible 129that many protocols may exist, in which case a particular protocol 130must be specified in this manner. 131The protocol number to use is 132particular to the 133.Dq "communication domain" 134in which communication 135is to take place; see 136.Xr protocols 5 . 137.Pp 138Sockets of type 139.Dv SOCK_STREAM 140are full-duplex byte streams, similar 141to pipes. 142A stream socket must be in a 143.Em connected 144state before any data may be sent or received 145on it. 146A connection to another socket is created with a 147.Xr connect 2 148system call. 149Once connected, data may be transferred using 150.Xr read 2 151and 152.Xr write 2 153calls or some variant of the 154.Xr send 2 155and 156.Xr recv 2 157functions. 158(Some protocol families, such as the Internet family, 159support the notion of an 160.Dq implied connect , 161which permits data to be sent piggybacked onto a connect operation by 162using the 163.Xr sendto 2 164system call.) 165When a session has been completed a 166.Xr close 2 167may be performed. 168Out-of-band data may also be transmitted as described in 169.Xr send 2 170and received as described in 171.Xr recv 2 . 172.Pp 173The communications protocols used to implement a 174.Dv SOCK_STREAM 175insure that data 176is not lost or duplicated. 177If a piece of data for which the 178peer protocol has buffer space cannot be successfully transmitted 179within a reasonable length of time, then 180the connection is considered broken and calls 181will indicate an error with 182-1 returns and with 183.Er ETIMEDOUT 184as the specific code 185in the global variable 186.Va errno . 187The protocols optionally keep sockets 188.Dq warm 189by forcing transmissions 190roughly every minute in the absence of other activity. 191An error is then indicated if no response can be 192elicited on an otherwise 193idle connection for an extended period (e.g.\& 5 minutes). 194A 195.Dv SIGPIPE 196signal is raised if a process sends 197on a broken stream; this causes naive processes, 198which do not handle the signal, to exit. 199.Pp 200.Dv SOCK_SEQPACKET 201sockets employ the same system calls 202as 203.Dv SOCK_STREAM 204sockets. 205The only difference 206is that 207.Xr read 2 208calls will return only the amount of data requested, 209and any remaining in the arriving packet will be discarded. 210.Pp 211.Dv SOCK_DGRAM 212and 213.Dv SOCK_RAW 214sockets allow sending of datagrams to correspondents 215named in 216.Xr send 2 217calls. 218Datagrams are generally received with 219.Xr recvfrom 2 , 220which returns the next datagram with its return address. 221.Pp 222An 223.Xr fcntl 2 224system call can be used to specify a process group to receive 225a 226.Dv SIGURG 227signal when the out-of-band data arrives. 228It may also enable non-blocking I/O 229and asynchronous notification of I/O events 230via 231.Dv SIGIO . 232.Pp 233The operation of sockets is controlled by socket level 234.Em options . 235These options are defined in the file 236.In sys/socket.h . 237The 238.Xr setsockopt 2 239and 240.Xr getsockopt 2 241system calls are used to set and get options, respectively. 242.Sh RETURN VALUES 243A -1 is returned if an error occurs, otherwise the return 244value is a descriptor referencing the socket. 245.Sh ERRORS 246The 247.Fn socket 248system call fails if: 249.Bl -tag -width Er 250.It Bq Er EPROTONOSUPPORT 251The protocol type or the specified protocol is not supported 252within this domain. 253.It Bq Er EMFILE 254The per-process descriptor table is full. 255.It Bq Er ENFILE 256The system file table is full. 257.It Bq Er EACCES 258Permission to create a socket of the specified type and/or protocol 259is denied. 260.It Bq Er ENOBUFS 261Insufficient buffer space is available. 262The socket cannot be created until sufficient resources are freed. 263.El 264.Sh SEE ALSO 265.Xr accept 2 , 266.Xr bind 2 , 267.Xr connect 2 , 268.Xr getpeername 2 , 269.Xr getsockname 2 , 270.Xr getsockopt 2 , 271.Xr ioctl 2 , 272.Xr listen 2 , 273.Xr read 2 , 274.Xr recv 2 , 275.Xr select 2 , 276.Xr send 2 , 277.Xr shutdown 2 , 278.Xr socketpair 2 , 279.Xr write 2 , 280.Xr getprotoent 3 , 281.Xr netgraph 4 , 282.Xr protocols 5 283.Rs 284.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 285.%B PS1 286.%N 7 287.Re 288.Rs 289.%T "BSD Interprocess Communication Tutorial" 290.%B PS1 291.%N 8 292.Re 293.Sh HISTORY 294The 295.Fn socket 296system call appeared in 297.Bx 4.2 . 298