man2/socket.2

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