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: src/lib/libc/sys/socket.2,v 1.12.2.11 2002/12/29 16:35:34 schweikh Exp $ 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 49.Fn Socket 50creates an endpoint for communication and returns a descriptor. 51.Pp 52The 53.Fa domain 54parameter specifies a communications domain within which 55communication will take place; this selects the protocol family 56which should be used. 57These families are defined in the include file 58.Ao Pa sys/socket.h Ac . 59The currently understood formats are: 60.Pp 61.Bd -literal -offset indent -compact 62PF_LOCAL Host-internal protocols, formerly called PF_UNIX, 63PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL, 64PF_INET Internet version 4 protocols, 65PF_IMPLINK ARPAnet IMP addresses, 66PF_PUP PUP protocols, like BSP, 67PF_CHAOS MIT CHAOS protocols, 68PF_NS Xerox Network Systems protocols, 69PF_ISO ISO protocols, 70PF_OSI Open Systems Interconnection protocols, 71PF_ECMA European Computer Manufacturers, 72PF_DATAKIT Datakit protocols, 73PF_CCITT ITU-T protocols, like X.25, 74PF_SNA IBM SNA, 75PF_DECnet DECnet, 76PF_DLI DEC Direct Data Link Interface protocol, 77PF_LAT LAT protocol, 78PF_HYLINK NSC Hyperchannel, 79PF_APPLETALK AppleTalk protocols, 80PF_ROUTE Internal Routing protocol, 81PF_LINK Link layer interface, 82PF_XTP eXpress Transfer Protocol, 83PF_COIP Connection-Oriented IP, aka ST II, 84PF_CNT Computer Network Technology, 85PF_SIP Simple Internet Protocol, 86PF_IPX Novell Internet Packet eXchange protocol, 87PF_RTIP Help Identify RTIP packets, 88PF_PIP Help Identify PIP packets, 89PF_ISDN Integrated Services Digital Network, 90PF_KEY Internal key-management function, 91PF_INET6 Internet version 6 protocols, 92PF_NATM Native ATM access, 93PF_ATM ATM, 94PF_NETGRAPH Netgraph sockets 95.Ed 96.Pp 97The socket has the indicated 98.Fa type , 99which specifies the semantics of communication. Currently 100defined types are: 101.Pp 102.Bd -literal -offset indent -compact 103SOCK_STREAM Stream socket, 104SOCK_DGRAM Datagram socket, 105SOCK_RAW Raw-protocol interface, 106SOCK_RDM Reliably-delivered packet, 107SOCK_SEQPACKET Sequenced packet stream 108.Ed 109.Pp 110A 111.Dv SOCK_STREAM 112type provides sequenced, reliable, 113two-way connection based byte streams. 114An out-of-band data transmission mechanism may be supported. 115A 116.Dv SOCK_DGRAM 117socket supports 118datagrams (connectionless, unreliable messages of 119a fixed (typically small) maximum length). 120A 121.Dv SOCK_SEQPACKET 122socket may provide a sequenced, reliable, 123two-way connection-based data transmission path for datagrams 124of fixed maximum length; a consumer may be required to read 125an entire packet with each read system call. 126This facility is protocol specific, and presently implemented 127only for 128.Dv PF_NS . 129.Dv SOCK_RAW 130sockets provide access to internal network protocols and interfaces. 131The types 132.Dv SOCK_RAW , 133which is available only to the super-user, and 134.Dv SOCK_RDM , 135which is planned, 136but not yet implemented, are not described here. 137.Pp 138The 139.Fa protocol 140specifies a particular protocol to be used with the socket. 141Normally only a single protocol exists to support a particular 142socket type within a given protocol family. However, it is possible 143that many protocols may exist, in which case a particular protocol 144must be specified in this manner. The protocol number to use is 145particular to the 146.Dq "communication domain" 147in which communication 148is to take place; see 149.Xr protocols 5 . 150.Pp 151Sockets of type 152.Dv SOCK_STREAM 153are full-duplex byte streams, similar 154to pipes. A stream socket must be in a 155.Em connected 156state before any data may be sent or received 157on it. A connection to another socket is created with a 158.Xr connect 2 159call. 160Once connected, data may be transferred using 161.Xr read 2 162and 163.Xr write 2 164calls or some variant of the 165.Xr send 2 166and 167.Xr recv 2 168calls. 169(Some protocol families, such as the Internet family, 170support the notion of an 171.Dq implied connect , 172which permits data to be sent piggybacked onto a connect operation by 173using the 174.Xr sendto 2 175call.) 176When a session has been completed a 177.Xr close 2 178may be performed. 179Out-of-band data may also be transmitted as described in 180.Xr send 2 181and received as described in 182.Xr recv 2 . 183.Pp 184The communications protocols used to implement a 185.Dv SOCK_STREAM 186insure that data 187is not lost or duplicated. If a piece of data for which the 188peer protocol has buffer space cannot be successfully transmitted 189within a reasonable length of time, then 190the connection is considered broken and calls 191will indicate an error with 192-1 returns and with 193.Er ETIMEDOUT 194as the specific code 195in the global variable 196.Va errno . 197The protocols optionally keep sockets 198.Dq warm 199by forcing transmissions 200roughly every minute in the absence of other activity. 201An error is then indicated if no response can be 202elicited on an otherwise 203idle connection for a extended period (e.g. 5 minutes). 204A 205.Dv SIGPIPE 206signal is raised if a process sends 207on a broken stream; this causes naive processes, 208which do not handle the signal, to exit. 209.Pp 210.Dv SOCK_SEQPACKET 211sockets employ the same system calls 212as 213.Dv SOCK_STREAM 214sockets. The only difference 215is that 216.Xr read 2 217calls will return only the amount of data requested, 218and any remaining in the arriving packet will be discarded. 219.Pp 220.Dv SOCK_DGRAM 221and 222.Dv SOCK_RAW 223sockets allow sending of datagrams to correspondents 224named in 225.Xr send 2 226calls. Datagrams are generally received with 227.Xr recvfrom 2 , 228which returns the next datagram with its return address. 229.Pp 230An 231.Xr fcntl 2 232call can be used to specify a process group to receive 233a 234.Dv SIGURG 235signal when the out-of-band data arrives. 236It may also enable non-blocking I/O 237and asynchronous notification of I/O events 238via 239.Dv SIGIO . 240.Pp 241The operation of sockets is controlled by socket level 242.Em options . 243These options are defined in the file 244.Ao Pa sys/socket.h Ac . 245.Xr Setsockopt 2 246and 247.Xr getsockopt 2 248are used to set and get options, respectively. 249.Sh RETURN VALUES 250A -1 is returned if an error occurs, otherwise the return 251value is a descriptor referencing the socket. 252.Sh ERRORS 253The 254.Fn socket 255call fails if: 256.Bl -tag -width Er 257.It Bq Er EPROTONOSUPPORT 258The protocol type or the specified protocol is not supported 259within this domain. 260.It Bq Er EMFILE 261The per-process descriptor table is full. 262.It Bq Er ENFILE 263The system file table is full. 264.It Bq Er EACCES 265Permission to create a socket of the specified type and/or protocol 266is denied. 267.It Bq Er ENOBUFS 268Insufficient buffer space is available. 269The socket cannot be created until sufficient resources are freed. 270.El 271.Sh SEE ALSO 272.Xr accept 2 , 273.Xr bind 2 , 274.Xr connect 2 , 275.Xr getpeername 2 , 276.Xr getsockname 2 , 277.Xr getsockopt 2 , 278.Xr ioctl 2 , 279.Xr listen 2 , 280.Xr read 2 , 281.Xr recv 2 , 282.Xr select 2 , 283.Xr send 2 , 284.Xr shutdown 2 , 285.Xr socketpair 2 , 286.Xr write 2 , 287.Xr getprotoent 3 , 288.Xr netgraph 4 , 289.Xr protocols 5 290.Rs 291.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 292.%B PS1 293.%N 7 294.Re 295.Rs 296.%T "BSD Interprocess Communication Tutorial" 297.%B PS1 298.%N 8 299.Re 300.Sh HISTORY 301The 302.Fn socket 303function call appeared in 304.Bx 4.2 . 305