1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\" must display the following acknowledgement:
15 .\" This product includes software developed by the University of
16 .\" California, Berkeley and its contributors.
17 .\" 4. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $
36 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
37 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
38 .\" Modified 1998, 1999 by Andi Kleen <ak@muc.de>
39 .\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com>
40 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
42 .TH SOCKET 2 2021-03-22 "Linux" "Linux Programmer's Manual"
44 socket \- create an endpoint for communication
47 .B #include <sys/socket.h>
49 .BI "int socket(int " domain ", int " type ", int " protocol );
53 creates an endpoint for communication and returns a file descriptor
54 that refers to that endpoint.
55 The file descriptor returned by a successful call will be
56 the lowest-numbered file descriptor not currently open for the process.
60 argument specifies a communication domain; this selects the protocol
61 family which will be used for communication.
62 These families are defined in
64 The formats currently understood by the Linux kernel include:
85 T}:IPv4 Internet protocols:T{
91 Amateur radio AX.25 protocol
93 .\" Part of ax25-tools
98 T}:IPX \- Novell protocols:
106 T}:ITU-T X.25 / ISO-8208 protocol:T{
111 T}:IPv6 Internet protocols:T{
117 DECet protocol sockets
122 Key management protocol, originally developed for usage with IPsec
127 Kernel user interface device
134 Low-level packet interface
141 .\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4
142 Reliable Datagram Sockets (RDS) protocol
144 .\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7
145 .\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7
153 Generic PPP transport layer, for setting up L2 tunnels
159 .\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa
160 Logical link control (IEEE 802.2 LLC) protocol
165 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
166 InfiniBand native addressing
171 .\" commits: 0189197f441602acdca3f97750d392a895b778fd
172 Multiprotocol Label Switching
177 .\" commits: 8dbde28d9711475a..5423dd67bd0108a1
178 Controller Area Network automotive bus protocol
183 .\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4
184 TIPC, "cluster domain sockets" protocol
189 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
190 Bluetooth low-level socket protocol
195 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
196 Interface to kernel crypto API
201 .\" commit: d021c344051af91f42c5ba9fdedc176740cbd238
202 VSOCK (originally "VMWare VSockets") protocol
203 for hypervisor-guest communication
210 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
211 KCM (kernel connection multiplexer) interface
216 .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7
217 XDP (express data path) interface
221 Further details of the above address families,
222 as well as information on several other address families, can be found in
223 .BR address_families (7).
225 The socket has the indicated
227 which specifies the communication semantics.
228 Currently defined types
232 Provides sequenced, reliable, two-way, connection-based byte streams.
233 An out-of-band data transmission mechanism may be supported.
236 Supports datagrams (connectionless, unreliable messages of a fixed
240 Provides a sequenced, reliable, two-way connection-based data
241 transmission path for datagrams of fixed maximum length; a consumer is
242 required to read an entire packet with each input system call.
245 Provides raw network protocol access.
248 Provides a reliable datagram layer that does not guarantee ordering.
251 Obsolete and should not be used in new programs;
255 Some socket types may not be implemented by all protocol families.
257 Since Linux 2.6.27, the
259 argument serves a second purpose:
260 in addition to specifying a socket type,
261 it may include the bitwise OR of any of the following values,
262 to modify the behavior of
268 file status flag on the open file description (see
270 referred to by the new file descriptor.
271 Using this flag saves extra calls to
273 to achieve the same result.
276 Set the close-on-exec
278 flag on the new file descriptor.
279 See the description of the
283 for reasons why this may be useful.
287 specifies a particular protocol to be used with the socket.
288 Normally only a single protocol exists to support a particular
289 socket type within a given protocol family, in which case
291 can be specified as 0.
292 However, it is possible that many protocols may exist, in
293 which case a particular protocol must be specified in this manner.
294 The protocol number to use is specific to the \*(lqcommunication domain\*(rq
295 in which communication is to take place; see
299 on how to map protocol name strings to protocol numbers.
303 are full-duplex byte streams.
306 A stream socket must be in
309 state before any data may be sent or received on it.
311 another socket is created with a
314 Once connected, data may be transferred using
318 calls or some variant of the
323 When a session has been completed a
326 Out-of-band data may also be transmitted as described in
328 and received as described in
331 The communications protocols which implement a
333 ensure that data is not lost or duplicated.
334 If a piece of data for which
335 the peer protocol has buffer space cannot be successfully transmitted
336 within a reasonable length of time, then the connection is considered
340 is enabled on the socket the protocol checks in a protocol-specific
341 manner if the other end is still alive.
344 signal is raised if a process sends or receives
345 on a broken stream; this causes naive processes,
346 which do not handle the signal, to exit.
348 sockets employ the same system calls as
351 The only difference is that
353 calls will return only the amount of data requested,
354 and any data remaining in the arriving packet will be discarded.
355 Also all message boundaries in incoming datagrams are preserved.
360 sockets allow sending of datagrams to correspondents named in
363 Datagrams are generally received with
365 which returns the next datagram along with the address of its sender.
368 is an obsolete socket type to receive raw packets directly from the
377 operation can be used to specify a process or process group to receive a
379 signal when the out-of-band data arrives or
383 connection breaks unexpectedly.
384 This operation may also be used to set the process or process group
385 that receives the I/O and asynchronous notification of I/O events via
397 When the network signals an error condition to the protocol module (e.g.,
398 using an ICMP message for IP) the pending error flag is set for the socket.
399 The next operation on this socket will return the error code of the pending
401 For some protocols it is possible to enable a per-socket error queue
402 to retrieve detailed information about the error; see
407 The operation of sockets is controlled by socket level
409 These options are defined in
415 are used to set and get options.
417 On success, a file descriptor for the new socket is returned.
418 On error, \-1 is returned, and
420 is set to indicate the error.
424 Permission to create a socket of the specified type and/or protocol
428 The implementation does not support the specified address family.
431 Unknown protocol, or protocol family not available.
434 .\" Since Linux 2.6.27
439 The per-process limit on the number of open file descriptors has been reached.
442 The system-wide limit on the total number of open files has been reached.
444 .BR ENOBUFS " or " ENOMEM
445 Insufficient memory is available.
447 created until sufficient resources are freed.
450 The protocol type or the specified protocol is not
451 supported within this domain.
453 Other errors may be generated by the underlying protocol modules.
455 POSIX.1-2001, POSIX.1-2008, 4.4BSD.
461 flags are Linux-specific.
465 It is generally portable to/from
466 non-BSD systems supporting clones of the BSD socket layer (including
469 The manifest constants used under 4.x BSD for protocol families
476 and so on are used for address
478 However, already the BSD man page promises: "The protocol
479 family generally is the same as the address family", and subsequent
480 standards use AF_* everywhere.
482 An example of the use of
505 .BR address_families (7),
512 \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq
514 \(lqBSD Interprocess Communication Tutorial\(rq,
516 .I UNIX Programmer's Supplementary Documents Volume 1.