]>
Commit | Line | Data |
---|---|---|
77117f4f MK |
1 | '\" t |
2 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. | |
3 | .\" All rights reserved. | |
4 | .\" | |
a9cd9cb7 | 5 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
77117f4f MK |
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. | |
8c9302dc | 33 | .\" %%%LICENSE_END |
77117f4f MK |
34 | .\" |
35 | .\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $ | |
36 | .\" | |
37 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
38 | .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> | |
39 | .\" Modified 1998, 1999 by Andi Kleen <ak@muc.de> | |
40 | .\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com> | |
41 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> | |
42 | .\" | |
5722c835 | 43 | .TH SOCKET 2 2015-07-23 "Linux" "Linux Programmer's Manual" |
77117f4f MK |
44 | .SH NAME |
45 | socket \- create an endpoint for communication | |
46 | .SH SYNOPSIS | |
47 | .BR "#include <sys/types.h>" " /* See NOTES */" | |
48 | .br | |
49 | .B #include <sys/socket.h> | |
50 | .sp | |
51 | .BI "int socket(int " domain ", int " type ", int " protocol ); | |
52 | .SH DESCRIPTION | |
53 | .BR socket () | |
54 | creates an endpoint for communication and returns a descriptor. | |
55 | .PP | |
56 | The | |
57 | .I domain | |
58 | argument specifies a communication domain; this selects the protocol | |
59 | family which will be used for communication. | |
60 | These families are defined in | |
61 | .IR <sys/socket.h> . | |
62 | The currently understood formats include: | |
63 | .TS | |
64 | tab(:); | |
65 | l l l. | |
66 | Name:Purpose:Man page | |
67 | T{ | |
d4c8c97c | 68 | .BR AF_UNIX ", " AF_LOCAL |
77117f4f MK |
69 | T}:T{ |
70 | Local communication | |
71 | T}:T{ | |
72 | .BR unix (7) | |
73 | T} | |
74 | T{ | |
d4c8c97c | 75 | .B AF_INET |
77117f4f MK |
76 | T}:IPv4 Internet protocols:T{ |
77 | .BR ip (7) | |
78 | T} | |
79 | T{ | |
d4c8c97c | 80 | .B AF_INET6 |
77117f4f MK |
81 | T}:IPv6 Internet protocols:T{ |
82 | .BR ipv6 (7) | |
83 | T} | |
84 | T{ | |
d4c8c97c | 85 | .B AF_IPX |
77117f4f MK |
86 | T}:IPX \- Novell protocols: |
87 | T{ | |
d4c8c97c | 88 | .B AF_NETLINK |
77117f4f MK |
89 | T}:T{ |
90 | Kernel user interface device | |
91 | T}:T{ | |
92 | .BR netlink (7) | |
93 | T} | |
94 | T{ | |
d4c8c97c | 95 | .B AF_X25 |
77117f4f MK |
96 | T}:ITU-T X.25 / ISO-8208 protocol:T{ |
97 | .BR x25 (7) | |
98 | T} | |
99 | T{ | |
d4c8c97c | 100 | .B AF_AX25 |
77117f4f MK |
101 | T}:T{ |
102 | Amateur radio AX.25 protocol | |
103 | T}: | |
104 | T{ | |
d4c8c97c | 105 | .B AF_ATMPVC |
77117f4f MK |
106 | T}:Access to raw ATM PVCs: |
107 | T{ | |
d4c8c97c | 108 | .B AF_APPLETALK |
caf2083a | 109 | T}:AppleTalk:T{ |
77117f4f MK |
110 | .BR ddp (7) |
111 | T} | |
112 | T{ | |
d4c8c97c | 113 | .B AF_PACKET |
77117f4f MK |
114 | T}:T{ |
115 | Low level packet interface | |
116 | T}:T{ | |
117 | .BR packet (7) | |
118 | T} | |
31d070f8 SM |
119 | T{ |
120 | .B AF_ALG | |
121 | T}:T{ | |
122 | Interface to kernel crypto API | |
123 | T} | |
77117f4f MK |
124 | .TE |
125 | .PP | |
126 | The socket has the indicated | |
127 | .IR type , | |
128 | which specifies the communication semantics. | |
129 | Currently defined types | |
130 | are: | |
1ee674a4 | 131 | .TP 16 |
77117f4f MK |
132 | .B SOCK_STREAM |
133 | Provides sequenced, reliable, two-way, connection-based byte streams. | |
134 | An out-of-band data transmission mechanism may be supported. | |
135 | .TP | |
136 | .B SOCK_DGRAM | |
137 | Supports datagrams (connectionless, unreliable messages of a fixed | |
138 | maximum length). | |
139 | .TP | |
140 | .B SOCK_SEQPACKET | |
141 | Provides a sequenced, reliable, two-way connection-based data | |
142 | transmission path for datagrams of fixed maximum length; a consumer is | |
143 | required to read an entire packet with each input system call. | |
144 | .TP | |
145 | .B SOCK_RAW | |
146 | Provides raw network protocol access. | |
147 | .TP | |
148 | .B SOCK_RDM | |
149 | Provides a reliable datagram layer that does not guarantee ordering. | |
150 | .TP | |
151 | .B SOCK_PACKET | |
152 | Obsolete and should not be used in new programs; | |
153 | see | |
154 | .BR packet (7). | |
155 | .PP | |
d332f86f | 156 | Some socket types may not be implemented by all protocol families. |
77117f4f | 157 | .PP |
af14d9f8 MK |
158 | Since Linux 2.6.27, the |
159 | .I type | |
160 | argument serves a second purpose: | |
161 | in addition to specifying a socket type, | |
162 | it may include the bitwise OR of any of the following values, | |
163 | to modify the behavior of | |
164 | .BR socket (): | |
165 | .TP 16 | |
166 | .B SOCK_NONBLOCK | |
167 | Set the | |
168 | .BR O_NONBLOCK | |
169 | file status flag on the new open file description. | |
170 | Using this flag saves extra calls to | |
171 | .BR fcntl (2) | |
172 | to achieve the same result. | |
173 | .TP | |
174 | .B SOCK_CLOEXEC | |
175 | Set the close-on-exec | |
176 | .RB ( FD_CLOEXEC ) | |
177 | flag on the new file descriptor. | |
c5571b61 | 178 | See the description of the |
af14d9f8 MK |
179 | .B O_CLOEXEC |
180 | flag in | |
181 | .BR open (2) | |
182 | for reasons why this may be useful. | |
183 | .PP | |
77117f4f MK |
184 | The |
185 | .I protocol | |
186 | specifies a particular protocol to be used with the socket. | |
187 | Normally only a single protocol exists to support a particular | |
188 | socket type within a given protocol family, in which case | |
189 | .I protocol | |
190 | can be specified as 0. | |
191 | However, it is possible that many protocols may exist, in | |
192 | which case a particular protocol must be specified in this manner. | |
193 | The protocol number to use is specific to the \*(lqcommunication domain\*(rq | |
194 | in which communication is to take place; see | |
195 | .BR protocols (5). | |
196 | See | |
197 | .BR getprotoent (3) | |
198 | on how to map protocol name strings to protocol numbers. | |
199 | .PP | |
200 | Sockets of type | |
201 | .B SOCK_STREAM | |
f6e34058 | 202 | are full-duplex byte streams. |
77117f4f MK |
203 | They do not preserve |
204 | record boundaries. | |
205 | A stream socket must be in | |
206 | a | |
207 | .I connected | |
208 | state before any data may be sent or received on it. | |
209 | A connection to | |
210 | another socket is created with a | |
211 | .BR connect (2) | |
212 | call. | |
213 | Once connected, data may be transferred using | |
214 | .BR read (2) | |
215 | and | |
216 | .BR write (2) | |
217 | calls or some variant of the | |
218 | .BR send (2) | |
219 | and | |
220 | .BR recv (2) | |
221 | calls. | |
222 | When a session has been completed a | |
223 | .BR close (2) | |
224 | may be performed. | |
225 | Out-of-band data may also be transmitted as described in | |
226 | .BR send (2) | |
227 | and received as described in | |
228 | .BR recv (2). | |
229 | .PP | |
230 | The communications protocols which implement a | |
231 | .B SOCK_STREAM | |
232 | ensure that data is not lost or duplicated. | |
233 | If a piece of data for which | |
234 | the peer protocol has buffer space cannot be successfully transmitted | |
235 | within a reasonable length of time, then the connection is considered | |
236 | to be dead. | |
237 | When | |
238 | .B SO_KEEPALIVE | |
239 | is enabled on the socket the protocol checks in a protocol-specific | |
240 | manner if the other end is still alive. | |
241 | A | |
242 | .B SIGPIPE | |
243 | signal is raised if a process sends or receives | |
244 | on a broken stream; this causes naive processes, | |
245 | which do not handle the signal, to exit. | |
246 | .B SOCK_SEQPACKET | |
247 | sockets employ the same system calls as | |
248 | .B SOCK_STREAM | |
249 | sockets. | |
250 | The only difference is that | |
251 | .BR read (2) | |
252 | calls will return only the amount of data requested, | |
253 | and any data remaining in the arriving packet will be discarded. | |
254 | Also all message boundaries in incoming datagrams are preserved. | |
255 | .PP | |
256 | .B SOCK_DGRAM | |
257 | and | |
258 | .B SOCK_RAW | |
259 | sockets allow sending of datagrams to correspondents named in | |
260 | .BR sendto (2) | |
261 | calls. | |
262 | Datagrams are generally received with | |
263 | .BR recvfrom (2), | |
264 | which returns the next datagram along with the address of its sender. | |
265 | .PP | |
266 | .B SOCK_PACKET | |
267 | is an obsolete socket type to receive raw packets directly from the | |
268 | device driver. | |
269 | Use | |
270 | .BR packet (7) | |
271 | instead. | |
272 | .PP | |
273 | An | |
274 | .BR fcntl (2) | |
275 | .B F_SETOWN | |
276 | operation can be used to specify a process or process group to receive a | |
277 | .B SIGURG | |
278 | signal when the out-of-band data arrives or | |
279 | .B SIGPIPE | |
280 | signal when a | |
281 | .B SOCK_STREAM | |
282 | connection breaks unexpectedly. | |
283 | This operation may also be used to set the process or process group | |
284 | that receives the I/O and asynchronous notification of I/O events via | |
285 | .BR SIGIO . | |
286 | Using | |
287 | .B F_SETOWN | |
288 | is equivalent to an | |
289 | .BR ioctl (2) | |
290 | call with the | |
291 | .B FIOSETOWN | |
292 | or | |
293 | .B SIOCSPGRP | |
294 | argument. | |
295 | .PP | |
296 | When the network signals an error condition to the protocol module (e.g., | |
297 | using a ICMP message for IP) the pending error flag is set for the socket. | |
298 | The next operation on this socket will return the error code of the pending | |
299 | error. | |
300 | For some protocols it is possible to enable a per-socket error queue | |
301 | to retrieve detailed information about the error; see | |
302 | .B IP_RECVERR | |
303 | in | |
304 | .BR ip (7). | |
305 | .PP | |
306 | The operation of sockets is controlled by socket level | |
307 | .IR options . | |
308 | These options are defined in | |
309 | .IR <sys/socket.h> . | |
310 | The functions | |
311 | .BR setsockopt (2) | |
312 | and | |
313 | .BR getsockopt (2) | |
314 | are used to set and get options, respectively. | |
47297adb | 315 | .SH RETURN VALUE |
77117f4f MK |
316 | On success, a file descriptor for the new socket is returned. |
317 | On error, \-1 is returned, and | |
318 | .I errno | |
319 | is set appropriately. | |
320 | .SH ERRORS | |
321 | .TP | |
322 | .B EACCES | |
323 | Permission to create a socket of the specified type and/or protocol | |
324 | is denied. | |
325 | .TP | |
326 | .B EAFNOSUPPORT | |
327 | The implementation does not support the specified address family. | |
328 | .TP | |
329 | .B EINVAL | |
330 | Unknown protocol, or protocol family not available. | |
331 | .TP | |
af14d9f8 MK |
332 | .B EINVAL |
333 | .\" Since Linux 2.6.27 | |
334 | Invalid flags in | |
335 | .IR type . | |
336 | .TP | |
77117f4f | 337 | .B EMFILE |
26c32fab | 338 | The per-process limit on the number of open file descriptors has been reached. |
77117f4f MK |
339 | .TP |
340 | .B ENFILE | |
341 | The system limit on the total number of open files has been reached. | |
342 | .TP | |
343 | .BR ENOBUFS " or " ENOMEM | |
344 | Insufficient memory is available. | |
345 | The socket cannot be | |
346 | created until sufficient resources are freed. | |
347 | .TP | |
348 | .B EPROTONOSUPPORT | |
349 | The protocol type or the specified protocol is not | |
350 | supported within this domain. | |
351 | .PP | |
352 | Other errors may be generated by the underlying protocol modules. | |
47297adb | 353 | .SH CONFORMING TO |
478298bf | 354 | POSIX.1-2001, POSIX.1-2008, 4.4BSD. |
af14d9f8 MK |
355 | |
356 | The | |
357 | .B SOCK_NONBLOCK | |
358 | and | |
359 | .B SOCK_CLOEXEC | |
360 | flags are Linux-specific. | |
361 | ||
77117f4f MK |
362 | .BR socket () |
363 | appeared in 4.2BSD. | |
364 | It is generally portable to/from | |
365 | non-BSD systems supporting clones of the BSD socket layer (including | |
efbfd7ec | 366 | System\ V variants). |
77117f4f | 367 | .SH NOTES |
478298bf | 368 | POSIX.1 does not require the inclusion of |
77117f4f MK |
369 | .IR <sys/types.h> , |
370 | and this header file is not required on Linux. | |
371 | However, some historical (BSD) implementations required this header | |
372 | file, and portable applications are probably wise to include it. | |
373 | ||
374 | The manifest constants used under 4.x BSD for protocol families | |
375 | are | |
376 | .BR PF_UNIX , | |
377 | .BR PF_INET , | |
4a037a4a MK |
378 | and so on, while |
379 | .BR AF_UNIX , | |
1f1fd5ef | 380 | .BR AF_INET , |
4a037a4a | 381 | and so on are used for address |
77117f4f MK |
382 | families. |
383 | However, already the BSD man page promises: "The protocol | |
384 | family generally is the same as the address family", and subsequent | |
385 | standards use AF_* everywhere. | |
31d070f8 | 386 | |
bfa44335 MK |
387 | The |
388 | .B AF_ALG | |
389 | protocol type was added in Linux 2.6.38. | |
3c4dfb62 SM |
390 | More information on this interface is provided with the kernel HTML |
391 | documentation at | |
392 | .IR https://www.kernel.org/doc/htmldocs/crypto-API/User.html . | |
77117f4f MK |
393 | .SH EXAMPLE |
394 | An example of the use of | |
395 | .BR socket () | |
396 | is shown in | |
397 | .BR getaddrinfo (3). | |
47297adb | 398 | .SH SEE ALSO |
77117f4f MK |
399 | .BR accept (2), |
400 | .BR bind (2), | |
c1d0454a | 401 | .BR close (2), |
77117f4f MK |
402 | .BR connect (2), |
403 | .BR fcntl (2), | |
404 | .BR getpeername (2), | |
405 | .BR getsockname (2), | |
406 | .BR getsockopt (2), | |
407 | .BR ioctl (2), | |
408 | .BR listen (2), | |
409 | .BR read (2), | |
410 | .BR recv (2), | |
411 | .BR select (2), | |
412 | .BR send (2), | |
413 | .BR shutdown (2), | |
414 | .BR socketpair (2), | |
415 | .BR write (2), | |
416 | .BR getprotoent (3), | |
417 | .BR ip (7), | |
418 | .BR socket (7), | |
419 | .BR tcp (7), | |
420 | .BR udp (7), | |
421 | .BR unix (7) | |
173fe7e7 | 422 | |
77117f4f | 423 | \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq |
173fe7e7 DP |
424 | and |
425 | \(lqBSD Interprocess Communication Tutorial\(rq, | |
426 | reprinted in | |
77117f4f | 427 | .I UNIX Programmer's Supplementary Documents Volume 1. |