man2/socket.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   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
   7 .\" are met:
   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.
  20 .\"
  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
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $
  35 .\"
  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>
  41 .\"
  42 .TH SOCKET 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  43 .SH NAME
  44 socket \- create an endpoint for communication
  45 .SH SYNOPSIS
  46 .nf
  47 .B #include <sys/socket.h>
  48 .PP
  49 .BI "int socket(int " domain ", int " type ", int " protocol );
  50 .fi
  51 .SH DESCRIPTION
  52 .BR socket ()
  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.
  57 .PP
  58 The
  59 .I domain
  60 argument specifies a communication domain; this selects the protocol
  61 family which will be used for communication.
  62 These families are defined in
  63 .IR <sys/socket.h> .
  64 The formats currently understood by the Linux kernel include:
  65 .TS
  66 tab(:);
  67 l1 lw40 l.
  68 Name:Purpose:Man page
  69 T{
  70 .BR AF_UNIX
  71 T}:T{
  72 Local communication
  73 T}:T{
  74 .BR unix (7)
  75 T}
  76 T{
  77 .B AF_LOCAL
  78 T}:T{
  79 Synonym for
  80 .B AF_UNIX
  81 T}:T{
  82 T}
  83 T{
  84 .B AF_INET
  85 T}:IPv4 Internet protocols:T{
  86 .BR ip (7)
  87 T}
  88 T{
  89 .B AF_AX25
  90 T}:T{
  91 Amateur radio AX.25 protocol
  92 T}:T{
  93 .\" Part of ax25-tools
  94 .BR ax25 (4)
  95 T}
  96 T{
  97 .B AF_IPX
  98 T}:IPX \- Novell protocols:
  99 T{
 100 .B AF_APPLETALK
 101 T}:AppleTalk:T{
 102 .BR ddp (7)
 103 T}
 104 T{
 105 .B AF_X25
 106 T}:ITU-T X.25 / ISO-8208 protocol:T{
 107 .BR x25 (7)
 108 T}
 109 T{
 110 .B AF_INET6
 111 T}:IPv6 Internet protocols:T{
 112 .BR ipv6 (7)
 113 T}
 114 T{
 115 .B AF_DECnet
 116 T}:T{
 117 DECet protocol sockets
 118 T}
 119 T{
 120 .B AF_KEY
 121 T}:T{
 122 Key management protocol, originally developed for usage with IPsec
 123 T}
 124 T{
 125 .B AF_NETLINK
 126 T}:T{
 127 Kernel user interface device
 128 T}:T{
 129 .BR netlink (7)
 130 T}
 131 T{
 132 .B AF_PACKET
 133 T}:T{
 134 Low-level packet interface
 135 T}:T{
 136 .BR packet (7)
 137 T}
 138 T{
 139 .B AF_RDS
 140 T}:T{
 141 .\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4
 142 Reliable Datagram Sockets (RDS) protocol
 143 T}:T{
 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
 146 .BR rds (7)
 147 .br
 148 .BR rds\-rdma (7)
 149 T}
 150 T{
 151 .B AF_PPPOX
 152 T}:T{
 153 Generic PPP transport layer, for setting up L2 tunnels
 154 (L2TP and PPPoE)
 155 T}
 156 T{
 157 .B AF_LLC
 158 T}:T{
 159 .\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa
 160 Logical link control (IEEE 802.2 LLC) protocol
 161 T}
 162 T{
 163 .B AF_IB
 164 T}:T{
 165 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
 166 InfiniBand native addressing
 167 T}
 168 T{
 169 .B AF_MPLS
 170 T}:T{
 171 .\" commits: 0189197f441602acdca3f97750d392a895b778fd
 172 Multiprotocol Label Switching
 173 T}
 174 T{
 175 .B AF_CAN
 176 T}:T{
 177 .\" commits: 8dbde28d9711475a..5423dd67bd0108a1
 178 Controller Area Network automotive bus protocol
 179 T}
 180 T{
 181 .B AF_TIPC
 182 T}:T{
 183 .\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4
 184 TIPC, "cluster domain sockets" protocol
 185 T}
 186 T{
 187 .B AF_BLUETOOTH
 188 T}:T{
 189 .\" commits: 8d36eb01da5d371f..ce117ffac2e93334
 190 Bluetooth low-level socket protocol
 191 T}
 192 T{
 193 .B AF_ALG
 194 T}:T{
 195 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
 196 Interface to kernel crypto API
 197 T}
 198 T{
 199 .B AF_VSOCK
 200 T}:T{
 201 .\" commit: d021c344051af91f42c5ba9fdedc176740cbd238
 202 VSOCK (originally "VMWare VSockets") protocol
 203 for hypervisor-guest communication
 204 T}:T{
 205 .BR vsock (7)
 206 T}
 207 T{
 208 .B AF_KCM
 209 T}:T{
 210 .\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314
 211 KCM (kernel connection multiplexer) interface
 212 T}
 213 T{
 214 .B AF_XDP
 215 T}:T{
 216 .\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7
 217 XDP (express data path) interface
 218 T}
 219 .TE
 220 .PP
 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).
 224 .PP
 225 The socket has the indicated
 226 .IR type ,
 227 which specifies the communication semantics.
 228 Currently defined types
 229 are:
 230 .TP 16
 231 .B SOCK_STREAM
 232 Provides sequenced, reliable, two-way, connection-based byte streams.
 233 An out-of-band data transmission mechanism may be supported.
 234 .TP
 235 .B SOCK_DGRAM
 236 Supports datagrams (connectionless, unreliable messages of a fixed
 237 maximum length).
 238 .TP
 239 .B SOCK_SEQPACKET
 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.
 243 .TP
 244 .B SOCK_RAW
 245 Provides raw network protocol access.
 246 .TP
 247 .B SOCK_RDM
 248 Provides a reliable datagram layer that does not guarantee ordering.
 249 .TP
 250 .B SOCK_PACKET
 251 Obsolete and should not be used in new programs;
 252 see
 253 .BR packet (7).
 254 .PP
 255 Some socket types may not be implemented by all protocol families.
 256 .PP
 257 Since Linux 2.6.27, the
 258 .I type
 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
 263 .BR socket ():
 264 .TP 16
 265 .B SOCK_NONBLOCK
 266 Set the
 267 .BR O_NONBLOCK
 268 file status flag on the open file description (see
 269 .BR open (2))
 270 referred to by the new file descriptor.
 271 Using this flag saves extra calls to
 272 .BR fcntl (2)
 273 to achieve the same result.
 274 .TP
 275 .B SOCK_CLOEXEC
 276 Set the close-on-exec
 277 .RB ( FD_CLOEXEC )
 278 flag on the new file descriptor.
 279 See the description of the
 280 .B O_CLOEXEC
 281 flag in
 282 .BR open (2)
 283 for reasons why this may be useful.
 284 .PP
 285 The
 286 .I protocol
 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
 290 .I protocol
 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
 296 .BR protocols (5).
 297 See
 298 .BR getprotoent (3)
 299 on how to map protocol name strings to protocol numbers.
 300 .PP
 301 Sockets of type
 302 .B SOCK_STREAM
 303 are full-duplex byte streams.
 304 They do not preserve
 305 record boundaries.
 306 A stream socket must be in
 307 a
 308 .I connected
 309 state before any data may be sent or received on it.
 310 A connection to
 311 another socket is created with a
 312 .BR connect (2)
 313 call.
 314 Once connected, data may be transferred using
 315 .BR read (2)
 316 and
 317 .BR write (2)
 318 calls or some variant of the
 319 .BR send (2)
 320 and
 321 .BR recv (2)
 322 calls.
 323 When a session has been completed a
 324 .BR close (2)
 325 may be performed.
 326 Out-of-band data may also be transmitted as described in
 327 .BR send (2)
 328 and received as described in
 329 .BR recv (2).
 330 .PP
 331 The communications protocols which implement a
 332 .B SOCK_STREAM
 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
 337 to be dead.
 338 When
 339 .B SO_KEEPALIVE
 340 is enabled on the socket the protocol checks in a protocol-specific
 341 manner if the other end is still alive.
 342 A
 343 .B SIGPIPE
 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.
 347 .B SOCK_SEQPACKET
 348 sockets employ the same system calls as
 349 .B SOCK_STREAM
 350 sockets.
 351 The only difference is that
 352 .BR read (2)
 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.
 356 .PP
 357 .B SOCK_DGRAM
 358 and
 359 .B SOCK_RAW
 360 sockets allow sending of datagrams to correspondents named in
 361 .BR sendto (2)
 362 calls.
 363 Datagrams are generally received with
 364 .BR recvfrom (2),
 365 which returns the next datagram along with the address of its sender.
 366 .PP
 367 .B SOCK_PACKET
 368 is an obsolete socket type to receive raw packets directly from the
 369 device driver.
 370 Use
 371 .BR packet (7)
 372 instead.
 373 .PP
 374 An
 375 .BR fcntl (2)
 376 .B F_SETOWN
 377 operation can be used to specify a process or process group to receive a
 378 .B SIGURG
 379 signal when the out-of-band data arrives or
 380 .B SIGPIPE
 381 signal when a
 382 .B SOCK_STREAM
 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
 386 .BR SIGIO .
 387 Using
 388 .B F_SETOWN
 389 is equivalent to an
 390 .BR ioctl (2)
 391 call with the
 392 .B FIOSETOWN
 393 or
 394 .B SIOCSPGRP
 395 argument.
 396 .PP
 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
 400 error.
 401 For some protocols it is possible to enable a per-socket error queue
 402 to retrieve detailed information about the error; see
 403 .B IP_RECVERR
 404 in
 405 .BR ip (7).
 406 .PP
 407 The operation of sockets is controlled by socket level
 408 .IR options .
 409 These options are defined in
 410 .IR <sys/socket.h> .
 411 The functions
 412 .BR setsockopt (2)
 413 and
 414 .BR getsockopt (2)
 415 are used to set and get options.
 416 .SH RETURN VALUE
 417 On success, a file descriptor for the new socket is returned.
 418 On error, \-1 is returned, and
 419 .I errno
 420 is set to indicate the error.
 421 .SH ERRORS
 422 .TP
 423 .B EACCES
 424 Permission to create a socket of the specified type and/or protocol
 425 is denied.
 426 .TP
 427 .B EAFNOSUPPORT
 428 The implementation does not support the specified address family.
 429 .TP
 430 .B EINVAL
 431 Unknown protocol, or protocol family not available.
 432 .TP
 433 .B EINVAL
 434 .\" Since Linux 2.6.27
 435 Invalid flags in
 436 .IR type .
 437 .TP
 438 .B EMFILE
 439 The per-process limit on the number of open file descriptors has been reached.
 440 .TP
 441 .B ENFILE
 442 The system-wide limit on the total number of open files has been reached.
 443 .TP
 444 .BR ENOBUFS " or " ENOMEM
 445 Insufficient memory is available.
 446 The socket cannot be
 447 created until sufficient resources are freed.
 448 .TP
 449 .B EPROTONOSUPPORT
 450 The protocol type or the specified protocol is not
 451 supported within this domain.
 452 .PP
 453 Other errors may be generated by the underlying protocol modules.
 454 .SH CONFORMING TO
 455 POSIX.1-2001, POSIX.1-2008, 4.4BSD.
 456 .PP
 457 The
 458 .B SOCK_NONBLOCK
 459 and
 460 .B SOCK_CLOEXEC
 461 flags are Linux-specific.
 462 .PP
 463 .BR socket ()
 464 appeared in 4.2BSD.
 465 It is generally portable to/from
 466 non-BSD systems supporting clones of the BSD socket layer (including
 467 System\ V variants).
 468 .SH NOTES
 469 The manifest constants used under 4.x BSD for protocol families
 470 are
 471 .BR PF_UNIX ,
 472 .BR PF_INET ,
 473 and so on, while
 474 .BR AF_UNIX ,
 475 .BR AF_INET ,
 476 and so on are used for address
 477 families.
 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.
 481 .SH EXAMPLES
 482 An example of the use of
 483 .BR socket ()
 484 is shown in
 485 .BR getaddrinfo (3).
 486 .SH SEE ALSO
 487 .BR accept (2),
 488 .BR bind (2),
 489 .BR close (2),
 490 .BR connect (2),
 491 .BR fcntl (2),
 492 .BR getpeername (2),
 493 .BR getsockname (2),
 494 .BR getsockopt (2),
 495 .BR ioctl (2),
 496 .BR listen (2),
 497 .BR read (2),
 498 .BR recv (2),
 499 .BR select (2),
 500 .BR send (2),
 501 .BR shutdown (2),
 502 .BR socketpair (2),
 503 .BR write (2),
 504 .BR getprotoent (3),
 505 .BR address_families (7),
 506 .BR ip (7),
 507 .BR socket (7),
 508 .BR tcp (7),
 509 .BR udp (7),
 510 .BR unix (7)
 511 .PP
 512 \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq
 513 and
 514 \(lqBSD Interprocess Communication Tutorial\(rq,
 515 reprinted in
 516 .I UNIX Programmer's Supplementary Documents Volume 1.