]>
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 | .\" | |
4b8c67d9 | 43 | .TH SOCKET 2 2017-09-15 "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> | |
68e4db0a | 50 | .PP |
77117f4f MK |
51 | .BI "int socket(int " domain ", int " type ", int " protocol ); |
52 | .SH DESCRIPTION | |
53 | .BR socket () | |
29899888 MK |
54 | creates an endpoint for communication and returns a file descriptor |
55 | that refers to that endpoint. | |
047013ac MK |
56 | The file descriptor returned by a successful call will be |
57 | the lowest-numbered file descriptor not currently open for the process. | |
77117f4f MK |
58 | .PP |
59 | The | |
60 | .I domain | |
61 | argument specifies a communication domain; this selects the protocol | |
62 | family which will be used for communication. | |
63 | These families are defined in | |
64 | .IR <sys/socket.h> . | |
22570de1 | 65 | The formats currently understood by the Linux kernel include: |
77117f4f MK |
66 | .TS |
67 | tab(:); | |
698c7b2f | 68 | l1 lw40 l. |
77117f4f MK |
69 | Name:Purpose:Man page |
70 | T{ | |
e900e16c | 71 | .BR AF_UNIX |
77117f4f MK |
72 | T}:T{ |
73 | Local communication | |
74 | T}:T{ | |
75 | .BR unix (7) | |
76 | T} | |
77 | T{ | |
e900e16c MK |
78 | .B AF_LOCAL |
79 | T}:T{ | |
80 | Synonym for | |
81 | .B AF_UNIX | |
82 | T}:T{ | |
83 | T} | |
84 | T{ | |
d4c8c97c | 85 | .B AF_INET |
77117f4f MK |
86 | T}:IPv4 Internet protocols:T{ |
87 | .BR ip (7) | |
88 | T} | |
89 | T{ | |
5880549a ES |
90 | .B AF_AX25 |
91 | T}:T{ | |
92 | Amateur radio AX.25 protocol | |
93 | T}:T{ | |
94 | .\" Part of ax25-tools | |
95 | .BR ax25 (4) | |
77117f4f MK |
96 | T} |
97 | T{ | |
d4c8c97c | 98 | .B AF_IPX |
77117f4f MK |
99 | T}:IPX \- Novell protocols: |
100 | T{ | |
5880549a ES |
101 | .B AF_APPLETALK |
102 | T}:AppleTalk:T{ | |
103 | .BR ddp (7) | |
104 | T} | |
105 | T{ | |
d4c8c97c | 106 | .B AF_X25 |
77117f4f MK |
107 | T}:ITU-T X.25 / ISO-8208 protocol:T{ |
108 | .BR x25 (7) | |
109 | T} | |
110 | T{ | |
5880549a ES |
111 | .B AF_INET6 |
112 | T}:IPv6 Internet protocols:T{ | |
113 | .BR ipv6 (7) | |
114 | T} | |
115 | T{ | |
5880549a ES |
116 | .B AF_DECnet |
117 | T}:T{ | |
e900e16c | 118 | DECet protocol sockets |
5880549a | 119 | T} |
77117f4f | 120 | T{ |
5880549a ES |
121 | .B AF_KEY |
122 | T}:T{ | |
698c7b2f | 123 | Key management protocol, originally developed for usage with IPsec |
5880549a ES |
124 | T} |
125 | T{ | |
126 | .B AF_NETLINK | |
127 | T}:T{ | |
128 | Kernel user interface device | |
129 | T}:T{ | |
130 | .BR netlink (7) | |
77117f4f MK |
131 | T} |
132 | T{ | |
d4c8c97c | 133 | .B AF_PACKET |
77117f4f | 134 | T}:T{ |
e900e16c | 135 | Low-level packet interface |
77117f4f MK |
136 | T}:T{ |
137 | .BR packet (7) | |
138 | T} | |
5880549a | 139 | T{ |
5880549a ES |
140 | .B AF_RDS |
141 | T}:T{ | |
142 | .\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4 | |
698c7b2f | 143 | Reliable Datagram Sockets (RDS) protocol |
5880549a ES |
144 | T}:T{ |
145 | .\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7 | |
146 | .\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7 | |
e900e16c MK |
147 | .BR rds (7) |
148 | .br | |
8dcb9145 | 149 | .BR rds-rdma (7) |
5880549a ES |
150 | T} |
151 | T{ | |
5880549a ES |
152 | .B AF_PPPOX |
153 | T}:T{ | |
154 | Generic PPP transport layer, for setting up up L2 tunnels | |
e900e16c | 155 | (L2TP and PPPoE) |
5880549a ES |
156 | T} |
157 | T{ | |
5880549a ES |
158 | .B AF_LLC |
159 | T}:T{ | |
160 | .\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa | |
698c7b2f | 161 | Logical link control (IEEE 802.2 LLC) protocol |
5880549a ES |
162 | T} |
163 | T{ | |
164 | .B AF_IB | |
165 | T}:T{ | |
166 | .\" commits: 8d36eb01da5d371f..ce117ffac2e93334 | |
698c7b2f | 167 | InfiniBand native addressing |
5880549a ES |
168 | T} |
169 | T{ | |
170 | .B AF_MPLS | |
171 | T}:T{ | |
172 | .\" commits: 0189197f441602acdca3f97750d392a895b778fd | |
698c7b2f | 173 | Multiprotocol Label Switching |
5880549a ES |
174 | T} |
175 | T{ | |
176 | .B AF_CAN | |
177 | T}:T{ | |
178 | .\" commits: 8dbde28d9711475a..5423dd67bd0108a1 | |
698c7b2f | 179 | Controller Area Network automotive bus protocol |
5880549a ES |
180 | T} |
181 | T{ | |
182 | .B AF_TIPC | |
183 | T}:T{ | |
184 | .\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4 | |
698c7b2f | 185 | TIPC, "cluster domain sockets" protocol |
5880549a ES |
186 | T} |
187 | T{ | |
188 | .B AF_BLUETOOTH | |
189 | T}:T{ | |
190 | .\" commits: 8d36eb01da5d371f..ce117ffac2e93334 | |
698c7b2f | 191 | Bluetooth low-level socket protocol |
5880549a ES |
192 | T} |
193 | T{ | |
31d070f8 SM |
194 | .B AF_ALG |
195 | T}:T{ | |
5880549a | 196 | .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 |
698c7b2f | 197 | Interface to kernel crypto API |
5880549a ES |
198 | T} |
199 | T{ | |
5880549a ES |
200 | .B AF_KCM |
201 | T}:T{ | |
202 | .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 | |
698c7b2f | 203 | KCM (kernel connection multiplexor) interface |
5880549a ES |
204 | T} |
205 | T{ | |
9eadb327 TK |
206 | .B AF_XDP |
207 | T}:T{ | |
5880549a | 208 | .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7 |
698c7b2f | 209 | XDP (express data path) interface |
9eadb327 | 210 | T} |
77117f4f MK |
211 | .TE |
212 | .PP | |
43c8308e MK |
213 | Further details of the above address families, |
214 | as well as information on several other address families, can be found in | |
215 | .BR address_families (7). | |
216 | .PP | |
77117f4f MK |
217 | The socket has the indicated |
218 | .IR type , | |
219 | which specifies the communication semantics. | |
220 | Currently defined types | |
221 | are: | |
1ee674a4 | 222 | .TP 16 |
77117f4f MK |
223 | .B SOCK_STREAM |
224 | Provides sequenced, reliable, two-way, connection-based byte streams. | |
225 | An out-of-band data transmission mechanism may be supported. | |
226 | .TP | |
227 | .B SOCK_DGRAM | |
228 | Supports datagrams (connectionless, unreliable messages of a fixed | |
229 | maximum length). | |
230 | .TP | |
231 | .B SOCK_SEQPACKET | |
232 | Provides a sequenced, reliable, two-way connection-based data | |
233 | transmission path for datagrams of fixed maximum length; a consumer is | |
234 | required to read an entire packet with each input system call. | |
235 | .TP | |
236 | .B SOCK_RAW | |
237 | Provides raw network protocol access. | |
238 | .TP | |
239 | .B SOCK_RDM | |
240 | Provides a reliable datagram layer that does not guarantee ordering. | |
241 | .TP | |
242 | .B SOCK_PACKET | |
243 | Obsolete and should not be used in new programs; | |
244 | see | |
245 | .BR packet (7). | |
246 | .PP | |
d332f86f | 247 | Some socket types may not be implemented by all protocol families. |
77117f4f | 248 | .PP |
af14d9f8 MK |
249 | Since Linux 2.6.27, the |
250 | .I type | |
251 | argument serves a second purpose: | |
252 | in addition to specifying a socket type, | |
253 | it may include the bitwise OR of any of the following values, | |
254 | to modify the behavior of | |
255 | .BR socket (): | |
256 | .TP 16 | |
257 | .B SOCK_NONBLOCK | |
258 | Set the | |
259 | .BR O_NONBLOCK | |
7f11e32c MK |
260 | file status flag on the open file description (see |
261 | .BR open (2)) | |
262 | referred to by the new file descriptor. | |
af14d9f8 MK |
263 | Using this flag saves extra calls to |
264 | .BR fcntl (2) | |
265 | to achieve the same result. | |
266 | .TP | |
267 | .B SOCK_CLOEXEC | |
268 | Set the close-on-exec | |
269 | .RB ( FD_CLOEXEC ) | |
270 | flag on the new file descriptor. | |
c5571b61 | 271 | See the description of the |
af14d9f8 MK |
272 | .B O_CLOEXEC |
273 | flag in | |
274 | .BR open (2) | |
275 | for reasons why this may be useful. | |
276 | .PP | |
77117f4f MK |
277 | The |
278 | .I protocol | |
279 | specifies a particular protocol to be used with the socket. | |
280 | Normally only a single protocol exists to support a particular | |
281 | socket type within a given protocol family, in which case | |
282 | .I protocol | |
283 | can be specified as 0. | |
284 | However, it is possible that many protocols may exist, in | |
285 | which case a particular protocol must be specified in this manner. | |
286 | The protocol number to use is specific to the \*(lqcommunication domain\*(rq | |
287 | in which communication is to take place; see | |
288 | .BR protocols (5). | |
289 | See | |
290 | .BR getprotoent (3) | |
291 | on how to map protocol name strings to protocol numbers. | |
292 | .PP | |
293 | Sockets of type | |
294 | .B SOCK_STREAM | |
f6e34058 | 295 | are full-duplex byte streams. |
77117f4f MK |
296 | They do not preserve |
297 | record boundaries. | |
298 | A stream socket must be in | |
299 | a | |
300 | .I connected | |
301 | state before any data may be sent or received on it. | |
302 | A connection to | |
303 | another socket is created with a | |
304 | .BR connect (2) | |
305 | call. | |
306 | Once connected, data may be transferred using | |
307 | .BR read (2) | |
308 | and | |
309 | .BR write (2) | |
310 | calls or some variant of the | |
311 | .BR send (2) | |
312 | and | |
313 | .BR recv (2) | |
314 | calls. | |
315 | When a session has been completed a | |
316 | .BR close (2) | |
317 | may be performed. | |
318 | Out-of-band data may also be transmitted as described in | |
319 | .BR send (2) | |
320 | and received as described in | |
321 | .BR recv (2). | |
322 | .PP | |
323 | The communications protocols which implement a | |
324 | .B SOCK_STREAM | |
325 | ensure that data is not lost or duplicated. | |
326 | If a piece of data for which | |
327 | the peer protocol has buffer space cannot be successfully transmitted | |
328 | within a reasonable length of time, then the connection is considered | |
329 | to be dead. | |
330 | When | |
331 | .B SO_KEEPALIVE | |
332 | is enabled on the socket the protocol checks in a protocol-specific | |
333 | manner if the other end is still alive. | |
334 | A | |
335 | .B SIGPIPE | |
336 | signal is raised if a process sends or receives | |
337 | on a broken stream; this causes naive processes, | |
338 | which do not handle the signal, to exit. | |
339 | .B SOCK_SEQPACKET | |
340 | sockets employ the same system calls as | |
341 | .B SOCK_STREAM | |
342 | sockets. | |
343 | The only difference is that | |
344 | .BR read (2) | |
345 | calls will return only the amount of data requested, | |
346 | and any data remaining in the arriving packet will be discarded. | |
347 | Also all message boundaries in incoming datagrams are preserved. | |
348 | .PP | |
349 | .B SOCK_DGRAM | |
350 | and | |
351 | .B SOCK_RAW | |
352 | sockets allow sending of datagrams to correspondents named in | |
353 | .BR sendto (2) | |
354 | calls. | |
355 | Datagrams are generally received with | |
356 | .BR recvfrom (2), | |
357 | which returns the next datagram along with the address of its sender. | |
358 | .PP | |
359 | .B SOCK_PACKET | |
360 | is an obsolete socket type to receive raw packets directly from the | |
361 | device driver. | |
362 | Use | |
363 | .BR packet (7) | |
364 | instead. | |
365 | .PP | |
366 | An | |
367 | .BR fcntl (2) | |
368 | .B F_SETOWN | |
369 | operation can be used to specify a process or process group to receive a | |
370 | .B SIGURG | |
371 | signal when the out-of-band data arrives or | |
372 | .B SIGPIPE | |
373 | signal when a | |
374 | .B SOCK_STREAM | |
375 | connection breaks unexpectedly. | |
376 | This operation may also be used to set the process or process group | |
377 | that receives the I/O and asynchronous notification of I/O events via | |
378 | .BR SIGIO . | |
379 | Using | |
380 | .B F_SETOWN | |
381 | is equivalent to an | |
382 | .BR ioctl (2) | |
383 | call with the | |
384 | .B FIOSETOWN | |
385 | or | |
386 | .B SIOCSPGRP | |
387 | argument. | |
388 | .PP | |
389 | When the network signals an error condition to the protocol module (e.g., | |
b5fe8515 | 390 | using an ICMP message for IP) the pending error flag is set for the socket. |
77117f4f MK |
391 | The next operation on this socket will return the error code of the pending |
392 | error. | |
393 | For some protocols it is possible to enable a per-socket error queue | |
394 | to retrieve detailed information about the error; see | |
395 | .B IP_RECVERR | |
396 | in | |
397 | .BR ip (7). | |
398 | .PP | |
399 | The operation of sockets is controlled by socket level | |
400 | .IR options . | |
401 | These options are defined in | |
402 | .IR <sys/socket.h> . | |
403 | The functions | |
404 | .BR setsockopt (2) | |
405 | and | |
406 | .BR getsockopt (2) | |
83a9c27c | 407 | are used to set and get options. |
47297adb | 408 | .SH RETURN VALUE |
77117f4f MK |
409 | On success, a file descriptor for the new socket is returned. |
410 | On error, \-1 is returned, and | |
411 | .I errno | |
412 | is set appropriately. | |
413 | .SH ERRORS | |
414 | .TP | |
415 | .B EACCES | |
416 | Permission to create a socket of the specified type and/or protocol | |
417 | is denied. | |
418 | .TP | |
419 | .B EAFNOSUPPORT | |
420 | The implementation does not support the specified address family. | |
421 | .TP | |
422 | .B EINVAL | |
423 | Unknown protocol, or protocol family not available. | |
424 | .TP | |
af14d9f8 MK |
425 | .B EINVAL |
426 | .\" Since Linux 2.6.27 | |
427 | Invalid flags in | |
428 | .IR type . | |
429 | .TP | |
77117f4f | 430 | .B EMFILE |
26c32fab | 431 | The per-process limit on the number of open file descriptors has been reached. |
77117f4f MK |
432 | .TP |
433 | .B ENFILE | |
e258766b | 434 | The system-wide limit on the total number of open files has been reached. |
77117f4f MK |
435 | .TP |
436 | .BR ENOBUFS " or " ENOMEM | |
437 | Insufficient memory is available. | |
438 | The socket cannot be | |
439 | created until sufficient resources are freed. | |
440 | .TP | |
441 | .B EPROTONOSUPPORT | |
442 | The protocol type or the specified protocol is not | |
443 | supported within this domain. | |
444 | .PP | |
445 | Other errors may be generated by the underlying protocol modules. | |
47297adb | 446 | .SH CONFORMING TO |
478298bf | 447 | POSIX.1-2001, POSIX.1-2008, 4.4BSD. |
efeece04 | 448 | .PP |
af14d9f8 MK |
449 | The |
450 | .B SOCK_NONBLOCK | |
451 | and | |
452 | .B SOCK_CLOEXEC | |
453 | flags are Linux-specific. | |
efeece04 | 454 | .PP |
77117f4f MK |
455 | .BR socket () |
456 | appeared in 4.2BSD. | |
457 | It is generally portable to/from | |
458 | non-BSD systems supporting clones of the BSD socket layer (including | |
efbfd7ec | 459 | System\ V variants). |
77117f4f | 460 | .SH NOTES |
478298bf | 461 | POSIX.1 does not require the inclusion of |
77117f4f MK |
462 | .IR <sys/types.h> , |
463 | and this header file is not required on Linux. | |
464 | However, some historical (BSD) implementations required this header | |
465 | file, and portable applications are probably wise to include it. | |
efeece04 | 466 | .PP |
77117f4f MK |
467 | The manifest constants used under 4.x BSD for protocol families |
468 | are | |
469 | .BR PF_UNIX , | |
470 | .BR PF_INET , | |
4a037a4a MK |
471 | and so on, while |
472 | .BR AF_UNIX , | |
1f1fd5ef | 473 | .BR AF_INET , |
4a037a4a | 474 | and so on are used for address |
77117f4f MK |
475 | families. |
476 | However, already the BSD man page promises: "The protocol | |
477 | family generally is the same as the address family", and subsequent | |
478 | standards use AF_* everywhere. | |
efeece04 | 479 | .PP |
bfa44335 MK |
480 | The |
481 | .B AF_ALG | |
482 | protocol type was added in Linux 2.6.38. | |
3c4dfb62 SM |
483 | More information on this interface is provided with the kernel HTML |
484 | documentation at | |
5465ae95 | 485 | .IR https://www.kernel.org/doc/htmldocs/crypto\-API/User.html . |
9eadb327 TK |
486 | .PP |
487 | The | |
488 | .B AF_XDP | |
489 | protocol type was added in Linux 4.18. | |
534d8bf8 MK |
490 | More information on this interface is provided in the kernel source file |
491 | .IR Documentation/networking/af_xdp.rst . | |
77117f4f MK |
492 | .SH EXAMPLE |
493 | An example of the use of | |
494 | .BR socket () | |
495 | is shown in | |
496 | .BR getaddrinfo (3). | |
47297adb | 497 | .SH SEE ALSO |
77117f4f MK |
498 | .BR accept (2), |
499 | .BR bind (2), | |
c1d0454a | 500 | .BR close (2), |
77117f4f MK |
501 | .BR connect (2), |
502 | .BR fcntl (2), | |
503 | .BR getpeername (2), | |
504 | .BR getsockname (2), | |
505 | .BR getsockopt (2), | |
506 | .BR ioctl (2), | |
507 | .BR listen (2), | |
508 | .BR read (2), | |
509 | .BR recv (2), | |
510 | .BR select (2), | |
511 | .BR send (2), | |
512 | .BR shutdown (2), | |
513 | .BR socketpair (2), | |
514 | .BR write (2), | |
515 | .BR getprotoent (3), | |
43c8308e | 516 | .BR address_families (7), |
77117f4f MK |
517 | .BR ip (7), |
518 | .BR socket (7), | |
519 | .BR tcp (7), | |
520 | .BR udp (7), | |
521 | .BR unix (7) | |
efeece04 | 522 | .PP |
77117f4f | 523 | \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq |
173fe7e7 DP |
524 | and |
525 | \(lqBSD Interprocess Communication Tutorial\(rq, | |
526 | reprinted in | |
77117f4f | 527 | .I UNIX Programmer's Supplementary Documents Volume 1. |