man2/socket.2

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