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