1.\" $NetBSD: socket.2,v 1.18 2000/10/05 12:45:23 ad 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 June 4, 1993 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 <sys/types.h> 46.Fd #include <sys/socket.h> 47.Ft int 48.Fn socket "int domain" "int type" "int protocol" 49.Sh DESCRIPTION 50.Fn socket 51creates an endpoint for communication and returns a descriptor. 52.Pp 53The 54.Fa domain 55parameter specifies a communications domain within which 56communication will take place; this selects the protocol family 57which should be used. 58These families are defined in the include file 59.Ao Pa sys/socket.h Ac . 60The currently understood formats are 61.Pp 62.Bd -literal -offset indent -compact 63PF_LOCAL local (previously UNIX) domain protocols 64PF_INET ARPA Internet protocols 65PF_INET6 ARPA IPv6 (Internet Protocol version 6) protocols 66PF_ISO ISO protocols 67PF_NS Xerox Network Systems protocols 68PF_IMPLINK IMP \*(lqhost at IMP\*(rq link layer 69PF_APPLETALK AppleTalk protocols 70.Ed 71.Pp 72The socket has the indicated 73.Fa type , 74which specifies the semantics of communication. Currently 75defined types are: 76.Pp 77.Bd -literal -offset indent -compact 78SOCK_STREAM 79SOCK_DGRAM 80SOCK_RAW 81SOCK_SEQPACKET 82SOCK_RDM 83.Ed 84.Pp 85A 86.Dv SOCK_STREAM 87type provides sequenced, reliable, 88two-way connection based byte streams. 89An out-of-band data transmission mechanism may be supported. 90A 91.Dv SOCK_DGRAM 92socket supports 93datagrams (connectionless, unreliable messages of 94a fixed (typically small) maximum length). 95A 96.Dv SOCK_SEQPACKET 97socket may provide a sequenced, reliable, 98two-way connection-based data transmission path for datagrams 99of fixed maximum length; a consumer may be required to read 100an entire packet with each read system call. 101This facility is protocol specific, and presently implemented 102only for 103.Dv PF_NS . 104.Dv SOCK_RAW 105sockets provide access to internal network protocols and interfaces. 106The types 107.Dv SOCK_RAW , 108which is available only to the super-user, and 109.Dv SOCK_RDM , 110which is planned, 111but not yet implemented, are not described here. 112.Pp 113The 114.Fa protocol 115specifies a particular protocol to be used with the socket. 116Normally only a single protocol exists to support a particular 117socket type within a given protocol family. However, it is possible 118that many protocols may exist, in which case a particular protocol 119must be specified in this manner. The 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. A stream socket must be in a 128.Em connected 129state before any data may be sent or received 130on it. A connection to another socket is created with a 131.Xr connect 2 132call. Once 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. When a session has been completed a 141.Xr close 2 142may be performed. 143Out-of-band data may also be transmitted as described in 144.Xr send 2 145and received as described in 146.Xr recv 2 . 147.Pp 148The communications protocols used to implement a 149.Dv SOCK_STREAM 150ensure that data 151is not lost or duplicated. If a piece of data for which the 152peer protocol has buffer space cannot be successfully transmitted 153within a reasonable length of time, then 154the connection is considered broken and calls 155will indicate an error with 156-1 returns and with 157.Er ETIMEDOUT 158as the specific code 159in the global variable 160.Va errno . 161The protocols optionally keep sockets 162.Dq warm 163by forcing transmissions 164roughly every minute in the absence of other activity. 165An error is then indicated if no response can be 166elicited on an otherwise 167idle connection for a extended period (e.g. 5 minutes). 168A 169.Dv SIGPIPE 170signal is raised if a process sends 171on a broken stream; this causes naive processes, 172which do not handle the signal, to exit. 173.Pp 174.Dv SOCK_SEQPACKET 175sockets employ the same system calls 176as 177.Dv SOCK_STREAM 178sockets. The only difference 179is that 180.Xr read 2 181calls will return only the amount of data requested, 182and any remaining in the arriving packet will be discarded. 183.Pp 184.Dv SOCK_DGRAM 185and 186.Dv SOCK_RAW 187sockets allow sending of datagrams to correspondents 188named in 189.Xr send 2 190calls. Datagrams are generally received with 191.Xr recvfrom 2 , 192which returns the next datagram with its return address. 193.Pp 194An 195.Xr fcntl 2 196call can be used to specify a process group to receive 197a 198.Dv SIGURG 199signal when the out-of-band data arrives. 200It may also enable non-blocking I/O 201and asynchronous notification of I/O events 202via 203.Dv SIGIO . 204.Pp 205The operation of sockets is controlled by socket level 206.Em options . 207These options are defined in the file 208.Ao Pa sys/socket.h Ac . 209The 210.Xr setsockopt 2 211and 212.Xr getsockopt 2 213system calls are used to set and get options, respectively. 214.Sh RETURN VALUES 215A -1 is returned if an error occurs, otherwise the return 216value is a descriptor referencing the socket. 217.Sh ERRORS 218The 219.Fn socket 220call fails if: 221.Bl -tag -width Er 222.It Bq Er EPROTONOSUPPORT 223The protocol type or the specified protocol is not supported 224within this domain. 225.It Bq Er EMFILE 226The per-process descriptor table is full. 227.It Bq Er ENFILE 228The system file table is full. 229.It Bq Er EACCES 230Permission to create a socket of the specified type and/or protocol 231is denied. 232.It Bq Er ENOBUFS 233Insufficient buffer space is available. 234The socket cannot be created until sufficient resources are freed. 235.El 236.Sh SEE ALSO 237.Xr accept 2 , 238.Xr bind 2 , 239.Xr connect 2 , 240.Xr getprotoent 3 , 241.Xr getsockname 2 , 242.Xr getsockopt 2 , 243.Xr ioctl 2 , 244.Xr listen 2 , 245.Xr read 2 , 246.Xr recv 2 , 247.Xr poll 2 , 248.Xr select 2 , 249.Xr send 2 , 250.Xr setsockopt 2 , 251.Xr shutdown 2 , 252.Xr socketpair 2 , 253.Xr write 2 254.Rs 255.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 256.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 257.Re 258.Rs 259.%T "BSD Interprocess Communication Tutorial" 260.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 261.Re 262.Sh HISTORY 263The 264.Fn socket 265function call appeared in 266.Bx 4.2 . 267