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