1.\" $NetBSD: socket.2,v 1.23 2002/10/01 18:10:45 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)socket.2 8.1 (Berkeley) 6/4/93 35.\" 36.Dd October 16, 2001 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.Fd #include \*[Lt]sys/socket.h\*[Gt] 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 local (previously UNIX) domain protocols 63PF_INET ARPA Internet protocols 64PF_INET6 ARPA IPv6 (Internet Protocol version 6) protocols 65PF_ISO ISO protocols 66PF_NS Xerox Network Systems protocols 67PF_IMPLINK IMP \*(lqhost at IMP\*(rq link layer 68PF_APPLETALK AppleTalk protocols 69.Ed 70.Pp 71The socket has the indicated 72.Fa type , 73which specifies the semantics of communication. 74Currently defined types are: 75.Pp 76.Bd -literal -offset indent -compact 77SOCK_STREAM 78SOCK_DGRAM 79SOCK_RAW 80SOCK_SEQPACKET 81SOCK_RDM 82.Ed 83.Pp 84A 85.Dv SOCK_STREAM 86type provides sequenced, reliable, 87two-way connection based byte streams. 88An out-of-band data transmission mechanism may be supported. 89A 90.Dv SOCK_DGRAM 91socket supports 92datagrams (connectionless, unreliable messages of 93a fixed (typically small) maximum length). 94A 95.Dv SOCK_SEQPACKET 96socket may provide a sequenced, reliable, 97two-way connection-based data transmission path for datagrams 98of fixed maximum length; a consumer may be required to read 99an entire packet with each read system call. 100This facility is protocol specific, and presently implemented 101only for 102.Dv PF_NS . 103.Dv SOCK_RAW 104sockets provide access to internal network protocols and interfaces. 105The types 106.Dv SOCK_RAW , 107which is available only to the super-user, and 108.Dv SOCK_RDM , 109which is planned, 110but not yet implemented, are not described here. 111.Pp 112The 113.Fa protocol 114specifies a particular protocol to be used with the socket. 115Normally only a single protocol exists to support a particular 116socket type within a given protocol family. 117However, it is possible that many protocols may exist, in which case 118a particular protocol must be specified in this manner. 119The protocol number to use is 120particular to the \*(lqcommunication domain\*(rq in which communication 121is to take place; see 122.Xr protocols 5 . 123.Pp 124Sockets of type 125.Dv SOCK_STREAM 126are full-duplex byte streams, similar 127to pipes. 128A stream socket must be in a 129.Em connected 130state before any data may be sent or received 131on it. 132A connection to another socket is created with a 133.Xr connect 2 134call. 135Once connected, data may be transferred using 136.Xr read 2 137and 138.Xr write 2 139calls or some variant of the 140.Xr send 2 141and 142.Xr recv 2 143calls. 144When a session has been completed a 145.Xr close 2 146may be performed. 147Out-of-band data may also be transmitted as described in 148.Xr send 2 149and received as described in 150.Xr recv 2 . 151.Pp 152The communications protocols used to implement a 153.Dv SOCK_STREAM 154ensure that data 155is not lost or duplicated. 156If a piece of data for which the 157peer protocol has buffer space cannot be successfully transmitted 158within a reasonable length of time, then 159the connection is considered broken and calls 160will indicate an error with 161-1 returns and with 162.Er ETIMEDOUT 163as the specific code 164in the global variable 165.Va errno . 166The protocols optionally keep sockets 167.Dq warm 168by forcing transmissions 169roughly every minute in the absence of other activity. 170An error is then indicated if no response can be 171elicited on an otherwise 172idle connection for a extended period (e.g. 5 minutes). 173A 174.Dv SIGPIPE 175signal is raised if a process sends 176on a broken stream; this causes naive processes, 177which do not handle the signal, to exit. 178.Pp 179.Dv SOCK_SEQPACKET 180sockets employ the same system calls 181as 182.Dv SOCK_STREAM 183sockets. 184The only difference is that 185.Xr read 2 186calls will return only the amount of data requested, 187and any remaining in the arriving packet will be discarded. 188.Pp 189.Dv SOCK_DGRAM 190and 191.Dv SOCK_RAW 192sockets allow sending of datagrams to correspondents 193named in 194.Xr send 2 195calls. 196Datagrams are generally received with 197.Xr recvfrom 2 , 198which returns the next datagram with its return address. 199.Pp 200An 201.Xr fcntl 2 202call can be used to specify a process group to receive 203a 204.Dv SIGURG 205signal when the out-of-band data arrives. 206It may also enable non-blocking I/O 207and asynchronous notification of I/O events 208via 209.Dv SIGIO . 210.Pp 211The operation of sockets is controlled by socket level 212.Em options . 213These options are defined in the file 214.Ao Pa sys/socket.h Ac . 215The 216.Xr setsockopt 2 217and 218.Xr getsockopt 2 219system calls are used to set and get options, respectively. 220.Sh RETURN VALUES 221A -1 is returned if an error occurs, otherwise the return 222value is a descriptor referencing the socket. 223.Sh ERRORS 224The 225.Fn socket 226call fails if: 227.Bl -tag -width Er 228.It Bq Er EPROTONOSUPPORT 229The protocol type or the specified protocol is not supported 230within this domain. 231.It Bq Er EMFILE 232The per-process descriptor table is full. 233.It Bq Er ENFILE 234The system file table is full. 235.It Bq Er EACCES 236Permission to create a socket of the specified type and/or protocol 237is denied. 238.It Bq Er ENOBUFS 239Insufficient buffer space is available. 240The socket cannot be created until sufficient resources are freed. 241.El 242.Sh SEE ALSO 243.Xr accept 2 , 244.Xr bind 2 , 245.Xr connect 2 , 246.Xr getsockname 2 , 247.Xr getsockopt 2 , 248.Xr ioctl 2 , 249.Xr listen 2 , 250.Xr poll 2 , 251.Xr read 2 , 252.Xr recv 2 , 253.Xr select 2 , 254.Xr send 2 , 255.Xr setsockopt 2 , 256.Xr shutdown 2 , 257.Xr socketpair 2 , 258.Xr write 2 , 259.Xr getprotoent 3 260.Rs 261.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 262.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 263.Re 264.Rs 265.%T "BSD Interprocess Communication Tutorial" 266.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 267.Re 268.Sh HISTORY 269The 270.Fn socket 271function call appeared in 272.Bx 4.2 . 273