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