| 1 | .\" Copyright (c) 1983 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement |
| 3 | .\" specifies the terms and conditions for redistribution. |
| 4 | .\" |
| 5 | .\" @(#)socket.2 5.1 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH SOCKET 2 "18 July 1983" |
| 8 | .UC 5 |
| 9 | .SH NAME |
| 10 | socket \- create an endpoint for communication |
| 11 | .SH SYNOPSIS |
| 12 | .nf |
| 13 | .ft B |
| 14 | #include <sys/types.h> |
| 15 | #include <sys/socket.h> |
| 16 | .PP |
| 17 | .ft B |
| 18 | s = socket(af, type, protocol) |
| 19 | int s, af, type, protocol; |
| 20 | .fi |
| 21 | .SH DESCRIPTION |
| 22 | .I Socket |
| 23 | creates an endpoint for communication and returns a descriptor. |
| 24 | .PP |
| 25 | The |
| 26 | .I af |
| 27 | parameter specifies an address format with which addresses specified |
| 28 | in later operations using the socket should be interpreted. These |
| 29 | formats are defined in the include file |
| 30 | .IR <sys/socket.h> . |
| 31 | The currently understood formats are |
| 32 | .PP |
| 33 | .RS |
| 34 | .nf |
| 35 | .ta 1.25i 1.75i |
| 36 | AF_UNIX (UNIX path names), |
| 37 | AF_INET (ARPA Internet addresses), |
| 38 | AF_PUP (Xerox PUP-I Internet addresses), and |
| 39 | AF_IMPLINK (IMP \*(lqhost at IMP\*(rq addresses). |
| 40 | .fi |
| 41 | .RE |
| 42 | .PP |
| 43 | The socket has the indicated |
| 44 | .I type |
| 45 | which specifies the semantics of communication. Currently |
| 46 | defined types are: |
| 47 | .PP |
| 48 | .RS |
| 49 | .nf |
| 50 | SOCK_STREAM |
| 51 | SOCK_DGRAM |
| 52 | SOCK_RAW |
| 53 | SOCK_SEQPACKET |
| 54 | SOCK_RDM |
| 55 | .fi |
| 56 | .RE |
| 57 | .PP |
| 58 | A SOCK_STREAM type provides sequenced, reliable, |
| 59 | two-way connection based byte streams with an out-of-band data |
| 60 | transmission mechanism. |
| 61 | A SOCK_DGRAM socket supports |
| 62 | datagrams (connectionless, unreliable messages of |
| 63 | a fixed (typically small) maximum length). |
| 64 | SOCK_RAW sockets provide access to internal network interfaces. |
| 65 | The types SOCK_RAW, |
| 66 | which is available only to the super-user, and |
| 67 | SOCK_SEQPACKET and SOCK_RDM, which are planned, |
| 68 | but not yet implemented, are not described here. |
| 69 | .PP |
| 70 | The |
| 71 | .I protocol |
| 72 | specifies a particular protocol to be used with the socket. |
| 73 | Normally only a single protocol exists to support a particular |
| 74 | socket type using a given address format. However, it is possible |
| 75 | that many protocols may exist in which case a particular protocol |
| 76 | must be specified in this manner. The protocol number to use is |
| 77 | particular to the \*(lqcommunication domain\*(rq in which communication |
| 78 | is to take place; see |
| 79 | .IR services (3N) |
| 80 | and |
| 81 | .IR protocols (3N). |
| 82 | .PP |
| 83 | Sockets of type SOCK_STREAM |
| 84 | are full-duplex byte streams, similar |
| 85 | to pipes. A stream socket must be in a |
| 86 | .I connected |
| 87 | state before any data may be sent or received |
| 88 | on it. A connection to another socket is created with a |
| 89 | .IR connect (2) |
| 90 | call. Once connected, data may be transferred using |
| 91 | .IR read (2) |
| 92 | and |
| 93 | .IR write (2) |
| 94 | calls or some variant of the |
| 95 | .IR send (2) |
| 96 | and |
| 97 | .IR recv (2) |
| 98 | calls. When a session has been completed a |
| 99 | .IR close (2) |
| 100 | may be performed. |
| 101 | Out-of-band data may also be transmitted as described in |
| 102 | .IR send (2) |
| 103 | and received as described in |
| 104 | .IR recv (2). |
| 105 | .PP |
| 106 | The communications protocols used to implement a |
| 107 | SOCK_STREAM insure that data |
| 108 | is not lost or duplicated. If a piece of data for which the |
| 109 | peer protocol has buffer space cannot be successfully transmitted |
| 110 | within a reasonable length of time, then |
| 111 | the connection is considered broken and calls |
| 112 | will indicate an error with |
| 113 | \-1 returns and with ETIMEDOUT as the specific code |
| 114 | in the global variable errno. |
| 115 | The protocols optionally keep sockets \*(lqwarm\*(rq by |
| 116 | forcing transmissions |
| 117 | roughly every minute in the absence of other activity. |
| 118 | An error is then indicated if no response can be |
| 119 | elicited on an otherwise |
| 120 | idle connection for a extended period (e.g. 5 minutes). |
| 121 | A SIGPIPE signal is raised if a process sends |
| 122 | on a broken stream; this causes naive processes, |
| 123 | which do not handle the signal, to exit. |
| 124 | .PP |
| 125 | SOCK_DGRAM and SOCK_RAW |
| 126 | sockets allow sending of datagrams to correspondents |
| 127 | named in |
| 128 | .IR send (2) |
| 129 | calls. It is also possible to receive datagrams at |
| 130 | such a socket with |
| 131 | .IR recv (2). |
| 132 | .PP |
| 133 | An |
| 134 | .IR fcntl (2) |
| 135 | call can be used to specify a process group to receive |
| 136 | a SIGURG signal when the out-of-band data arrives. |
| 137 | .PP |
| 138 | The operation of sockets is controlled by socket level |
| 139 | .IR options . |
| 140 | These options are defined in the file |
| 141 | .RI < sys/socket.h > |
| 142 | and explained below. |
| 143 | .I Setsockopt |
| 144 | and |
| 145 | .IR getsockopt (2) |
| 146 | are used to set and get options, respectively. |
| 147 | .PP |
| 148 | .RS |
| 149 | .DT |
| 150 | .nf |
| 151 | SO_DEBUG turn on recording of debugging information |
| 152 | SO_REUSEADDR allow local address reuse |
| 153 | SO_KEEPALIVE keep connections alive |
| 154 | SO_DONTROUTE do no apply routing on outgoing messages |
| 155 | SO_LINGER linger on close if data present |
| 156 | SO_DONTLINGER do not linger on close |
| 157 | .fi |
| 158 | .RE |
| 159 | .PP |
| 160 | SO_DEBUG enables debugging in the underlying protocol modules. |
| 161 | SO_REUSEADDR indicates the rules used in validating addresses supplied |
| 162 | in a |
| 163 | .IR bind (2) |
| 164 | call should allow reuse of local addresses. SO_KEEPALIVE enables the |
| 165 | periodic transmission of messages on a connected socket. Should the |
| 166 | connected party fail to respond to these messages, the connection is |
| 167 | considered broken and processes using the socket are notified via a |
| 168 | SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should |
| 169 | bypass the standard routing facilities. Instead, messages are directed |
| 170 | to the appropriate network interface according to the network portion |
| 171 | of the destination address. SO_LINGER |
| 172 | and SO_DONTLINGER control the actions taken when unsent messags |
| 173 | are queued on socket and a |
| 174 | .IR close (2) |
| 175 | is performed. |
| 176 | If the socket promises reliable delivery of data and SO_LINGER is set, |
| 177 | the system will block the process on the |
| 178 | .I close |
| 179 | attempt until it is able to transmit the data or until it decides it |
| 180 | is unable to deliver the information (a timeout period, termed the |
| 181 | linger interval, is specified in the |
| 182 | .IR setsockopt |
| 183 | call when SO_LINGER is requested). |
| 184 | If SO_DONTLINGER is specified and a |
| 185 | .I close |
| 186 | is issued, the system will process the close in a manner which allows |
| 187 | the process to continue as quickly as possible. |
| 188 | .SH "RETURN VALUE |
| 189 | A \-1 is returned if an error occurs, otherwise the return |
| 190 | value is a descriptor referencing the socket. |
| 191 | .SH "ERRORS |
| 192 | The \fIsocket\fP call fails if: |
| 193 | .TP 20 |
| 194 | [EAFNOSUPPORT] |
| 195 | The specified address family is not supported in this version |
| 196 | of the system. |
| 197 | .TP 20 |
| 198 | [ESOCKTNOSUPPORT] |
| 199 | The specified socket type is not supported in this address family. |
| 200 | .TP 20 |
| 201 | [EPROTONOSUPPORT] |
| 202 | The specified protocol is not supported. |
| 203 | .TP 20 |
| 204 | [EMFILE] |
| 205 | The per-process descriptor table is full. |
| 206 | .TP 20 |
| 207 | [ENOBUFS] |
| 208 | No buffer space is available. The socket cannot be created. |
| 209 | .SH SEE ALSO |
| 210 | accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), |
| 211 | ioctl(2), listen(2), recv(2), |
| 212 | select(2), send(2), shutdown(2), socketpair(2) |
| 213 | .br |
| 214 | ``A 4.2BSD Interprocess Communication Primer''. |
| 215 | .SH BUGS |
| 216 | The use of keepalives is a questionable feature for this layer. |