Debian Codegraph @

upstream/debian-unstable/man2/socket.2

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