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