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