2 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
3 .\" All rights reserved.
5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
35 .\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $
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>
43 .TH SOCKET 2 2019-03-06 "Linux" "Linux Programmer's Manual"
45 socket \- create an endpoint for communication
47 .BR "#include <sys/types.h>" " /* See NOTES */"
49 .B #include <sys/socket.h>
51 .BI "int socket(int " domain ", int " type ", int " protocol );
54 creates an endpoint for communication and returns a file descriptor
55 that refers to that endpoint.
56 The file descriptor returned by a successful call will be
57 the lowest-numbered file descriptor not currently open for the process.
61 argument specifies a communication domain; this selects the protocol
62 family which will be used for communication.
63 These families are defined in
65 The formats currently understood by the Linux kernel include:
86 T}:IPv4 Internet protocols:T{
92 Amateur radio AX.25 protocol
94 .\" Part of ax25-tools
99 T}:IPX \- Novell protocols:
107 T}:ITU-T X.25 / ISO-8208 protocol:T{
112 T}:IPv6 Internet protocols:T{
118 DECet protocol sockets
123 Key management protocol, originally developed for usage with IPsec
128 Kernel user interface device
135 Low-level packet interface
142 .\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4
143 Reliable Datagram Sockets (RDS) protocol
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
154 Generic PPP transport layer, for setting up up L2 tunnels
160 .\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa
161 Logical link control (IEEE 802.2 LLC) protocol
166 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
167 InfiniBand native addressing
172 .\" commits: 0189197f441602acdca3f97750d392a895b778fd
173 Multiprotocol Label Switching
178 .\" commits: 8dbde28d9711475a..5423dd67bd0108a1
179 Controller Area Network automotive bus protocol
184 .\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4
185 TIPC, "cluster domain sockets" protocol
190 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
191 Bluetooth low-level socket protocol
196 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
197 Interface to kernel crypto API
202 .\" commit: d021c344051af91f42c5ba9fdedc176740cbd238
203 VSOCK (originally "VMWare VSockets") protocol
204 for hypervisor-guest communication
211 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
212 KCM (kernel connection multiplexor) interface
217 .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7
218 XDP (express data path) interface
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).
226 The socket has the indicated
228 which specifies the communication semantics.
229 Currently defined types
233 Provides sequenced, reliable, two-way, connection-based byte streams.
234 An out-of-band data transmission mechanism may be supported.
237 Supports datagrams (connectionless, unreliable messages of a fixed
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.
246 Provides raw network protocol access.
249 Provides a reliable datagram layer that does not guarantee ordering.
252 Obsolete and should not be used in new programs;
256 Some socket types may not be implemented by all protocol families.
258 Since Linux 2.6.27, the
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
269 file status flag on the open file description (see
271 referred to by the new file descriptor.
272 Using this flag saves extra calls to
274 to achieve the same result.
277 Set the close-on-exec
279 flag on the new file descriptor.
280 See the description of the
284 for reasons why this may be useful.
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
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
300 on how to map protocol name strings to protocol numbers.
304 are full-duplex byte streams.
307 A stream socket must be in
310 state before any data may be sent or received on it.
312 another socket is created with a
315 Once connected, data may be transferred using
319 calls or some variant of the
324 When a session has been completed a
327 Out-of-band data may also be transmitted as described in
329 and received as described in
332 The communications protocols which implement a
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
341 is enabled on the socket the protocol checks in a protocol-specific
342 manner if the other end is still alive.
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.
349 sockets employ the same system calls as
352 The only difference is that
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.
361 sockets allow sending of datagrams to correspondents named in
364 Datagrams are generally received with
366 which returns the next datagram along with the address of its sender.
369 is an obsolete socket type to receive raw packets directly from the
378 operation can be used to specify a process or process group to receive a
380 signal when the out-of-band data arrives or
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
398 When the network signals an error condition to the protocol module (e.g.,
399 using an ICMP message for IP) the pending error flag is set for the socket.
400 The next operation on this socket will return the error code of the pending
402 For some protocols it is possible to enable a per-socket error queue
403 to retrieve detailed information about the error; see
408 The operation of sockets is controlled by socket level
410 These options are defined in
416 are used to set and get options.
418 On success, a file descriptor for the new socket is returned.
419 On error, \-1 is returned, and
421 is set appropriately.
425 Permission to create a socket of the specified type and/or protocol
429 The implementation does not support the specified address family.
432 Unknown protocol, or protocol family not available.
435 .\" Since Linux 2.6.27
440 The per-process limit on the number of open file descriptors has been reached.
443 The system-wide limit on the total number of open files has been reached.
445 .BR ENOBUFS " or " ENOMEM
446 Insufficient memory is available.
448 created until sufficient resources are freed.
451 The protocol type or the specified protocol is not
452 supported within this domain.
454 Other errors may be generated by the underlying protocol modules.
456 POSIX.1-2001, POSIX.1-2008, 4.4BSD.
462 flags are Linux-specific.
466 It is generally portable to/from
467 non-BSD systems supporting clones of the BSD socket layer (including
470 POSIX.1 does not require the inclusion of
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.
476 The manifest constants used under 4.x BSD for protocol families
483 and so on are used for address
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.
489 An example of the use of
512 .BR address_families (7),
519 \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq
521 \(lqBSD Interprocess Communication Tutorial\(rq,
523 .I UNIX Programmer's Supplementary Documents Volume 1.