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