]>
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 | .\" | |
9ba01802 | 43 | .TH SOCKET 2 2019-03-06 "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{ | |
ff085a5e | 154 | Generic PPP transport layer, for setting 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{ | |
49c3b226 ES |
200 | .B AF_VSOCK |
201 | T}:T{ | |
202 | .\" commit: d021c344051af91f42c5ba9fdedc176740cbd238 | |
203 | VSOCK (originally "VMWare VSockets") protocol | |
204 | for hypervisor-guest communication | |
205 | T}:T{ | |
206 | .BR vsock (7) | |
207 | T} | |
208 | T{ | |
5880549a ES |
209 | .B AF_KCM |
210 | T}:T{ | |
211 | .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 | |
698c7b2f | 212 | KCM (kernel connection multiplexor) interface |
5880549a ES |
213 | T} |
214 | T{ | |
9eadb327 TK |
215 | .B AF_XDP |
216 | T}:T{ | |
5880549a | 217 | .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7 |
698c7b2f | 218 | XDP (express data path) interface |
9eadb327 | 219 | T} |
77117f4f MK |
220 | .TE |
221 | .PP | |
43c8308e MK |
222 | Further details of the above address families, |
223 | as well as information on several other address families, can be found in | |
224 | .BR address_families (7). | |
225 | .PP | |
77117f4f MK |
226 | The socket has the indicated |
227 | .IR type , | |
228 | which specifies the communication semantics. | |
229 | Currently defined types | |
230 | are: | |
1ee674a4 | 231 | .TP 16 |
77117f4f MK |
232 | .B SOCK_STREAM |
233 | Provides sequenced, reliable, two-way, connection-based byte streams. | |
234 | An out-of-band data transmission mechanism may be supported. | |
235 | .TP | |
236 | .B SOCK_DGRAM | |
237 | Supports datagrams (connectionless, unreliable messages of a fixed | |
238 | maximum length). | |
239 | .TP | |
240 | .B SOCK_SEQPACKET | |
241 | Provides a sequenced, reliable, two-way connection-based data | |
242 | transmission path for datagrams of fixed maximum length; a consumer is | |
243 | required to read an entire packet with each input system call. | |
244 | .TP | |
245 | .B SOCK_RAW | |
246 | Provides raw network protocol access. | |
247 | .TP | |
248 | .B SOCK_RDM | |
249 | Provides a reliable datagram layer that does not guarantee ordering. | |
250 | .TP | |
251 | .B SOCK_PACKET | |
252 | Obsolete and should not be used in new programs; | |
253 | see | |
254 | .BR packet (7). | |
255 | .PP | |
d332f86f | 256 | Some socket types may not be implemented by all protocol families. |
77117f4f | 257 | .PP |
af14d9f8 MK |
258 | Since Linux 2.6.27, the |
259 | .I type | |
260 | argument serves a second purpose: | |
261 | in addition to specifying a socket type, | |
262 | it may include the bitwise OR of any of the following values, | |
263 | to modify the behavior of | |
264 | .BR socket (): | |
265 | .TP 16 | |
266 | .B SOCK_NONBLOCK | |
267 | Set the | |
268 | .BR O_NONBLOCK | |
7f11e32c MK |
269 | file status flag on the open file description (see |
270 | .BR open (2)) | |
271 | referred to by the new file descriptor. | |
af14d9f8 MK |
272 | Using this flag saves extra calls to |
273 | .BR fcntl (2) | |
274 | to achieve the same result. | |
275 | .TP | |
276 | .B SOCK_CLOEXEC | |
277 | Set the close-on-exec | |
278 | .RB ( FD_CLOEXEC ) | |
279 | flag on the new file descriptor. | |
c5571b61 | 280 | See the description of the |
af14d9f8 MK |
281 | .B O_CLOEXEC |
282 | flag in | |
283 | .BR open (2) | |
284 | for reasons why this may be useful. | |
285 | .PP | |
77117f4f MK |
286 | The |
287 | .I protocol | |
288 | specifies a particular protocol to be used with the socket. | |
289 | Normally only a single protocol exists to support a particular | |
290 | socket type within a given protocol family, in which case | |
291 | .I protocol | |
292 | can be specified as 0. | |
293 | However, it is possible that many protocols may exist, in | |
294 | which case a particular protocol must be specified in this manner. | |
295 | The protocol number to use is specific to the \*(lqcommunication domain\*(rq | |
296 | in which communication is to take place; see | |
297 | .BR protocols (5). | |
298 | See | |
299 | .BR getprotoent (3) | |
300 | on how to map protocol name strings to protocol numbers. | |
301 | .PP | |
302 | Sockets of type | |
303 | .B SOCK_STREAM | |
f6e34058 | 304 | are full-duplex byte streams. |
77117f4f MK |
305 | They do not preserve |
306 | record boundaries. | |
307 | A stream socket must be in | |
308 | a | |
309 | .I connected | |
310 | state before any data may be sent or received on it. | |
311 | A connection to | |
312 | another socket is created with a | |
313 | .BR connect (2) | |
314 | call. | |
315 | Once connected, data may be transferred using | |
316 | .BR read (2) | |
317 | and | |
318 | .BR write (2) | |
319 | calls or some variant of the | |
320 | .BR send (2) | |
321 | and | |
322 | .BR recv (2) | |
323 | calls. | |
324 | When a session has been completed a | |
325 | .BR close (2) | |
326 | may be performed. | |
327 | Out-of-band data may also be transmitted as described in | |
328 | .BR send (2) | |
329 | and received as described in | |
330 | .BR recv (2). | |
331 | .PP | |
332 | The communications protocols which implement a | |
333 | .B SOCK_STREAM | |
334 | ensure that data is not lost or duplicated. | |
335 | If a piece of data for which | |
336 | the peer protocol has buffer space cannot be successfully transmitted | |
337 | within a reasonable length of time, then the connection is considered | |
338 | to be dead. | |
339 | When | |
340 | .B SO_KEEPALIVE | |
341 | is enabled on the socket the protocol checks in a protocol-specific | |
342 | manner if the other end is still alive. | |
343 | A | |
344 | .B SIGPIPE | |
345 | signal is raised if a process sends or receives | |
346 | on a broken stream; this causes naive processes, | |
347 | which do not handle the signal, to exit. | |
348 | .B SOCK_SEQPACKET | |
349 | sockets employ the same system calls as | |
350 | .B SOCK_STREAM | |
351 | sockets. | |
352 | The only difference is that | |
353 | .BR read (2) | |
354 | calls will return only the amount of data requested, | |
355 | and any data remaining in the arriving packet will be discarded. | |
356 | Also all message boundaries in incoming datagrams are preserved. | |
357 | .PP | |
358 | .B SOCK_DGRAM | |
359 | and | |
360 | .B SOCK_RAW | |
361 | sockets allow sending of datagrams to correspondents named in | |
362 | .BR sendto (2) | |
363 | calls. | |
364 | Datagrams are generally received with | |
365 | .BR recvfrom (2), | |
366 | which returns the next datagram along with the address of its sender. | |
367 | .PP | |
368 | .B SOCK_PACKET | |
369 | is an obsolete socket type to receive raw packets directly from the | |
370 | device driver. | |
371 | Use | |
372 | .BR packet (7) | |
373 | instead. | |
374 | .PP | |
375 | An | |
376 | .BR fcntl (2) | |
377 | .B F_SETOWN | |
378 | operation can be used to specify a process or process group to receive a | |
379 | .B SIGURG | |
380 | signal when the out-of-band data arrives or | |
381 | .B SIGPIPE | |
382 | signal when a | |
383 | .B SOCK_STREAM | |
384 | connection breaks unexpectedly. | |
385 | This operation may also be used to set the process or process group | |
386 | that receives the I/O and asynchronous notification of I/O events via | |
387 | .BR SIGIO . | |
388 | Using | |
389 | .B F_SETOWN | |
390 | is equivalent to an | |
391 | .BR ioctl (2) | |
392 | call with the | |
393 | .B FIOSETOWN | |
394 | or | |
395 | .B SIOCSPGRP | |
396 | argument. | |
397 | .PP | |
398 | When the network signals an error condition to the protocol module (e.g., | |
b5fe8515 | 399 | using an ICMP message for IP) the pending error flag is set for the socket. |
77117f4f MK |
400 | The next operation on this socket will return the error code of the pending |
401 | error. | |
402 | For some protocols it is possible to enable a per-socket error queue | |
403 | to retrieve detailed information about the error; see | |
404 | .B IP_RECVERR | |
405 | in | |
406 | .BR ip (7). | |
407 | .PP | |
408 | The operation of sockets is controlled by socket level | |
409 | .IR options . | |
410 | These options are defined in | |
411 | .IR <sys/socket.h> . | |
412 | The functions | |
413 | .BR setsockopt (2) | |
414 | and | |
415 | .BR getsockopt (2) | |
83a9c27c | 416 | are used to set and get options. |
47297adb | 417 | .SH RETURN VALUE |
77117f4f MK |
418 | On success, a file descriptor for the new socket is returned. |
419 | On error, \-1 is returned, and | |
420 | .I errno | |
421 | is set appropriately. | |
422 | .SH ERRORS | |
423 | .TP | |
424 | .B EACCES | |
425 | Permission to create a socket of the specified type and/or protocol | |
426 | is denied. | |
427 | .TP | |
428 | .B EAFNOSUPPORT | |
429 | The implementation does not support the specified address family. | |
430 | .TP | |
431 | .B EINVAL | |
432 | Unknown protocol, or protocol family not available. | |
433 | .TP | |
af14d9f8 MK |
434 | .B EINVAL |
435 | .\" Since Linux 2.6.27 | |
436 | Invalid flags in | |
437 | .IR type . | |
438 | .TP | |
77117f4f | 439 | .B EMFILE |
26c32fab | 440 | The per-process limit on the number of open file descriptors has been reached. |
77117f4f MK |
441 | .TP |
442 | .B ENFILE | |
e258766b | 443 | The system-wide limit on the total number of open files has been reached. |
77117f4f MK |
444 | .TP |
445 | .BR ENOBUFS " or " ENOMEM | |
446 | Insufficient memory is available. | |
447 | The socket cannot be | |
448 | created until sufficient resources are freed. | |
449 | .TP | |
450 | .B EPROTONOSUPPORT | |
451 | The protocol type or the specified protocol is not | |
452 | supported within this domain. | |
453 | .PP | |
454 | Other errors may be generated by the underlying protocol modules. | |
47297adb | 455 | .SH CONFORMING TO |
478298bf | 456 | POSIX.1-2001, POSIX.1-2008, 4.4BSD. |
efeece04 | 457 | .PP |
af14d9f8 MK |
458 | The |
459 | .B SOCK_NONBLOCK | |
460 | and | |
461 | .B SOCK_CLOEXEC | |
462 | flags are Linux-specific. | |
efeece04 | 463 | .PP |
77117f4f MK |
464 | .BR socket () |
465 | appeared in 4.2BSD. | |
466 | It is generally portable to/from | |
467 | non-BSD systems supporting clones of the BSD socket layer (including | |
efbfd7ec | 468 | System\ V variants). |
77117f4f | 469 | .SH NOTES |
478298bf | 470 | POSIX.1 does not require the inclusion of |
77117f4f MK |
471 | .IR <sys/types.h> , |
472 | and this header file is not required on Linux. | |
473 | However, some historical (BSD) implementations required this header | |
474 | file, and portable applications are probably wise to include it. | |
efeece04 | 475 | .PP |
77117f4f MK |
476 | The manifest constants used under 4.x BSD for protocol families |
477 | are | |
478 | .BR PF_UNIX , | |
479 | .BR PF_INET , | |
4a037a4a MK |
480 | and so on, while |
481 | .BR AF_UNIX , | |
1f1fd5ef | 482 | .BR AF_INET , |
4a037a4a | 483 | and so on are used for address |
77117f4f MK |
484 | families. |
485 | However, already the BSD man page promises: "The protocol | |
486 | family generally is the same as the address family", and subsequent | |
487 | standards use AF_* everywhere. | |
77117f4f MK |
488 | .SH EXAMPLE |
489 | An example of the use of | |
490 | .BR socket () | |
491 | is shown in | |
492 | .BR getaddrinfo (3). | |
47297adb | 493 | .SH SEE ALSO |
77117f4f MK |
494 | .BR accept (2), |
495 | .BR bind (2), | |
c1d0454a | 496 | .BR close (2), |
77117f4f MK |
497 | .BR connect (2), |
498 | .BR fcntl (2), | |
499 | .BR getpeername (2), | |
500 | .BR getsockname (2), | |
501 | .BR getsockopt (2), | |
502 | .BR ioctl (2), | |
503 | .BR listen (2), | |
504 | .BR read (2), | |
505 | .BR recv (2), | |
506 | .BR select (2), | |
507 | .BR send (2), | |
508 | .BR shutdown (2), | |
509 | .BR socketpair (2), | |
510 | .BR write (2), | |
511 | .BR getprotoent (3), | |
43c8308e | 512 | .BR address_families (7), |
77117f4f MK |
513 | .BR ip (7), |
514 | .BR socket (7), | |
515 | .BR tcp (7), | |
516 | .BR udp (7), | |
517 | .BR unix (7) | |
efeece04 | 518 | .PP |
77117f4f | 519 | \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq |
173fe7e7 DP |
520 | and |
521 | \(lqBSD Interprocess Communication Tutorial\(rq, | |
522 | reprinted in | |
77117f4f | 523 | .I UNIX Programmer's Supplementary Documents Volume 1. |