1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)socket.2 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt SOCKET 2 10.Os BSD 4.2 11.Sh NAME 12.Nm socket 13.Nd create an endpoint for communication 14.Sh SYNOPSIS 15.Fd #include <sys/types.h> 16.Fd #include <sys/socket.h> 17.Ft int 18.Fn socket "int domain" "int type" "int protocol" 19.Sh DESCRIPTION 20.Fn Socket 21creates an endpoint for communication and returns a descriptor. 22.Pp 23The 24.Fa domain 25parameter specifies a communications domain within which 26communication will take place; this selects the protocol family 27which should be used. 28These families are defined in the include file 29.Ao Pa sys/socket.h Ac . 30The currently understood formats are 31.Pp 32.Bd -literal -offset indent -compact 33AF_UNIX (UNIX internal protocols), 34AF_INET (ARPA Internet protocols), 35AF_ISO (ISO protocols), 36AF_NS (Xerox Network Systems protocols), and 37AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer). 38.Ed 39.Pp 40The socket has the indicated 41.Fa type , 42which specifies the semantics of communication. Currently 43defined types are: 44.Pp 45.Bd -literal -offset indent -compact 46SOCK_STREAM 47SOCK_DGRAM 48SOCK_RAW 49SOCK_SEQPACKET 50SOCK_RDM 51.Ed 52.Pp 53A 54.Dv SOCK_STREAM 55type provides sequenced, reliable, 56two-way connection based byte streams. 57An out-of-band data transmission mechanism may be supported. 58A 59.Dv SOCK_DGRAM 60socket supports 61datagrams (connectionless, unreliable messages of 62a fixed (typically small) maximum length). 63A 64.Dv SOCK_SEQPACKET 65socket may provide a sequenced, reliable, 66two-way connection-based data transmission path for datagrams 67of fixed maximum length; a consumer may be required to read 68an entire packet with each read system call. 69This facility is protocol specific, and presently implemented 70only for 71.Dv PF_NS . 72.Dv SOCK_RAW 73sockets provide access to internal network protocols and interfaces. 74The types 75.Dv SOCK_RAW , 76which is available only to the super-user, and 77.Dv SOCK_RDM , 78which is planned, 79but not yet implemented, are not described here. 80.Pp 81The 82.Fa protocol 83specifies a particular protocol to be used with the socket. 84Normally only a single protocol exists to support a particular 85socket type within a given protocol family. However, it is possible 86that many protocols may exist, in which case a particular protocol 87must be specified in this manner. The protocol number to use is 88particular to the \*(lqcommunication domain\*(rq in which communication 89is to take place; see 90.Xr protocols 5 . 91.Pp 92Sockets of type 93.Dv SOCK_STREAM 94are full-duplex byte streams, similar 95to pipes. A stream socket must be in a 96.Em connected 97state before any data may be sent or received 98on it. A connection to another socket is created with a 99.Xr connect 2 100call. Once connected, data may be transferred using 101.Xr read 2 102and 103.Xr write 2 104calls or some variant of the 105.Xr send 2 106and 107.Xr recv 2 108calls. When a session has been completed a 109.Xr close 2 110may be performed. 111Out-of-band data may also be transmitted as described in 112.Xr send 2 113and received as described in 114.Xr recv 2 . 115.Pp 116The communications protocols used to implement a 117.Dv SOCK_STREAM 118insure that data 119is not lost or duplicated. If a piece of data for which the 120peer protocol has buffer space cannot be successfully transmitted 121within a reasonable length of time, then 122the connection is considered broken and calls 123will indicate an error with 124-1 returns and with 125.Dv ETIMEDOUT 126as the specific code 127in the global variable 128.Va errno . 129The protocols optionally keep sockets 130.Dq warm 131by forcing transmissions 132roughly every minute in the absence of other activity. 133An error is then indicated if no response can be 134elicited on an otherwise 135idle connection for a extended period (e.g. 5 minutes). 136A 137.Dv SIGPIPE 138signal is raised if a process sends 139on a broken stream; this causes naive processes, 140which do not handle the signal, to exit. 141.Pp 142.Dv SOCK_SEQPACKET 143sockets employ the same system calls 144as 145.Dv SOCK_STREAM 146sockets. The only difference 147is that 148.Xr read 2 149calls will return only the amount of data requested, 150and any remaining in the arriving packet will be discarded. 151.Pp 152.Dv SOCK_DGRAM 153and 154.Dv SOCK_RAW 155sockets allow sending of datagrams to correspondents 156named in 157.Xr send 2 158calls. Datagrams are generally received with 159.Xr recvfrom 2 , 160which returns the next datagram with its return address. 161.Pp 162An 163.Xr fcntl 2 164call can be used to specify a process group to receive 165a 166.Dv SIGURG 167signal when the out-of-band data arrives. 168It may also enable non-blocking I/O 169and asynchronous notification of I/O events 170via 171.Dv SIGIO . 172.Pp 173The operation of sockets is controlled by socket level 174.Em options . 175These options are defined in the file 176.Ao Pa sys/socket.h Ac . 177.Xr Setsockopt 2 178and 179.Xr getsockopt 2 180are used to set and get options, respectively. 181.Sh RETURN VALUES 182A -1 is returned if an error occurs, otherwise the return 183value is a descriptor referencing the socket. 184.Sh ERRORS 185The 186.Fn socket 187call fails if: 188.Bl -tag -width EPROTONOPSUPPORTA 189.It Bq Er EPROTONOSUPPORT 190The protocol type or the specified protocol is not supported 191within this domain. 192.It Bq Er EMFILE 193The per-process descriptor table is full. 194.It Bq Er ENFILE 195The system file table is full. 196.It Bq Er EACCESS 197Permission to create a socket of the specified type and/or protocol 198is denied. 199.It Bq Er ENOBUFS 200Insufficient buffer space is available. 201The socket cannot be created until sufficient resources are freed. 202.El 203.Sh SEE ALSO 204.Xr accept 2 , 205.Xr bind 2 , 206.Xr connect 2 , 207.Xr getprotoent 3 , 208.Xr getsockname 2 , 209.Xr getsockopt 2 , 210.Xr ioctl 2 , 211.Xr listen 2 , 212.Xr read 2 , 213.Xr recv 2 , 214.Xr select 2 , 215.Xr send 2 , 216.Xr shutdown 2 , 217.Xr socketpair 2 , 218.Xr write 2 219.Rs 220.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 221.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 222.Re 223.Rs 224.%T "BSD Interprocess Communication Tutorial" 225.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" 226.Re 227.Sh HISTORY 228The 229.Nm 230function call appeared in 231.Bx 4.2 . 232