man2/socket.2

   1 '\" t
   2 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   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 .\"
  15 .TH socket 2 (date) "Linux man-pages (unreleased)"
  16 .SH NAME
  17 socket \- create an endpoint for communication
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <sys/socket.h>
  24 .P
  25 .BI "int socket(int " domain ", int " type ", int " protocol );
  26 .fi
  27 .SH DESCRIPTION
  28 .BR socket ()
  29 creates an endpoint for communication and returns a file descriptor
  30 that refers to that endpoint.
  31 The file descriptor returned by a successful call will be
  32 the lowest-numbered file descriptor not currently open for the process.
  33 .P
  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> .
  40 The formats currently understood by the Linux kernel include:
  41 .TS
  42 tab(:);
  43 l1 lw40 l.
  44 Name:Purpose:Man page
  45 T{
  46 .B AF_UNIX
  47 T}:T{
  48 Local communication
  49 T}:T{
  50 .BR unix (7)
  51 T}
  52 T{
  53 .B AF_LOCAL
  54 T}:T{
  55 Synonym for
  56 .B AF_UNIX
  57 T}:T{
  58 T}
  59 T{
  60 .B AF_INET
  61 T}:IPv4 Internet protocols:T{
  62 .BR ip (7)
  63 T}
  64 T{
  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)
  71 T}
  72 T{
  73 .B AF_IPX
  74 T}:IPX \- Novell protocols:
  75 T{
  76 .B AF_APPLETALK
  77 T}:AppleTalk:T{
  78 .BR ddp (7)
  79 T}
  80 T{
  81 .B AF_X25
  82 T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{
  83 .BR x25 (7)
  84 T}
  85 T{
  86 .B AF_INET6
  87 T}:IPv6 Internet protocols:T{
  88 .BR ipv6 (7)
  89 T}
  90 T{
  91 .B AF_DECnet
  92 T}:T{
  93 DECet protocol sockets
  94 T}
  95 T{
  96 .B AF_KEY
  97 T}:T{
  98 Key management protocol, originally developed for usage with IPsec
  99 T}
 100 T{
 101 .B AF_NETLINK
 102 T}:T{
 103 Kernel user interface device
 104 T}:T{
 105 .BR netlink (7)
 106 T}
 107 T{
 108 .B AF_PACKET
 109 T}:T{
 110 Low-level packet interface
 111 T}:T{
 112 .BR packet (7)
 113 T}
 114 T{
 115 .B AF_RDS
 116 T}:T{
 117 .\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4
 118 Reliable Datagram Sockets (RDS) protocol
 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
 122 .BR rds (7)
 123 .br
 124 .BR rds\-rdma (7)
 125 T}
 126 T{
 127 .B AF_PPPOX
 128 T}:T{
 129 Generic PPP transport layer, for setting up L2 tunnels
 130 (L2TP and PPPoE)
 131 T}
 132 T{
 133 .B AF_LLC
 134 T}:T{
 135 .\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa
 136 Logical link control (IEEE 802.2 LLC) protocol
 137 T}
 138 T{
 139 .B AF_IB
 140 T}:T{
 141 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
 142 InfiniBand native addressing
 143 T}
 144 T{
 145 .B AF_MPLS
 146 T}:T{
 147 .\" commits: 0189197f441602acdca3f97750d392a895b778fd
 148 Multiprotocol Label Switching
 149 T}
 150 T{
 151 .B AF_CAN
 152 T}:T{
 153 .\" commits: 8dbde28d9711475a..5423dd67bd0108a1
 154 Controller Area Network automotive bus protocol
 155 T}
 156 T{
 157 .B AF_TIPC
 158 T}:T{
 159 .\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4
 160 TIPC, "cluster domain sockets" protocol
 161 T}
 162 T{
 163 .B AF_BLUETOOTH
 164 T}:T{
 165 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
 166 Bluetooth low-level socket protocol
 167 T}
 168 T{
 169 .B AF_ALG
 170 T}:T{
 171 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
 172 Interface to kernel crypto API
 173 T}
 174 T{
 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{
 184 .B AF_KCM
 185 T}:T{
 186 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
 187 KCM (kernel connection multiplexer) interface
 188 T}
 189 T{
 190 .B AF_XDP
 191 T}:T{
 192 .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7
 193 XDP (express data path) interface
 194 T}
 195 .TE
 196 .P
 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).
 200 .P
 201 The socket has the indicated
 202 .IR type ,
 203 which specifies the communication semantics.
 204 Currently defined types
 205 are:
 206 .TP 16
 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).
 230 .P
 231 Some socket types may not be implemented by all protocol families.
 232 .P
 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
 243 .B O_NONBLOCK
 244 file status flag on the open file description (see
 245 .BR open (2))
 246 referred to by the new file descriptor.
 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.
 255 See the description of the
 256 .B O_CLOEXEC
 257 flag in
 258 .BR open (2)
 259 for reasons why this may be useful.
 260 .P
 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.
 276 .P
 277 Sockets of type
 278 .B SOCK_STREAM
 279 are full-duplex byte streams.
 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).
 306 .P
 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.
 332 .P
 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.
 342 .P
 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.
 349 .P
 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.
 372 .P
 373 When the network signals an error condition to the protocol module (e.g.,
 374 using an ICMP message for IP) the pending error flag is set for the socket.
 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).
 382 .P
 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)
 391 are used to set and get options.
 392 .SH RETURN VALUE
 393 On success, a file descriptor for the new socket is returned.
 394 On error, \-1 is returned, and
 395 .I errno
 396 is set to indicate the error.
 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
 409 .B EINVAL
 410 .\" Since Linux 2.6.27
 411 Invalid flags in
 412 .IR type .
 413 .TP
 414 .B EMFILE
 415 The per-process limit on the number of open file descriptors has been reached.
 416 .TP
 417 .B ENFILE
 418 The system-wide limit on the total number of open files has been reached.
 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.
 428 .P
 429 Other errors may be generated by the underlying protocol modules.
 430 .SH STANDARDS
 431 POSIX.1-2008.
 432 .P
 433 .B SOCK_NONBLOCK
 434 and
 435 .B SOCK_CLOEXEC
 436 are Linux-specific.
 437 .SH HISTORY
 438 POSIX.1-2001, 4.4BSD.
 439 .P
 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
 444 System\ V variants).
 445 .P
 446 The manifest constants used under 4.x BSD for protocol families
 447 are
 448 .BR PF_UNIX ,
 449 .BR PF_INET ,
 450 and so on, while
 451 .BR AF_UNIX ,
 452 .BR AF_INET ,
 453 and so on are used for address
 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.
 458 .SH EXAMPLES
 459 An example of the use of
 460 .BR socket ()
 461 is shown in
 462 .BR getaddrinfo (3).
 463 .SH SEE ALSO
 464 .BR accept (2),
 465 .BR bind (2),
 466 .BR close (2),
 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),
 482 .BR address_families (7),
 483 .BR ip (7),
 484 .BR socket (7),
 485 .BR tcp (7),
 486 .BR udp (7),
 487 .BR unix (7)
 488 .P
 489 \[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq]
 490 and
 491 \[lq]BSD Interprocess Communication Tutorial\[rq],
 492 reprinted in
 493 .I UNIX Programmer's Supplementary Documents Volume 1.